orca/ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md

Orca Orchestration Implementation Checklist

This is the durable implementation ledger for the orchestration primitives proposal. Update it in the same change that implements, removes, or materially revises an item. The design source is docs/orchestration-primitives.html; keep it synchronized with this checklist.

How to use this file

• Check an item only after its implementation and proportionate tests are complete.
• If an item changes meaning, edit the checklist and add a dated decision-log entry explaining why.
• After every implementation session, append a progress-log entry with files, tests, findings, and the next concrete step.
• Do not mark a phase complete while any acceptance test in that phase remains open.
• Preserve the non-goals. A new subsystem requires separate evidence and a separate proposal.

Status meanings:

• [ ] not started or not proven
• [x] implemented and verified
• DEFERRED deliberately outside the current implementation sequence

Current summary

• Fresh primitive-oriented design written and repeatedly reviewed.
• Product UI changes explicitly excluded.
• Current orchestration skill now teaches setup-run for new worktrees, batch processing, agentTerminalHandle preference, and the custom-argv setup-policy limitation.
• Phase 0 command/skill compatibility work complete.
• Phase 1 local Run, mailbox, lifecycle, and idempotency primitives complete.
• Phase 2 same-server composed worker lifecycle complete.
• Phase 3 connected-server federation complete.
• Revalidate Phase 3 after the 2026-07-24 post-rebase dogfood exposed a renderer-adoption process-identity regression.
• Phase 4 structured worker output is implemented with passing automated coverage and physical local, mixed-version, restart, disconnect, and Windows-home to Mac-worker evidence; optional symmetric acceptance checks remain tracked below.
• Hard-cutover migration fence implemented and locally verified; branch-head CI remains the final remote check.

Scope invariants

• Agents choose decomposition, topology, placement, parallelism, and recovery strategy.
• Low-level worktree, terminal, setup, and handoff commands remain independently usable.
• Every composed mutation with external effects returns explicit effects and an honest outcome; control-plane-only mutations return their exact resource receipt.
• Worker assertions remain labeled as worker reports, not Orca-verified correctness.
• Silence alone never proves worker death or triggers replacement.
• Multi-server Runs use one authoritative Run home and connected worker servers.
• Runtime/server/host identity mechanics remain hidden from ordinary agent commands.

Explicit non-goals:

• No product dashboard, Run UI, badges, or coordinator chat UI.
• No scheduler, automatic placement, capacity allocator, fairness, or priority aging.
• No automatic retry or replacement based on silence.
• No commit, branch, merge, integration, or target-ref tracking.
• No filesystem read-only/writer enforcement.
• No generalized ACL, organization, role, or worker-profile system.
• No replicated Run database, leader election, or automatic Run-home failover.
• No dead-letter/poison-message workflow.
• No universal provider-session or transcript framework.

Phase 0 — Vocabulary and current-agent ergonomics

Command compatibility

• Remove or rename the existing scheduler-like orca orchestration run --spec before shipping lightweight run-* commands.
• Publish the canonical command map in CLI help.
• Define aliases or explicit deprecations for any renamed current command.
• Keep current flat task commands unless a separately justified CLI migration changes them.
• Require explicit destructive reset scope; bare reset must not imply reset-all.

Skill and recipes

• Teach that check --wait returns a message batch, not one message.
• Teach processing every returned message and waiting until expected Dispatches settle.
• Document crash-safe explicit acknowledgment and redelivery of an unacknowledged batch.
• Prefer agentTerminalHandle, then legacy startupTerminal.handle, then exact terminal-list resolution.
• Pass --setup run for new worktrees by default.
• State a concrete reason before using --setup skip or --setup inherit.
• Preserve start-immediately as the normal setup/agent startup policy.
• Warn that the two-step custom-argv launch cannot preserve explicit wait-for-setup.
• Add executable current-version recipes for local fan-out, new worktrees, completion/failure, questions, timeout recovery, and restart limitations.
• Ensure installed, bundled, repository, and generated orchestration skill copies stay in sync.

Phase 0 acceptance

• An agent reading only CLI help and the skill can select current versus new worktree correctly.
• The agent starts all independent workers before blocking.
• The agent cannot mistake the old scheduler Run for a lightweight namespace Run.
• Recipes contain only commands supported by the matching shipped CLI version.

Phase 1 — Run, mailbox, lifecycle, and durable mutation receipts

Lightweight Run

• Add a Run table with stable Run ID, objective, created/updated timestamps, and home database.
• Add mandatory Run association to new Tasks, Dispatches, Messages, deliveries, and questions.
• Migrate pre-Run orchestration rows into one unbound, inspect-only legacy Run.
• Keep old scheduler-run storage distinct from lightweight Runs.
• Implement run-create, run-use, run-current, run-list, and run-show.
• Bind a coordinator pane explicitly; never infer a Run from a worktree or sole candidate.
• Store one active mailbox consumer generation per Run.
• Rebinding fences the old consumer and cancels its active waiter.
• Do not implement Run archive/delete in V1.

Logical routing and prompt safety

• Add stable run:<id> and exact dispatch:<id> message recipients.
• Do not add a task-recipient retargeting rule in V1.
• Make send, ask, reply, completion, heartbeat, and runtime notices inbox-only.
• Ensure only explicit dispatch injection and terminal-send operations can modify terminal input.
• Define send success as durable acceptance, not observation or action.
• Rename or remove check --inject if its name implies remote delivery.
• Reject explicit Run/recipient targets from federated workers when the only valid destination is their authenticated Run home.

Crash-safe inbox consumption

• Add one FIFO mailbox sequence.
• Bound each actionable delivery to 50 messages.
• Allow one outstanding Delivery and one active actionable waiter per Run mailbox.
• Return the identical Delivery ID and batch until acknowledgment.
• Implement whole-batch idempotent acknowledgment.
• Bind Delivery acknowledgment to the current consumer generation.
• Implement atomic ack -> check -> register waiter.
• Keep peek/all/history modes read-only.
• Treat type filters as wake predicates only; return the oldest full actionable batch.
• Return typed timeout, cancelled, connection-lost, waiter-exists, stale-delivery, and consumer-fenced outcomes.
• Preserve unacknowledged mail across client and Orca process restart.

Truthful lifecycle

• Require outcome=succeeded|failed on terminal worker reports.
• Map authenticated succeeded reports to Dispatch succeeded and Task completed.
• Map authenticated failed reports to Dispatch failed and Task failed.
• Persist stale/foreign reports as history without lifecycle mutation.
• Reject malformed lifecycle transitions with typed missing/invalid fields.
• Label result provenance as worker_report.
• Apply every terminal transition as one transactional compare-and-set.
• First committed completion, stop fence, or abandon wins.
• Make duplicate identical completion idempotent.

Questions

• Model a question as durable message/thread state, not a task gate.
• Default ask from an active Dispatch to its owning Run mailbox.
• Record one idempotent first answer from the current Run consumer generation.
• Reject conflicting later answers.
• Resume by original message ID after timeout or disconnect.
• Recover a lost ask-acceptance response through the same mutation retry receipt.
• Close pending questions when their Dispatch stops or is abandoned.
• Wake closed question waits with dispatch_inactive.

Narrow pane authority

• Mint an unforgeable per-Dispatch capability at lifecycle injection.
• Carry the capability outside user-controlled request parameters on native, WSL, and SSH CLI bridges.
• Persist only its verifier or secure-store reference.
• Verify capability, exact managed pane, Dispatch ID, and process incarnation for lifecycle calls.
• Revoke/fence the capability on stop, abandon, or replacement.
• Do not generalize this into user/role access control.

Durable mutation ledger

• Let clients retain/reuse one opaque retry request ID after unknown acceptance.
• Before effects, persist authenticated caller/peer, request ID, canonical payload hash, operation state, and receipt.
• Join concurrent identical mutations or return the recorded result.
• Return request_mismatch for the same request ID with a changed payload.
• Cover Run/Task creation, send, ask, reply, acknowledgment, start, stop, and abandon.
• Persist dedupe receipts across Orca restart.

Phase 1 acceptance

• Two Runs on the same runtime never mix tasks or mail.
• An old coordinator cannot acknowledge or reply after run-use fences it.
• A returned but unacknowledged batch is replayed after client/runtime restart.
• Success, failure, stale completion, malformed completion, and duplicate completion tests pass.
• Ask timeout/resume, same reply replay, conflicting reply, and stopped-Dispatch tests pass.
• A forged pane/handle field cannot mutate lifecycle state.

Phase 2 — Same-server composed worker lifecycle

Command grammar and topology

• Implement worker-start, worker-show, worker-read, worker-stop, and worker-abandon for workers owned by the Run home.
• Current worktree creates one fresh agent terminal unless --terminal is explicit.
• Named existing worktree creates one fresh agent terminal unless reuse is explicit.
• Current/existing worktrees do not rerun creation-time setup or configured tabs.
• New child worktree uses agent-first creation and reuses its returned agent terminal.
• New top-level worktree uses agent-first creation with independent Orca lineage.
• Reject child/top-level creation for folder projects before effects; use current/existing folder workspaces instead.
• Pass the supported exact repo, base, lineage, display/comment metadata, and setup options to the existing worktree primitive rather than duplicating policy. --on owns connected-server placement; project/host convenience selection remains on low-level worktree create.
• Require a configured agent launcher before any mutation.
• Reject selector/option conflicts before effects for current/existing worktrees.

Setup and startup

• Omitted setup on a new worktree resolves to run for orchestration starts.
• No configured setup hook resolves to not_configured, not failure.
• Preserve repository setupAgentStartupPolicy.
• Preserve whether setup came from an explicit request or Orca's orchestration default across connected-server starts.
• Default start-immediately launches setup and agent side by side.
• Under start-immediately, setup outcome never gates Dispatch readiness regardless of when it is observed.
• Track the setup command's exit code without waiting for its interactive terminal shell to exit or closing the setup tab.
• Register the completion observer before replaying bounded recent output so fast local setup commands cannot finish in an observation gap.
• Carry the exact created setup terminal handle; never infer setup identity from a display title shared with configured tabs or split panes.
• Scope completion signals to a private per-invocation token and preserve uncertain terminal outcomes as running rather than converting a disconnect into setup failure.
• The return receipt contains the latest setup state.
• Only post-return setup state changes emit a typed setup notice.
• Setup failure never automatically stops or fails an already-ready worker.
• Explicit wait-for-setup completes setup successfully before agent launch and task injection.
• Under wait-for-setup, setup failure produces start failure before task delivery.
• Custom-argv two-step launch is rejected or clearly unsupported under wait-for-setup.

Start operation and receipts

• In one transaction, create a starting Dispatch, move the Task, and record the mutation request.
• Persist the accepted Dispatch ID in a pending start receipt so restart recovery returns an exact worker-show command.
• Persist before/after stage receipts around irreversible effects.
• Return only ready, failed, or outcome_unknown.
• Define ready as TUI idle, durable Dispatch attachment, and accepted lifecycle/task input.
• Echo effective timeout, setup startup policy, defaults, and resolution sources.
• Enumerate every effect: worktree, setup, agent terminal, setup terminal, each configured terminal pane, and dispatch input; include exact tab/leaf identity when available.
• Persist accepted dispatch input atomically with the ready transition so later setup refreshes cannot erase it.
• Tag every terminal effect with role and created/reused action.
• Report setup as running only after its exact PTY spawn receipt is durable.
• List every residual resource on failure or unknown outcome.
• Never claim an effect was created before it exists.
• Do not add a background provisioning executor; intentionally launched setup may continue as its receipt states.

