pi-worker-graph 0.1.0-dev.0

package/docs/DESIGN.md

@@ -0,0 +1,392 @@
+# Design
+
+## Purpose
+
+`pi-worker-graph` lets one Pi orchestrator execute a dependency graph of writable
+workers against one shared checkout. It minimizes context sharing: immutable edge
+outputs carry planned dependencies, while a small journal carries unexpected
+coordination facts.
+
+The graph domain is implemented independently of Pi. Process execution,
+persistence, tools, and user interface behavior are later integration layers.
+
+## Runtime roles
+
+### Orchestrator
+
+The parent Pi session:
+
+- understands the task and repository constraints;
+- defines nodes and dependency edges;
+- decides which ready nodes may safely overlap;
+- receives graph progress and structured results;
+- reviews the integrated checkout with read-only tools;
+- commissions final validation as dependent tasks and weighs what they report,
+  because the mode suppresses the parent's own command execution;
+- delegates repairs rather than editing while worker-graph mode is active.
+
+### Worker
+
+A child Pi session:
+
+- receives one bounded assignment;
+- operates directly in the shared checkout;
+- receives outputs only from its direct prerequisites;
+- may publish run-scoped coordination events or messages;
+- reports a structured result;
+- cannot spawn another worker.
+
+## Graph domain
+
+The public graph module accepts arbitrary payloads:
+
+```ts
+interface GraphTask<TPayload = unknown> {
+  id: string;
+  needs?: readonly string[];
+  payload?: TPayload;
+}
+
+interface GraphRequest<TPayload = unknown> {
+  tasks: readonly GraphTask<TPayload>[];
+  concurrency?: number;
+}
+```
+
+Normalization trims IDs, deduplicates and sorts dependency lists, and preserves
+task order and payload identity. Validation completes before execution:
+
+- IDs are non-empty and unique after normalization.
+- Every dependency names a node in the request.
+- A node cannot depend on itself.
+- The graph is acyclic.
+- Concurrency, when provided, is a positive integer.
+
+Executor-specific schemas add assignment text, working directory policy, expected
+paths, acceptance criteria, profiles, and hard resource limits. The runtime must
+apply graph-size and dependency-count limits before invoking the graph domain.
+
+## Node states and scheduling
+
+Node states are:
+
+```text
+pending -> running -> succeeded
+        |          -> failed
+        |          -> aborted
+        -> failed
+        -> aborted
+        -> blocked
+```
+
+Terminal states do not transition. A task can fail or abort before reaching
+`running` when startup fails or cancellation arrives before execution.
+
+Scheduling uses deterministic topological frontiers:
+
+1. Find pending nodes whose direct prerequisites all succeeded.
+2. Start eligible nodes up to the configured concurrency limit.
+3. Persist each terminal result.
+4. Mark pending nodes blocked when any prerequisite failed, aborted, or was
+   blocked.
+5. Recompute the ready frontier.
+6. Finish when every node is succeeded, failed, aborted, or blocked.
+
+A graph with no edges is an ordinary parallel batch. A linear graph is a chain.
+The pure graph module returns every eligible node in a deterministic order; the
+executor applies the configured concurrency limit when selecting work to start.
+The graph module does not spawn workers.
+
+## Edge context
+
+Each worker reports a compact result:
+
+```ts
+interface NodeOutput {
+  schemaVersion: 1;
+  summary: string;
+  changedFiles: Array<{ path: string; description: string }>;
+  interfaces: string[];
+  decisions: string[];
+  validation: Array<{ command: string; result: string }>;
+  blockers: string[];
+}
+```
+
+The report schema is versioned independently of the enclosing filesystem record.
+Reports require exactly these fields, use non-empty bounded strings, limit each
+section's item count, and have a hard aggregate UTF-8 JSON size limit.
+Changed-file paths use normalized repository-relative form; they are report data,
+not authority to access a path. Untyped executor values are validated and copied
+into immutable snapshots before publication. Malformed or oversized reports fail
+the node. A valid report with one or more blockers also fails the node, but is
+retained for parent review; its dependents do not run.
+
+For a node, outputs from each task named directly in `needs` are serialized in
+task-ID order into canonical named JSON blocks for the execution adapter to
+prepend to its assignment. Worker-authored text is explicitly marked as
+untrusted report data within those blocks. Full transcripts and undeclared report
+fields are not propagated. The complete serialization, including block labels
+and the warning, is measured in UTF-8 bytes against a hard limit. Overflow fails
+the downstream node without truncation, and stays that way: truncating it would
+run a dependent worker against an incomplete prerequisite contract, and a
+retained artifact cannot repair that because artifacts never cross a dependency
+edge (D19).
+
+Persisted output records use their own envelope schema version, independently of
+the worker-report schema version. Current envelopes include run and task identity,
+attempt, completion time, status, bounded diagnostics, a reference to a
+retained text artifact when there is one, and what the attempt spent.
+
+Usage is recorded for every terminal status, aborted included: an attempt the
+run stopped had still spent what it spent by then. A timeout and an abort are
+decided by the runner, which discards whatever the executor eventually settles
+with, so usage the executor reported is carried onto the runner's own outcome
+rather than lost with it. Failures carry usage too, on
+`TaskExecutionFailure`. An executor that does not account for its own spend
+reports nothing rather than zeros, which would read as work that cost nothing.
+
+Zero spend and unknown spend are different answers. An executor whose
+telemetry was absent, or carried a field that was not a usable number, records
+no usage rather than zeros: a complete-looking zero would read as work that
+cost nothing. An absent optional field is still zero, because a provider that
+bills no cache write reports none.
+
+A run's total is derived from the outputs it published rather than stored
+alongside them: derived is correct for a run that was interrupted, and needs no
+summary kept in step. Reading it applies the same output-to-node-state
+agreement every other reader requires, so a total is never assembled from
+records the rest of the store refuses; only a task that published no output at
+all is an expected absence. Such a task is reported as unaccounted when it ran,
+and as not started when it did not — the first is a gap in the accounting, the
+second is not.
+
+Token counts come from the provider's telemetry and cost from the runtime's
+pricing of those tokens, so cost is an estimate and tokens are the sturdier
+number.
+
+A retained text artifact is bounded long-form text that does not belong in the
+structured report — a log, investigation notes, detailed review findings. A
+worker publishes one deliberately, through an optional `artifact` field on the
+final-report tool; it is never runtime spillover from a report that did not
+fit. The runtime never parses it and never propagates it over a dependency
+edge, so a report that leans on its artifact is an incomplete report. It is published under the same mutation lock as the output
+that references it, and before that output, so an interruption can only strand
+an artifact no output claims. An artifact is therefore readable only through
+its reference, which names the byte length the artifact must still have. An
+aborted task produced nothing to retain and may not publish one. Artifacts are
+records with the same identity envelope as every other stored record, rather
+than bare text files, so an artifact cannot be read as belonging to a run, task,
+or attempt other than the one that wrote it. They are removed with their run.
+
+## Coordination journal
+
+Journal events are for information discovered after scheduling:
+
+```ts
+type EventKind =
+  | "decision"
+  | "interface"
+  | "risk"
+  | "conflict"
+  | "handoff"
+  | "progress";
+
+interface RunEvent {
+  schemaVersion: 1;
+  kind: "run-event";
+  eventId: string;
+  runId: string;
+  taskId: string;
+  timestamp: string;
+  eventKind: EventKind;
+  message: string;
+  paths?: string[];
+  symbols?: string[];
+  recipients?: string[];
+}
+```
+
+Directed messages carry the same envelope with a sender and one recipient task.
+
+Workers explicitly query relevant entries by recipient, path, symbol, or cursor.
+The runtime does not inject the entire journal into every turn. Live steering is
+outside the MVP.
+
+Every record in a run shares one monotonic sequence, so an identifier is also a
+position: a cursor names a point that no later record can precede, and a worker
+polling with one cannot silently skip a record published between two reads. A
+publisher holds the run mutation lock while checking the active owner and
+linking its record, so ownership release cannot land between validation and
+publication. Within the critical section, the record itself is exclusively
+created under the first free identifier; an interrupted publisher leaves no
+identifier behind.
+
+The orchestrator and every worker of a run contend for that one lock, so the
+parent has to tell a lock a live worker holds from one a worker was killed
+while holding. It is not a judgement about elapsed time: the lock is claimed by
+linking a record that is already complete on disk, so it never exists without
+naming its holder, and contention is reported apart from an ownership conflict.
+A parent mutation that meets a lock waits it out, and recovers it only when the
+lock names a task of its own graph whose promise has already settled. Its own
+task the graph runner knows to be finished; a sibling still running is waited
+for rather than interrupted, so ordinary contention no longer costs a graph.
+The runner recovers whatever remains before releasing ownership, once every
+task has settled.
+
+Coordination is bounded on both sides. A run retains a fixed maximum number of
+records, and publishing past it fails explicitly instead of silently degrading
+reads. One record is bounded as a whole when it is published, at half a page, so
+field bounds cannot combine into a record larger than a page. A read is bounded
+by a requested record count and by the serialized JSON array size, including its
+brackets and separators, and reports a cursor for the remainder, so no record
+can enlarge a worker's context beyond the page bound.
+
+One journal holds both kinds, so a read passes over records it will never
+return: the other kind, and another task's mail. Its cursor runs past those as
+well as past what it delivered, so a polling worker pays for each record once
+rather than re-reading the journal on every call. Only a record examined and
+held back — the one that overflowed the page — stays ahead of the cursor. A
+cursor consequently belongs to the query that produced it; reused under a
+different filter or recipient it starts past records that filter would have
+matched.
+
+Publishing requires the run to have an active owner, but not the owner's
+capability. Workers are the authors of coordination records and never hold the
+capability that advances node state, so an unowned or finished run stays
+immutable while worker writes remain unprivileged. Records are attributed to a
+task rather than authenticated: every worker of a run shares this state root, as
+they already share the checkout.
+
+## Persistence
+
+The state root is resolved from runtime configuration and defaults beneath Pi's
+agent data directory. It never defaults inside the target checkout. A bounded
+run count is enforced through atomically created run reservations. Reaching the
+limit fails before a worker starts and never deletes prior state implicitly.
+
+Per-run layout:
+
+```text
+<state-root>/runs/<run-id>/
+  run.json                    immutable graph and configuration
+  owner.json                  exclusive active lifecycle owner
+  nodes/<task-key>.json       parent-owned current node state
+  outputs/<task-key>.json     terminal structured output
+  artifacts/<task-key>.json   bounded retained text for one task attempt
+  coordination/<id>.json      immutable events and directed messages, in one
+                              run-global sequence
+  sessions/<task-key>/...     optional child session state
+```
+
+Task IDs are validated or encoded before use as path components. Immutable
+records are published by writing a same-directory temporary file with restrictive
+permissions and atomically renaming it. Mutable parent-owned state is replaced
+atomically. One extension instance permits only one graph lifecycle at a time.
+Active graph execution claims an exclusive owner record before mutating node
+state or outputs. Each mutation also holds a per-run filesystem lock through its
+full asynchronous read/validate/commit sequence, so ownership cannot be
+released and reassigned mid-mutation. Resumable or externally addressable runs
+still require an API that acquires and verifies that ownership before advancing
+an existing run.
+
+## Child process contract
+
+Every worker receives explicit run and task identity plus the state directory,
+and no other runtime state; in particular it never receives the run's ownership
+capability. The child detects worker mode and registers coordination and
+reporting tools, but not graph-spawning tools or orchestrator commands. Pi's
+tool allowlist is strict over built-in and extension tools, so the adapter
+allowlists the coordination tools on exactly the condition under which the child
+registers them, and advertises them in the assignment only then. Secrets are not
+added to child arguments, prompts, environment metadata persisted by the
+runtime, or graph state.
+
+The MVP transport is a one-shot Pi JSON-mode subprocess behind the execution
+adapter. It runs without session persistence or discovered extensions, skills,
+and prompt templates; only an explicit built-in tool allowlist and the child
+report extension are active. Repository context files remain enabled as trusted
+worker instructions. Task content is sent over stdin rather than argv.
+The adapter owns process-group cancellation, forced cleanup, event-stream
+framing bounds, and bounded exit classification. It projects capped progress
+snapshots containing only task identity, phase, allowlisted tool names, and
+numeric usage. Worker text and tool payloads are not forwarded to the parent.
+
+Classification favours completed work over incidental process noise. A captured,
+validated report outranks a provider error or a nonzero exit reported after it,
+because the report is the task contract and the child is already finished by
+then. Cancellation and a distrusted event stream still outrank a report, since
+neither leaves it trustworthy. Bounds that protect the parent are framing bounds:
+an unparseable line is skipped, never fatal, so a worker that legitimately emits
+a large transcript is not failed after its edits have landed.
+
+A report only counts when it was genuinely the worker's last action. Pi batches
+the tool calls of one assistant message and honours a terminating result only
+when the whole batch terminates, so the adapter reconstructs the batch the
+report belonged to from the assistant `message_end` event and watches for tool
+executions after it. A report that shared its batch, or that work outlived, is
+rejected rather than reported as success.
+
+The worker executable is identified positively rather than inferred. The adapter
+resolves Pi's CLI entry point through this package's dependency on Pi and runs it
+with the current JavaScript runtime, so there is no `PATH` search and no command
+interpreter on any platform. `PI_CODING_AGENT` is not evidence of identity — Pi
+exports it into every process it starts, including programs run by its own `bash`
+tool — so it only corroborates the single-file-build case, where the running
+executable is neither `node` nor `bun`. When neither route identifies Pi, the
+adapter requires an explicit command instead of guessing through a shell.
+
+## Mode lifecycle
+
+The extension provides:
+
+```text
+/swarm on
+/swarm status
+/swarm off
+```
+
+and an opt-in startup flag. The parent `worker_graph` tool is registered once but
+removed from the active tool set until the mode is enabled. Worker children take
+a mutually exclusive extension path and receive only their final-report tool.
+
+Entering the mode snapshots the complete active-tool set, removes the built-in
+`bash`, `edit`, and `write` tools, and activates `worker_graph` in their place.
+The snapshot and enabled state are stored in a bounded custom Pi session entry,
+restored on resume and tree navigation, and restored exactly when the mode ends.
+Worker children never register this lifecycle.
+
+## Failure semantics
+
+- Invalid graph: reject before spawning.
+- Worker startup, provider, or tool failure: mark the node failed with bounded
+  diagnostics.
+- Failed or aborted prerequisite: block dependents without running them.
+- Abort: terminate running children and settle remaining nodes as aborted or
+  blocked.
+- Journal failure: report it; never silently claim coordination succeeded.
+- Worker-report overflow: reject the report so the worker can correct and
+  resubmit it; compact parent review projections mark every truncated field or
+  omitted report explicitly. Truncating a report is the runtime choosing which
+  structured fields to cut, so it does not do that (D19).
+- Process crash: persisted terminal nodes remain terminal; running nodes become
+  interrupted and require an explicit retry or recovery decision.
+
+`interrupted` is recovery metadata rather than a normal graph-domain terminal
+state until retry semantics are defined.
+
+## Same-tree concurrency
+
+The runtime does not claim to make simultaneous writes safe. It reduces risk
+through:
+
+- careful graph decomposition;
+- optional advisory path and symbol claims;
+- instructions to re-read files before editing;
+- preference for exact edits over whole-file rewrites;
+- avoiding broad formatter or generator operations during a parallel frontier;
+- orchestrator review of the integrated checkout;
+- deterministic repository checks before acceptance.
+
+Cross-process file locking is not part of the initial design. It would introduce
+hidden serialization without protecting semantic coupling across different files.

