@jstn-sdk/rcs 0.1.0

package/docs/contracts/multi-state-transition-contract.md

@@ -0,0 +1,115 @@
+# Multi-state transition compatibility contract
+
+This document freezes the first-pass peer workflow state model for the approved
+multi-state compatibility rollout from `.rcs/plans/prd-multi-state-compat.md`.
+
+## Canonical sources of truth
+
+The runtime must treat workflow state as a combination of:
+
+- mode state files under `.rcs/state/{scope}/<mode>-state.json`
+- canonical workflow enumeration under `.rcs/state/{scope}/skill-active-state.json`
+
+`skill-active-state.json` is the canonical active-set inventory. Legacy top-level
+fields such as `skill` or `phase` may remain as compatibility metadata, but they
+must not override the authoritative active set when multiple workflow members
+are live.
+
+## Approved first-pass combinations
+
+Allowed active-set shapes in this rollout are intentionally narrow:
+
+- standalone single-workflow state for tracked workflows
+- `team + ralph`
+- `team + ultrawork`
+
+The resulting active set is peer state. Neither member is semantically primary
+just because it was activated first or happens to occupy the legacy top-level
+`skill` field.
+
+## Standalone-only workflows
+
+These workflows remain standalone in this pass and must reject overlap attempts:
+
+- `autopilot`
+- `autoresearch`
+
+A denied overlap must preserve the current state unchanged.
+
+## Transition rules
+
+A canonical transition helper should answer three questions for every writer or
+consumer that mutates workflow state:
+
+1. Is the requested transition allowed from the current active set?
+2. What is the resulting active set if it is allowed?
+3. What operator guidance should be shown if it is denied?
+
+Until a combination is explicitly approved, the default rule is deny-without-
+mutation.
+
+## Invalid transition UX
+
+Every denied transition must:
+
+1. keep the current active state unchanged
+2. name the denied combination explicitly
+3. explain how to clear incompatible state before retrying
+4. mention both supported clearing surfaces:
+   - `rcs state ...`
+   - `rcs_state.*` MCP tools
+
+Example operator guidance shape:
+
+> Cannot activate `<requested>` while `<active-set>` is still active. Clear the
+> incompatible state first via `rcs state ...` or the `rcs_state.*` MCP tools,
+> then retry the transition.
+
+### Operator recovery examples
+
+CLI parity surface:
+
+- `rcs state clear --input '{"mode":"team"}' --json`
+- `rcs state clear --input '{"mode":"ralph","all_sessions":true}' --json`
+
+MCP parity surface:
+
+- `rcs_state.state_clear({ mode: "team" })`
+- `rcs_state.state_clear({ mode: "ralph", all_sessions: true })`
+
+## Brownfield consumer expectations
+
+The following surfaces must consume the same transition semantics instead of
+re-inventing their own precedence rules:
+
+- `src/state/skill-active.ts` — canonical active-set persistence/sync
+- `src/hooks/keyword-detector.ts` — keyword-triggered activation should add or
+  deny according to the allowlist instead of overwriting to a single owner
+- `src/modes/base.ts` — mode start validation must defer to the same transition
+  rules and emit the same operator guidance
+- `src/mcp/state-server.ts` — state writes/clears must preserve combined state
+  correctly and remove only the cleared member
+- `src/hud/state.ts` — HUD rendering must show approved combined states even
+  when legacy top-level metadata is non-authoritative
+- `src/hooks/agents-overlay.ts` — AGENTS overlay active-mode reporting must list
+  every active approved member
+- `src/scripts/codex-native-hook.ts` — Stop/continuation logic must respect the
+  combined state and stop blocking when the relevant member is cleared
+
+## Scope behavior
+
+Session-scoped state remains authoritative when present. Root scope remains a
+compatibility fallback only. Clearing one member of an approved combined set
+must not accidentally delete the entire combined state.
+
+## Regression expectations
+
+Implementation should be considered complete only when tests prove:
+
+1. canonical active state can hold a multi-entry active set
+2. `team + ralph` is allowed in both activation orders
+3. `team + ultrawork` is allowed in both activation orders
+4. unsupported overlaps deny without mutation
+5. denial messages mention both `rcs state` and `rcs_state.*`
+6. HUD / overlay / stop-hook consumers honor the combined set consistently
+7. `autopilot` and `autoresearch` still reject unsupported overlap attempts; `autopilot -> ralplan` is the only review-driven planning loopback exception