Dispatch and Task state machine

• Implement starting, ready, start-unknown, failed, succeeded, stopping, stop-unknown, stopped, and abandoned Dispatch states.
• Block the Task while start/stop outcome remains unknown.
• Allow semantic --retry-of only from explicit failed, stopped, abandoned, or proven no-effect states.
• Require the replacement to repeat its intended placement and agent/terminal choice; do not silently inherit a prior attempt's topology.
• Reject unsafe retry without mutation.
• Completed Tasks require a follow-up Task rather than retry.

Show, read, stop, and abandon

• Route operations by Dispatch ID after start; do not require resource IDs again.
• Implement V1 worker-read as a thin route to bounded terminal-read.
• Preserve cursor, limit, terminal status, and limited/truncated fields.
• Stop fences lifecycle and blocks the Task in one home-side compare-and-set.
• Stop affects only the supervised agent terminal/process.
• Never delete the worktree, setup terminal, configured tabs, or unrelated processes.
• Return stopped, already-settled, failed, and stop-unknown receipts truthfully.
• Abandon performs no remote/process action, retains possibly-live resources, and enables a warned replacement.

Same-server recovery tests

• Current, existing, child, top-level, explicit-terminal, and configured-tab starts pass.
• Setup run/skip/inherit and start-immediately/wait-for-setup combinations pass.
• Trust/update prompt, setup failure, terminal failure, and task-input failure receipts pass.
• Crash before effect, after possible effect/before receipt, and after durable receipt are distinguishable as failed/no-residual, outcome-unknown, and failed-with-residual respectively.
• Stop/completion races preserve the first committed terminal transition.
• Restart never adopts a same-looking pane or process incarnation.

Phase 3 — Connected Orca server federation

Placement and identity

• Add worker-only --on <saved-environment> without changing global --environment meaning.
• Default worker placement to the Run home.
• Require --on for remote existing worktree/terminal selectors in V1.
• Resolve remote resources through explicit read-only discovery; never guess by name/path.
• Return server_required, worktree_not_found_on_server, and terminal_worktree_mismatch before related worker effects; treat a mismatched remote Dispatch/home receipt as resource_server_mismatch and never adopt it.
• Pin each remote Dispatch to the authenticated worker-server public-key fingerprint.
• Store runtime ID only as a process epoch, never durable server identity.
• Return peer_changed with no effect if a saved environment is re-paired to a different server.
• Preserve a routing tombstone when an environment with nonterminal Dispatches is removed.

Remote Dispatch attachment

• Persist a narrow attachment on the worker server before task input.
• Store home peer identity, Dispatch capability verifier, stable pane/process incarnation, resource receipts, protocol version, and relay cursors.
• Do not copy the Run DAG/database to the worker server.
• Protect attachment credentials/database/WAL/SHM as current-user-only on macOS, Linux, and Windows.

Bidirectional relay

• Use the existing authenticated saved-environment connection; require no public callback or reciprocal pairing.
• Run a Run-home subscription/pull service for active remote Dispatches.
• Persist worker-to-home lifecycle/questions until home import acknowledgment.
• Persist home-to-worker replies/control mail until worker import acknowledgment.
• Route coordinator send --to dispatch:<id> through that same durable relay and wake the exact remote worker's local check --wait.
• Key relay items by pinned peer, Dispatch ID, direction, monotonic sequence, and a 128-bit-or-stronger message ID.
• Import only contiguous source sequences; buffer/reject gaps.
• Acknowledge only the highest contiguous committed sequence.
• Assign ordinary Run-mailbox order only at home import.
• Apply lifecycle transition and message import in one transaction before acknowledgment.
• Enforce per-message and per-Dispatch count/byte quotas.
• Coalesce heartbeats and reserve room for one terminal lifecycle report.
• Return relay_quota_exceeded; do not add a dead-letter system.

Federated control and recovery

• Route show/read/stop/retry by Dispatch receipt; agents do not repeat --on.
• Forward the same application retry request ID across home and worker server.
• Return typed unknown outcome with last durable stage and exact next commands.
• Reconcile a lost federated stop response from a later authoritative stopped receipt.
• Treat abandonment of a superseded Dispatch as a no-op for the replacement Task.
• Preserve and relay post-return federated setup evidence without changing worker lifecycle.
• Recreate active relay subscriptions after Run-home restart.
• Preserve worker attachment and relay state after worker-server restart.
• Report running only when pane and process incarnation match after restart.
• One disconnected worker server must not block local or other-server inbox delivery.
• No automatic worker replacement on disconnect or silence.

Capability negotiation

• Advertise one aggregate orchestrationFederationV1 control-plane capability.
• Pin peer fingerprint and protocol version in the durable operation record.
• Revalidate them inside the worker-side mutation, not only in a preflight probe.
• Return capability_unsupported before Dispatch/resource/prompt effects.
• Keep host/Git/setup validation inside existing primitives rather than a generalized capability matrix.

Federation scenario matrix

• Post-rebase physical Mac Run home -> Windows worker preserves exact process identity through renderer adoption, routed read, heartbeat, question/reply, completion, and stop.
• Mac Run home -> Windows worker: start, completion, failure, question/reply, read, and stop.
• Windows Run home -> Mac worker: the same flows through a saved Mac pairing.
• Native, WSL, SSH, and relay-backed execution-host paths preserve ownership and CLI capability.
• Run home restarts alone; worker server restarts alone; both restart.
• Disconnect before send proves no effect.
• Disconnect after possible acceptance returns unknown and deduplicates exact retry.
• Duplicate and reordered relay frames/acknowledgments converge without loss or duplication.
• Re-pair/key change cannot retarget an active Dispatch.
• Same-looking handles/resources on two servers never cross-route.
• Mixed server versions fail before effects.
• Windows PowerShell quoting, Windows paths, WSL environment propagation, and SSH bridge allowlists pass.

Phase 4 — Structured worker output

• Reuse Orca's exact pane/process-to-provider-session association; do not create a second status system.
• Keep bounded terminal-read as the universal fallback.
• Read only Codex, Claude/OpenClaude, and Grok transcripts supported by the existing Native Chat decoders.
• Never guess the latest session by current working directory, terminal title, logo, or agent type.
• Pin Dispatch, process, source, and provider session for the full opaque cursor chain.
• Preserve the existing structured native-chat message/block representation and emit bounded parsing/clipping warnings.
• Label terminal fallback and its reason explicitly.
• Read transcripts on the worker-owning server and never serialize their filesystem paths.
• Fall back to the legacy federated terminal-read RPC when a connected server lacks the additive structured-read method.
• Cover exact selection, sibling-session isolation, source changes, malformed input, limits, path privacy, CLI rendering, and mixed-version fallback with automated tests.
• Physically verify local Codex, two same-worktree Codex sessions, cursor continuation, provider-session replacement, explicit terminal selection, and safe Run-home restart behavior.
• Physically verify Mac Run home -> older Windows worker terminal fallback, including an opaque continuation cursor and explicit transcript-required failure.
• Physically verify hooks-disabled automatic fallback and disconnect/reconnect.
• Physically verify exact structured Mac-to-Windows and Windows-to-Mac reads after both worker servers run the new additive method.
• Do not add resume, live-stream control, session exclusivity, or a universal transcript ontology.

Migration — Hard cutover from pre-Run orchestration

Contract and effect fence

• Add one orchestration contract version and one advertised runtime capability without changing the global runtime protocol.
• Keep one shared mutation/read classifier for CLI, runtime dispatch, durable receipts, and connected-server calls.
• Require the contract before parameter parsing, mutation receipts, database writes, prompt injection, process actions, or connected-server mutations.
• Preflight local and paired runtime capabilities before a new CLI sends a mutation.
• Carry the contract through native Unix/named-pipe, WebSocket, and connected-server envelopes.
• Retire coordinator-start, coordinator-stop, run, and run-stop before RPC effects.
• Do not add a compatibility executor, automatic rewrite, legacy scheduler, or in-flight drain.

Agent recovery and legacy inspection

• Return effectsApplied=false, structured guide metadata, and executable argument-only skills get orchestration --full recovery.
• Attach the same guide recovery to no-bound-Run and missing worker outcome errors.
• Preserve explicit read-only Run, task, inbox, Dispatch, gate, and terminal inspection.
• Allow task-list --run run_legacy_local without binding the legacy Run.
• Keep default/actionable check and acknowledgment fenced; only explicit peek/all history reads may inspect legacy mail.
• Document that active pre-upgrade agents keep running as processes but are unsupervised and must be inspected before replacement.
• Remove the legacy scheduler recipe from the version-matched full orchestration guide.

Migration acceptance

• Missing/wrong contract rejects every classified mutation before parsing, receipt, and effect.
• Current-contract mutations still execute and retain durable retry receipts.
• Read-only inspection works without a contract and does not consume legacy data.
• Local and remote clients reject a runtime missing the contract capability before mutation.
• Native and encrypted WebSocket transports preserve the contract field.
• Old worker_done leaves message, Task, and Dispatch state unchanged.
• Human and JSON errors preserve no-effects and guide-reload recovery.
• skills get orchestration --full remains runtime-independent and generated guides stay in sync.
• Branch-head CI passes after the verified migration commit is pushed. Local orchestration, repository tests, typechecks, reliability gates, and production builds pass.

Cross-cutting quality gates

Persistence and transactions

• Define process-crash durability separately from sudden-power-loss durability.
• Keep SQLite WAL + synchronous=NORMAL for the documented process-crash guarantee; require a separate policy change before promising sudden-power-loss durability.
• Keep lifecycle import, terminal transitions, and acknowledgment transaction boundaries explicit.
• Exercise migrations from existing task/message/dispatch/scheduler-run data.

Cross-platform

• Native macOS, Linux, and Windows tests cover each new CLI/RPC contract.
• WSL and SSH host identity/capability state is scoped to the actual execution host.
• Paths use platform utilities; examples are PowerShell/cmd/POSIX safe.
• Named-pipe, Unix-socket, WebSocket, WSL, and SSH bridges carry Dispatch capabilities safely.

Documentation

• CLI help owns exact flags, selectors, defaults, outcome fields, and exit-code behavior; typed RPC errors remain the machine-readable error contract.
• The skill owns short decision recipes and common misuses, not protocol internals.
• Every shipped phase updates this checklist and adds a progress-log entry.
• The ignored HTML proposal and this tracked checklist remain semantically synchronized.

Findings and decision log

2026-07-22 — Phase 2 closure without option-surface creep

• worker-start passes exact repository, base, child/top-level lineage, display/comment metadata, and setup choices into the existing worktree primitive. It does not duplicate worktree create's project/host convenience resolver: --on already names the connected Orca server and --repo names the repository on that server.
• A gated setup receipt becomes succeeded only after the agent wrapper proves setup completed. A confirmed spawn/script failure fails before task input; timeout keeps running because silence is not failure.
• The existing single durable worker row is the operation stage journal. A pre-effect failure has no residuals, possible acceptance before receipt is unknown, and later failure after a durable effect lists exact residual resources. No background saga executor or general effect engine was added.
• This earlier Phase 4 deferral was based on an incomplete audit. Orca already retained an exact pane-scoped provider-session association from agent hooks; the narrow implementation now exposes it to the worker-owning runtime and still falls back when that evidence is absent.

