Guarantees vs. Best-Effort

Metateam aims to be reliable, but its behavior depends on third-party AI clients and operating system state. This page clarifies what is a hard guarantee and what is a "best-effort" convenience.

Session Capture

Contract (in current implementation)

  • Hook readiness: Claude Code and Gemini SessionStart hooks signal client readiness and re-register crew agents after client-side resets.
  • Background Uploads: Upload work is detached from the interactive terminal so your session can exit immediately.

Best-Effort

  • Communicator-driven upload: Crew session upload is driven by the communicator/session tailer. If transcript discovery or client transcript format changes break detection, upload can be missed until Metateam is updated.
  • Manual catch-up upload: metateam session upload can recover sessions from known transcript locations or explicit transcript files. It depends on readable local files and compatible transcript formats.
  • Resume Chains: Matching resumed sessions to their root ID depends on the client providing a session reference in its transcript. If the client changes its transcript format, resume chains might break until Metateam is updated.

Context Loading

Contract (in current implementation)

  • Content Delivery: When managed summon prepares an agent and the API is reachable, the CLI writes formatted context to START.md beside the generated instruction file. Manual metateam start writes the same formatted context to stdout.
  • Important Entries: Entries marked as important are included in summon-generated START.md and manual metateam start payloads when project detection/pinning succeeds.

Best-Effort

  • Project Detection: While project detection has a clear precedence (pin file > git remote > path prefix), it can fail if your environment is missing git metadata or if a pin file is unreadable.
  • Relevance Ranking: Session summaries returned in START.md / metateam start are ranked using BM25. Like all search systems, relevance is "best-effort"—it might include a session that is technically similar but not helpful, or miss a helpful one with no keyword overlap.

Crew and Attractor

Contract (in current implementation)

  • Deterministic Merge: Attractor parallel fan-in merges sort branches by ID and namespace context keys to avoid collisions.

Best-Effort

  • Agent Compliance: We cannot guarantee that an AI agent will follow the communication protocol (writing to the mail-board, using metateam crew message). Personas include instructions for these behaviors, but the agent’s actual compliance depends on the underlying model’s capabilities.
  • Observability Persistence: The .crew/history.md and mail-board files are written locally. If an agent fails so catastrophically that it cannot run CLI commands, the history record for that event might be incomplete.
  • Message Delivery: crew message relies on a live tmux session and successful tmux message delivery. If the session does not exist, tmux is unhealthy, or message delivery fails, delivery is not guaranteed.

Network and Security

Contract (in current implementation)

  • Marker Files: Metateam skips START context generation and session uploads in any directory tree where a .nometateam file is present (unless overridden by a closer .yesmetateam). Summon-time START generation also clears stale START.md cache files under .nometateam.

Best-Effort

  • Compaction: Compaction is a "best-effort" size reduction to ensure uploads succeed. It is not a security feature and does not guarantee the removal of sensitive information.