package/docs/contracts/multi-state-transition-review.md

@@ -0,0 +1,134 @@
+# Multi-state transition compatibility review notes
+
+Date: 2026-04-09  
+Reviewer lane: worker-3
+
+## Scope reviewed
+
+Compared the branch state against:
+
+- `.rcs/plans/prd-multi-state-compat.md`
+- `.rcs/plans/test-spec-multi-state-compat.md`
+
+Reviewed brownfield surfaces:
+
+- `src/state/skill-active.ts`
+- `src/hooks/keyword-detector.ts`
+- `src/modes/base.ts`
+- `src/mcp/state-server.ts`
+- `src/hud/state.ts`
+- `src/hooks/agents-overlay.ts`
+- `src/scripts/codex-native-hook.ts`
+
+## Current branch snapshot
+
+**Status:** the repository already contains partial multi-state foundations, but
+it does not yet expose one documented canonical transition contract.
+
+Observed strengths:
+
+- `src/state/skill-active.ts` already persists `active_skills[]`, normalizes
+  visible entries, and can sync more than one tracked workflow into the
+  canonical state file.
+- `src/hud/state.ts` and `src/hooks/agents-overlay.ts` already read canonical
+  skill-active state and are structurally closer to a peer-state model than a
+  strict single-owner model.
+- `src/modes/base.ts` already preserves key standalone restrictions:
+  `autopilot` and `autoresearch` remain exclusive; `ralph` and `ultrawork`
+  remain mutually exclusive with each other.
+
+Primary gaps relative to the PRD/test-spec:
+
+1. **No explicit transition-rule helper exists yet.**
+   - Transition semantics are still distributed across mode lifecycle,
+     keyword detection, MCP writes, HUD/overlay readers, and native-stop logic.
+2. **Keyword activation is still effectively single-owner.**
+   - `recordSkillActivation()` uses `detectPrimaryKeyword()` and writes a fresh
+     one-entry `active_skills` array for the selected skill, so prompt-side
+     activation still overwrites rather than validating/appending approved peer
+     combinations.
+3. **Invalid-transition guidance is not standardized.**
+   - `src/modes/base.ts` still throws `Run cancel first.` for exclusivity
+     failures, which does not meet the new requirement to mention explicit
+     clearing paths via `rcs state` and `rcs_state.*`.
+4. **The contract is not documented in one operator-facing place.**
+   - The PRD and test spec define the rollout, but the repo lacked a dedicated
+     contract doc describing the allowed set, the denied set, and the required
+     recovery UX.
+
+## Brownfield review details
+
+### `src/state/skill-active.ts`
+
+- Good base for canonical peer state: it already deduplicates `active_skills[]`
+  and can retain multiple active entries.
+- Still needs a shared allowlist-aware transition layer above persistence so the
+  state file cannot drift into unsupported combinations.
+
+### `src/hooks/keyword-detector.ts`
+
+- Main brownfield risk for this feature.
+- The prompt-side path currently records only the primary detected keyword and
+  seeds one active skill at a time.
+- This is the clearest remaining single-owner assumption in the review sample.
+
+### `src/modes/base.ts`
+
+- Current exclusivity rules are partly aligned with the rollout goals, because
+  `team` is not exclusive while `autopilot`/`autoresearch` are.
+- However, the rules are encoded as a hard-coded exclusive set and generic error
+  text, not as a canonical transition model with machine-testable guidance.
+
+### `src/mcp/state-server.ts`
+
+- Already syncs canonical skill-active state for mode writes/clears.
+- Needs to consume the same allowlist/error builder as every other writer so
+  MCP state writes cannot permit combinations the keyword or mode path denies.
+
+### `src/hud/state.ts` and `src/hooks/agents-overlay.ts`
+
+- These consumers already appear structurally ready for a combined active set.
+- They still depend on upstream writers to keep the canonical state valid and to
+  stop relying on top-level legacy fields as semantic truth.
+
+### `src/scripts/codex-native-hook.ts`
+
+- Stop handling already reads canonical skill-active state plus mode files.
+- It still needs the finalized transition contract so combined-state blocking and
+  clearing behavior stay aligned with the eventual allowlist.
+
+## Documentation action taken in this lane
+
+Added a dedicated contract doc:
+
+- `docs/contracts/multi-state-transition-contract.md`
+
+This freezes the rollout expectations for:
+
+- approved first-pass overlaps
+- standalone-only workflows
+- denial UX requirements
+- brownfield consumer responsibilities
+- regression expectations
+
+Also clarified two adjacent operator-facing docs so the approved overlap is not
+misread as the old linked `team ralph` lifecycle:
+
+- `docs/contracts/ralph-state-contract.md`
+- `docs/codex-native-hooks.md`
+
+Added concrete recovery examples to the compatibility contract so denial
+messages can point operators at exact parity surfaces instead of vague
+placeholders:
+
+- `rcs state clear --input '{"mode":"team"}' --json`
+- `rcs_state.state_clear({ mode: "team" })`
+
+## Reviewer conclusion
+
+The branch already has meaningful peer-state groundwork, but the PRD is correct
+that behavior is still fragmented. The main implementation risk is not raw state
+storage; it is inconsistent transition ownership across keyword activation, mode
+start validation, MCP writes, and stop/overlay consumers. The new contract doc
+should give the implementation lanes a stable operator-facing target while the
+code is migrated to a single allowlist-driven transition model.