2026-07-22 — Final setup/startup review

• Keep setup-run as the new-worktree orchestration default.
• Preserve Orca's existing start-immediately default: setup and agent run side by side.
• Only explicit wait-for-setup gates agent launch/task delivery.
• A custom-argv two-step terminal launch cannot preserve wait-for-setup and must not silently bypass it.
• Receipts must enumerate role-tagged agent, setup, and configured terminals; a boolean setupSpawned is insufficient.
• Setup outcome never gates readiness under start-immediately, regardless of observation timing.

2026-07-22 — Federation robustness review

• Multi-server operation is a core requirement, not a later optional product feature.
• Use a single authoritative Run home with narrow remote Dispatch attachments and bidirectional relay; do not replicate the Run database.
• Pin active Dispatches to authenticated peer identity so re-pairing cannot redirect work.
• Use contiguous, scoped relay sequences and bounded storage.
• Hide peer fingerprints, relay cursors, process incarnations, and capabilities from normal agents.

2026-07-22 — Validation and scope boundary

• Phase 0 and Phase 1 are complete: their command, recipe, Run, inbox, lifecycle, question, authority, and mutation-ledger acceptance rows now have focused passing tests.
• Phase 2 remains open until the full existing-worktree/explicit-terminal/setup-policy/failure-stage matrix is covered. Passing current/new-worktree and recovery slices are not enough to claim it.
• Phase 3 remains open until the named Mac/Windows, WSL, SSH, relay, restart, disconnect, and quoting matrix runs on those actual paths. The in-process federation harness proves protocol behavior but is not a substitute for cross-platform acceptance.
  • At this point Phase 4 stayed deferred pending proof of an exact association. The later structured-output audit found the existing pane-scoped hook association and superseded this decision without adding a universal provider framework.

2026-07-21 — Simplification decision

• Replace the original broad orchestration redesign with four public concepts: Run, Task, Dispatch, and Message.
• Keep agent-owned strategy and strong control-plane primitives.
• Remove UI, scheduler, capacity allocation, access enforcement, commit/integration tracking, generalized provider/session abstractions, and other speculative product machinery.
• Retain Run because it provides a durable namespace and home mailbox across connected servers, not because it schedules work.

Progress log

Append new entries chronologically. Do not rewrite older entries except to correct factual errors.

2026-07-22 — Checklist initialized

• Changes:
  • Created this tracked implementation ledger from the reviewed orchestration proposal.
  • Recorded all phases, acceptance tests, non-goals, and review-derived invariants.
  • Updated the current orchestration skill to prefer setup-run, preserve start-immediately, process message batches, prefer agentTerminalHandle, and reject custom-argv wait-policy bypass.
• Files:
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
  • skills/orchestration/SKILL.md
  • docs/orchestration-primitives.html (ignored design source)
• Verification:
  • HTML parsed successfully with balanced tags and unique IDs.
  • Final review Task completed without an architectural blocker.
• Findings:
  • Implementation may begin with Phase 0.
  • Phase 2 readiness/receipt work depends on the explicit setup and role-tagged-effect contracts recorded above.
• Next:
  • Finish Phase 0 command compatibility and version-matched recipes.

2026-07-22 — Phase 0 command safety and vocabulary

• Changes:
  • Renamed the scheduler-like command surface to coordinator-start and coordinator-stop while retaining run and run-stop as documented deprecated aliases.
  • Updated root help and both orchestration skill sources to distinguish the legacy automatic loop from the proposed lightweight Run namespace and to prefer the explicit task/dispatch/wait loop.
  • Made orchestration reset require exactly one of --all, --tasks, or --messages before it contacts the runtime.
  • Synchronized setup, worker-terminal selection, and message-batch guidance into the canonical guide and regenerated the bundled CLI guide.
• Files:
  • src/cli/specs/orchestration.ts
  • src/cli/handlers/orchestration.ts
  • src/cli/help.ts
  • src/cli/handlers/orchestration.test.ts
  • src/cli/index.test.ts
  • src/main/runtime/orchestration-cli-subprocess.test.ts
  • skill-guides/orchestration.md
  • skills/orchestration/SKILL.md
  • src/cli/bundled-skill-guides.ts
• Verification:
  • pnpm vitest run --config config/vitest.config.ts src/cli/index.test.ts src/cli/handlers/orchestration.test.ts — 199 tests passed.
  • pnpm verify:bundled-skill-guides — passed.
  • pnpm typecheck:cli — passed.
  • git diff --check — passed.
• Findings:
  • Keeping hidden compatibility aliases preserves existing scripts without advertising the old scheduler noun as the normal agent path.
  • Truthful success/failure recipes depend on the Phase 1 explicit lifecycle outcome; do not document the current behavior as if a failed worker_done failed the Task.
• Next:
  • Implement explicit succeeded/failed worker-report semantics and then finish the version-matched Phase 0 recipes without lying about failure behavior.

2026-07-22 — Truthful worker terminal outcomes

• Changes:
  • Added the structured --outcome succeeded|failed worker-report field to local and SSH fallback CLI payload construction and injected preambles.
  • Added one transactional compare-and-set that settles the Dispatch and Task together, promotes dependents only on success, and replays an identical terminal outcome idempotently.
  • Persisted worker result provenance, message identity, summary, files, and report path as a labeled worker_report rather than an Orca-verified result.
  • Converted missing, invalid, unknown, stale, mismatched, inactive, and foreign reports into typed, high-priority audit rows without mutating lifecycle state.
  • Updated the legacy automatic coordinator loop to record failed worker reports as failed tasks.
• Files:
  • src/cli/specs/orchestration.ts
  • src/cli/handlers/orchestration.ts
  • src/main/ssh/ssh-remote-orchestration-send.ts
  • src/main/runtime/orchestration/types.ts
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/orchestration/lifecycle-reconciliation.ts
  • src/main/runtime/orchestration/preamble.ts
  • src/main/runtime/orchestration/coordinator.ts
  • Corresponding CLI, SSH, preamble, DB lifecycle, coordinator, and RPC tests/snapshots
  • Both orchestration skill sources and the generated bundled guide
• Verification:
  • Five focused CLI/lifecycle/preamble/coordinator/SSH test files — 124 tests passed.
  • src/main/runtime/rpc/methods/orchestration.test.ts — 114 tests passed.
  • pnpm typecheck:node — passed.
  • pnpm typecheck:cli — passed.
  • pnpm verify:bundled-skill-guides and git diff --check — passed.
• Findings:
  • The old subject-based failure convention was not merely confusing: it irreversibly completed a failed Task. Requiring a tiny enum is a robust primitive, not workflow policy.
  • Stop and abandon still need to share this terminal-transition fence before the broader first-writer-wins checklist item can be marked complete.
• Next:
  • Add the lightweight Run schema and explicit coordinator binding, then key new Task/Dispatch/ Message state to that Run without changing agent placement policy.

2026-07-22 — Lightweight Run foundation and inbox-only mail

• Changes:
  • Added schema v7 with lightweight Runs, stable explicit pane binding, consumer generations, and an inspect-only legacy Run for all migrated pre-Run rows.
  • Kept legacy automatic coordinator-loop storage in its existing coordinator_runs table.
  • Added run-create, run-use, run-current, run-list, and run-show across CLI/RPC, with explicit binding and no worktree or sole-candidate inference.
  • Scoped new Task creation/list/update/dispatch operations to an explicit or currently bound Run; Dispatches and decision gates inherit their Task's Run.
  • Removed structured-mail prompt injection from send and ask. Mail now persists and wakes waiters only; deliberate dispatch --inject and terminal send remain the input-writing paths.
  • Renamed the local message renderer from check --inject to check --format, retaining only a one-release RPC compatibility field.
• Files:
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/orchestration/types.ts
  • src/main/runtime/rpc/methods/orchestration-runs.ts
  • src/main/runtime/rpc/methods/orchestration.ts
  • src/main/runtime/orchestration/orchestration-error.ts
  • src/main/runtime/rpc/errors.ts
  • src/cli/specs/orchestration.ts
  • src/cli/handlers/orchestration.ts
  • Related DB, RPC, CLI, and help tests; both skill sources and the bundled guide
• Verification:
  • Focused DB/RPC/CLI command suite — 384 tests passed.
  • pnpm typecheck:node and pnpm typecheck:cli — passed.
  • pnpm generate:bundled-skill-guides and pnpm verify:bundled-skill-guides — passed.
  • git diff --check — passed.
• Findings:
  • Run identity is now real without changing scheduling or placement policy, but Messages and questions still need stable logical recipients before mandatory Run association is complete.
  • Consumer generation exists, but waiter cancellation and acknowledgment fencing belong to the crash-safe Delivery implementation and remain intentionally unchecked.
• Next:
  • Implement Run-owned logical mailboxes and stable run:<id> / dispatch:<id> routing, then replace consume-on-read with one crash-safe outstanding Delivery per Run.

2026-07-22 — Crash-safe Run inbox and durable questions

• Changes:
  • Added stable run:<id> and dispatch:<id> recipients; lifecycle sends from an active Dispatch now default to its Run and no longer require agents to carry a coordinator terminal handle.
  • Added schema v8 Deliveries: one FIFO batch of at most 50 rows, one outstanding batch per Run, exact replay until whole-batch acknowledgment, and consumer-generation fencing.
  • Made check --ack <delivery> --wait perform ack, check, and waiter registration without an intervening async gap; type filters are wake predicates and never split the FIFO batch.
  • Added typed timeout, cancellation/connection-loss, second-waiter, stale-Delivery, and fenced- consumer outcomes, plus persisted Delivery replay after an Orca database reopen.
  • Added schema v9 question threads keyed by the original message ID, with active-Dispatch Run defaulting, timeout-safe resume, current-consumer first-answer authority, idempotent replay, and conflicting-answer rejection.
  • Updated injected worker guidance and the orchestration skill so normal lifecycle and question commands omit internal Run/server identity and coordinators explicitly process/ack each batch.
• Files:
  • src/main/runtime/orchestration/types.ts
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/orca-runtime.ts
  • src/main/runtime/rpc/methods/orchestration.ts
  • src/main/runtime/rpc/methods/orchestration-runs.ts
  • src/main/runtime/orchestration/preamble.ts
  • CLI specs/handlers, RPC error mapping, skill sources, snapshots, and focused tests
• Verification:
  • DB/RPC/runtime/CLI/preamble focused suite — 1,190 tests passed after the expected preamble snapshot update.
  • Delivery tests cover 50-row bounds, FIFO replay, idempotent ack, filter wake semantics, consumer fencing, and reopen recovery.
  • Question tests cover create/answer, same-answer replay, answer conflict, timeout persistence, resume, unrelated wakes, and Dispatch closure storage behavior.
• Findings:
  • A Run inbox needs only one durable Delivery row plus immutable message IDs; no dead-letter, selective NACK, or second Event subsystem is necessary.
  • Question answers belong in thread state rather than inbox-read state, so replying never accidentally acknowledges the coordinator's whole Delivery.
