claude-team-mcp 0.7.0__tar.gz → 0.8.2__tar.gz

{claude_team_mcp-0.7.0 → claude_team_mcp-0.8.2}/.pebbles/events.jsonl

@@ -179,3 +179,52 @@
 {"type":"close","timestamp":"2026-01-28T23:37:13.690021Z","issue_id":"cic-ba6","payload":{}}
 {"type":"comment","timestamp":"2026-01-28T23:37:28.697959Z","issue_id":"cic-2d8","payload":{"body":"Completed tmux window naming update: format now '\u003cname\u003e | \u003cproject\u003e [issue]'; project name derived from project_path with .worktrees handling; issue id pulled from bead or annotation. Updated tmux backend + spawn logic and added tests."}}
 {"type":"close","timestamp":"2026-01-28T23:37:30.840687Z","issue_id":"cic-2d8","payload":{}}
+{"type":"create","timestamp":"2026-01-30T17:41:16.111959Z","issue_id":"cic-345","payload":{"description":"Currently the tmux backend uses a single global 'claude-team' session for all workers. Instead, create a separate tmux session per project path. This makes it easier to monitor workers by project when using tmux locally.\n\nScope: investigate current session naming, identify all touch points, propose naming scheme, assess impact on discovery/adoption/cleanup.","priority":"2","title":"Per-project tmux sessions instead of global claude-team session","type":"task"}}
+{"type":"status_update","timestamp":"2026-01-30T17:45:04.28959Z","issue_id":"cic-345","payload":{"status":"in_progress"}}
+{"type":"close","timestamp":"2026-01-30T17:52:20.629185Z","issue_id":"cic-345","payload":{}}
+{"type":"create","timestamp":"2026-01-31T16:47:58.166575Z","issue_id":"cic-bbd","payload":{"description":"## Problem\n\nTwo disconnected views of worker state:\n\n1. **list_workers (MCP)** — in-memory SessionRegistry, wiped on restart. No persistence.\n2. **Event log (events.jsonl)** — persistent lifecycle events, but no MCP query API. External consumers resort to shell scripts to parse it.\n\nAfter restart, list_workers returns empty even if workers are alive. Event log has history but no programmatic access.\n\n## Proposed Solution (Option C)\n\n### Part 1: Enhance list_workers with event log recovery\n- On startup, reconstruct known worker state from event log snapshots\n- list_workers becomes single source of truth for current state\n\n### Part 2: New worker_events MCP tool\n- Wraps read_events_since() as MCP tool\n- Returns state transitions, completions, stuck workers\n- Supersedes closed cic-467 (poll_worker_changes)\n\n## Context\n- events.py has read_events_since(), get_latest_snapshot() — not wired to MCP\n- Registry has tmux adoption but doesn't use event log for recovery\n- Monitoring agents currently shell out to parse events.jsonl directly","priority":"1","title":"Unified worker state API — merge registry + event log","type":"feature"}}
+{"type":"status_update","timestamp":"2026-01-31T16:48:32.350157Z","issue_id":"cic-bbd","payload":{"status":"in_progress"}}
+{"type":"close","timestamp":"2026-01-31T17:00:14.556752Z","issue_id":"cic-bbd","payload":{}}
+{"type":"create","timestamp":"2026-01-31T17:00:32.968359Z","issue_id":"cic-68b","payload":{"description":"## Problem\n\nWhen Codex has a pending update, it shows an interactive TUI prompt (Update now / Skip / Skip until next version) that blocks the session from becoming interactive. The claude-team spawn logic times out at 30s waiting for Codex to be ready, but the prompt is sitting there waiting for user input.\n\nThis is a silent failure — the server logs show a timeout but there's no indication it's an update prompt specifically.\n\n## Immediate Workaround\n\nSet `check_for_update_on_startup = false` in `~/.codex/config.toml`. Done for Josh's machine.\n\n## Proposed Solution for claude-team\n\n### Option A: Detect and auto-dismiss (recommended)\nAfter spawning Codex in tmux, scrape the pane for update prompt indicators (e.g. 'Update now', 'Skip until next version') and send key '2' (Skip) automatically. This keeps the user's codex up-to-date awareness while not blocking automation.\n\n### Option B: Set env/config to suppress\nHave claude-team set an env var or write a temporary config overlay that disables the update check for spawned workers. Codex supports `check_for_update_on_startup = false` in config.toml.\n\n### Option C: Document and warn\nAdd to spawn_workers output a warning when Codex times out, suggesting the config flag.\n\n## Context\n- Codex source: `codex-rs/tui/src/update_prompt.rs` — uses `get_upgrade_version_for_popup(config)`\n- Config flag: `check_for_update_on_startup` (defaults true)\n- Dismiss mechanism: option 3 persists to `~/.codex/version.json` dismissed_version field\n- The prompt accepts key inputs: 1=Update, 2=Skip, 3=Skip until next version, Esc=Skip","priority":"1","title":"Handle Codex update prompt blocking worker spawn","type":"bug"}}
+{"type":"status_update","timestamp":"2026-01-31T22:34:51.762832Z","issue_id":"cic-bbd","payload":{"status":"open"}}
+{"type":"update","timestamp":"2026-01-31T22:34:51.762832Z","issue_id":"cic-bbd","payload":{"type":"epic"}}
+{"type":"create","timestamp":"2026-01-31T22:35:00.158594Z","issue_id":"cic-fd1","payload":{"description":"Create a lightweight RecoveredSession type in registry.py that represents sessions restored from the event log.\n\n## Requirements\n- Fields: session_id, name, project_path, terminal_id, agent_type, status, last_activity, created_at\n- Implement to_dict() matching ManagedSession output format\n- Add source field: 'event_log' (vs 'registry' for live sessions)\n- Add event_state field: 'idle' | 'active' | 'closed'\n- Add recovered_at and last_event_ts timestamps\n- is_idle() should return based on snapshot state only (no JSONL access)\n\n## State Mapping\n- event state 'idle' -\u003e SessionStatus.READY\n- event state 'active' -\u003e SessionStatus.BUSY\n- event state 'closed' -\u003e new or virtual status\n\n## Files\n- src/claude_team_mcp/registry.py\n\n## Design Doc\ndocs/design/unified-worker-state.md — 'Recovered session representation' section","priority":"1","title":"RecoveredSession dataclass","type":"task"}}
+{"type":"create","timestamp":"2026-01-31T22:35:07.170878Z","issue_id":"cic-169","payload":{"description":"Add a recovery method to SessionRegistry that merges event log state into the registry without overwriting live sessions.\n\n## Signature\nrecover_from_events(snapshot: dict | None, events: list[WorkerEvent]) -\u003e RecoveryReport\n\n## Behavior\n- Input: output of get_latest_snapshot() + read_events_since(snapshot_ts)\n- If session already exists in registry, skip (don't override live state)\n- If session only in event log, create RecoveredSession entry\n- If session closed by events, mark closed in recovered state\n- Return RecoveryReport with counts (added, skipped, closed)\n\n## Integration\n- list_all() should return merged list of ManagedSession + RecoveredSession\n- list_by_status() should include recovered entries\n\n## Dependencies\n- Depends on: cic-fd1 (RecoveredSession dataclass)\n\n## Files\n- src/claude_team_mcp/registry.py\n\n## Design Doc\ndocs/design/unified-worker-state.md — 'Proposed recovery entry point' section","priority":"1","title":"SessionRegistry.recover_from_events() method","type":"task"}}
+{"type":"create","timestamp":"2026-01-31T22:35:13.527812Z","issue_id":"cic-80f","payload":{"description":"Wire recover_from_events() into server startup so list_workers returns useful data after restart.\n\n## Approach\n- Eager recovery at startup: call get_latest_snapshot() + read_events_since() and feed into registry.recover_from_events()\n- Add lazy fallback in list_workers: if registry is empty on first call, attempt recovery\n- Log recovery results (added/skipped/closed counts)\n\n## Integration Point\n- Server lifespan in src/claude_team_mcp/server.py (AppContext setup)\n\n## Dependencies\n- Depends on: cic-169 (recover_from_events method)\n\n## Files\n- src/claude_team_mcp/server.py\n\n## Design Doc\ndocs/design/unified-worker-state.md — 'Recovery timing' section","priority":"1","title":"Startup recovery — seed registry from event log on boot","type":"task"}}
+{"type":"create","timestamp":"2026-01-31T22:35:20.470243Z","issue_id":"cic-22e","payload":{"description":"New MCP tool exposing event log queries. Supersedes closed cic-467.\n\n## Tool Signature\nworker_events(\n    since: str | None = None,\n    limit: int = 1000,\n    include_snapshot: bool = False,\n    include_summary: bool = False,\n    stale_threshold_minutes: int = 10,\n    project_filter: str | None = None,\n) -\u003e dict\n\n## Response Shape\n{\n  events: [{ts, type, worker_id, data}],\n  count: N,\n  summary: {started, closed, idle, active, stuck, last_event_ts},  // if include_summary\n  snapshot: {ts, data}  // if include_snapshot\n}\n\n## Summary Semantics\n- started/closed/idle/active: lists from event window\n- stuck: active workers with last_activity \u003e stale_threshold_minutes\n- last_event_ts: newest event timestamp\n\n## Implementation\n- Wraps events.read_events_since() and events.get_latest_snapshot()\n- New file: src/claude_team_mcp/tools/worker_events.py\n- Register in src/claude_team_mcp/tools/__init__.py\n\n## Design Doc\ndocs/design/unified-worker-state.md — 'Part 2' section","priority":"1","title":"worker_events MCP tool","type":"task"}}
+{"type":"create","timestamp":"2026-01-31T22:35:26.908995Z","issue_id":"cic-71d","payload":{"description":"Extend list_workers output with provenance fields so clients can distinguish live vs recovered sessions.\n\n## New Fields in Worker Output\n- source: 'registry' | 'event_log'\n- event_state: 'idle' | 'active' | 'closed' (only for recovered entries)\n- recovered_at: ISO timestamp (only for recovered entries)\n- last_event_ts: ISO timestamp of last applied event (only for recovered entries)\n\n## Backward Compatibility\n- Existing fields (status, session_id, name, etc.) unchanged\n- New fields are additive only\n- Live sessions get source='registry', no event_state/recovered_at fields\n\n## Dependencies\n- Depends on: cic-fd1 (RecoveredSession with these fields)\n\n## Files\n- src/claude_team_mcp/tools/list_workers.py","priority":"2","title":"list_workers: add source and event_state fields","type":"task"}}
+{"type":"create","timestamp":"2026-01-31T22:35:34.422147Z","issue_id":"cic-c8e","payload":{"description":"Comprehensive tests for the unified worker state feature.\n\n## Test Cases\n\n### RecoveredSession\n- Construction from snapshot data\n- to_dict() output matches expected format\n- State mapping (idle-\u003eready, active-\u003ebusy, closed)\n- is_idle() returns snapshot-based state\n\n### recover_from_events()\n- Recovery from snapshot only (no events)\n- Recovery from snapshot + events\n- Live sessions not overwritten\n- Closed sessions marked correctly\n- Empty snapshot/events returns empty recovery\n- RecoveryReport counts are accurate\n\n### Startup recovery\n- Server startup seeds registry from event log\n- Lazy fallback triggers on empty registry\n\n### worker_events tool\n- Basic since/limit filtering\n- include_snapshot flag\n- include_summary with stuck detection\n- project_filter\n- Empty event log returns empty result\n\n## Dependencies\n- Depends on: cic-fd1, cic-169, cic-80f, cic-22e","priority":"1","title":"Tests for recovery + worker_events","type":"task"}}
+{"type":"rename","timestamp":"2026-01-31T22:35:46.410975Z","issue_id":"cic-fd1","payload":{"new_id":"cic-bbd.1"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:46.410983Z","issue_id":"cic-bbd.1","payload":{"dep_type":"parent-child","depends_on":"cic-bbd"}}
+{"type":"rename","timestamp":"2026-01-31T22:35:46.475283Z","issue_id":"cic-169","payload":{"new_id":"cic-bbd.2"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:46.47529Z","issue_id":"cic-bbd.2","payload":{"dep_type":"parent-child","depends_on":"cic-bbd"}}
+{"type":"rename","timestamp":"2026-01-31T22:35:46.547381Z","issue_id":"cic-80f","payload":{"new_id":"cic-bbd.3"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:46.547389Z","issue_id":"cic-bbd.3","payload":{"dep_type":"parent-child","depends_on":"cic-bbd"}}
+{"type":"rename","timestamp":"2026-01-31T22:35:46.776865Z","issue_id":"cic-22e","payload":{"new_id":"cic-bbd.4"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:46.776871Z","issue_id":"cic-bbd.4","payload":{"dep_type":"parent-child","depends_on":"cic-bbd"}}
+{"type":"rename","timestamp":"2026-01-31T22:35:47.05952Z","issue_id":"cic-71d","payload":{"new_id":"cic-bbd.5"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:47.059527Z","issue_id":"cic-bbd.5","payload":{"dep_type":"parent-child","depends_on":"cic-bbd"}}
+{"type":"rename","timestamp":"2026-01-31T22:35:47.216144Z","issue_id":"cic-c8e","payload":{"new_id":"cic-bbd.6"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:47.216151Z","issue_id":"cic-bbd.6","payload":{"dep_type":"parent-child","depends_on":"cic-bbd"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:52.361655Z","issue_id":"cic-bbd.2","payload":{"dep_type":"blocks","depends_on":"cic-bbd.1"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:52.436176Z","issue_id":"cic-bbd.3","payload":{"dep_type":"blocks","depends_on":"cic-bbd.2"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:52.519314Z","issue_id":"cic-bbd.5","payload":{"dep_type":"blocks","depends_on":"cic-bbd.1"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:52.717406Z","issue_id":"cic-bbd.6","payload":{"dep_type":"blocks","depends_on":"cic-bbd.1"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:52.91719Z","issue_id":"cic-bbd.6","payload":{"dep_type":"blocks","depends_on":"cic-bbd.2"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:53.301899Z","issue_id":"cic-bbd.6","payload":{"dep_type":"blocks","depends_on":"cic-bbd.3"}}
+{"type":"dep_add","timestamp":"2026-01-31T22:35:53.507305Z","issue_id":"cic-bbd.6","payload":{"dep_type":"blocks","depends_on":"cic-bbd.4"}}
+{"type":"status_update","timestamp":"2026-01-31T22:53:29.845364Z","issue_id":"cic-bbd.1","payload":{"status":"in_progress"}}
+{"type":"status_update","timestamp":"2026-01-31T22:53:31.744371Z","issue_id":"cic-bbd.4","payload":{"status":"in_progress"}}
+{"type":"close","timestamp":"2026-01-31T22:55:03.007686Z","issue_id":"cic-bbd.4","payload":{}}
+{"type":"close","timestamp":"2026-01-31T22:55:09.910056Z","issue_id":"cic-bbd.1","payload":{}}
+{"type":"status_update","timestamp":"2026-02-01T00:03:44.3476Z","issue_id":"cic-bbd.5","payload":{"status":"in_progress"}}
+{"type":"status_update","timestamp":"2026-02-01T00:03:49.271441Z","issue_id":"cic-bbd.2","payload":{"status":"in_progress"}}
+{"type":"close","timestamp":"2026-02-01T00:05:11.852731Z","issue_id":"cic-bbd.5","payload":{}}
+{"type":"close","timestamp":"2026-02-01T00:06:14.749225Z","issue_id":"cic-bbd.2","payload":{}}
+{"type":"status_update","timestamp":"2026-02-01T00:14:33.94628Z","issue_id":"cic-bbd.3","payload":{"status":"in_progress"}}
+{"type":"close","timestamp":"2026-02-01T00:16:29.352825Z","issue_id":"cic-bbd.3","payload":{}}
+{"type":"status_update","timestamp":"2026-02-01T01:37:20.777219Z","issue_id":"cic-bbd.6","payload":{"status":"in_progress"}}
+{"type":"close","timestamp":"2026-02-01T01:40:51.835629Z","issue_id":"cic-bbd.6","payload":{}}
+{"type":"create","timestamp":"2026-02-02T23:29:52.330658Z","issue_id":"cic-ebd","payload":{"description":"tmux_session_name_for_project() hashes the full project_path. Worktree paths produce unique hashes, creating one tmux session per worker instead of one per project. Fix: resolve worktree paths to main repo before hashing.","priority":"1","title":"tmux: worktree paths create separate sessions instead of sharing per-project session","type":"bug"}}
+{"type":"status_update","timestamp":"2026-02-02T23:30:32.877924Z","issue_id":"cic-ebd","payload":{"status":"in_progress"}}
+{"type":"close","timestamp":"2026-02-02T23:33:33.785116Z","issue_id":"cic-ebd","payload":{}}

{claude_team_mcp-0.7.0 → claude_team_mcp-0.8.2}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-02-02
+
+### Fixed
+- **tmux session naming**: Worktree paths no longer create separate tmux sessions per worker. Removed hash from session names — format is now `claude-team-{slug}` (e.g. `claude-team-pagedrop-infra`). All workers for the same project share one tmux session with separate windows.
+
+## [0.8.0] - 2026-01-30
+
+### Added
+- **System-wide config file** (`~/.claude-team/config.json`): Centralized configuration replacing environment variables
+  - Typed dataclasses with JSON validation
+  - Version field for future migrations
+  - Precedence: env var → config file → built-in default
+- **Config CLI**: `claude-team config init|show|get|set` commands
+- **Per-project tmux sessions**: Each project gets its own tmux session (`claude-team-<slug>-<hash>`) instead of a single shared session
+  - Easier local monitoring — `tmux ls` shows projects separately
+  - Discovery scans all tmux panes and filters by managed prefix
+
+### Fixed
+- Worktree branch/directory names capped at 30 chars to avoid filesystem limits
+- Test isolation from user config file (tests no longer affected by `~/.claude-team/config.json`)
+
+### Changed
+- Tmux `list_sessions` and discovery now scan all sessions with prefix filter instead of targeting a single session
+
 ## [0.7.0] - 2026-01-29
 
 ### Added

{claude_team_mcp-0.7.0 → claude_team_mcp-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-team-mcp
-Version: 0.7.0
+Version: 0.8.2
 Summary: MCP server for managing multiple Claude Code sessions via iTerm2
 Project-URL: Homepage, https://github.com/Martian-Engineering/claude-team
 Project-URL: Repository, https://github.com/Martian-Engineering/claude-team

claude_team_mcp-0.8.2/docs/design/unified-worker-state.md

@@ -0,0 +1,190 @@
+# Unified Worker State: list_workers recovery + worker_events API
+
+Status: Proposed
+Date: 2026-01-31
+Issue: cic-bbd
+
+## Context
+
+Today we have two sources of worker state:
+
+- `SessionRegistry` (in-memory, cleared on restart) drives `list_workers`.
+- `events.jsonl` (persistent) stores snapshots + transitions from `WorkerPoller` in
+  `src/claude_team/poller.py`, with helpers in `src/claude_team/events.py`.
+
+After restart, `list_workers` returns empty even though workers may still exist.
+External consumers resort to parsing `events.jsonl` because MCP exposes no event API.
+
+## Goals
+
+- `list_workers` should return a useful view after restart by recovering from the
+  latest persisted events.
+- Expose event log data via an MCP tool (`worker_events`) with a stable response
+  schema for consumers.
+- Keep changes additive and avoid breaking existing client expectations.
+
+## Non-Goals
+
+- Perfect real-time accuracy after restart (terminal liveness still requires
+  backend adoption).
+- Changing polling cadence or event log format.
+- Backfilling old historical events beyond what exists in `events.jsonl`.
+
+## Part 1: list_workers recovery API surface
+
+### Proposed recovery entry point
+
+Add a registry-level recovery API that merges the event log into the registry
+state without overwriting live sessions.
+
+Suggested API shape (names illustrative):
+
+- `SessionRegistry.recover_from_events(snapshot: dict | None, events: list[WorkerEvent]) -> RecoveryReport`
+  - **Input:**
+    - `snapshot`: output of `get_latest_snapshot()` (may be `None`).
+    - `events`: `read_events_since(snapshot_ts)` (may be empty).
+  - **Behavior:**
+    - If a session already exists in the registry, do not override it.
+    - If a session is only in the event log, create a lightweight recovered entry.
+    - If a session is closed by events, mark it closed in recovered state.
+  - **Output:**
+    - `RecoveryReport` with counts (added, updated, ignored) and timestamp used.
+
+### Recovered session representation
+
+Recovered entries should be distinguishable and safe for read-only usage.
+
+Proposed interface (implementation can vary):
+
+- A new lightweight `RecoveredSession` object that implements:
+  - `session_id`, `name`, `project_path`, `terminal_id`, `agent_type` (from snapshot)
+  - `status` mapped from event state (see mapping below)
+  - `last_activity` / `created_at` from snapshot when available
+  - `to_dict()` for MCP output
+  - `is_idle()` returns `None` or uses snapshot state only (never touches JSONL)
+- `SessionRegistry.list_all()` returns a merged list of:
+  - live `ManagedSession` objects, plus
+  - recovered entries not present in the registry
+
+### State mapping
+
+Event log snapshots record:
+
+- `state`: `"idle"` or `"active"` (from `detect_worker_idle`)
+- `status`: `"spawning" | "ready" | "busy"` (from `ManagedSession.to_dict()`)
+
+Recommended mapping rules:
+
+- Prefer snapshot `state` for consistency across restarts.
+- Map `state` -> `SessionStatus` for output:
+  - `idle` -> `ready`
+  - `active` -> `busy`
+  - `closed` -> (new virtual state or keep `busy` + `state="closed"`)
+
+To preserve backwards compatibility, keep the existing `status` field but add
+new fields so clients can detect recovery state explicitly:
+
+- `source`: `"registry" | "event_log"`
+- `event_state`: `"idle" | "active" | "closed"` (when recovered)
+- `recovered_at`: ISO timestamp when recovery occurred
+- `last_event_ts`: ISO timestamp of the last applied event
+
+### Recovery timing
+
+Two compatible entry points:
+
+1. **Eager (startup):** in server boot, call recovery once and seed the registry.
+2. **Lazy (first list):** in `list_workers`, if registry is empty, perform recovery
+   then return merged output.
+
+Recommendation: **eager** recovery at startup for predictable behavior, plus a
+lazy fallback in `list_workers` for safety if startup recovery fails.
+
+### Tradeoffs (list_workers recovery)
+
+- **Pros:** `list_workers` no longer empty after restart; preserves metadata and
+  session IDs for monitoring tools.
+- **Cons:** recovered entries may be stale; terminal handles are missing, so
+  control actions (send/close) still require adoption.
+- **Risk mitigation:** mark `source=event_log` and include `last_event_ts` to
+  communicate staleness to clients.
+
+## Part 2: worker_events MCP tool API surface
+
+### Proposed tool signature
+
+Tool name: `worker_events`
+
+Parameters:
+
+- `since` (string | null): ISO 8601 timestamp; returns events at or after this
+  time. If omitted, returns most recent events (bounded by `limit`).
+- `limit` (int, default 1000): maximum number of events returned.
+- `include_snapshot` (bool, default false): if true, include the latest snapshot
+  event (even if it predates `since`) in the response.
+- `include_summary` (bool, default false): include summary aggregates.
+- `stale_threshold_minutes` (int, default 10): used only when
+  `include_summary=true` to classify “stuck” workers.
+
+### Proposed response shape
+
+```
+{
+  "events": [
+    {"ts": "...", "type": "snapshot|worker_started|worker_idle|worker_active|worker_closed",
+     "worker_id": "...", "data": { ... }}
+  ],
+  "count": 123,
+  "summary": {
+    "started": ["id1", "id2"],
+    "closed": ["id3"],
+    "idle": ["id4"],
+    "active": ["id5"],
+    "stuck": ["id6"],
+    "last_event_ts": "..."
+  },
+  "snapshot": {
+    "ts": "...",
+    "data": {"count": 2, "workers": [ ... ]}
+  }
+}
+```
+
+### Summary semantics
+
+- **started/closed/idle/active** lists come from the returned event window.
+- **stuck** is derived from the latest known state (snapshot + events) where:
+  - worker is `active`, and
+  - last activity is older than `stale_threshold_minutes`.
+- **last_event_ts** is the newest event timestamp in the response.
+
+This aligns with the intent of the former `poll_worker_changes` output while
+exposing the raw events for richer client-side handling.
+
+### Tradeoffs (worker_events)
+
+- **Pros:** simple API around existing persistence; consumers can poll with a
+  timestamp cursor instead of parsing JSONL.
+- **Cons:** no stable event IDs; clients should track the last timestamp and may
+  receive duplicates if multiple events share the same timestamp.
+- **Mitigation:** include `last_event_ts` and recommend clients request
+  `since=last_event_ts` and de-duplicate by `(ts, type, worker_id)`.
+
+## Open Questions
+
+- Do we want a new explicit `SessionStatus.CLOSED` for recovered entries, or is
+  `status` plus `event_state="closed"` sufficient?
+- Should recovery include an opt-in `include_closed` flag to hide sessions that
+  have closed since the last snapshot?
+- Should `worker_events` support an optional `project_filter` (parity with
+  `list_workers`)?
+
+## Recommendation
+
+Implement recovery as an additive merge from `events.get_latest_snapshot()` plus
+`events.read_events_since(snapshot_ts)`, surfaced via a registry recovery helper
+and a new `RecoveredSession` type. Add explicit `source` and `event_state` fields
+in `list_workers` output to communicate provenance and staleness.
+
+Expose a new `worker_events` MCP tool with a minimal `since/limit` API and an
+optional summary section for consumers that want quick status deltas.

{claude_team_mcp-0.7.0 → claude_team_mcp-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-team-mcp"
-version = "0.7.0"
+version = "0.8.2"
 description = "MCP server for managing multiple Claude Code sessions via iTerm2"
 readme = "README.md"
 requires-python = ">=3.11"

{claude_team_mcp-0.7.0 → claude_team_mcp-0.8.2}/src/claude_team/events.py

@@ -4,11 +4,14 @@ from __future__ import annotations
 
 from dataclasses import asdict, dataclass
 from datetime import datetime, timedelta, timezone
+import logging
 import json
 import os
 from pathlib import Path
 from typing import Literal
 
+from claude_team_mcp.config import ConfigError, EventsConfig, load_config
+
 try:
     import fcntl
 except ImportError:  # pragma: no cover - platform-specific
@@ -19,6 +22,8 @@ try:
 except ImportError:  # pragma: no cover - platform-specific
     msvcrt = None
 
+logger = logging.getLogger("claude-team-mcp")
+
 
 EventType = Literal[
     "snapshot",
@@ -40,8 +45,20 @@ def _int_env(name: str, default: int) -> int:
         return default
 
 
-DEFAULT_ROTATION_MAX_SIZE_MB = _int_env("CLAUDE_TEAM_EVENTS_MAX_SIZE_MB", 1)
-DEFAULT_ROTATION_RECENT_HOURS = _int_env("CLAUDE_TEAM_EVENTS_RECENT_HOURS", 24)
+def _load_rotation_config() -> EventsConfig:
+    # Resolve rotation defaults from config, applying env overrides.
+    try:
+        config = load_config()
+        events_config = config.events
+    except ConfigError as exc:
+        logger.warning(
+            "Invalid config file; using default event rotation config: %s", exc
+        )
+        events_config = EventsConfig()
+    return EventsConfig(
+        max_size_mb=_int_env("CLAUDE_TEAM_EVENTS_MAX_SIZE_MB", events_config.max_size_mb),
+        recent_hours=_int_env("CLAUDE_TEAM_EVENTS_RECENT_HOURS", events_config.recent_hours),
+    )
 
 
 @dataclass
@@ -89,6 +106,7 @@ def append_events(events: list[WorkerEvent]) -> None:
     payloads = [json.dumps(_event_to_dict(event), ensure_ascii=False) for event in events]
     block = "\n".join(payloads) + "\n"
     event_ts = _latest_event_timestamp(events)
+    rotation_config = _load_rotation_config()
 
     with path.open("r+", encoding="utf-8") as handle:
         _lock_file(handle)
@@ -97,8 +115,8 @@ def append_events(events: list[WorkerEvent]) -> None:
                 handle,
                 path,
                 current_ts=event_ts,
-                max_size_mb=DEFAULT_ROTATION_MAX_SIZE_MB,
-                recent_hours=DEFAULT_ROTATION_RECENT_HOURS,
+                max_size_mb=rotation_config.max_size_mb,
+                recent_hours=rotation_config.recent_hours,
             )
             # Hold the lock across the entire write and flush cycle.
             handle.seek(0, os.SEEK_END)
@@ -169,8 +187,8 @@ def get_latest_snapshot() -> dict | None:
 
 
 def rotate_events_log(
-    max_size_mb: int = DEFAULT_ROTATION_MAX_SIZE_MB,
-    recent_hours: int = DEFAULT_ROTATION_RECENT_HOURS,
+    max_size_mb: int | None = None,
+    recent_hours: int | None = None,
     now: datetime | None = None,
 ) -> None:
     """Rotate the log daily or by size, retaining active/recent workers."""
@@ -179,6 +197,12 @@ def rotate_events_log(
         return
 
     current_ts = now or datetime.now(timezone.utc)
+    if max_size_mb is None or recent_hours is None:
+        rotation_config = _load_rotation_config()
+        if max_size_mb is None:
+            max_size_mb = rotation_config.max_size_mb
+        if recent_hours is None:
+            recent_hours = rotation_config.recent_hours
 
     with path.open("r+", encoding="utf-8") as handle:
         _lock_file(handle)

{claude_team_mcp-0.7.0 → claude_team_mcp-0.8.2}/src/claude_team_mcp/cli_backends/__init__.py

@@ -6,15 +6,17 @@ This allows claude-team to orchestrate multiple agent types through a unified in
 """
 
 from .base import AgentCLI
-from .claude import ClaudeCLI, claude_cli
-from .codex import CodexCLI, codex_cli
+from .claude import ClaudeCLI, claude_cli, get_claude_command
+from .codex import CodexCLI, codex_cli, get_codex_command
 
 __all__ = [
     "AgentCLI",
     "ClaudeCLI",
     "claude_cli",
+    "get_claude_command",
     "CodexCLI",
     "codex_cli",
+    "get_codex_command",
     "get_cli_backend",
 ]
 

{claude_team_mcp-0.7.0 → claude_team_mcp-0.8.2}/src/claude_team_mcp/cli_backends/claude.py

@@ -10,6 +10,45 @@ from typing import Literal
 
 from .base import AgentCLI
 
+# Built-in default command.
+_DEFAULT_COMMAND = "claude"
+
+# Environment variable for command override (takes highest precedence).
+_ENV_VAR = "CLAUDE_TEAM_COMMAND"
+
+
+def get_claude_command() -> str:
+    """
+    Get the Claude CLI command with precedence: env var > config > default.
+
+    Resolution order:
+    1. CLAUDE_TEAM_COMMAND environment variable (for override)
+    2. Config file commands.claude setting
+    3. Built-in default "claude"
+
+    Returns:
+        The command to use for Claude CLI
+    """
+    # Environment variable takes highest precedence (for override).
+    env_val = os.environ.get(_ENV_VAR)
+    if env_val:
+        return env_val
+
+    # Try config file next.
+    # Import here to avoid circular imports and lazy-load config.
+    try:
+        from ..config import ConfigError, load_config
+
+        config = load_config()
+    except ConfigError:
+        return _DEFAULT_COMMAND
+
+    if config.commands.claude:
+        return config.commands.claude
+
+    # Fall back to built-in default.
+    return _DEFAULT_COMMAND
+
 
 class ClaudeCLI(AgentCLI):
     """
@@ -31,10 +70,12 @@ class ClaudeCLI(AgentCLI):
         """
         Return the Claude CLI command.
 
-        Respects CLAUDE_TEAM_COMMAND environment variable for overrides
-        (e.g., "happy" wrapper).
+        Resolution order:
+        1. CLAUDE_TEAM_COMMAND environment variable (for override)
+        2. Config file commands.claude setting
+        3. Built-in default "claude"
         """
-        return os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+        return get_claude_command()
 
     def build_args(
         self,
@@ -102,8 +143,7 @@ class ClaudeCLI(AgentCLI):
 
     def _is_default_command(self) -> bool:
         """Check if using the default 'claude' command (not a custom wrapper)."""
-        cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
-        return cmd == "claude"
+        return get_claude_command() == _DEFAULT_COMMAND
 
 
 # Singleton instance for convenience

{claude_team_mcp-0.7.0 → claude_team_mcp-0.8.2}/src/claude_team_mcp/cli_backends/codex.py

@@ -12,6 +12,45 @@ from typing import Literal
 
 from .base import AgentCLI
 
+# Built-in default command.
+_DEFAULT_COMMAND = "codex"
+
+# Environment variable for command override (takes highest precedence).
+_ENV_VAR = "CLAUDE_TEAM_CODEX_COMMAND"
+
+
+def get_codex_command() -> str:
+    """
+    Get the Codex CLI command with precedence: env var > config > default.
+
+    Resolution order:
+    1. CLAUDE_TEAM_CODEX_COMMAND environment variable (for override)
+    2. Config file commands.codex setting
+    3. Built-in default "codex"
+
+    Returns:
+        The command to use for Codex CLI
+    """
+    # Environment variable takes highest precedence (for override).
+    env_val = os.environ.get(_ENV_VAR)
+    if env_val:
+        return env_val
+
+    # Try config file next.
+    # Import here to avoid circular imports and lazy-load config.
+    try:
+        from ..config import ConfigError, load_config
+
+        config = load_config()
+    except ConfigError:
+        return _DEFAULT_COMMAND
+
+    if config.commands.codex:
+        return config.commands.codex
+
+    # Fall back to built-in default.
+    return _DEFAULT_COMMAND
+
 
 class CodexCLI(AgentCLI):
     """
@@ -35,10 +74,12 @@ class CodexCLI(AgentCLI):
         """
         Return the Codex CLI command.
 
-        Respects CLAUDE_TEAM_CODEX_COMMAND environment variable for overrides
-        (e.g., "happy codex" wrapper).
+        Resolution order:
+        1. CLAUDE_TEAM_CODEX_COMMAND environment variable (for override)
+        2. Config file commands.codex setting
+        3. Built-in default "codex"
         """
-        return os.environ.get("CLAUDE_TEAM_CODEX_COMMAND", "codex")
+        return get_codex_command()
 
     def build_args(
         self,