package/docs/NEXT.md

@@ -0,0 +1,229 @@
+# Current development status
+
+## Implemented
+
+The repository now has a small transport-independent core plus an initial Pi
+adapter. Automated tests remain provider-free:
+
+- normalized, fully validated DAGs with frozen graph structure;
+- deterministic frontiers and guarded node transitions;
+- failed and aborted dependency blocking;
+- immutable versioned run manifests with opaque task storage keys;
+- one bounded retained text artifact per task attempt, published deliberately
+  through an optional `worker_graph_report` field, revalidated at every
+  boundary it crosses, published before and vouched for by the output that
+  references it, kept off dependency edges, named by byte length in the
+  parent-facing result, and removed with its run;
+- report and prerequisite-context overflow that stay fail-closed rather than
+  truncating into an artifact;
+- per-attempt token and cost accounting persisted with the attempt, kept for a
+  failed, timed-out, or aborted attempt as well as a succeeded one, summed per
+  run through `/swarm usage` and `readRunUsage()`, and attributed per task in
+  the parent-facing result;
+- accounting that keeps zero and unknown apart: absent or unusable telemetry
+  leaves an attempt unaccounted rather than free, a run total is only summed
+  from outputs that agree with node state, and a task that never ran is
+  reported apart from one that ran and recorded nothing;
+- parent-owned node state and immutable terminal outputs;
+- restrictive permissions and atomic filesystem publication;
+- bounded UTF-8 JSON records with explicit read and identity errors;
+- an injected asynchronous task-executor interface;
+- a strict versioned structured worker-report contract;
+- defensive report validation and immutable JSON snapshots;
+- normalized repository-relative changed-file paths and bounded diagnostics;
+- blocker-bearing report failure with retained parent-visible output;
+- bounded concurrent DAG execution with deterministic frontier selection;
+- durable terminal output before dependent activation;
+- direct-prerequisite-only output propagation;
+- deterministic task-ordered prerequisite report serialization;
+- named JSON report blocks with explicit untrusted-data labeling;
+- exact UTF-8 context accounting and fail-without-truncation overflow behavior;
+- explicit provider/model/thinking/tool worker profiles with no model defaults;
+- one-shot Pi JSON-mode subprocess workers in the target checkout;
+- task delivery over stdin rather than child-process arguments;
+- child isolation from discovered extensions, skills, prompt templates, and sessions;
+- a child-only terminating structured final-report tool, with recoverable
+  rejection so a worker can correct and resubmit a report;
+- enforcement that the report really was the worker's final action, covering
+  Pi's parallel tool batches;
+- positive identification of Pi's executable, with no shell on any platform;
+- event-stream framing bounds that skip unparseable lines instead of failing a
+  worker whose transcript is legitimately large;
+- allowlisted adapter failure diagnostics, surfaced through one pre-run error
+  type and one execution failure type;
+- process-group cancellation with forced termination fallback and post-exit
+  collection of orphaned grandchildren;
+- sanitized executor failures, cancellation, and task timeouts;
+- task, dependency, concurrency, payload, output, and context limits;
+- bounded, redacted worker progress projection and aggregate usage accounting;
+- a strict global `worker-graph.json` profile configuration;
+- a default state root beneath Pi's agent directory, with checkout-local roots
+  rejected by the extension;
+- one static, fully bounded `worker_graph` parent tool;
+- explicit `/swarm on`, `/swarm status`, `/swarm off`, `/swarm usage`, and
+  `--swarm` activation;
+- an optional configured orchestrator session model and thinking level, applied
+  on activation and restored on exit, refused unless the mode knows the
+  identifiers that restore it, the model is one Pi can find, and its provider
+  is authenticated, with a model the configuration stopped naming still put
+  back and a restore that cannot be performed reported rather than swallowed;
+- session-persisted swarm mode with exact active-tool restoration and built-in
+  parent mutation tools suppressed while active, with branch-recorded state
+  governing session-tree navigation and activation refused for any tool set the
+  extension could not restore;
+- compact, explicitly bounded worker-report projection for parent review and
+  focused follow-up graphs, delivered in a labeled block worker text cannot
+  close;
+- a configurable retained-run cap enforced by atomically claimed capacity slots,
+  with deterministic arbitration between concurrent creators, no implicit
+  deletion, stranded slots reported for explicit removal, and inconsistent
+  run/slot state failing closed;
+- explicit retention cleanup through `/swarm runs` and `/swarm delete`: a
+  listing of everything holding capacity, and deletion of a named run with its
+  slot, refused while an orchestrator holds the run and ordered so an
+  interruption can only strand a slot;
+- immutable bounded run-scoped coordination events and directed inbox messages,
+  in one run-global journal, with cursor-based queries and child-only Pi tools;
+- a run mutation lock that names its holder, so contention between the parent
+  and a publishing worker is reported apart from an ownership conflict, waited
+  out rather than resolved by force, and recovered only when the lock names a
+  task the graph runner knows has finished;
+- coordination cursors that run past records a reader is never given, so
+  polling costs only the records published since the previous call;
+- a verified npm artifact containing the compiled runtime, loaded from a clean
+  temporary install in offline Pi RPC mode;
+- behavioral coverage using `node:test`, fakes, and temporary directories.
+
+Normal parent sessions register the `/swarm` control command, but the
+`worker_graph` tool is inactive until explicitly enabled. The report tool is
+registered only inside explicitly marked worker children. Active graph
+lifecycles claim an exclusive owner before mutating run state; resumable or
+externally addressable runs are not implemented yet.
+
+## Verify the baseline
+
+```bash
+npm install
+npm run check
+npm run build
+cp docs/worker-graph.example.json ~/.pi/agent/worker-graph.json
+pi -e .
+```
+
+`npm run check` currently runs the adapter, configuration, context, extension,
+graph, orchestrator, report, store, and runner suites. `npm run build` must run
+before `pi -e .`, because `extensions/index.ts` re-exports the compiled entry
+point from `dist/`. The configuration copy is required rather than optional:
+the extension has no provider or model defaults, and `/swarm runs` and
+`/swarm delete` resolve the state root through the same file, so a missing
+`worker-graph.json` answers both subcommands with a configuration error.
+Loading the package in Pi adds the `/swarm` control command, whose `runs` and
+`delete` subcommands work whether or not the mode is enabled, but leaves the
+parent tool set unchanged. The entry point registers
+the worker report tool only when `PI_WORKER_GRAPH_ROLE=worker`, which the
+parent sets on worker subprocesses and never on its own session. Active graph
+lifecycles claim an exclusive owner record before mutating run state; resumable
+or externally addressable runs are not implemented yet.
+
+## Next implementation slice
+
+Prepare the vertical slice for a prerelease:
+
+1. Run an optional provider-backed smoke test with two independent workers and a
+   dependent validation node when provider-backed testing is desired; this is
+   intentionally skipped for the current local pass.
+2. Review, tag, and publish the npm prerelease through the maintainer-owned Git
+   and registry workflow.
+3. Type `/swarm runs` and `/swarm delete <run-id>` once in a live Pi session.
+   Their state-root resolution has now been exercised against a real agent
+   directory: a real `worker-graph.json` resolved the default
+   `~/.pi/agent/worker-graph` root, and a created run was listed with its slot
+   and then deleted, leaving `runs/slots` empty at mode `0700`. What remains
+   unverified is the command surface itself — argument parsing, the notified
+   text, and `ctx.cwd` as the working directory — because those need the
+   interactive session rather than a direct store call.
+4. Keep every automated path provider-free behind the existing fake subprocess
+   and injected orchestrator boundaries.
+5. Exercise the configured orchestrator model once in a live session. Its
+   activation, refusal, and restore paths are covered by fakes; what no test
+   can cover is Pi's own `setModel` against a real provider catalogue and real
+   authentication. Confirm specifically whether the shutdown restore lands:
+   `session_shutdown` awaits an asynchronous model change, and Pi does wait for
+   that handler on both quit paths: `interactive-mode.js` awaits
+   `runtimeHost.dispose()`, which awaits `emitSessionShutdownEvent`, which
+   awaits each handler in turn. It is not awaited on `emergencyTerminalExit`
+   or `uncaughtCrash`, where the terminal is already gone.
+
+## Deferred run-store work
+
+Before a resumable or externally addressable run API is added, retain the
+fail-closed ownership contract so two orchestrators cannot advance one run, and
+the rule that a mutation lock is recovered only by a holder that can be shown
+to have finished.
+
+Retained text artifacts are complete end to end and their policy is settled in
+D19: publication is deliberate, and neither overflow becomes truncation.
+
+One question is left open deliberately. The orchestrator learns that an
+artifact exists, and how large it is, but has no way to read it: the review
+names `artifactBytes` and not a path, and no tool returns the text. A library
+caller uses `readNodeArtifact()`. Giving the orchestrator the artifact's path
+would make its own `read` tool sufficient, but that widens what the parent may
+reach outside the checkout, so it is a decision rather than an addition.
+
+## Deferred worker instruction work
+
+The worker concurrency contract is now sent in the worker prompt
+(`src/pi-subprocess.ts`) and asserted by the adapter suite: stay inside the
+assignment, prefer small exact edits, reconcile rather than restore a file to
+the version first read, never run git restore/reset/checkout/stash/clean and
+never commit, push, or branch, no repository-wide formatters or generators or
+dependency updates without explicit ownership, re-read changed files before
+reporting, and report an unclear semantic conflict as a blocker instead of
+guessing. The orchestrator guidance in `src/orchestrator.ts` carries the
+matching parent-side decomposition, overlap, serialization, and acceptance
+rules.
+
+What remains undecided is one report field. `NodeOutput` carries `summary`,
+`changedFiles`, `interfaces`, `decisions`, `validation`, and `blockers`
+(`src/output.ts`), so an observation about another worker's edits can only
+reach the parent's terminal report as prose in `summary` or as a blocker.
+Adding a field is a schema version change.
+
+It is less pressing than it was. A worker that notices a concurrent change
+already has a structured channel while it runs — a `conflict` coordination
+event (`src/store.ts`), which the parent and other workers can read — and a
+retained artifact for the long form of what it saw. Neither is the terminal
+report, so the question stands; it is no longer a dead end.
+
+## Deferred budget work
+
+Usage is now recorded but nothing acts on it. The runtime bounds tasks,
+concurrency, payload, output, context, and per-task runtime; it has no token or
+cost ceiling, so a graph can spend without limit as long as each worker stays
+inside its timeout.
+
+The next slice is a configured budget in `worker-graph.json`, checked in the
+runner between frontiers and enforced through the existing abort path, which
+already settles remaining nodes and returns a result with usage intact. Two
+things to settle first: whether the budget counts tokens or cost — cost is the
+provider's estimate, tokens are the sturdy number — and whether crossing it
+aborts the graph or only refuses to open the next frontier.
+
+## Constraints to preserve
+
+- Keep the implementation and exported API as small as possible.
+- Validate the complete graph and runtime bounds before starting work.
+- Do not add provider or model defaults.
+- Do not add automatic Git operations or worktrees.
+- Do not store runtime state in the target checkout by default.
+- Do not propagate undeclared or unbounded context between tasks.
+- Do not add recursive worker delegation.
+- Use fake executors for automated integration tests.
+
+## Decisions still needed
+
+Review barriers, retention cleanup, and worker-session resumption semantics
+remain deferred until their runtime layers are implemented. Broader Pi
+compatibility can be claimed only after testing versions beyond the current
+0.85.1 development pin.