• Next:
  • Replace caller-supplied pane claims with a narrow Dispatch capability and add the durable mutation ledger needed to recover unknown acceptance without replaying effects.

2026-07-22 — Narrow Dispatch lifecycle capability

• Changes:
  • Minted a 256-bit per-Dispatch secret for injected workers while persisting only its SHA-256 verifier.
  • Bound lifecycle/question authority to the exact runtime-observed pane and PTY process incarnation in addition to the Dispatch ID.
  • Carried the secret in the authenticated RPC envelope across local socket, WebSocket, shared remote-runtime, and SSH fallback transports rather than orchestration payload fields.
  • Revoked the capability when worker completion/failure settles the Dispatch and stopped trusting caller-supplied pane metadata in the SSH fallback.
• Files:
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/orchestration/types.ts
  • src/main/runtime/orchestration/preamble.ts
  • src/main/runtime/rpc/core.ts
  • src/main/runtime/rpc/dispatcher.ts
  • src/main/runtime/rpc/methods/orchestration.ts
  • CLI and remote transport implementations plus focused tests
• Verification:
  • Ten focused DB/RPC/runtime/CLI/SSH files — 1,238 tests passed.
  • Capability cases cover missing token, wrong token, wrong pane, changed process incarnation, success, and post-settlement revocation.
  • pnpm typecheck:node and pnpm typecheck:cli — passed.
• Findings:
  • Terminal handles and environment-provided pane strings are useful routing metadata but are not lifecycle authority.
  • Stop, abandon, and replacement must use the same revocation fence before that remaining checklist item can be completed.
• Next:
  • Add the durable mutation ledger and use it to recover unknown acceptance without repeating external effects.

2026-07-22 — Durable mutation receipts

• Changes:
  • Added schema v11 mutation receipts keyed by an authenticated-caller fingerprint and opaque request ID, with canonical payload hashing and pending/completed state.
  • Replayed completed results across retries and restart, joined concurrent identical mutations, rejected changed input as request_mismatch, and surfaced orphaned pending work as operation_unknown.
  • Added request IDs to local socket, named-pipe, WebSocket, saved-environment, and SSH fallback envelopes; successful receipts echo the ID while transport failures retain it as recovery data.
  • Persisted blocking-question acceptance before waiting, so retry after a lost response returns the original question instead of creating another.
• Files:
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/orchestration/types.ts
  • src/main/runtime/rpc/core.ts
  • src/main/runtime/rpc/dispatcher.ts
  • Runtime-client and transport files, CLI orchestration handlers/specs, and focused tests
• Verification:
  • Twelve focused DB/RPC/runtime/CLI/SSH files — 1,260 tests passed.
  • pnpm typecheck:node, pnpm typecheck:cli, and git diff --check — passed.
• Findings:
  • Generic control-plane mutations can safely discard a pending receipt when their handler returns a known failure; future worker start/stop must instead return and preserve typed unknown outcomes around external effects.
  • The ledger infrastructure covers every existing V1 mutation; worker start/stop/abandon will be added to the same policy when those commands exist.
• Next:
  • Implement the same-server worker lifecycle and its first-writer-wins stop/abandon fence.

2026-07-22 — Same-server worker lifecycle foundation

• Changes:
  • Added schema v12 composed-worker state and created the starting Dispatch plus Task transition before terminal effects.
  • Added synchronous worker-start for the current or an exact existing worktree, with fresh-agent default, explicit-terminal reuse, TUI readiness, capability attachment, lifecycle injection, and honest failed receipts with residual resources.
  • Added Dispatch-routed worker-show and bounded worker-read.
  • Added first-writer-wins worker-stop and worker-abandon; stop closes only the supervised agent terminal, while abandon performs no process/filesystem action and retains residual receipts.
  • Closed and woke pending question waits when a worker is settled, stopped, or abandoned.
• Files:
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/orchestration/types.ts
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • src/main/runtime/rpc/methods/orchestration.ts
  • src/main/runtime/orca-runtime.ts
  • CLI orchestration specs/handlers and focused DB/RPC/CLI tests
• Verification:
  • Focused DB/RPC/CLI command suite — 412 tests passed.
  • pnpm typecheck:node and pnpm typecheck:cli — passed.
• Findings:
  • Keeping composed state in a narrow extension table preserves legacy Dispatch compatibility while giving worker operations the richer start/stop states they need.
  • New-worktree setup, stage journaling around worktree creation, and true unknown-start recovery remain open; current/existing workers are the verified slice.
• Next:
  • Add agent-first child/top-level creation with setup-run default and startup-policy receipts, then extend the same Dispatch routing across connected Orca servers.

2026-07-22 — Agent-first new-worktree workers and setup receipts

• Changes:
  • Added child and top-level agent-first worktree creation to worker-start, reusing the exact startup agent terminal and listing setup/configured terminals as role-tagged effects.
  • Made omitted setup resolve to run, preserved explicit run/skip/inherit and repository startup policy, and returned not_configured when no setup hook exists.
  • Kept start-immediately setup non-gating, persisted later setup success/failure, and emitted a typed Run notice without changing a ready worker's lifecycle state.
  • Narrowed setup receipts to callers that explicitly await terminal provisioning so ordinary worktree creation does not report renderer-delegated setup as a false spawn failure.
  • Added typed unknown-start recovery when worktree creation may have been accepted before a connection failure.
• Files:
  • src/main/runtime/orca-runtime.ts
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • src/main/runtime/rpc/methods/orchestration-workers-new-worktree.test.ts
  • src/main/runtime/rpc/methods/orchestration.test.ts
  • src/shared/types.ts
• Verification:
  • New-worktree worker scenarios — 8 tests passed.
  • Worker RPC plus runtime worktree suites — 911 tests passed.
  • pnpm typecheck:node — passed.
• Findings:
  • A setup status is only truthful after the supervised caller awaits the runtime's terminal provisioning result; normal renderer-delegated creation should retain its existing launch payload instead.
  • The generic mutation receipt and starting Dispatch are still separate commits, so atomic start acceptance and crash-boundary reconciliation remain open.
• Next:
  • Make worker-start acceptance one transaction, then add restart reconciliation that never adopts a same-looking pane or process.

2026-07-22 — Atomic worker acceptance and conservative restart recovery

• Changes:
  • Moved the worker-start retry request insertion into the same SQLite transaction that creates the starting Dispatch and moves its Task to dispatched.
  • Added a process runtime epoch to composed Dispatches so interrupted starts/stops become explicit unknown outcomes after restart instead of remaining indefinitely in transitional states.
  • Made worker show/read/stop verify the persisted stable pane plus exact PTY process incarnation; a same-looking replacement is reported as changed and is never read or closed.
  • Restricted semantic retry to the Task's latest failed, stopped, or abandoned Dispatch.
• Files:
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/orchestration/types.ts
  • src/main/runtime/rpc/core.ts
  • src/main/runtime/rpc/dispatcher.ts
  • src/main/runtime/rpc/errors.ts
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • Focused DB, mutation-ledger, new-worktree, and recovery tests
• Verification:
  • Atomic acceptance and recovery suite — 231 tests passed.
  • Follow-up DB/recovery/new-worktree suite — 93 tests passed.
  • pnpm typecheck:node — passed.
• Findings:
  • Runtime ID is useful only as a process epoch. It is not a durable server identity and must not be used to route federated Dispatches.
  • After restart, preserving uncertainty is safer than adopting a restored pane: the prior worker may still exist, but only explicit stop/abandon/retry recovery may replace it.
• Next:
  • Audit and close the remaining same-server acceptance rows, then implement saved-environment placement and the narrow federated Dispatch attachment.

2026-07-22 — Connected-server federation and crash-safe relay

• Changes:
  • Added worker-only --on <saved-environment> placement while keeping Run/Task authority on the current server and routing later show/read/stop operations solely by Dispatch ID.
  • Pinned remote Dispatches to the saved server public-key fingerprint and stored runtime identity only as a replaceable process epoch; re-pairing returns peer_changed before effects.
  • Added a narrow worker-server attachment with protocol version, capability verifier, exact pane/process identity, effects, setup state, and bidirectional relay cursors—without copying the Run DAG.
  • Added durable worker-to-home lifecycle/question relay and home-to-worker reply relay with contiguous sequence checks, source acknowledgment, quotas, heartbeat coalescing, and reserved terminal-report capacity.
  • Made home import commit the message, question/lifecycle transition, and source cursor in one transaction before acknowledgment.
  • Added federated show/read/stop, stop/completion ordering, timeout/resume after worker restart, relay restart, exact-process checks, ack-loss replay, gap rejection, peer-change fencing, and POSIX database/WAL/SHM permission coverage. Windows uses Orca's existing current-user-only userData DACL boundary.
  • Added an agent-facing cookbook for local fan-out, setup-default new worktrees, Mac/Windows placement, completion/failure, ask/resume/reply, and conditional recovery.
• Files:
  • src/main/runtime/orchestration/environment-transport.ts
  • src/main/runtime/orchestration/federation-sync.ts
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/rpc/methods/orchestration-federation.ts
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • Federation, permissions, CLI, transport, skill-guide, and protocol capability tests/sources
• Verification:
  • Federation scenarios — 14 tests passed.
  • Federation plus database-permission scenarios — 15 tests passed.
  • Focused database/lifecycle/federation regression suite — 111 tests passed.
  • pnpm typecheck:node and bundled skill-guide verification — passed.
• Findings:
  • The stable saved-environment public-key fingerprint is server identity; a runtime UUID is only an epoch and must never retarget a Dispatch after restart.
  • The worker server needs only an authenticated attachment and relay outbox, not a replicated Run database, scheduler, callback listener, or general ACL system.
  • Setup remains explicit in receipts but non-gating by default; only repository wait-for-setup policy delays agent launch.
• Next:
  • Run the complete orchestration/CLI regression matrix, close any remaining checklist gaps, then run repository validation and prepare the commit/PR.

2026-07-22 — Final modularization and verification pass

• Changes:
  • Split federation, worker control/observation/topology, mutation execution, CLI specs, runtime transport support, SSH error formatting, and database/CLI tests into domain-named modules so no new max-lines bypass was needed.
  • Regenerated the bundled skill manifests after the orchestration guide changed.
  • Updated skill-guidance and lifecycle-rejection tests for the renamed legacy coordinator command, setup-run default, agent-terminal fallback, and mandatory worker outcome.
  • Kept unrelated daemon/UI/localization baseline failures out of the orchestration diff.
• Files:
  • src/main/runtime/rpc/methods/orchestration-federation-*.ts
  • src/main/runtime/rpc/methods/orchestration-worker-*.ts
  • src/main/runtime/orchestration/orchestration-*-db.test.ts
  • src/main/runtime/rpc/orchestration-mutation-executor.ts
  • src/main/runtime/rpc/runtime-feature-interaction.ts
  • src/main/ipc/runtime-environment-shared-control-support.ts
  • src/cli/specs/orchestration-worker-specs.ts
  • src/cli/handlers/orchestration-run-cli.test.ts
  • src/main/ssh/ssh-remote-cli-error-response.ts