package/docs/contracts/mux-operation-space.md

@@ -0,0 +1,49 @@
+# RCS ↔ mux canonical operation space
+
+This document defines the mux boundary owned by RCS core semantics.
+
+## Canonical operations
+
+| Operation | Purpose |
+|---|---|
+| `resolve-target` | Convert a logical delivery target into an adapter-specific endpoint. |
+| `send-input` | Forward literal input to a resolved target. |
+| `capture-tail` | Read a bounded tail of adapter output. |
+| `inspect-liveness` | Check whether a target is still alive. |
+| `attach` | Attach the operator to a live target. |
+| `detach` | Detach the operator from a live target. |
+
+## Target kinds
+- `delivery-handle`
+- `detached`
+
+## Transport primitives
+- `SubmitPolicy` controls how many isolated `C-m` submissions the adapter emits.
+- `InputEnvelope` holds literal text plus newline-normalization rules.
+- `InjectionPreflight` captures readiness checks before delivery.
+- `PaneReadinessReason` explains why a target is or is not injectable.
+- `DeliveryConfirmation` records whether a send was confirmed, active-task confirmed, or left unconfirmed.
+- `ConfirmationPolicy` defines the retry/verification window used by the adapter.
+
+## Rules
+- The semantic contract must not depend on tmux-native nouns.
+- Tmux is the first adapter, not the model.
+- Adapter results may include tmux identifiers for debugging, but those identifiers are not semantic truth.
+- Retry, confirmation, and delivery decisions belong to the runtime contract, not the adapter implementation.
+
+## TmuxAdapter implementation
+
+`TmuxAdapter` is fully implemented in `crates/rcs-mux/src/tmux.rs`. All six canonical operations are supported. All `MuxOperation`, `MuxOutcome`, `MuxTarget`, and related types derive `Serialize`/`Deserialize`.
+
+Exact tmux CLI invocations per operation:
+
+| Operation | tmux command |
+|---|---|
+| `ResolveTarget` | `tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index}'` — verifies the handle appears in the pane list |
+| `SendInput` | `tmux send-keys -t <target> -l '<text>'` (literal text), then one `tmux send-keys -t <target> C-m` per press defined by `SubmitPolicy::Enter { presses, delay_ms }` |
+| `CaptureTail` | `tmux capture-pane -t <target> -p -S -<lines>` |
+| `InspectLiveness` | `tmux has-session -t <session>` (session name extracted from the handle, e.g. `"mysess:0.1"` → `"mysess"`) |
+| `Attach` | `tmux attach-session -t <target>` |
+| `Detach` | `tmux detach-client -t <target>` |
+
+Target handles use the format `session_name:window_index.pane_index` (e.g. `"rcs:0.1"`). `MuxTarget::Detached` is rejected for all operations that require a real pane.

package/docs/contracts/ralph-cancel-contract.md

