diff --git a/.yoi/tickets/00001KVWSQM22/artifacts/orchestration-plan.jsonl b/.yoi/tickets/00001KVWSQM22/artifacts/orchestration-plan.jsonl new file mode 100644 index 00000000..8060ca34 --- /dev/null +++ b/.yoi/tickets/00001KVWSQM22/artifacts/orchestration-plan.jsonl @@ -0,0 +1 @@ +{"id":"orch-plan-20260624-190611-1","ticket_id":"00001KVWSQM22","kind":"accepted_plan","accepted_plan":{"summary":"Ticket `00001KVWSQM22` は implementation_ready as a design/planning artifact。専用 worktree `/home/hare/Projects/yoi/.worktree/00001KVWSQM22-backend-orch-runtime` と branch `work/00001KVWSQM22-backend-orch-runtime` で、Backend internal Orchestrator runtime / Kanban durable orchestration event / WorkerRuntime registry identity and spawn-intent boundary を明文化する。Backend internal Orchestrator の full implementation や direct filesystem authority は non-goal。","branch":"work/00001KVWSQM22-backend-orch-runtime","worktree":"/home/hare/Projects/yoi/.worktree/00001KVWSQM22-backend-orch-runtime","role_plan":"Orchestrator: routing acceptance, worktree creation, final integration/validation/cleanup. Coder: design/planning implementation in dedicated child worktree, producing maintained design documentation and any minimal code/test updates needed to align existing Workspace runtime/Panel queue boundaries. Reviewer: read-only review against recorded IntentPacket, focusing on authority boundaries, durable event semantics, runtime identity, and non-goals."},"author":"yoi-orchestrator","at":"2026-06-24T19:06:11Z"} diff --git a/.yoi/tickets/00001KVWSQM22/item.md b/.yoi/tickets/00001KVWSQM22/item.md index 9468721c..63109c21 100644 --- a/.yoi/tickets/00001KVWSQM22/item.md +++ b/.yoi/tickets/00001KVWSQM22/item.md @@ -1,8 +1,8 @@ --- title: 'Backend internal Orchestrator runtime for Kanban operations' -state: 'queued' +state: 'done' created_at: '2026-06-24T12:29:58Z' -updated_at: '2026-06-24T19:04:55Z' +updated_at: '2026-06-24T19:15:42Z' assignee: null queued_by: 'workspace-panel' queued_at: '2026-06-24T19:04:55Z' diff --git a/.yoi/tickets/00001KVWSQM22/thread.md b/.yoi/tickets/00001KVWSQM22/thread.md index 52d878a9..9c1bd481 100644 --- a/.yoi/tickets/00001KVWSQM22/thread.md +++ b/.yoi/tickets/00001KVWSQM22/thread.md @@ -30,4 +30,228 @@ Marked ready by `yoi ticket state`. Ticket を `workspace-panel` が queued にしました。 +--- + + + +## Decision + +Routing decision: implementation_ready + +Reason: +- Dashboard Queue により人間が Orchestrator routing を許可した queued Ticket として確認した。 +- Ticket body は Backend internal Orchestrator runtime / Kanban operation / durable orchestration event / WorkerRuntime registry identity / spawn intent / session overview boundary / safety authority を具体的に列挙している。 +- `TicketRelationQuery` は blocking relation 0 件、routing 前 `TicketOrchestrationPlanQuery` は既存 plan 0 件だった。 +- Ticket の受け入れ条件は「planning artifact を明文化する」性質であり、Backend internal Orchestrator の full implementation は non-goal と明記されている。したがって Coder に実装詳細を固定させるのではなく、maintained design/planning document と必要最小限の boundary alignment を作る task として bounded に進められる。 +- risk flags 相当の domain は orchestration authority / runtime identity / durable event / raw session boundary だが、Bash/raw filesystem/raw socket/raw session ingest を authority にしない、`queued -> inprogress` acceptance を守る、Browser が raw local path を渡さない、という invariant が明示されている。risk は reviewer focus と escalation condition に反映すればよく、planning return 理由にはならない。 +- 現在 inprogress Ticket は 0 件、orchestration worktree は clean。既存 worktree は unrelated paused Ctrl-X cancel worktree のみで、この Ticket の branch/worktree はまだ無い。 + +Evidence checked: +- Ticket body / thread: `item.md`, `thread.md`。thread は create、planning->ready、ready->queued のみで未解決 blocker は記録されていない。 +- Relations / orchestration plan: relation 0 件、routing 前 plan 0 件。accepted plan `orch-plan-20260624-190611-1` を記録済み。 +- Workspace/code context: recent Worker runtime registry / spawn boundary work in `crates/workspace-server/src/hosts.rs`, `crates/workspace-server/src/server.rs`; Dashboard/Kanban queue surface in `crates/tui/src/dashboard/mod.rs`; docs/design structure under `docs/design/`。 +- Workspace state: `/home/hare/Projects/yoi/.worktree/orchestration` は clean。visible Pods は current Orchestrator と stopped/restorable historical role Pods only, active child work is none。 + +IntentPacket: + +Intent: +- Kanban UI operation を Backend internal Orchestrator Worker へ安全に接続するための design/planning artifact を作る。Kanban operation は durable orchestration event として記録され、internal Orchestrator は domain-specific tools で event を処理し、実 filesystem-capable work は local/remote runtime 上の Coder/Reviewer/helper Worker へ委譲する境界を明確にする。 + +Binding decisions / invariants: +- Kanban click / API request から Backend process が直接 shell/git/filesystem を実行しない。 +- implementation side effect 前には既存 Ticket lifecycle authority、特に `queued -> inprogress` acceptance と decision record を保持する。 +- `ready -> queued` は Orchestrator routing human gate として扱い、unattended scheduler にしない。 +- Browser は raw local path / socket path / runtime registry path / raw session path / executable path を authority として渡さない。 +- UI display は `worker-name@runtime-name` 形式を使ってよいが、API authority にはしない。 +- canonical API identity は `runtime_id` + `worker_id` の runtime-scoped opaque id とする。 +- DB design は surrogate worker record id + `UNIQUE(runtime_id, worker_id)` を優先候補とし、run overview / lifecycle event / usage aggregate 参照に使える形にする。 +- Backend durable projection は raw transcript 全量ではなく overview / decision / lifecycle / usage aggregate を中心にする。raw session/provider trace は runtime-local source/debug log として bounded read に留める。 +- Backend internal Orchestrator の full implementation、Kanban UI completion、remote protocol、raw session full DB ingest、Ticket DB migration、permission/auth completion は non-goal。 + +Requirements / acceptance criteria: +- Kanban operation から durable orchestration event を生成する方針が明文化される。 +- Backend internal Orchestrator Worker の責務 / non-responsibility、domain-specific tool/operation surface、failure/blocker/retry/event ack semantics が整理される。 +- WorkerRuntime registry と spawn intent の接続方針が明記される。 +- runtime/worker identity, display label, DB identity, event and overview projection boundaries が明確化される。 +- filesystem-capable work は runtime 上の Coder/Reviewer/helper Worker に委譲する方針が明記される。 +- existing docs/code organization に沿って maintained design artifact が置かれる。 + +Implementation latitude: +- Primary output は docs/design などの maintained design document でよい。必要に応じて README/index や small comments/tests を追加してよい。 +- 既存 Workspace runtime registry / spawn boundary の code names に合わせて wording を調整してよい。 +- Full backend implementation や new DB schema migration はしない。 + +Escalate if: +- Backend process が direct shell/git/filesystem authority を持つ設計にしないと要件を満たせない。 +- raw session full ingest / raw socket path / raw workspace path を API authority にする必要が出る。 +- `ready -> queued` の human gate を scheduler/lease に置き換える必要が出る。 +- API canonical identity を display label や raw Pod name に寄せる必要が出る。 +- Ticket DB migration / permission-auth model completion / remote runtime protocol をこの Ticket で固定する必要が出る。 + +Validation: +- `git diff --check` +- docs-only なら `cargo fmt --check` は不要だが、Rust/comments/tests を触るなら `cargo fmt --check` と relevant `cargo check` / `cargo test` を実施する。 +- If `crates/workspace-server` is touched: `cargo test -p yoi-workspace-server` and `cargo check -p yoi`。 + +Current code/docs map: +- Primary docs: `docs/design/` and docs index/README if appropriate。 +- Context code: `crates/workspace-server/src/hosts.rs`, `crates/workspace-server/src/server.rs`, `crates/tui/src/dashboard/mod.rs`。 +- Avoid: root/original workspace operations, broad scheduler implementation, Kanban UI completion, remote Host protocol, raw session DB ingest, Ticket storage migration。 + +Critical risks / reviewer focus: +- accidental scheduler/lease semantics。 +- Backend internal Orchestrator gaining raw shell/filesystem/socket authority。 +- display labels becoming API authority。 +- runtime workspace root / process cwd / worker id / DB surrogate id confusion。 +- raw session/provider trace becoming Backend durable projection instead of bounded debug source。 +- design doc that repeats Ticket text without resolving event/ack/failure/spawn-intent boundaries. + +Next action: +- `queued -> inprogress` を記録してから worktree-workflow で `/home/hare/Projects/yoi/.worktree/00001KVWSQM22-backend-orch-runtime` を作成し、multi-agent-workflow で Coder/Reviewer sibling loop に進める。 + +--- + + + +## State changed + +Orchestrator acceptance: queued -> inprogress + +- 直前確認で `TicketShow` は state `queued`、blocking relation は 0 件、accepted plan `orch-plan-20260624-190611-1` を確認した。 +- routing decision と IntentPacket は Ticket thread に記録済み。 +- `00001KVWSQM22` は planning/design artifact として implementation-ready であり、Backend internal Orchestrator の full implementation は non-goal として明示した。 +- これ以降に worktree-workflow で `/home/hare/Projects/yoi/.worktree/00001KVWSQM22-backend-orch-runtime` を作成し、multi-agent-workflow に接続する。 + +--- + + + +## Implementation report + +Implementation orchestration update: + +- worktree-workflow に従い、implementation worktree `/home/hare/Projects/yoi/.worktree/00001KVWSQM22-backend-orch-runtime` と branch `work/00001KVWSQM22-backend-orch-runtime` を作成した。 +- child worktree では tracked `.yoi` project records を見える状態にし、`.yoi/memory`、local/runtime/log/lock/secret-like `.yoi` paths を sparse-checkout で除外する方針にした。 +- Coder Pod `yoi-coder-00001KVWSQM22-backend-orch-runtime` を sibling として起動した。write scope は child worktree に限定し、runtime workspace root `/home/hare/Projects/yoi` は startup 要件を満たすため non-recursive read のみにした。 +- Coder には root/original workspace と orchestration worktree で read/write/validation/git operation を行わないよう明示した。 +- この Ticket は full implementation ではなく design/planning artifact として進める。 + +--- + + + +## Implementation report + +Implementation report: + +- 対象: Ticket `00001KVWSQM22` +- 作業ブランチ: `work/00001KVWSQM22-backend-orch-runtime` +- 作業場所: `/home/hare/Projects/yoi/.worktree/00001KVWSQM22-backend-orch-runtime` +- コミット: `f901b9bee37a03faf380894926241107362da360` +- コミットメッセージ: `docs: design backend internal orchestrator runtime` + +変更ファイル: + +- `docs/design/workspace-kanban-orchestrator-runtime.md` + - Kanban/API 操作から Backend internal Orchestrator Worker へ接続するための設計文書を追加。 + - durable orchestration event の形、`ack` / `defer` / `fail`、idempotency/restart/retry 方針を整理。 + - Backend internal Orchestrator が routing/control-plane Worker であり、Bash/filesystem/git/raw socket/session authority を持たないことを明記。 + - Coder/Reviewer/helper など filesystem-capable work は typed spawn intent と `WorkerRuntimeRegistry` 経由で委譲する設計として整理。 + - runtime/worker identity、API 形状、DB projection 方針、`display_ref` / `pod_name` が authority ではないことを明記。 + - raw session は通常 projection ではなく bounded debug-only とする境界を整理。 + - dependency/conflict/dirty workspace/missing requirement/runtime unavailable などの waiting/blocker reason を整理。 + +- `docs/README.md` + - 新しい設計文書を docs index に追加。 + +- `docs/design/overview.md` + - `workspace-server` を local Workspace control-plane seam として位置づけ、raw path/socket/Pod/session を browser/API authority にしない方針を追記。 + +検証: + +- `git diff --check`: success +- docs-only 変更のため `cargo fmt` / `cargo test` / `cargo check` は実行していません。 + +残リスク / エスカレーション: + +- 本 Ticket の意図どおり、設計・計画 artifact の作成までで停止しています。 +- Backend internal Orchestrator 本体、Kanban UI 完成、spawn 実装、remote runtime protocol、raw session DB ingest、Ticket storage DB migration、permission/auth completion は未実装のまま non-goal として明記しました。 +- merge / close は行っていません。 + +--- + + + +## Review: approve + +Review result: approve + +確認範囲: +- child worktree `/home/hare/Projects/yoi/.worktree/00001KVWSQM22-backend-orch-runtime` のみ。 +- Ticket `item.md` / `thread.md` / `artifacts/orchestration-plan.jsonl`、commit `f901b9b...` の docs diff、追加 design doc を read-only で確認。 +- `git diff --check 8931227..f901b9b -- docs/...`: success。 + +承認根拠: +- 追加された `docs/design/workspace-kanban-orchestrator-runtime.md` は Ticket の単純コピーではなく、維持対象の設計 artifact として Core rule / durable events / ack-defer-fail / internal Orchestrator tool surface / spawn intent / API identity / DB projection / failure semantics / future implementation order まで具体化している。 +- Kanban/API 操作から durable orchestration event、Backend internal Orchestrator Worker、`WorkerRuntimeRegistry`、typed spawn intent、filesystem-capable Coder/Reviewer/helper Worker への委譲までの鎖が明記されている。 +- `ready -> queued` は human gate であり unattended scheduler / lease ではない、と明記されている。 +- Backend internal Orchestrator は routing/control-plane Worker で、`Bash`、raw filesystem、git/worktree/build、raw socket/session path、raw session full ingest を持たない境界が明確。 +- API authority は `runtime_id` + `worker_id` の opaque runtime-scoped identity に限定し、`worker-name@runtime-name` / `display_ref` / `pod_name` / path / socket / session を authority にしない方針が明記されている。 +- DB/projection は surrogate `workers.id` + `UNIQUE(runtime_id, worker_id)`、run overview / lifecycle / usage aggregate 参照方針まで記述されている。 +- failure/blocker/retry/ack/defer/fail semantics は future implementation Ticket の入力として十分な初期方針になっている。 +- Non-goals も維持されており、full backend implementation、Kanban UI completion、remote protocol、raw session DB ingest、Ticket DB migration、permission/auth completion に踏み込んでいない。 + +Non-blocking notes: +- child worktree 側の Ticket thread には Orchestrator 側で記録した implementation_report が見えなかったが、Orchestrator 側 Ticket record には report を記録済みであり、レビューは commit/diff と Coder report に基づいて行った。 +- 新規 design doc は diff 上 EOF newline が無いように見えたが、`git diff --check` は通っており blocker ではない。 + +--- + + + +## Implementation report + +Integration outcome: + +- Coder `yoi-coder-00001KVWSQM22-backend-orch-runtime` が implementation branch `work/00001KVWSQM22-backend-orch-runtime` に design artifact を commit した。 + - design commit: `f901b9be docs: design backend internal orchestrator runtime` +- Reviewer `yoi-reviewer-00001KVWSQM22-backend-orch-runtime` は read-only review で `approve`。durable orchestration event、ack/defer/fail、Backend internal Orchestrator tool surface、spawn intent、runtime/worker identity、DB projection、failure semantics、non-goals が future implementation Ticket の入力として十分に具体化されていることを確認した。 +- Orchestrator worktree `/home/hare/Projects/yoi/.worktree/orchestration` で branch `work/00001KVWSQM22-backend-orch-runtime` を merge 済み。 + - merge commit: `4e713fce merge: 00001KVWSQM22 backend orchestrator design` + +Changed files: +- `docs/design/workspace-kanban-orchestrator-runtime.md` +- `docs/README.md` +- `docs/design/overview.md` + +Validation in Orchestrator worktree: +- `git diff --check HEAD~1..HEAD`: success +- `git diff --check f367d732..HEAD -- docs .yoi/tickets/00001KVWSQM22`: success + +Notes: +- docs/design-only change のため Cargo validation は実施していない。 +- Reviewer non-blocking note: child worktree 側の Ticket thread には Orchestrator 側 report が見えなかったが、Orchestrator 側 Ticket record には report/review/outcome を記録済み。 +- Backend internal Orchestrator 本体、Kanban UI completion、Coder/Reviewer spawn 実装、remote runtime protocol、raw session DB ingest、Ticket DB migration、permission/auth completion は non-goal のまま。 + +Next action: +- Mark Ticket done after this integration/validation evidence. +- Then stop related child Pods and remove only the child implementation worktree/branch. + +--- + + + +## State changed + +Design/planning artifact is merged into the orchestration branch and validated. + +Evidence: +- merge commit: `4e713fce merge: 00001KVWSQM22 backend orchestrator design` +- reviewer result: approve +- validation in `/home/hare/Projects/yoi/.worktree/orchestration` succeeded: + - `git diff --check HEAD~1..HEAD` + - `git diff --check f367d732..HEAD -- docs .yoi/tickets/00001KVWSQM22` + +Closure is not performed here; this state records implementation/design completion after merge/validation. + --- diff --git a/docs/README.md b/docs/README.md index 5678a0b4..4e06628e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,8 +14,9 @@ It is not a dumping ground for external research, old plans, API inventories, or 6. [`design/plugin-packages.md`](design/plugin-packages.md) — plugin package distribution, discovery, and enablement boundaries. 7. [`development/plugin-development.md`](development/plugin-development.md) — how to build, package, enable, and inspect Yoi Plugins. 8. [`design/memory-knowledge.md`](design/memory-knowledge.md) — generated memory, Knowledge, and audit records. -9. [`development/work-items.md`](development/work-items.md) — how project work is recorded and reviewed. -10. [`development/validation.md`](development/validation.md) — how to check changes. +9. [`design/workspace-kanban-orchestrator-runtime.md`](design/workspace-kanban-orchestrator-runtime.md) — how Kanban operations become durable orchestration events and backend-internal routing decisions. +10. [`development/work-items.md`](development/work-items.md) — how project work is recorded and reviewed. +11. [`development/validation.md`](development/validation.md) — how to check changes. ## What belongs here diff --git a/docs/design/overview.md b/docs/design/overview.md index dc260734..161b520b 100644 --- a/docs/design/overview.md +++ b/docs/design/overview.md @@ -16,6 +16,7 @@ That rule shapes the crate split. The runtime can restart, attach, compact, or d - `manifest` resolves Profiles, Manifests, model/provider references, scopes, prompts, and tool permission policy into a runtime contract. - `tools` implements built-in tools with bounded output and policy-aware execution. - `memory` owns generated memory, Knowledge records, linting, staging, and audit observations. +- `workspace-server` is the local Workspace control-plane seam. It can project Tickets, Workers, lifecycle, usage, and orchestration events, but browser/API operations must stay on opaque backend identities instead of raw local paths, sockets, Pod names, or session files. - `tui` is a UI over Pod authority; it should not invent durable state. ## Why these boundaries exist diff --git a/docs/design/workspace-kanban-orchestrator-runtime.md b/docs/design/workspace-kanban-orchestrator-runtime.md new file mode 100644 index 00000000..653e00e7 --- /dev/null +++ b/docs/design/workspace-kanban-orchestrator-runtime.md @@ -0,0 +1,285 @@ +# Workspace Kanban to backend Orchestrator runtime + +Workspace Kanban operations are control-plane requests. They may change Ticket state and request orchestration, but they must not directly execute shell, git, filesystem work, or send authority-bearing messages to raw local Pod sockets. The durable boundary is an orchestration event consumed by a backend-internal Orchestrator Worker. + +This document records the design boundary for connecting Kanban operations, Tickets, the Workspace backend, `WorkerRuntimeRegistry`, and filesystem-capable Workers. It is intentionally a planning artifact: it does not require the Workspace backend to implement every table, API, remote protocol, or spawn adapter immediately. + +## Core rule + +A browser click or API request can create durable intent; it cannot be the authority to perform implementation side effects. + +The minimum chain for implementation work is: + +1. A user or authorized caller changes a Ticket through the Workspace/Ticket API. +2. The state change and its orchestration event are committed durably in the same logical operation. +3. A backend-internal Orchestrator Worker reads the event with domain-specific tools. +4. The Orchestrator records a routing decision. +5. If the Ticket is queued, unblocked, and accepted for implementation, the Orchestrator records `queued -> inprogress` plus the acceptance decision before any implementation side effect. +6. The Orchestrator creates typed spawn intents for filesystem-capable Coder, Reviewer, or helper Workers. +7. A local or remote runtime adapter resolves those intents into concrete worker launch/configuration using its own authority and capability policy. + +`ready -> queued` is therefore a human gate for Orchestrator routing, not an unattended scheduler and not a lease that automatically starts code execution. + +## Durable orchestration events + +Orchestration events are immutable control-plane records derived from Ticket operations. They are not raw LLM messages, Pod notifications, or socket writes. + +Initial event kinds: + +- `ticket_queued`: emitted for `ready -> queued`; requests Orchestrator routing/start-if-unblocked checks. +- `ticket_state_changed`: emitted for other lifecycle transitions that may affect orchestration state. +- `ticket_returned_to_planning`: emitted when a Ticket is moved back to `planning` because concrete requirements, decisions, dependencies, or acceptance evidence are missing. +- `ticket_done`: emitted when implementation/review flow records `done`; used for completion projection and close-readiness, not implicit close. + +A stable event shape should include: + +```text +orchestration_event { + event_id: opaque id, # durable event identity + workspace_id: opaque workspace id, + ticket_id: canonical Ticket id, + kind: ticket_queued | ticket_state_changed | ticket_returned_to_planning | ticket_done, + before_state: optional Ticket state, + after_state: optional Ticket state, + actor: { kind, key, display, source? }, # human, worker, api client, system + source: { kind, surface, operation }, # kanban_api, ticket_api, orchestrator, import, ... + request_id: opaque idempotency/correlation id, + caused_by_event_id: optional event id, + occurred_at: timestamp from the authoritative mutation, + recorded_at: timestamp when stored, + body: bounded structured reason/summary, # no raw transcript or raw local path authority +} +``` + +`request_id` is a correlation and idempotency key. For API-originated state changes, retrying the same request must return or reference the already-created Ticket transition and orchestration event instead of creating a second routing command. The event store should reject duplicate `(source, request_id)` pairs for mutation-producing requests, while allowing new events for distinct state changes. + +The Ticket state mutation and event append must be atomic from the backend's perspective. If the Ticket changes but the event cannot be recorded, routing must be considered failed and visible; if an event exists, the Orchestrator must be able to recover it after backend restart. + +## Event processing, retry, ack, defer, fail + +Event delivery state is separate from the immutable event. A future implementation can store per-consumer delivery rows such as `(event_id, consumer_id, status, attempts, visible_after, last_error, updated_at)`. That delivery mechanism is only for reliable control-plane processing; it must not redefine `queued` as a scheduler state. + +The backend-internal Orchestrator handles each event idempotently: + +- Reload the current Ticket, relations, orchestration plan, worker links, and relevant runtime summaries before deciding. +- Treat stale events as evidence, not commands. For example, a `ticket_queued` event for a Ticket that is now `planning` should be acknowledged with a stale/no-op decision rather than spawning work. +- Record a decision, waiting reason, or failure summary before acknowledging a routing event. +- Create spawn intents with stable `intent_id`s so dispatch retry can detect already-created intents. + +Delivery outcomes: + +- `ack`: the event has been interpreted and its durable outcome is recorded. The outcome may be `no_op_stale`, `routed_to_worker`, `blocked_waiting`, `returned_to_planning`, or `completion_projected`. +- `defer`: the event is valid but cannot progress now. The Orchestrator records a waiting reason and optional retry condition/backoff. Defer is appropriate for dependency not done, target conflict, dirty workspace reported by a capable runtime, missing worker capacity, or runtime unavailable. +- `fail`: processing cannot safely continue without operator or developer intervention. Fail is appropriate for invariant violations, malformed event payloads, missing Ticket authority, identity ambiguity, repeated dispatch inconsistency, or a request that would require forbidden authority. + +Retries must be bounded and idempotent. A retry may re-read the Ticket and registry and either dispatch a previously recorded intent, update a waiting reason, or fail with escalation. It must not execute shell/git/filesystem work in the backend process to "check" whether progress is possible. + +## Backend-internal Orchestrator Worker + +The backend-internal Orchestrator is a routing/control-plane Worker. It can be hosted inside the Workspace backend runtime because its tools operate on domain records and runtime registry abstractions rather than the workspace filesystem. + +Responsibilities: + +- Read durable orchestration events and delivery state. +- Inspect Tickets, Ticket relations, accepted orchestration plans, worker links, and bounded project-record projections. +- Decide whether a queued Ticket is ready for implementation, should wait, should return to planning, or should request review/closure follow-up. +- Record decisions, audit summaries, blocker/waiting reasons, and orchestration plan artifacts. +- Select a runtime by required capabilities. +- Create and dispatch typed spawn intents through `WorkerRuntimeRegistry`. +- Append/read worker run overviews, lifecycle summaries, and usage aggregates. +- Escalate when authority, requirements, or runtime capabilities are insufficient. + +Non-responsibilities: + +- No `Bash` authority. +- No raw workspace `Read`/`Write`/`Edit` authority. +- No direct git/worktree/build execution. +- No raw local Pod socket or session path authority. +- No use of browser-supplied local paths, executable paths, runtime registry paths, `display_ref`, `pod_name`, or runtime display names as operation authority. +- No raw session transcript full ingest into the Workspace database. +- No permission/auth, remote runtime protocol, Ticket DB migration, Kanban UI completion, or Coder/Reviewer spawn implementation completion in this design step. + +If routing needs evidence that only filesystem access can provide, the Orchestrator records a helper spawn intent for a filesystem-capable runtime or records a waiting/escalation reason. It does not temporarily grant itself filesystem tools. + +## Domain-specific tool surface + +The internal Orchestrator should receive backend tools, not generic Pod tools. The tools should be narrow enough to enforce lifecycle and authority rules and broad enough to let future Orchestrator prompts reason without hidden context injection. + +Required operation groups: + +- Ticket operations: + - list Tickets by state/risk/assignment bounds; + - show Ticket details, thread summaries, and relevant artifacts; + - append Ticket comments/implementation reports/review notes; + - perform validated state transitions, including `queued -> inprogress`, return-to-planning, and `done` recording. +- Relation and plan operations: + - read typed Ticket relations and derived blockers; + - read/write bounded orchestration plan artifacts; + - record conflict/capacity/waiting/accepted-plan notes. +- Event delivery operations: + - read pending orchestration events; + - ack, defer, or fail events with durable reason codes; + - query retry/defer state by event, Ticket, or consumer. +- Runtime registry operations: + - list runtimes and capability summaries; + - look up Workers by canonical `runtime_id` + `worker_id`; + - query capability support such as backend-internal tools, filesystem, shell, git, worktrees, bounded transcript read, stream availability, and worker spawn support. +- Spawn intent operations: + - create spawn intents; + - dispatch intents to a selected runtime; + - read intent state and acceptance evidence; + - associate intent/Worker summaries with Tickets. +- Worker overview and usage operations: + - append/read run overview entries; + - append/read lifecycle summaries; + - read usage aggregates for dashboard/control-plane display. +- Audit and decision operations: + - append routing decisions with actor/source/request id; + - append authority-boundary failures and escalation requests; + - query bounded decision history for a Ticket. + +Forbidden operation groups for the internal Orchestrator: + +- shell execution; +- raw filesystem read/write/edit over repository paths; +- raw Unix socket connects or socket path notification; +- raw session full transcript ingest; +- local Pod metadata path or session path access as authority; +- browser-provided display labels, paths, or executable strings as authority. + +## WorkerRuntime registry and spawn intents + +`WorkerRuntimeRegistry` is the boundary between backend control-plane decisions and runtime-specific worker launch. The Orchestrator asks for capabilities and submits typed intents; it does not construct low-level process commands. + +A spawn intent should describe policy and purpose rather than launch mechanics: + +```text +worker_spawn_intent { + intent_id: opaque id, + parent_event_id: orchestration event id, + request_id: idempotency/correlation id, + ticket_id: canonical Ticket id, + role: intake | orchestrator | coder | reviewer | helper, + purpose: route | implement | review | inspect | validate | summarize, + required_capabilities: [backend_internal_tools | workspace_fs | shell | git | worktrees | build | bounded_transcript], + workspace: { workspace_id, repository_targets? }, + cwd_semantics: role_default | ticket_worktree | target_repository | runtime_resolved, + profile_intent: builtin role/profile selector intent, + workflow_intent: optional workflow slug/phase intent, + input_packet_ref: durable bounded context reference, + acceptance_requirement: socket_ready | run_accepted(expected_segments) | decision_recorded, +} +``` + +The browser must not provide raw workspace roots, child cwd, executable paths, raw profile files, socket paths, local Pod names, or runtime display names in this intent. API callers can request high-level operations such as "queue this Ticket" or "open this canonical Worker"; the backend and runtime adapters resolve launch details from trusted workspace records, runtime configuration, and capability policy. + +Runtime adapters are responsible for translating an accepted intent: + +- A backend-internal runtime may create routing-only/intake/dashboard-assistant Workers with backend tools and no filesystem scope. +- A local Pod runtime may resolve a Coder/Reviewer intent into Pod launch arguments, scope, delegated filesystem paths, branch/worktree policy, prompt/profile/workflow selection, and acceptance evidence. +- A remote runtime may perform the same adaptation on a different machine without exposing local paths to the browser or storing them as API authority. + +Dispatch success means the runtime accepted the typed intent and returned durable acceptance evidence. It does not by itself prove the Ticket is done. Worker progress is projected through lifecycle, overview, review, and Ticket state records. + +## Runtime selection by capability + +Runtime choice is capability-driven: + +- Backend-internal runtime is suitable for routing-only Orchestrator work, intake refinement, dashboard assistant behavior, event processing, decision recording, and registry lookups. +- Filesystem-capable local or remote runtimes are required for Coder, Reviewer, worktree creation, git operations, builds, tests, repository inspection, and helper checks that need repository files. +- Bounded transcript read is a debug/support capability. It is not a substitute for overview/decision/lifecycle projections. + +If no runtime satisfies the required capabilities, the Orchestrator records `runtime_unavailable` as a waiting reason and defers or escalates. It must not silently downgrade to the backend-internal runtime for work that requires filesystem, shell, git, or worktree authority. + +## Worker identity, API, and database projection + +External API identity is runtime-scoped and opaque: + +- Worker detail: `GET /api/runtimes/{runtime_id}/workers/{worker_id}`. +- Cross-runtime list: `GET /api/workers`, with each item carrying `runtime_id`, `worker_id`, and display fields. + +`worker-name@runtime-name` is a display label (`display_ref`) only. It is not unique enough for authority and must not be accepted as the target of mutating operations. Similarly, local Pod `pod_name`, runtime display names, raw runtime registry paths, and socket/session paths are implementation diagnostics, not API authority. + +A browser-safe Worker summary can expose: + +```text +worker_summary { + runtime_id, + worker_id, + display_name, + runtime_display_name, + display_ref, + role, + state, + capabilities, + implementation: { + kind, + display_hint, + pod_name? # local Pod runtime only; diagnostic/display hint, not authority + } +} +``` + +For database projection, prefer a surrogate worker record id plus a uniqueness constraint on runtime-scoped identity: + +```text +workers ( + id INTEGER PRIMARY KEY, + runtime_id TEXT NOT NULL, + worker_id TEXT NOT NULL, + display_name TEXT NOT NULL, + runtime_display_name TEXT NOT NULL, + display_ref TEXT NOT NULL, + implementation_kind TEXT NOT NULL, + implementation_display_hint TEXT, + observed_at TEXT NOT NULL, + UNIQUE(runtime_id, worker_id) +) +``` + +Run overviews, lifecycle events, Ticket worker links, and usage aggregates may reference the surrogate `workers.id` internally for stable joins. External APIs should continue to expose and accept only `runtime_id` + `worker_id` for Worker identity. + +## Session, overview, lifecycle, and usage boundary + +The Workspace backend durable projection should center on: + +- orchestration events and delivery outcomes; +- routing decisions and audit records; +- worker lifecycle summaries; +- worker run overviews; +- Ticket state/relation/plan projections; +- usage aggregates. + +Raw session JSONL, provider traces, verbose event streams, local sockets, and local Pod metadata files remain runtime-local source/debug logs. The backend may expose bounded debug reads later, but that surface must be explicit, purpose-limited, permissioned, size-limited, and never treated as the normal Kanban/Orchestration UI data model. + +This keeps dashboard views stable across local/remote runtimes and prevents raw transcript contents from becoming hidden durable authority for why a control-plane decision happened. If a decision matters, it must be written as a decision/audit/overview record. + +## Failure, blocker, and waiting reason semantics + +The Orchestrator records why it did not dispatch work as carefully as why it did dispatch work. Initial reason categories: + +- `dependency_blocked`: required upstream Tickets or relations are unresolved. +- `conflict_blocked`: target paths, repositories, branches, or worker assignments conflict with active work. +- `dirty_workspace`: a filesystem-capable runtime reports that the relevant checkout/worktree is dirty or unsafe. The backend-internal Orchestrator does not inspect the filesystem itself. +- `missing_requirement`: the Ticket lacks a concrete decision, acceptance criterion, permission, or scope needed to start; the Orchestrator may return it to `planning` with a reason. +- `runtime_unavailable`: no registered runtime satisfies required capabilities or capacity. +- `identity_ambiguous`: the requested Worker/runtime cannot be resolved by canonical `runtime_id` + `worker_id`. +- `forbidden_authority`: completing the request would require raw shell/filesystem/socket/session/path authority in the backend process. +- `dispatch_inconsistent`: a spawn intent retry observed inconsistent runtime acceptance evidence. + +Waiting records should include ticket id, event id, reason code, human-readable summary, observed evidence, retry/unblock condition if any, and timestamp. A waiting reason may be cleared by a new Ticket event, relation change, runtime capability change, worker completion, or explicit operator action. + +Returning a Ticket to `planning` requires a concrete missing-decision or missing-information reason. Risk flags, unknown implementation details, or a need for reviewer focus are not sufficient by themselves. + +## Implementation sequence for future Tickets + +This design suggests the following order without making any of it part of this Ticket: + +1. Persist orchestration events for Kanban/Ticket state mutations, including idempotency by request id. +2. Add event delivery tools and decision/audit append tools for a backend-internal Orchestrator Worker. +3. Add runtime-scoped Worker detail APIs and backend worker projection records with surrogate ids and `UNIQUE(runtime_id, worker_id)`. +4. Add spawn intent persistence and registry dispatch stubs that preserve authority boundaries. +5. Implement local Pod runtime adaptation for Coder/Reviewer/helper intents. +6. Add remote runtime protocol only after the local typed-intent boundary is stable. + +At every step, keep the invariant that durable control-plane records explain why the system acted, while runtime-specific sockets, sessions, paths, and process launch details remain adapter-local implementation details. \ No newline at end of file