• Verification:
  • Focused orchestration/CLI/SSH suite: 20 files, 565 tests passed.
  • Runtime/subprocess/transport suite: 780 passed, 2 skipped.
  • Updated skill-guidance/lifecycle-rejection tests: 12 passed.
  • Full TypeScript check (Node, CLI, web), ordinary oxlint, max-lines ratchet, reliability gates, bundled guide verification, manifest verification, and localization catalog verification passed.
  • pnpm test could not start because the patched node-pty artifact does not load under local Node 24.18.0. Direct full Vitest ran 33,058 passing tests; its 24 remaining failures and 3 worker errors were native-PTY or unrelated timeout/baseline failures after the three stale orchestration assertions were fixed and rerun.
  • Full pnpm lint remains blocked only by unrelated existing switch-exhaustiveness and localization-coverage failures outside this change.
• Findings:
  • The implemented protocol has a clean authority split: the Run home owns orchestration truth; connected worker servers own only exact resources, an authenticated Dispatch attachment, and durable relay state.
  • The remaining unchecked Phase 2/3 rows are real acceptance work, not reasons to add a scheduler, UI, generalized capability matrix, provider-session layer, or automatic recovery.
• Next:
  • Add the missing focused Phase 2 scenarios and run the Phase 3 matrix on real Mac/Windows and WSL/SSH paths before marking those phases complete.

2026-07-22 — Phase 2 setup and receipt acceptance complete

• Changes:
  • Made wait-for-setup receipts settle to succeeded only after gated agent readiness and fail at setup_start or setup_wait before lifecycle/task input when setup is confirmed failed.
  • Preserved running on a gated timeout, avoiding a false setup-failure claim.
  • Added stage, role-tagged dispatch input, rich setup effect data, and exact terminal tab/leaf coordinates to composed-worker receipts.
  • Kept worker-start's option surface narrow: exact server via --on, exact repo via --repo, and pass-through base/lineage/display/comment/setup choices.
  • Updated CLI help, both skill sources, the generated guide/manifests, and the ignored HTML design.
• Files:
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • src/main/runtime/rpc/methods/orchestration-worker-topology.ts
  • src/main/runtime/rpc/methods/orchestration-federation.ts
  • src/main/runtime/rpc/methods/orchestration-federated-worker-start.ts
  • src/main/runtime/rpc/methods/orchestration-federation-effects.ts
  • Focused worker, federation, and CLI tests plus help/skill/checklist/design sources
• Verification:
  • Local/new-worktree/federation worker suites: 166 tests passed.
  • CLI handler/help suite: 197 tests passed.
  • Full Node/CLI/web TypeScript check passed.
• Findings:
  • The existing worktree startup wrapper already enforces setup-before-agent ordering; the missing work was truthful orchestration state and acceptance coverage, not a second setup runner.
  • Phase 2 is complete. Remaining unchecked rows are the real connected-platform Phase 3 matrix and cross-platform transport evidence.
• Next:
  • Exercise federation disconnect/reorder/restart semantics, then run branch-head Mac/Windows acceptance without replacing either production Orca runtime.

2026-07-22 — Native Mac-to-Windows acceptance gaps

• Changes:
  • Built and launched branch-head Mac and Windows servers on isolated profiles and paired them over the existing authenticated WebSocket transport.
  • Used a temporary, exact Tailscale TCP proxy because Windows Firewall correctly blocked the new test-binary port; production Orca and firewall policy were left unchanged.
  • Added explicit dev-CLI provenance so custom profile paths still generate orca-dev worker commands.
  • Increased only the Windows ConPTY bracketed-paste render gap before Enter from 500 ms to 1.5 s.
• Files:
  • config/scripts/orca-dev.mjs
  • src/cli/handlers/orchestration.ts
  • src/shared/agent-prompt-injection.ts
  • Focused wrapper, CLI, and prompt-injection tests
• Verification:
  • Native Windows discovery, exact worktree routing, pre-effect failure, retry, ready receipt, worker-read, and remote worker-stop all returned truthful branch-head receipts.
  • Focused dev-provenance and prompt-injection suite: 160 tests passed.
• Findings:
  • A fresh Windows agent profile surfaces trust/login/update prompts as typed agent_readiness failures with residual terminals, as designed.
  • The first authenticated Windows worker proved that 500 ms could leave a long preamble in the Codex input buffer, and that a custom dev profile could incorrectly call the production CLI.
  • Phase 3 remains open until the fixes are rebuilt on Windows and the full completion/question/ failure/restart matrix succeeds without a manual Enter or CLI substitution.
• Next:
  • Rebuild both branch servers with these fixes and repeat the real Mac-home to Windows-worker flow.

2026-07-22 — Headless Windows dev-worker CLI routing

• Changes:
  • Made every orca-dev entry path install profile-scoped orca-dev and orca terminal wrappers, including Windows .cmd wrappers and headless orca-dev serve.
  • Kept the wrapper generation shared with the Electron dev runner so interactive and headless dev servers expose the same exact CLI and user-data profile to worker terminals.
• Files:
  • config/scripts/dev-cli-terminal-wrapper.mjs
  • config/scripts/orca-dev.mjs
  • config/scripts/run-electron-vite-dev.mjs
  • Focused cross-platform wrapper tests
• Verification:
  • Wrapper, CLI provenance, dev-runner, preamble, and orchestration handler suites: 55 tests passed.
  • Focused oxlint and formatting checks passed.
• Findings:
  • The rebuilt prompt submitted automatically on Windows, but the worker then found no profile-scoped orca-dev command because headless serve bypassed the Electron dev runner and the runner itself had never written Windows wrappers into the PATH directory used by Orca terminals.
  • This is a dev/acceptance launcher defect, not a new federation primitive or production routing requirement.
• Next:
  • Rebuild and restart the Windows branch server, then repeat the same Dispatch and require an automatically relayed worker_done before checking any federation acceptance row.

2026-07-22 — Mac-home to Windows-worker federation accepted

• Changes:
  • Fast-forwarded and restarted the isolated Windows branch server with the profile-scoped wrapper fix while preserving its authenticated server key and saved-environment binding.
  • Exercised separate success, intentional failure, and blocking question/reply Dispatches from the isolated Mac Run home to native Windows Codex workers.
• Files:
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
• Verification:
  • Success ctx_f982ddb1bdf9 submitted without manual input, relayed worker_done, and atomically settled its Task/Dispatch as completed/succeeded.
  • Failure ctx_5f28665cf04a relayed outcome=failed and atomically settled its Task/Dispatch as failed without treating failure prose as success.
  • Question ctx_4aec24c47e30 relayed a typed question to the Mac Delivery, carried the blue reply back to the blocked Windows ask, then relayed a successful terminal report.
  • Routed bounded read and exact-agent stop were also exercised against Windows Dispatch receipts; stop closed only the accepted agent terminal.
• Findings:
  • Windows ConPTY prompt submission, profile-specific CLI selection, authenticated lifecycle acceptance, contiguous bidirectional relay, whole-batch acknowledgment, and terminal-state reconciliation now pass together in the real Mac-to-Windows path.
  • This completes only the named Mac-home to Windows-worker row; reverse direction, restart with an active Dispatch, disconnect/unknown-outcome, WSL/SSH/relay-host, and transport coverage remain open.
• Next:
  • Pair the isolated Mac server into the Windows test profile and run the same acceptance flow with Windows as the Run home.

2026-07-22 — Windows-home to Mac-worker federation accepted

• Changes:
  • Added a reciprocal saved Mac environment to the isolated Windows profile without exposing its pairing credential in terminal history.
  • Exercised separate success, intentional failure, blocking question/reply, bounded read, and exact stop Dispatches with Windows as Run home and native macOS as worker server.
  • Made worker observations report exited for the exact disconnected terminal instead of misleadingly projecting running; stop now refuses to close an exact-but-exited process again.
• Files:
  • src/main/runtime/rpc/methods/orchestration-worker-observation.ts
  • src/main/runtime/rpc/methods/orchestration-federation-control.ts
  • src/main/runtime/rpc/methods/orchestration-worker-stop.ts
  • Focused local/federated observation and stop tests
• Verification:
  • Success ctx_5188e1f8417e relayed from macOS and settled at the Windows Run home.
  • Failure ctx_a3418dc84ed6 relayed outcome=failed and settled failed at the Windows home.
  • Question ctx_a2521b88b6c9 carried square from Windows to the blocked macOS ask, followed by a successful terminal report.
  • Stop ctx_bec120349d3f first proved routed read against the exact Mac worker, then closed only that terminal and settled stopped/failed; the observation regression suites pass 36 tests.
• Findings:
  • One reciprocal pairing is sufficient for a Windows-owned Run to route Mac worker control while preserving a single Run database on Windows; no replicated scheduler or failover layer is needed.
  • Stable process identity and live process status are separate facts. A disconnected terminal can still be the exact historical worker, but it must not be labeled running or closed again.
• Next:
  • Validate active-Dispatch restart/disconnect and exact-retry behavior, then exercise WSL/SSH/relay execution-host propagation without broadening the federation protocol.

2026-07-22 — Federated restart and pre-acceptance disconnect accepted

• Changes:
  • Restarted the Windows Run home alone, the macOS worker server alone, and both servers while each had an active federated Dispatch.
  • Stopped the macOS worker server before a Windows-home start request could be accepted.
• Files:
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
• Verification:
  • Home-only restart preserved ctx_f0693ff30c27; worker-show found the same exact running macOS worker under the unchanged worker epoch, and routed stop succeeded.
  • Worker-only restart preserved ctx_3bbb0142f9aa at its Run home while the new macOS epoch truthfully reported the missing terminal as non-exact; routed stop returned stop_unknown without adopting or closing another process.
  • Restarting both sides preserved ctx_d46f68fa1400 and its attachment; inspection used the new worker epoch, reported missing with exactWorker=false, and stop again returned stop_unknown safely.
  • With macOS already unreachable, retry request disconnect-before-send-01 created neither a Dispatch nor an attachment for task_04fd0dc61065; the Task remained ready.
• Findings:
  • Durable home state and worker identity fencing survive independent epochs without requiring Run replication or authority failover.
  • A failed connection before remote acceptance is a clean no-effect result; it must not be promoted to an ambiguous outcome or consume the Task.
• Next:
  • Disconnect the worker route after possible acceptance, then follow the returned exact recovery command and prove that retry deduplicates to one remote effect.

2026-07-22 — Post-acceptance disconnect deduplicated

• Changes:
  • Cut the Windows Tailscale proxy while a Mac-home worker-start was provisioning remotely, then restored the same route and replayed the exact application request ID.
  • Allowed an explicit worker-stop to fence start_unknown locally and on the worker server; exact pane/process observation still decides whether a terminal may actually be closed.
• Files:
  • src/main/runtime/orchestration/db.ts
  • src/main/runtime/orchestration/orchestration-worker-dispatch-db.test.ts
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
• Verification:
  • The lost response left task_bb86c87bdc60 attached to one pending Dispatch, ctx_6580d07d9006, rather than creating a replacement.
  • Replaying request disconnect-after-start-01 returned the same Dispatch with state=outcome_unknown and mutation.replayed=true.
  • Remote inspection found one disconnect-after-acceptance-01 worktree, one exact agent terminal, and one expected setup terminal; no duplicate topology was created.
  • Worker Dispatch DB, federated control, and recovery suites passed 29 tests; node typecheck and focused oxlint passed. Branch-head CLI and Electron builds succeeded on macOS and Windows.
  • Relay tests reject an out-of-order sequence without advancing the cursor, later accept the missing and retried frames contiguously, treat the repeated frame as a duplicate, and preserve exactly two messages. Lost-ack retry and mailbox delivery suites passed with it (24 tests).