@@ -0,0 +1,23 @@
+# Ralph Cancellation Contract (Normative)
+
+This contract defines required post-conditions for Ralph cancellation when
+Ralph was started directly or as a standalone follow-up after other workflows.
+
+## Required post-conditions
+
+After cancelling Ralph, implementations MUST ensure:
+
+1. Targeted Ralph state is terminal and non-active:
+   - `active=false`
+   - `current_phase='cancelled'`
+   - `completed_at` is set (ISO8601)
+2. Linked mode behavior:
+   - If Ralph is linked to Ultrawork/Ecomode in the same scope, that linked mode MUST also be terminal/non-active.
+   - Unrelated unlinked modes in the same scope SHOULD remain unchanged.
+3. Cross-session safety:
+   - Cancellation MUST NOT mutate mode state in unrelated sessions.
+
+## Implementation alignment points
+
+- `src/cli/index.ts` (`cancelModes`) enforces scoped cancellation and linked cleanup ordering.
+- `skills/cancel/SKILL.md` documents scope-aware cancellation behavior and compatibility fallback policy.

package/docs/contracts/ralph-state-contract.md

@@ -0,0 +1,95 @@
+# Ralph State Contract (Frozen)
+
+## Canonical Ralph state schema
+
+Ralph runtime state is stored at `.rcs/state/{scope}/ralph-state.json` and MUST use this schema:
+
+- `active: boolean` **(required)**
+- `iteration: number` **(required while active)**
+- `max_iterations: number` **(required while active)**
+- `current_phase: string` **(required while active)**
+- `started_at: ISO8601 string` **(required while active)**
+- `completed_at?: ISO8601 string`
+- Optional linkage fields: `linked_ultrawork`, `linked_ecomode`, `linked_mode`
+- Optional ownership fields:
+  - `owner_rcs_session_id`
+  - `owner_codex_session_id`
+  - `owner_codex_thread_id` (legacy compatibility only)
+- Optional tmux anchor fields:
+  - `tmux_pane_id`
+  - `tmux_pane_set_at`
+- Optional stop/audit fields:
+  - `stop_reason`
+
+Ralph still owns its own mode state and there is no built-in
+`rcs team ralph ...` linked launch path anymore. Under the multi-state
+transition compatibility contract, `team + ralph` is an approved peer overlap,
+so Ralph may coexist with team when the canonical allowlist permits it. Other
+overlaps remain deny-by-default until they are explicitly approved. See
+`docs/contracts/multi-state-transition-contract.md`.
+
+Legacy phase aliases may be normalized for compatibility, but persisted values MUST end in the frozen enum below.
+
+## Frozen Ralph phase vocabulary
+
+`current_phase` for Ralph MUST be one of:
+
+- `starting`
+- `executing`
+- `verifying`
+- `fixing`
+- `complete`
+- `failed`
+- `cancelled`
+
+Unknown phase values MUST be rejected.
+
+Phase progression reference (illustrative):
+starting
+- `executing`
+- `verifying`
+- `fixing`
+- `complete`
+
+## Frozen scope policy
+
+1. If `session_id` is present (explicit argument or current `.rcs/state/session.json`), session scope (`.rcs/state/sessions/{session_id}/...`) is authoritative.
+2. Root scope (`.rcs/state/*.json`) is compatibility fallback only.
+3. Writes MUST target one scope (authoritative scope), never broadcast to unrelated sessions.
+4. If the current authoritative session already owns an active Ralph state, notify-hook MAY backfill missing owner metadata and refresh its tmux anchor fields in place.
+5. Same-Codex-session continuation MAY migrate a single active Ralph from one session scope into the current authoritative session scope when:
+   - the source Ralph is still active and non-terminal,
+   - `owner_codex_session_id` matches the live Codex payload `session_id`, or reconciliation consults legacy `owner_codex_thread_id` only when that session-id field is absent on the source Ralph,
+   - the current authoritative session does not already have `ralph-state.json` in that scope,
+   - reconciliation is driven by persisted Ralph ownership/state files, not by prompt-keyword parsing.
+6. If the current authoritative session already has `ralph-state.json`, notify-hook MUST NOT auto-revive it, replace it, or migrate another session's Ralph over it just because the current file is inactive/terminal. Explicit user-driven Ralph starts continue to write current scope through the normal mode/state-write path.
+7. Migration MUST preserve single-owner semantics:
+   - notify-hook reconciliation MUST serialize transfer decisions per state root before it writes session-scoped Ralph files,
+   - the destination session becomes authoritative,
+   - the source session is immediately deactivated with audit fields describing the transfer, and if deactivation fails after the destination write, the destination write MUST be rolled back,
+   - unrelated sessions MUST remain untouched.
+8. This scope reconciliation MUST run inside `scripts/notify-hook.js` before lifecycle counters, active-scope iteration updates, or tmux prompt injection read the active Ralph scope.
+9. `owner_codex_thread_id` is a legacy compatibility input. A current authoritative Ralph MAY temporarily retain it until a notify payload provides `session_id`; refreshed/current authoritative Ralph state canonicalizes to `owner_codex_session_id` once that session owner is available.
+
+## Consumer compatibility matrix
+
+| Consumer | Responsibility under frozen scope/phase contract |
+|---|---|
+| `src/hud/state.ts` | Read session scope first when current session is known; fall back to root only when scoped file is absent. |
+| `src/mcp/trace-server.ts` | Build mode timeline from authoritative scope paths resolved via state-path helpers. |
+| `scripts/notify-hook.js` | Update lifecycle counters only in the authoritative session scope (or root fallback), never all sessions. |
+| `scripts/notify-hook.js` | During notify-hook reconciliation, an active current-session Ralph may be normalized in place; otherwise a same-Codex-session continuation may migrate a single active Ralph only into an otherwise empty current authoritative session scope before later lifecycle/update/injection steps consume Ralph state. Existing current-scope Ralph files, even inactive ones, are not auto-replaced. Reconciliation stays keyed to persisted state ownership, not prompt-keyword parsing. |
+| `src/hooks/agents-overlay.ts` | Summarize active modes from scope-preferred mode files (session overrides root). |
+| `src/cli/index.ts` (`status`/`cancel`) | Status and cancellation operate on scope-preferred mode files; cancellation does not mutate unrelated sessions. |
+
+## Canonical PRD/progress sources
+
+- Canonical PRD: `.rcs/plans/prd-{slug}.md`
+- Startup validation source during the legacy-compatibility window: `.rcs/prd.json`
+- Canonical progress ledger: `.rcs/state/{scope}/ralph-progress.json`
+- Legacy compatibility migration:
+  - `.rcs/prd.json` migrates one-way to canonical PRD markdown when no canonical PRD exists.
+  - `.rcs/progress.txt` migrates one-way to canonical `ralph-progress.json` when no canonical ledger exists.
+  - Legacy files remain read-only compatibility artifacts for one release cycle.
+- Canonical PRD markdown is storage/documentation-canonical today; Ralph `--prd` startup still validates machine-readable story approval state from `.rcs/prd.json` until a structured replacement exists.
+- Prompt-side `$ralph` workflow activation is not equivalent to `rcs ralph --prd ...`; it may seed Ralph mode state and routing context, but the PRD startup gate remains an explicit CLI-path contract.