• Findings:
  • The acceptance run exposed one narrow recovery inconsistency: worker-show could prove an exact worker existed while worker-stop rejected the durable start_unknown state. Explicit stop now enters the same fenced stopping path from ready or start_unknown; unattached, missing, or identity-changed workers still become stop_unknown without a process action.
  • No scheduler, automatic retry, adoption, cleanup, or general distributed-operation framework is needed for this recovery path.
• Next:
  • Exercise duplicate/reordered relay convergence and the native/WSL/SSH transport matrix, then synchronize the HTML proposal with the implemented contract.

2026-07-22 — Cross-platform capability transport verified

• Changes:
  • Added an SSH compatibility-bridge test that carries the opaque Dispatch capability in the RPC envelope and settles only the matching pane/process Dispatch.
  • Added a composed worker-start test that binds the host-resolved orca-ide command and the Dispatch capability into one WSL worker preamble.
  • Updated the built-CLI reset fixture to recreate its required coordinator Run after a task reset.
  • Updated the HTML recovery contract so explicit stop from start_unknown remains fenced and process-identity checked.
• Files:
  • src/main/ssh/ssh-remote-orca-cli.test.ts
  • src/main/runtime/rpc/methods/orchestration-workers-new-worktree.test.ts
  • src/main/runtime/orchestration-cli-subprocess.test.ts
  • docs/orchestration-primitives.html (ignored design source)
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
• Verification:
  • Native macOS Unix-socket worker control, native Windows named-pipe lifecycle reporting, and bidirectional authenticated WebSocket federation passed in the real Mac/Windows matrix.
  • On the real Windows host, the PowerShell/SSH launcher, SSH command allowlist, host passthrough, WSL/native command selection, and multiline Windows quoting suites passed 31 tests; 13 Unix-socket-only runtime-client tests correctly skipped on Windows.
  • Platform-neutral SSH capability, WSL command selection, preamble, worker-start, and CLI envelope suites passed 94 focused tests on macOS.
  • The rebuilt CLI plus every orchestration, composed-worker, federation, and SSH regression file passed together: 25 files and 456 tests. Full Node/CLI/web typecheck, focused oxlint/format, generated-skill verification, and git diff --check passed.
• Findings:
  • The available Windows acceptance host has no WSL distribution installed and prompts to install the feature. Acceptance therefore uses explicit WSL host/path tests rather than mutating the machine. SSH is likewise exercised at the bridge and lifecycle boundary rather than requiring a new external host.
  • Native and relay-backed behavior is real end-to-end evidence; WSL and SSH evidence is bounded to the host-selection, prompt, envelope, quoting, allowlist, and lifecycle contracts Orca owns.
• Next:
  • Run the remaining full validation and Linux CI, then finish the ignored HTML synchronization and PR evidence without adding new orchestration concepts.

2026-07-22 — Phase 3 and cross-platform gates closed

• Changes:
  • Marked connected-server federation and the native cross-platform quality gate complete after branch-head Linux CI joined the real macOS/Windows acceptance evidence.
• Files:
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
• Verification:
  • PR #9925 completed with 17 successful checks and no failures: full Linux verify, Ubuntu and Windows native smoke, packaged Windows crash survival, and macOS/Ubuntu/Windows skill round trips.
  • Linux verify passed lint, generated-skill checks, max-lines enforcement, typecheck, repository- wide tests, unpacked-app build, and packaged CLI smoke.
• Findings:
  • Every implementation phase is now either complete or explicitly deferred with its prerequisite; no additional orchestration subsystem is required for V1.
• Next:
  • Review and merge PR #9925; keep Phase 4 deferred until exact provider-session association exists.

2026-07-22 — Final agent-contract audit

• Changes:
  • Synchronized the ignored HTML examples with the shipped mutation, Delivery, worker-start, and terminal-read result shapes; removed speculative Phase 4 output fields from the V1 path.
  • Made semantic retry explicitly repeat placement and agent/terminal choices, while transport recovery reuses only the exact mutation.requestId after a lost response.
  • Corrected worker state/error terminology, the cross-platform structured completion recipe, and the HTML implementation-status footer.
  • Updated the installed/versioned orchestration guidance to prefer worker-start, use question mail, and reserve low-level dispatch --inject for custom topology.
  • Fixed worker-read --cursor 0; the runtime supported the initial retained-output cursor but the orchestration CLI incorrectly required a positive value.
• Files:
  • src/cli/handlers/orchestration.ts
  • src/cli/handlers/orchestration-worker-cli.test.ts
  • src/cli/specs/orchestration-worker-specs.ts
  • skill-guides/orchestration.md
  • skills/orchestration/SKILL.md
  • generated bundled skill guide and skill-bundle manifests
  • docs/orchestration-primitives.html (ignored design source)
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
• Verification:
  • Focused worker CLI suite passed 3 tests, including cursor zero.
  • Final orchestration runtime/CLI/renderer/skill regression set passed 24 files and 450 tests.
  • Node, CLI, and web typechecks, bundled-guide and skill-manifest verification, focused formatting, and git diff --check passed.
  • A repository-wide run reached 34,190 passing tests and exposed the one intentionally changed skill assertion; after updating that assertion, the focused configured rerun above passed. The broad run also exhausted several Vitest fork-start deadlines under full local concurrency, while the previously green PR checks remain the authoritative clean full-suite baseline.
• Findings:
  • The implementation already returned durable request IDs as mutation.requestId; the remaining problem was stale naming and invented provenance fields in the ignored design example.
  • Stored start options are recovery evidence, not implicit replacement policy. Requiring explicit replacement placement keeps agents in control and avoids recreating a possibly-existing remote worktree by accident.
  • No new scheduler, retry engine, output adapter, projection layer, or federation subsystem is needed. Phase 4 remains deferred.
• Next:
  • Push the audit corrections and confirm PR #9925 is green at the new head.

2026-07-22 — CodeRabbit and internal review until clean

• Changes:
  • Validated every CodeRabbit finding; fixed relay type validation, stale runtime-owned terminal identity, setup receipt classification, Windows batch percent escaping, worker reconciliation, root-help discovery, canonical question schema, and deterministic waiter timing.
  • Coalesced overlapping per-Dispatch federation polls and added one warning per outage window.
  • Centralized the orchestration RPC envelope type without adding a new runtime abstraction.
  • Made reset scopes atomic and cleared matching worker/federation state while preserving relay cursors for message-only resets and the mutation ledger needed for lost-response deduplication.
• Files:
  • orchestration runtime, federation, worker-control, database, CLI help/client, wrapper, skill, and focused regression tests listed in the current working diff.
• Verification:
  • Focused runtime, federation, database, CLI, SSH, wrapper, and skill suites passed 1,103 tests.
  • The repository-wide configured suite passed 34,253 tests with 58 intentional skips.
  • Node, CLI, and web typechecks passed; focused oxlint, formatting, generated-skill checks, and git diff --check passed.
• Findings:
  • The type-only pairing import is valid TypeScript and remains type-only; Dispatch capability flags stay intentionally hidden because the authenticated worker preamble supplies them.
  • Persistent envelope-bearing WebSocket reuse remains a measured-later optimization; the V1 single-flight relay removes overlapping connection churn without growing transport scope.
  • The final re-review found no remaining in-scope correctness, ergonomics, elegance, or performance defect after fixing reset scope and relay-cursor preservation in round 2.
  • Full lint reaches unrelated existing failures in the unchanged skill-freshness switch and localization catalog; changed-file lint and every in-scope quality gate pass.
• Next:
  • Resolve CodeRabbit threads and confirm the PR checks at the final head.

2026-07-24 — Post-rebase physical federation dogfood

• Changes:
  • Rebased the branch onto current main and launched isolated branch-head desktop runtimes on the Mac Run home and the physical Windows worker server.
  • Started a real Windows Codex worker in a new top-level worktree with explicit setup-run.
  • Replaced the orchestration process fence's renderer generation with the controller-issued PTY incarnation when available, retaining the prior value only for legacy providers.
  • Added a runtime regression covering a visible terminal surface detaching and reattaching around the same process, followed by a replacement incarnation.
• Files:
  • src/main/runtime/orca-runtime.ts
  • src/main/runtime/orca-runtime.test.ts
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
• Verification:
  • The remote start returned ready in about nine seconds with setup running, startupPolicy=start-immediately, one agent terminal, one setup terminal, and accepted task input.
  • The original branch head then reproduced immediate identity_changed: routed read failed and the exact injected capability could not send a heartbeat or question.
  • The new focused process-identity regression passed, the 18-test federation suite passed, and Node typecheck passed.
• Findings:
  • A renderer pane generation is presentation state, not process identity. A healthy PTY can move between a runtime-owned background surface and the renderer without losing Dispatch authority.
  • The PTY controller incarnation is already available on native Windows/macOS and SSH/relay paths; using it fixes the race without relaxing replacement-process fencing or adding a new identity subsystem.
• Next:
  • Rebuild both branch runtimes, repeat the full physical Mac-to-Windows lifecycle, then run the remaining local error/recovery matrix before closing the revalidation rows.

2026-07-24 — Post-fix physical federation revalidation

• Changes:
  • Rebuilt and restarted the physical Windows branch runtime from b09c635ec, then repeated the Mac Run-home to Windows-worker flow on a fresh top-level worktree.
  • Abandoned the controlled stale-build attempt, linked the replacement with --retry-of, and exercised exact start-request replay plus exact remote worker stop.
  • Exercised missing-agent and invalid-remote-repo rejection without adding recovery automation.
• Verification:
  • The replacement returned ready while setup was running under start-immediately; worker-show reported the exact running process, bounded worker-read succeeded, and the worker's heartbeat reached the Mac Run home.
  • An inferred-Run blocking question carried the blue reply back to Windows, and the authenticated success report atomically settled the Task and Dispatch.
  • A transient connection close before acceptance left the second Task ready with no Dispatch. Retrying its exact request ID started one worker, and repeating that request returned the same Dispatch with replayed=true and no duplicate worktree or terminal.
  • worker-stop killed only the exact agent PTY. The setup terminal remained present, the Dispatch became stopped/failed, and the Task became blocked for explicit recovery.
  • An unconfigured agent failed locally. A missing remote repo produced a typed failed Dispatch with effects=[] and no residual resources.
• Findings:
  • The first repeated failure was a stale Windows build artifact, not a failed fix: the source checkout was at b09c635ec while out/main/index.js still had the old generation fence. Relaunching the branch dev process produced a new runtime epoch and the fixed behavior.
  • Omitted setup correctly resolved to Orca's run default. Its independent Windows install later failed in windows-native-registry, but that did not delay task delivery and remained isolated from exact agent stop.
  • From an unmanaged shell, a coordinator mailbox check must name --terminal; a CLI running inside the bound coordinator terminal continues to infer that identity normally.
• Next:
  • Resolve only concrete findings from the independent ergonomics/federation re-review, run the final local verification set, and reconcile PR review threads and CI.

2026-07-24 — Post-dogfood recovery and ergonomics hardening

• Changes:
  • Made lost remote stop responses reconcilable and prevented stale Dispatch abandonment from blocking an active replacement.
  • Persisted setup completion as evidence only, preserving settled lifecycle state locally and relaying the same outcome from a connected worker server.
  • Rejected misleading explicit targets from federated workers and consumed ask answers exactly once while retaining their durable thread record.
  • Stored the accepted Dispatch in pending worker-start receipts so a post-restart retry returns the exact inspection command.
  • Rejected new-worktree placement for folder projects before effects.
  • Restored the generated skill-history ledgers that the branch had accidentally truncated.
• Verification:
  • The full orchestration DB/RPC/CLI/SSH regression selection passed 516 tests; its focused recovery, setup, messaging, and mutation slice passed 239 tests.
  • The earlier physical Mac-home to Windows-worker lifecycle covered ready/read/heartbeat, ask/reply, completion, exact request replay, and exact stop.
• Findings:
  • These were narrow truthfulness and recovery gaps; none required a scheduler, automatic retry, access-control framework, replicated Run database, UI, or provider-session abstraction.
  • The release-contract test failure is already present on main; it is separate from this orchestration change. The skill round-trip failures were branch-caused and are fixed by restoring their committed history.
• Next:
  • Run the complete changed-file quality gates, rebuild the physical Windows dev runtime with this final patch, repeat the setup-status slice, then push and recheck PR CI/review state.

2026-07-24 — Physical receipt follow-up

• Changes:
  • Made local and connected-server ready transitions persist the accepted dispatch_input effect atomically, so later setup evidence cannot replace it with an older effect snapshot.
  • Carried the already-resolved setup source through the internal federation attach request, keeping omitted setup labeled orchestration_default and explicit setup labeled explicit_request.
• Verification:
  • The focused new-worktree, federation, and setup-evidence slice passed 37 tests.
  • The broader orchestration DB/RPC/CLI/SSH execution-host selection passed 630 tests.
  • Node and CLI typechecks, changed-file lint/format, and git diff --check passed.
• Findings:
  • Both defects were receipt-provenance bugs found by the physical Mac-home to Windows-worker run; neither changes worker placement, setup timing, lifecycle authority, or agent-facing commands.
• Next:
  • Rebuild both dev runtimes from this patch and repeat the physical setup-status slice before final PR reconciliation.

2026-07-24 — Truthful setup command completion

• Changes:
  • Wrapped only orchestration-created non-gating setup commands with a private per-invocation completion signal that preserves the command exit code.
  • Added one runtime observer that subscribes to raw PTY output, replays the bounded recent-output buffer, scans across chunk boundaries, and treats terminal exit as a fallback.
  • Updated local and connected-server setup evidence monitors to observe command completion while leaving the interactive setup terminal open.
  • Propagated the exact setup terminal handle through worktree receipts and hardened native Windows launch with an encoded PowerShell command plus an environment-carried runner path.
• Files:
  • src/main/runtime/orchestration/setup-completion-signal.ts
  • src/main/runtime/orca-runtime.ts
  • local and federation setup monitors and focused tests
  • ORCHESTRATION_IMPLEMENTATION_CHECKLIST.md
• Verification:
  • The completion helper, exact-effect, local worker, federation, and setup-evidence suites passed 43 tests.
  • Focused runtime tests proved live completion, replay-before-observer recovery, and opt-in setup wrapping while the shell remains running.
  • The complete runtime service suite passed 884 tests.
  • The broader orchestration/CLI/SSH/execution-host selection passed 529 tests.
  • Node, CLI, and web typechecks, the CLI/Electron build, focused lint/format, max-lines ratchet, and git diff --check passed.
  • The independent no-scope-creep recheck found no remaining correctness blocker.
• Findings:
  • Terminal exit is not setup-command completion because Orca intentionally runs setup in an interactive terminal that returns to a shell prompt.
  • Display titles are not terminal identity, and a disconnected terminal is not proof that its setup command failed.
  • The correction is runtime evidence only: it adds no public flag, setup job, scheduler, retry policy, process heuristic, or automatic tab closure.
• Next:
  • Rebuild both dev runtimes and repeat the physical Mac Run-home to Windows-worker setup-status slice, including a failing setup command that returns to a PowerShell prompt.

2026-07-24 — Physical Windows setup-completion proof

• Changes:
  • Rebuilt and restarted the Mac Run-home and physical Windows worker runtimes from 4aba390af.
  • Started a fresh Windows Codex worker from the Mac with omitted --setup, a new top-level worktree, and the exact Windows repo selector.
• Verification:
  • Mac runtime epoch 4a2a1cba-fd8b-41c7-b50b-caeac7415d9c and Windows runtime epoch 04cecad3-65a9-49a5-90ff-cdf04b09050f both became ready after restart.
  • Run run_0f6b471005af, Task task_11e981c692b5, and Dispatch ctx_f009a65c6d9d returned ready with setup running, source orchestration_default, policy start-immediately, the exact setup terminal term_bdcb2a0b-89c5-429c-8ae6-0fdc2457db15, and accepted dispatch input.
  • The real Windows setup command later exited 1 in windows-native-registry; worker-show changed setup to failed while preserving the succeeded worker, settled Dispatch, accepted input effect, and exact setup-terminal effect.
  • The setup terminal remained running and accepted a follow-up PowerShell command after failure. The Run mailbox contained exactly one high-priority setup-failed notice for the Dispatch.
• Findings:
  • The private per-invocation marker carried exit code 1 in raw setup-terminal output and did not appear in orchestration receipts or lifecycle messages.
  • Windows terminal reads still flatten PowerShell line-editor redraws into noisy repeated input text. The command executed once and orchestration state remained correct, so this pre-existing rendering artifact stays outside this PR.
• Next:
  • Re-run the final local quality gates, push this evidence-only checklist update, and reconcile PR CI and review state.

2026-07-24 — Structured worker-output implementation

• Changes:
  • Extended worker-read with auto|transcript|terminal source selection while preserving one Dispatch-only agent command.
  • Added exact pane/process/session selection from existing hook evidence, bounded Codex/Claude transcript reading, path-free source identities, and opaque source-pinned cursors.
  • Added a worker-local federated output RPC; mixed-version servers fall back through the existing terminal-read method and still receive an opaque Run-home cursor.
  • Added readable non-JSON transcript rendering, CLI help, skill guidance, typed errors, and malformed/oversized/clipping warnings.
• Files:
  • src/shared/orchestration-worker-output.ts
  • src/main/runtime/orchestration/worker-output-cursor.ts
  • src/main/runtime/orchestration/worker-provider-session.ts
  • src/main/runtime/orchestration/worker-transcript-payload.ts
  • src/main/runtime/orchestration/worker-transcript-read.ts
  • src/main/runtime/rpc/methods/orchestration-worker-output.ts
  • Worker control/federation, runtime status lookup, CLI, skill, design, and focused tests
• Verification:
  • Node and CLI typechecks passed.
  • Nineteen native-chat/structured-output suites passed 142 tests.
  • Sixteen orchestration CLI/RPC/federation suites passed 289 tests.
  • Five CLI registry/help/runtime-error suites passed 213 tests.
  • Mixed-version fallback continuation was additionally verified with an opaque cursor.
• Findings:
  • The prior Phase 4 deferral was factually wrong: hook snapshots already bind provider sessions to exact panes. Reusing that evidence avoids directory/title/logo guessing and avoids a second status subsystem.
  • Method probing is enough for mixed-version compatibility; a generalized provider capability matrix is unnecessary.
• Next:
  • Run the remaining full lint/test gates and the physical local plus Mac/Windows dogfood matrix before marking Phase 4 complete.

2026-07-24 — Structured-output local and mixed-version dogfood

• Changes:
  • Ran two simultaneous same-worktree Codex Dispatches with unique markers and verified exact transcript isolation plus opaque continuation.
  • Made transcript-position fallback IDs opaque after the physical response exposed the local Codex JSONL path.
  • Redacted pane-bound Dispatch capability tokens from structured prose, tool input, tool output, metadata, and image URLs after continuation exposed the lifecycle send command.
  • Corrected worker-read --help so --cursor is described as opaque rather than numeric.
  • Made forward paging advance safely across a transcript record larger than the bounded scan window, while continuing to discard its unfinished fragments.
  • Extended Dispatch-capability redaction to tool-input object keys as well as values.
• Verification:
  • Both simultaneous local reads selected different exact Codex source identities and contained only their own marker.
  • Continuation returned newly appended tool/assistant messages, limited=true, and the expected completion marker.
  • A fresh local response contained stable worker-message-* IDs, no .codex/sessions path, no dcap_ token, and explicit privacy/redaction warnings.
  • Starting a new Codex chat in the same pane caused the old cursor to return source_changed; a fresh read selected only the new chat marker.
  • Restarting the Run-home runtime preserved settled state and rejected a read when the exact worker process was no longer present.
  • Mac Run home -> older Windows worker returned source=terminal, fallbackReason=remote_capability_unavailable, an opaque cursor that continued successfully, and transcript_required when structured output was explicitly required.
• Findings:
  • Synthetic path-leak tests need fallback-ID records, not only provider records with explicit IDs.
  • Structured output must treat lifecycle capability text as secret even though the capability is also pane-bound; redaction is a narrow output boundary, not a generalized secret scanner.
  • Additive RPC probing works against the physical older Windows server without a capability matrix or server upgrade gate.
  • A bounded scan must still guarantee cursor progress; otherwise one pathological provider record can trap an agent in a valid-looking continuation loop.
• Next:
  • Commit/push the tested implementation, update the physical Windows dev runtime, then run exact Mac-to-Windows and Windows-to-Mac structured reads plus disconnect/reconnect.

2026-07-24 — Reverse dogfood found missing coordinator control mail

• Finding:
  • A Windows Run home successfully started and read an exact Mac Codex worker, and worker-to-home status relayed correctly. However, coordinator mail addressed to that remote worker remained queued at the Run home because only question replies used the home-to-worker relay.
  • The injected worker's local check --wait also looked only for a same-server Dispatch, so even an imported generic message could not wake it.
• Changes:
  • Route stable dispatch:<id> coordinator guidance through the existing per-Dispatch durable relay; terminal-handle targeting remains a legacy/local path.
  • Import control mail idempotently on the worker server, tolerate a replay after a lost import acknowledgment, and wake only the exact attached worker process.
  • Return a direction-aware relay receipt and teach CLI help, the versioned skill, and the cross-server cookbook to use the Dispatch ID for follow-ups.
• Verification:
  • Focused Node/CLI typechecks and 184 orchestration/federation/CLI tests passed before physical revalidation.
• Next:
  • Regenerate the bundled skill guide, re-review the narrow change, then repeat Windows-home to Mac-worker follow-up, completion, exact transcript continuation, and disconnect/reconnect.

2026-07-24 — Federated control-mail race hardening