package/docs/contracts/repo-aware-team-dag-decomposition.md

@@ -0,0 +1,98 @@
+# Repo-aware Team DAG decomposition contract
+
+This contract documents the repo-aware Team decomposition gate planned by `.rcs/plans/prd-repo-aware-team-decomposition.md`. It is intentionally a pre-runtime contract: Team may import or derive richer planning metadata before launch, but worker execution must continue to use the existing claim-safe task lifecycle.
+
+## Contract boundary
+
+- `rcs team` may preflight the latest approved PRD/test-spec pair and a matching DAG handoff artifact before `startTeam()` launches workers only when the invocation is approved for that pair: either the CLI input matches the PRD's approved Team launch hint, or the user uses a short approved follow-up such as `rcs team team` that resolves to that hint. Normal `rcs team [N[:role]] "task"` startup must not consume ambient/stale `team-dag-*.json` files.
+- The preflight output may change the startup task list, worker count, owner assignment, inbox text, and observability metadata.
+- Runtime task mutation remains owned by the Team state APIs. Preflight must not bypass `assignTask()`, `claimTask()`, `transitionTaskStatus()`, or `update-task` lifecycle constraints.
+- Existing `rcs team [N[:role]] "task"` behavior remains the fallback when no valid approved DAG handoff exists.
+
+## Artifact resolution
+
+1. Select the latest PRD using the same slug semantics as `selectLatestPlanningArtifacts()`, then require at least one matching `test-spec-<slug>.md`/`testspec-<slug>.md`; a PRD without its matching test spec is not an approved pair for DAG activation.
+2. Prefer `.rcs/plans/team-dag-<slug>.json` over embedded markdown handoff JSON after the approved invocation gate passes.
+3. If multiple matching JSON candidates are possible, choose the lexicographically latest path and record a `multiple_matches` warning in preflight metadata.
+4. If the sidecar exists but is invalid, fall back to legacy text decomposition in v1 and persist the fallback reason. Do not silently ignore the invalid artifact.
+5. If no valid sidecar exists, parse an optional fenced `Team DAG Handoff` block from the selected PRD.
+6. If no valid handoff is found, set `decomposition_source=legacy_text` and use the existing `buildTeamExecutionPlan()` path.
+
+## DAG node requirements
+
+Each imported node should validate to a bounded data shape:
+
+- stable symbolic `id`
+- `subject` and `description`
+- optional `role`
+- optional `lane`
+- optional `filePaths` and `domains`
+- optional symbolic `depends_on`
+- optional `requires_code_change`
+- optional acceptance or verification notes
+
+Validation must reject duplicate node IDs and cyclic dependencies before worker launch. Input order is the tie-breaker for topological sorting so generated task IDs are stable across runs.
+
+## Runtime dependency remap
+
+DAG dependencies are symbolic at plan time, but Team runtime readiness is based on concrete task IDs. The startup sequence must therefore be:
+
+1. Validate and topologically sort DAG nodes.
+2. Create Team tasks in stable order without symbolic dependency fields.
+3. Build `node_id -> task_id` from created tasks.
+4. Patch dependency fields through the supported state helper/API path so `depends_on`/`blocked_by` contains concrete task IDs only.
+5. Persist the mapping in `decomposition-report.json` for inspection and debugging.
+6. Generate worker inboxes after remapping so dependency summaries show real task IDs.
+
+Do not persist symbolic IDs into runtime task dependencies; `claimTask()` cannot prove readiness from plan-only IDs.
+
+## Persistence and observability
+
+Preflight should keep rich planning data out of the claim lifecycle task payload unless the task schema explicitly supports the field.
+
+| Data | Expected storage |
+| --- | --- |
+| `decomposition_source`, `dag_artifact_path`, `fallback_reason`, `worker_count_requested`, `worker_count_effective`, `worker_count_source`, `ready_lane_count` | team manifest/config metadata, via the top-level `team_decomposition` manifest block |
+| node-to-task mapping, allocation reasons, file/domain/lane hints, warnings | `.rcs/state/team/<team>/decomposition-report.json` and optional markdown summary |
+| runtime dependencies | `TeamTask.depends_on` / `blocked_by` with concrete task IDs |
+| `requires_code_change` | thread into `TeamTask` only through supported schema/API fields; otherwise reject or drop with an explicit validation warning |
+| worker-facing ownership hints | initial inbox text for the assigned worker |
+
+## Worker count policy
+
+- CLI-explicit counts are user overrides and should be honored up to hard safety caps. If the count exceeds useful ready lanes, keep the count but record surplus support/idle capacity.
+- Plan-suggested counts may be reduced to useful lanes when the DAG shows less parallel work than requested.
+- Default-derived counts may be reduced to useful lanes.
+- Reserve a verification lane only when there is code-changing implementation work to verify and the verification lane is not fully dependency-blocked.
+- Never exceed `DEFAULT_MAX_WORKERS`.
+
+## Allocation and role coherence
+
+Allocation should prefer:
+
+1. dependency-ready root lanes first;
+2. same owner for implementation nodes touching the same file/domain;
+3. specialist roles (`test-engineer`, `writer`, `security-reviewer`) kept coherent when there is enough lane capacity;
+4. generic fallback only when mixed-role assignment is unavoidable, with `worker_runtime_role_reason=mixed_roles_fallback` recorded.
+
+Allocation reasons should be short and stable enough for tests, startup summaries, and worker inboxes.
+
+## Worker inbox UX
+
+The initial inbox should include preflight data that materially affects worker behavior:
+
+- assigned file paths and domains;
+- lane label;
+- dependency summary with concrete task IDs;
+- allocation reason;
+- exact assigned task IDs after symbolic remap.
+
+This makes ownership constraints visible where workers actually operate instead of hiding them only in manifest metadata.
+
+## Review risks to guard in implementation
+
+- Do not put a large opaque DAG heuristic block directly into `src/cli/team.ts`; keep a small preflight module seam.
+- Do not widen `TeamTask` with rich metadata unless state readers, API interop, and monitor snapshots are updated together.
+- Do not treat RALPLAN-suggested worker counts as CLI-explicit overrides.
+- Do not bypass claim-safety by directly writing in-progress/completed task state during preflight.
+- Do not launch workers before symbolic dependencies are remapped to concrete Team task IDs.