• Changes:
  • Fence already-imported relay sequences before parsing or applying message side effects.
  • Require the remote attachment to remain ready before accepting each new coordinator message.
  • Recheck the Run-home worker state after importing worker lifecycle mail and do not push queued guidance after the worker settles.
  • Wake filtered worker waiters with the imported message's real type instead of always using status.
  • Negotiate a narrow control-mail capability and reject the send before queueing when an older worker server supports base federation but not the new relay kind.
• Verification:
  • Regression tests prove a replayed sequence with a different message ID creates no duplicate.
  • A waiter registered before worker_done receives no stale control mail after completion, and a direct late import is rejected as inactive.
  • An imported escalation wakes an escalation-filtered waiter while a status-filtered waiter times out normally.
  • A new Run home connected to a prior worker build can still start the worker, but control mail returns capability_unsupported and leaves no undeliverable relay row.
  • The focused federation suites passed 24 tests; the broader orchestration/CLI selection passed 475 tests.
  • Full typecheck, lint, bundled-skill verification, CLI build, Electron/Vite build, git diff --check, and the design-document reference-name audit passed.
• Findings:
  • Relay ordering and worker settlement are control-plane guardrails, not agent policy: the coordinator still chooses what to send and when.
  • Terminal worker state is authoritative for delivery; queued guidance is retained at the Run home but never injected into a completed worker.
• Next:
  • Complete the final read-only review, then repeat the physical Windows-home to Mac-worker follow-up, completion, exact transcript continuation, and disconnect/reconnect proof.

2026-07-24 — Physical control-mail acceptance and dogfood fixes

• Changes:
  • Restarted the physical Windows runtime from branch head and confirmed both federation capabilities before creating a fresh Windows-home Run.
  • Fixed check --ack <delivery> --peek so the exact Delivery is acknowledged before the read-only history projection; the previous early return silently ignored --ack.
  • Preserved the existing structured remote transport codes through the Run-home RPC boundary instead of collapsing disconnect, timeout, and malformed-response failures to runtime_error.
• Verification:
  • Run run_074503e3edc6, Task task_8a07840e7aad, and Dispatch ctx_d6bac1ee6409 started a fresh Codex worker in the existing Mac worktree with setup not_applicable.
  • The worker relayed ORCA_MAC_CONTROL_INITIAL_7C31, blocked on its Dispatch inbox, received coordinator guidance addressed to the stable Dispatch as ORCA_MAC_CONTROL_FOLLOWUP_A842, and returned one authenticated successful worker_done containing both markers.
  • The Windows home settled the Task and Dispatch once. worker-read --source auto returned source=transcript, provider=codex, an opaque cursor, both markers, and no capability token or transcript path.
  • Removing the Mac listener left the Windows Task completed. Reconnecting with the wrong leftover profile was rejected as unauthorized; reconnecting with the original profile preserved the settled Dispatch and correctly returned worker_identity_changed for transcript reads after the exact worker process was gone.
  • The focused RPC suites passed 163 tests; formatting, diff checks, full typecheck, CLI build, and desktop/web builds passed.
  • After the Windows generated main bundle was verified at 8dd0d1b16, Delivery delivery_888f972841d6 was acknowledged by check --ack ... --peek; the response echoed the exact acknowledged ID and returned zero unread rows.
  • With that build running, removing the Mac listener returned remote_runtime_unavailable while the Task stayed completed. Reconnect preserved the succeeded Dispatch, produced no duplicate Run mail, and returned worker_identity_changed rather than attributing the old transcript to a replacement process.
• Findings:
  • Delivery acknowledgment must compose with inspection modes explicitly; a successful command may not silently ignore the acknowledgment effect.
  • Remote transport already had narrow error codes. Preserving them is enough; no federation error hierarchy or retry engine is needed.
  • Saved peer identity fencing prevented accidental adoption of a server started from a different profile. Exact process fencing also prevented stale transcript attribution after restart.
  • On the Windows dogfood shell, the pnpm wrapper returned before its spawned Vite build completed. Verifying the generated bundle before restart exposed the race; invoking the Node build script directly produced the expected branch-head bundle.
• Next:
  • Run the final quality gates and review, push this evidence update, inspect PR CI, and remove only the temporary dogfood profile and listener after verification is complete.

2026-07-24 — Current-main rebase integration

• Changes:
  • Rebased the full implementation onto current origin/main.
  • Combined main's bounded one-shot remote-request admission with the orchestration authentication envelope in the same pre-serialized encrypted request.
  • Added a direct WebSocket regression proving the admitted request retains the orchestration capability and mutation ID.
• Verification:
  • The repository-configured orchestration, federation, remote-client, and skill selection passed 35 files and 465 tests.
  • Full Node/CLI/web typecheck, lint/reliability/manifest/localization gates, focused formatting, generated-skill verification, and git diff --check passed after the rebase.
  • Relay, CLI, Electron/Vite, and web production builds passed. The local CLI installer reported only the expected non-fatal lack of permission to replace /usr/local/bin/orca-dev.
• Findings:
  • The request must be serialized with its authentication envelope before it reserves bounded admission; rebuilding the frame after authentication would bypass the retained-byte contract.
• Next:
  • Push the rebased branch, inspect branch-head CI, then remove only the exact temporary dogfood resources.

2026-07-24 — Structured-output proposal synchronization

• Changes:
  • Updated the newer HTML proposal from its obsolete terminal-only Phase 4 deferral to the shipped auto|transcript|terminal contract.
  • Documented exact pane/process/session selection, opaque source-pinned cursors, labeled fallback, mixed-version behavior, and the implemented Phase 4 status.
• Verification:
  • Confirmed the proposal contains no named references to other orchestration products.
• Findings:
  • Implementation status and optional remaining physical acceptance are separate: the narrow output primitive is complete, while symmetric cross-machine dogfood remains visible in this ledger.
• Next:
  • Run document/skill checks, push the synchronization fix, resolve the review thread, and continue branch-head CI monitoring.

2026-07-25 — Physical Grok and OpenCode provider dogfood

• Changes:
  • Reused Native Chat's existing Grok session resolver and transcript decoder in worker-read.
  • Kept OpenCode on the generic terminal fallback because Native Chat has no OpenCode transcript decoder.
  • Applied Dispatch-capability redaction to terminal fallback lines as well as structured transcript blocks.
  • Updated the agent-facing skill and proposal to name the current structured provider set.
• Verification:
  • An isolated branch-head server started fresh same-worktree Grok and OpenCode workers through worker-start; both accepted their injected tasks and returned authenticated successful worker_done reports.
  • Grok returned source=transcript, provider=grok, the exact marker, opaque message IDs and cursor, and no capability token or transcript path.
  • OpenCode returned source=terminal, fallbackReason=provider_unsupported, the exact marker, and a source-pinned opaque cursor; explicitly requiring a transcript returned transcript_required.
  • The first OpenCode read exposed its pane-bound Dispatch capability in terminal text. After the fix and a clean runtime rebuild, the repeated physical read replaced it with [dispatch capability redacted], emitted an explicit warning, and contained no raw token.
  • Focused Native Chat/orchestration output tests passed 49 tests and Node typecheck passed.
• Findings:
  • Provider support and structured-output support remain separate: OpenCode orchestration is fully usable without inventing an OpenCode transcript adapter.
  • Terminal fallback is an orchestration output boundary and needs the same narrow secret redaction as structured output; this does not change direct terminal-read behavior.
• Next:
  • Run the complete orchestration regression selection and repository quality gates, then commit and push the provider dogfood fixes.

2026-07-25 — CI ask-admission fixture correction

• Changes:
  • Updated the WebSocket long-poll admission tests to place each simulated asking worker in a real Run with an active supervised Dispatch.
  • Kept the production rule that unsupervised workers cannot create blocking questions.
• Verification:
  • The complete runtime RPC test file passed 59 tests.
  • The broader orchestration/RPC/CLI selection passed 23 files and 391 tests.
  • Node typecheck and git diff --check passed.
• Findings:
  • The red CI assertions were stale test setup: old arbitrary terminal handles now fail orchestration.ask before holding an admission slot, exactly as the new contract requires.
• Next:
  • Push the test-only correction and confirm the replacement PR check is green.

2026-07-26 — Hard orchestration contract cutover

• Changes:
  • Added one shared orchestration contract version, runtime capability, and mutation classifier.
  • Fenced old, missing, and wrong-contract mutations before parsing, durable receipts, database writes, process actions, prompt injection, and connected-server effects.
  • Propagated the contract through Unix/named-pipe, WebSocket, connected-server, and SSH CLI transports, with capability preflight before local or federated mutations.
  • Retired the legacy scheduler commands locally and at RPC dispatch, preserving only explicit read-only legacy inspection.
  • Returned no-effects plus argument-only full-skill recovery and documented that pre-upgrade worker processes continue unsupervised until inspected.
• Verification:
  • Focused orchestration/federation selection: 56 files and 721 tests passed.
  • Repository suite excluding the independently reproducible system-SSH native-installer timeout: 3,479 files and 37,181 tests passed.
  • Node, CLI, and web typechecks passed.
  • Relay, CLI, Electron/Vite, and web production builds passed.
  • Bundled-skill verification, reliability gates, max-lines ratchet, and git diff --check passed.
  • The newer tracked HTML contains no named references to the audited orchestration projects; the older redesign HTML remains ignored and untracked.
• Findings:
  • A hard version fence plus executable skill recovery is simpler and safer than maintaining a legacy executor or draining in-flight legacy state.
  • Existing pre-upgrade processes are deliberately left alive, but rejected lifecycle calls cannot mutate current Task, Dispatch, or inbox state.
  • Full lint still reports the pre-existing localization audit for six unchanged Ghostty keyword strings; the excluded system-SSH test independently times out while installing native dependencies. Neither baseline issue is changed by this migration.
• Next:
  • Commit and push as OrcaWin, then inspect branch-head CI and mark the final remote acceptance item only after those checks settle.

2026-07-27 — Current-main rebase and CLI registry integration

• Changes:
  • Rebased the 26 orchestration commits onto current origin/main.
  • Preserved both main's active-worktree plugin context and orchestration's terminal process incarnation and launcher validation in their one overlapping runtime conflict.
  • Registered the current Run, worker, and retired-coordinator handler keys in main's new lazy CLI handler-group manifest.
  • Removed one trailing-whitespace artifact from the structured-output design header.
• Verification:
  • Conflict-focused runtime, federation, migration, and transport selection: 6 files and 995 tests passed.
  • Handler manifest, registry parity, and CLI integration: 3 files and 169 tests passed.
  • Repository suite excluding the independently reproducible system-SSH native-installer timeout: 3,586 files and 37,864 tests passed.
  • Node, CLI, and web typechecks, bundled-skill verification, reliability gates, max-lines ratchet, and conflict-marker audit passed.
• Findings:
  • The rebase itself had one additive method-placement conflict; neither behavior needed redesign.
  • Main's lazy handler manifest is an additional command-registration source of truth, so every new exported orchestration handler must be listed there.
  • Tests added on main depend on newly patched packages; refreshing from the rebased lockfile was required before their results were meaningful.
• Next:
  • Push the rebased branch as OrcaWin and inspect replacement branch-head CI.

Entry template

### YYYY-MM-DD — Short implementation milestone

- Changes:
  - ...
- Files:
  - `path`
- Verification:
  - command/test and result
- Findings:
  - decision, surprise, or risk
- Next:
  - one concrete next step