package/docs/contracts/runtime-authority-backlog-replay-readiness.md

@@ -0,0 +1,40 @@
+# Runtime authority, backlog, replay, and readiness semantics
+
+This document captures the Rust-owned runtime semantics that replace JS-side truth.
+
+## Authority
+- The runtime has one active authority lease at most.
+- A lease has:
+  - `owner`
+  - `lease_id`
+  - `leased_until`
+- A stale or expired lease must be marked stale before another owner is granted authority.
+- `AuthorityLease` (in `crates/rcs-runtime-core/src/authority.rs`) implements the state machine with three transitions:
+  - `acquire(owner, lease_id, leased_until)` — succeeds if no lease is held or the requesting owner already holds it; fails with `AlreadyHeldByOther` otherwise.
+  - `renew(owner, lease_id, leased_until)` — succeeds only if the same owner currently holds the lease; fails with `NotHeld` or `OwnerMismatch`.
+  - `force_release()` — unconditionally clears all lease fields including stale state.
+
+## Backlog
+- New work enters the backlog as `pending`.
+- Notification moves work from `pending` to `notified`.
+- Completion moves work from `notified` to either `delivered` or `failed`.
+- `pending`, `notified`, `delivered`, and `failed` are counts in the runtime snapshot.
+- `DispatchLog` (in `crates/rcs-runtime-core/src/dispatch.rs`) tracks individual `DispatchRecord` entries, each carrying `request_id`, `target`, `status`, and timestamps (`created_at`, `notified_at`, `delivered_at`, `failed_at`). Status transitions are enforced — invalid transitions (e.g. `pending -> delivered`) return `DispatchError::InvalidTransition`.
+
+## Replay / recovery
+- Replay is cursor-based and durable.
+- Replayed items must be deduplicated.
+- Deferred leader notification is tracked explicitly so observers can tell why delivery has not been surfaced yet.
+- `ReplayState` (in `crates/rcs-runtime-core/src/replay.rs`) tracks the current `cursor`, deduplicates by `event_id` via an internal `HashSet`, and records whether leader notification was intentionally deferred via `defer_leader_notification()` / `clear_deferred()`.
+
+## Readiness
+- Readiness is a Rust-authored snapshot, not an inferred CLI opinion.
+- The runtime is not ready when the lease is missing, stale, or otherwise invalid.
+- The snapshot should include the exact blockers so operators can see why recovery is paused.
+- `derive_readiness()` (in `crates/rcs-runtime-core/src/engine.rs`) computes `ReadinessSnapshot` from the current `AuthorityLease`, `DispatchLog`, and `ReplayState`. It returns `ReadinessSnapshot::ready()` only when the authority lease is held and not stale, and there are no pending replay events. All blocking reasons are collected into `readiness.reasons`.
+
+## Dispatch classification
+- `WorkerCli` selects the submit policy (`Claude` => 1 press, `Codex`/other => 2 presses).
+- `DispatchOutcomeReason` and `QueueTransition` classify send success, retry, pending, and failure outcomes.
+- Deferred leader-missing cases stay pending so the runtime can retry when a pane becomes available.
+- Unconfirmed sends can stay pending while retries remain; otherwise they fail with an unconfirmed reason.