@jini-ai/daemon 0.5.3 → 0.6.0

package/dist/index.d.ts

@@ -1,577 +1,81 @@
 /**
  * @module @jini-ai/daemon
  *
- * `RunLifecycle` + the durable `EventLog` kernel port (extraction-plan §8
- * task 5), plus the `ToolExecutor` tool-execution boundary (extraction-plan
- * §2.5 / §8 task 6), and `AgentExecutor` — the driver that wires
- * `@jini-ai/agent-runtime` into `RunLifecycle` (extraction-plan §2.1 / §3).
- * See `archived provenance ledger` for full provenance and scope-decision notes.
- *
- * The generic `ArtifactStore` kernel port used to live here too — moved to its own
- * `@jini-ai/artifacts` package on 2026-07-19 (see `tokens.ts`'s doc comment).
- *
- * `routines/` (2026-07-21) adds the `RoutineService` scheduler (DST-safe wall-clock schedule
- * math, race-safe scheduled-slot persistence) and the `RoutineStore` CRUD + run-history port,
- * mirroring `EventLog`'s kernel-owned, storage-injected precedent. See its own module doc and
- * `archived provenance ledger`'s dated section for provenance.
- *
- * `terminal-session.ts` (2026-07-21) adds the interactive-terminal session manager: a
- * `node-pty`-backed `PtySpawn` wired into `@jini-ai/platform`'s generic `TerminalService`, plus
- * session-ownership gating and the kill/write/resize lock `@jini-ai/daemon/http`'s `terminals.ts` route
- * pack calls into. This is this workspace's first native-compiled-addon dependency — see this
- * package's `package.json` and `archived provenance ledger`'s dated section.
-
- * Archived provenance rationale:
- * ## Design decisions (judgment calls the task brief explicitly asked for)
- *
- * **1. `RunLifecycle` does not spawn or signal subprocesses.** OD's `cancel()`
- * (`runs.ts:361-401`) does real tiered signal escalation (ACP `.abort()` → RPC
- * grace → `SIGTERM` on the process group → grace → `SIGKILL`, all
- * env-var-tunable). That is deeply subprocess/agent-CLI-adapter-specific and is
- * explicitly `@jini/agent-runtime`'s territory (task 7), not this task's. This
- * package's `cancel()` only records intent (`cancelRequested` + notifies
- * `onCancelRequested` listeners, an `AbortSignal`-shaped but framework-neutral
- * callback registry) and never itself forces a terminal transition — a driver
- * observes the signal and calls `finish()` once it knows the real outcome,
- * exactly mirroring OD's actual invariant that `finish()`/`design.runs.finish`
- * is the only path to a terminal state, called from the child's real `close`
- * event, never synchronously from `cancel()` itself.
- *
- * **2. `resume()` is a generalization, not a literal port.** OD has two
- * unrelated "resume" concepts (see the research notes cited in the handoff
- * report): (a) resuming the *external agent CLI's own* session via
- * `--resume <id>`/ACP `session/load`, persisted in OD's SQLite schema — a
- * real subprocess/vendor-CLI concern out of scope here — and (b) a
- * `run.resumable` flag surfaced to the client so a *next user turn* can invoke
- * (a). Neither is "resume an interrupted daemon-side run object" — that
- * concept doesn't exist in OD. `@jini/daemon`'s `resume()` builds that concept
- * fresh: a terminal run with `resumable: true` (set by whoever called
- * `finish()`) can transition back to `'running'` on the **same `runId`**,
- * continuing the **same `EventLog` cursor sequence** unbroken — no new `'start'`
- * event, no cursor reset. This was a deliberate choice to make `resume()`
- * meaningful and testable at the kernel layer without a real subprocess/session
- * concept to hang it on; see `characterization.test.ts` for the two-segment
- * proof (start→agent*→end(failed,resumable)→resume→agent*→end(succeeded), ids
- * monotonically increasing across the whole thing).
- *
- * **3. No `RunStore` port was extracted.** Extraction-plan §2.2's illustrative
- * composition example lists `RunStore` and `EventLog` as siblings a pack
- * depends on. This task's charter (§8 task 5) names only `RunLifecycle` +
- * `EventLog` as deliverables. `RunLifecycle`'s own run-status registry
- * (`Map<runId, RunRecord>`) is therefore an internal implementation detail of
- * this package's `createRunLifecycle`, not a separately swappable port — a
- * persistent run registry (surviving a daemon restart, not just an event
- * replay) is not implemented. **Flagged as a real follow-up**: a future task
- * (likely task 8, alongside the `@jini/sqlite` durable `EventLog` adapter)
- * should decide whether `RunLifecycle`'s registry needs its own `RunStore`
- * port for restart-durability parity with §2.2's example, or whether
- * `RunLifecycle` itself becomes the thing `@jini/sqlite` backs directly.
- *
- * **4. The `RunState`/`RunEndPayload.status` spelling mismatch is bridged, not
- * fixed.** `@jini/protocol`'s `RunState` uses `'cancelled'` (2 L) while
- * `RunEndPayload.status` uses `'canceled'` (1 L) — this is extraction-plan §12
- * C5's own cited vocabulary-firewall canary, already present in `@jini/protocol`
- * before this task started. `packages/protocol` is explicitly out of scope for
- * this task, so `run-lifecycle.ts` bridges the two spellings with an explicit
- * `TERMINAL_OUTCOME_TO_END_STATUS` lookup table (with a comment citing this)
- * rather than silently letting them drift or fixing the upstream package.
- * `run-lifecycle.test.ts`'s finish() test asserts the bridge explicitly.
- *
- * **5. Driver-emittable events are a closed, explicit union
- * (`DriverEmittableInput`)**, not `RunProtocolEvent` minus `'start'`/`'end'`
- * derived mechanically — `'start'` is only ever produced by `start()`, `'end'`
- * only by `finish()`; a driver calling `emit()` can only ever produce
- * `'agent'`/`'stdout'`/`'stderr'`/`'error'`. This mirrors OD's actual invariant
- * (`'start'` emitted once by the engine right before spawn, `'end'` only from
- * `design.runs.finish`) as a compile-time-enforced contract rather than a
- * runtime convention.
- *
- * **6. `emit()` throws (fails fast) on an unknown or already-terminal run**,
- * rather than silently no-op'ing. OD's own code pattern is the caller checking
- * `run.cancelRequested || design.runs.isTerminal(run.status)` defensively
- * *before* emitting (repeated ~10 times in `start-chat-run.ts` per the
- * research), i.e. OD treats "don't emit after terminal" as the caller's job,
- * not something `emit()` itself silently absorbs. This package makes that the
- * same explicit contract, but surfaces a violation as a thrown error (a driver
- * bug) instead of a silently-observed defensive check, per this codebase's
- * fail-fast-defaults convention.
- *
- * **7. A cancel listener that subscribes after `cancel()` already fired still
- * receives the notification immediately** (`onCancelRequested` replays the
- * last request if `cancelRequested` is already true at subscribe time). This
- * was found and fixed during this task's own mandatory score-skepticism pass
- * (a plain forward-only listener registry has no memory of past firings, so a
- * driver attaching late — e.g. after being constructed asynchronously — would
- * otherwise silently never learn a cancellation was already requested). No OD
- * equivalent exists to compare against; this is new, `AbortSignal`-inspired
- * behavior.
- *
- * ## New home decision
- *
- * Ranked alongside `RunLifecycle`/`EventLog` in `@jini/daemon` because, like
- * those, it is a daemon-startup-lifecycle concern — the origin's own doc
- * comment states it runs "at module import time in server.ts, before
- * `openDatabase` opens SQLite," i.e. before any daemon service starts, which is
- * exactly this package's charter ("stateful" lifecycle, not a pure-interfaces
- * package like `@jini/core`).
- *
- * ### Design decisions
- *
- * **1. Authorization vs. confirmation are two distinct gates, not one.**
- * `ToolPolicy.authorize` (owned by the tool's registration) answers "is this
- * principal permitted to use this tool at all" — a rule-based decision.
- * `ExecutionDelegate.onConfirm` (owned by the transport, only consulted when
- * `ToolDescriptor.requiresConfirmation` is set) answers "does the user want
- * to proceed with *this specific* invocation right now" — an interactive,
- * per-call gate. `ExecutionDelegate.onAuthorize` exists too, but only as an
- * additional veto *after* the policy already allows (e.g. "does this session
- * actually hold an active grant") — it can turn an `'allow'` into a `'deny'`,
- * never the reverse, and is never consulted when the policy itself denies
- * (tested explicitly).
- *
- * **2. Confirmation resumability is a real parked Promise, not a polling
- * flag.** When `ExecutionDelegate.onConfirm` doesn't supply a decision
- * synchronously (returns/resolves `undefined`), `execute()`'s returned
- * Promise is parked on an internal `Map<executionId, resolve>` and simply
- * does not settle — `resumeConfirmation(executionId, decision)` is the only
- * thing that can settle it, and it can be called from a completely separate
- * tick/request, arbitrarily far in the future, no polling required. This is
- * the concrete answer to "the headless kernel can't prompt, so the transport
- * injects an `ExecutionDelegate`": the kernel (`ToolExecutor`) never renders
- * anything; it hands the transport a notification (the `onConfirm` call) and
- * waits indefinitely for `resumeConfirmation`, exactly the shape a real UI
- * approval flow needs. One documented sharp edge: an `async` `onConfirm`
- * that itself resolves to `undefined` is treated as "the decision is
- * `undefined`" (i.e. denied) rather than "pending," since the code can only
- * tell "no decision yet" apart from "the Promise's inner value happens to be
- * undefined" by checking whether `onConfirm`'s *own return value* is
- * `undefined` before awaiting it — documented on the interface, not
- * silently surprising.
- *
- * **3. Output truncation is a text-output concern, not a general
- * serialization limit.** `ToolDescriptor.maxOutputBytes` only truncates a
- * `string` handler result exceeding that length; non-string (structured)
- * output passes through untouched even when the limit is set. A real
- * byte-accurate UTF-8 truncation or a generic-JSON-payload cap was judged
- * out of scope for this task's gate ("output truncation" — proven, not
- * maximally engineered) — a reasonable follow-up if a real tool handler
- * starts returning large structured payloads.
- *
- * **4. `execute()` throws (doesn't return a status) for an unknown tool
- * id.** Denial/confirmation-denial/timeout/cancellation/failure are all
- * legitimate business-domain outcomes modeled as `ToolExecutionResult`
- * variants; calling `execute()` with a `toolId` nothing registered is a
- * routing/programming bug, not a business outcome, so it's a thrown `Error`
- * instead — the same distinction OD's own `RunLifecycle`-equivalent code in
- * this package (`requireRun`) already draws between "unknown id" (throw) and
- * "legitimate terminal state" (return value).
- *
- * **5. No persistence.** Like `EventLog`'s in-memory reference
- * implementation, `createToolExecutor`'s audit records and pending-
- * confirmation state live only in the process; a real host that needs audit
- * records to survive a restart, or confirmation to resume across a daemon
- * restart, layers a durable store behind `getAuditRecord`/`resumeConfirmation`
- * later. Out of this task's scope (the gate is "one allowed + one denied
- * tool call, resumable confirmation, timeout, cancellation, output
- * truncation, and an audit record — no HTTP involved," which this satisfies
- * in-process).
- *
- * **6. A `finally` block was deliberately avoided around the handler's
- * try/catch.** An early draft cleaned up the timeout handle and the active-
- * `AbortController` map entry in a `finally` clause; istanbul/v8 instruments
- * try/finally with a synthetic "abrupt completion through finally" branch
- * that is unreachable here (nothing in the catch block can itself throw a
- * second exception past the catch), which the coverage-driven pass (Phase
- * 6.5) couldn't close without a contrived test. Repeating the two-line
- * cleanup at each of the try/catch's own return points instead avoided
- * introducing that uncoverable branch — a "dead branch, refactor away"
- * call, same discipline as the agent-protocol port's (Part 1) precedent.
- *
- * ### Design decisions
- *
- * **1. `resumable` is always `false` in v1.** `RunRetryFailureSignal` (the
- * richer classification `decideSafeRunRetry`, in `run/core/retry.ts`,
- * consumes) has no producer anywhere in this codebase — OD's real
- * ~20-vendor-CLI text-matching failure classifier
- * (`run-failure-classification.ts`, researched but never ported; see this
- * file's earlier "Not ported" section) was deliberately excluded as its own
- * substantial, unscoped task. Every `lifecycle.finish()` call
- * `AgentExecutor` makes — pre-spawn guard failures, spawn errors, and the
- * real `child.on('close', ...)` terminal transition alike — passes
- * `resumable: false`. A blanket "not retryable" default is the only honest
- * answer without a classifier; building one is a separate, unscoped
- * follow-up, not attempted here.
- *
- * **2. `turn_end` is not forwarded as an `'agent'` event, and v1 has no
- * multi-turn stdin-injection loop.** `turn_end` is Claude-stream-specific
- * (synthesized from an assistant message's `stop_reason`) and has no
- * `RunAgentPayload` variant — `translateAgentRuntimeEvent` routes it to a
- * `'turn-end'` translation kind that `run()` reacts to directly (closing
- * stdin) rather than durably recording. **v1 unconditionally closes stdin on
- * the first `turn_end` regardless of `stopReason`** — including
- * `stop_reason: 'tool_use'`, which in a real multi-turn caller would instead
- * inject the tool's result back into the same open stdin and keep the turn
- * going. Without that injection loop, a `tool_use`-ending turn's stdin still
- * closes (rather than hanging forever waiting for a continuation that will
- * never come); the agent CLI is responsible for deciding how to behave when
- * its stdin closes mid-tool-use, which each of the 9 defs already handles
- * via its own inactivity/EOF behavior. Building the real tool-continuation
- * loop needs `ToolExecutorToken` wiring (deciding what to send back) and is
- * explicitly out of this task's scope — see the plan's "Explicitly out of
- * scope" section.
- *
- * **3. Session-resume ids are an intentional, documented drop.** Some
- * parsers attach a resumable session handle to their `status` event
- * (OpenCode's `sessionID`, Codex's `thread_id`/`sess-*`, Qoder's
- * `session_id`+`qodercliVersion`) — `translateAgentRuntimeEvent`'s `status`
- * case only carries `label`/`model`/`ttftMs`/`detail` (the fields
- * `RunAgentPayload`'s `status` variant actually declares), so these ids are
- * silently dropped at translation time. This is unrelated to
- * `RunLifecycle.resume()`, which is run-level (does the daemon-side run
- * object transition back to `'running'`), not CLI-conversation-level (does
- * the underlying agent CLI continue its own multi-turn session) — persisting
- * and replaying these ids into a real `--resume`/`session/load` call on a
- * later turn is a downstream chat-composition concern with no current owner
- * in this codebase, matching the same "not this package's charter" boundary
- * this file's earlier §2's "resume" design decision draws.
- *
- * **4. `translateAgentRuntimeEvent`'s `usage` payload drops every sub-field
- * `RunAgentPayload`'s narrow `usage` variant has no room for.** The 4 parsers
- * attach `thought_tokens`, `cached_read_tokens`/`cached_write_tokens`
- * (opencode/gemini/codex), `modelUsage`/`stopReason`/`isError` (qoder), and a
- * top-level `stopReason` (claude/copilot) that `RunAgentPayload['usage']`
- * (only `usage?: {input_tokens?, output_tokens?}`, `costUsd?`, `durationMs?`)
- * has no field for — dropped, not silently miscoerced. Widening
- * `RunAgentPayload`'s `usage` shape to carry these is a `@jini/protocol`
- * change, out of this task's scope (protocol is a separate package with its
- * own owner).
- *
- * **5. `error` events carry a minimal `RunErrorPayload`** — `{message}`,
- * plus `error: {code, message}` only when the parser attached a string
- * `code` (currently only claude's error event does). The `raw` field some
- * parsers attach (opencode/gemini/qoder — a stringified copy of the whole
- * original event, for debugging) is not folded into the error payload; kept
- * minimal rather than speculatively enriched.
- *
- * **6. Every `lifecycle.emit()` call is funneled through a per-run FIFO
- * queue (`enqueueEmit`, private to `wireChildLifecycle`), not fired
- * independently.** A single stdout `data` chunk can synchronously produce
- * several parsed events (one JSON line's `feed()` call may invoke a stream
- * parser's `onEvent` more than once — e.g. Codex's `item.completed` firing
- * both a `tool_use` guard-check and a `tool_result`), and successive `data`
- * events must not have their derived `emit()` calls race each other out of
- * order. Each queued task is individually try/caught (a single failing
- * `emit()` — e.g. a race against an already-terminal run — does not block
- * delivery of subsequently queued events), and the `close` handler awaits
- * the queue fully drained before computing the terminal outcome, so
- * `finish()`'s `'end'` event is always durably last.
- *
- * **7. Cancellation escalates the child's full descendant process tree, not
- * just the direct child.** `@jini/platform`'s `collectProcessTreePids`
- * (cross-platform: POSIX `ps` / Windows `Get-CimInstance`) plus
- * `stopProcesses` (SIGTERM → poll-wait → SIGKILL escalation) were both
- * previously completely unused — zero callers anywhere in this codebase —
- * despite being an exact fit; `AgentExecutor` is their first real caller.
- * This catches MCP-server/tool-subprocess descendants an OD-style
- * POSIX-process-group-only kill would miss.
- *
- * **8. Native-agent authorization and Jini tool execution are two explicit
- * paths.** ACP's `onPermissionRequest` seam receives the tool-call metadata and
- * offered option ids before the ACP agent executes its own tool; without an
- * injected policy it fails closed, while a runnable host records and chooses an
- * offered allow/reject/cancel outcome. The
- * autonomous JSON-stream CLIs still report `tool_use` only after their internal
- * execution, so their telemetry remains observational. Separately,
- * `createDelegatedToolBridge` is the actual Jini-tool path: it emits a matching
- * run event pair around `ToolExecutor.execute`, so registry policy,
- * confirmation, timeout, cancellation, and the executor audit all apply. It is
- * transport-neutral by design; an MCP or other server must decode a concrete
- * delegated request before calling it.
- *
- * ## 2026-07-22 addition — terminal/PTY route pack: `pnpm guard` re-run, and `node-pty`'s missing Linux prebuild — a real deployment decision, not a bare flag
- *
- * The 2026-07-21 `terminal-session.ts` addition above flagged the `node-pty` Linux-prebuild gap but
- * left it as "undiscovered rather than mitigated" pending a real decision. This pass makes that
- * decision, backed by evidence gathered in this session, not assumption:
- *
- * **`pnpm guard`, actually run this session** (it had not been, per this task's own open-items
- * list): root `pnpm guard` (scans all of `packages/@jini/**`, including `terminal-session.ts`) — zero
- * violations. No R1–R7 boundary/neutrality/sprawl issues in this file.
- *
- * **The decision.** This repo's own `ADS-memory/reports/jini-port/START-HERE.md` states the architecture plainly:
- * *"Jini is a headless daemon"* — a long-running Node server process, the deployment shape that
- * overwhelmingly means a Linux host (container or bare server) in practice, not a developer's own
- * macOS/Windows machine. `node-pty@1.1.0`'s npm tarball bundles prebuilt native addons for
- * `darwin-arm64`/`darwin-x64`/`win32-arm64`/`win32-x64` but ships **no `linux-*` prebuild** — on a
- * Linux install, `node-pty`'s own `install` script falls back to `node-gyp rebuild`, which needs a
- * C/C++ toolchain (python3/make/a C compiler) present at `pnpm install` time.
- *
- * **Empirically verified in this exact session**, not inferred from reading `node-pty`'s source: this
- * task's own `pnpm install` ran on a real Linux (x64) sandbox with a standard build toolchain present
- * and the fallback **worked correctly and automatically** — `node-gyp rebuild` compiled
- * `pty.node` from source (`CXX(target) Release/obj.target/pty/src/unix/pty.o` →
- * `SOLINK_MODULE(target) Release/obj.target/pty.node`, `gyp info ok`) with zero manual intervention
- * beyond the `pnpm.onlyBuiltDependencies` allow-list entry the 2026-07-21 addition already added
- * (without that entry, pnpm's supply-chain-safety default silently skips native postinstall scripts
- * entirely and this fallback would never run at all — confirmed by that entry already being present
- * in this checkout's root `package.json` before this pass touched anything).
- *
- * **Decision: accept the gap, with a documented, actionable requirement — not a code fallback.**
- * Build-from-source *is* the fallback (already the default, already proven working end-to-end this
- * session); nothing further needs to be built. What was missing was making the requirement this
- * implies for a deployer explicit rather than silent: **a Linux host deploying this daemon must
- * have a C/C++ build toolchain (`python3`, `make`, a C compiler — e.g. Debian/Ubuntu's
- * `build-essential` package) available at `pnpm install` time.** This is *not* satisfied by a
- * minimal/`slim`/`alpine`-family base image out of the box (those deliberately omit build tooling to
- * stay small) — a deploying host must either use a base image that already includes one (e.g. the
- * non-slim `node:*-bookworm` family) or install the toolchain as an explicit build-stage step before
- * `pnpm install`. No CI configuration exists anywhere in this repo to encode this in (confirmed: no
- * `.github/workflows` directory) — this paragraph, plus the 2026-07-21 addition's own flag above, is
- * this decision's durable record until a real deployment/CI configuration task exists to encode it
- * as an executable check instead of documentation. Rejected alternatives: vendoring a prebuilt
- * `linux-x64`/`linux-arm64` `.node` binary into this repo (adds binary artifacts + a maintenance
- * burden for a native addon this package doesn't own) and pinning an older `node-pty` version that
- * might ship a Linux prebuild (checked — no version in this package's supported range ships one;
- * Linux users of `node-pty` upstream are documented to be expected to build from source).
- *
- * ## 2026-07-22 addition — two independent retry classifiers reconciled at merge time (audit fix, AUD-002)
- *
- * A second cloud session, working in parallel on a branch (`fix/audit-6-fixes-20260722`) that forked
- * before the paragraph above landed, independently built its **own** answer to the identical gap-4
- * problem: `classifyProcessExitFailure` + `defaultClassifyFailure`, both new exports added directly to
- * `agent-executor.ts`, with a **materially different policy** — only `signal === 'SIGPIPE'` was
- * classified retryable (`upstream_unavailable`/`network_error`); every other signal, including
- * `SIGKILL`/`SIGTERM`, was `process_exit`/`signal_killed` and explicitly **not** retryable. Because
- * this branch touched a file `main` had not (a different file than the `run/core/retry.ts` location
- * above), a raw `git merge` would have combined both silently with no conflict marker at all — two
- * same-shaped, contradictorily-behaving classifiers coexisting in the tree, one of them dead code by
- * accident of which line happened to get wired last. A deep-dive audit
- * (`ADS-memory/reports/audit-fastify-merge-and-six-gap-fixes-2026-07-22.md`, AUD-002) caught this
- * before it landed.
- *
- * **Decision made at merge time: keep this file's `run/core/retry.ts` version; delete the branch's
- * `agent-executor.ts` duplicate.** Reasoning: the branch's SIGPIPE-only policy is more conservative
- * but misses the single most common real-world signal-kill scenario this classifier exists for — an
- * OS/container OOM killer or infra-level eviction sending `SIGKILL` to a healthy process, which is
- * presumptively transient and exactly the case worth retrying. The broader "any signal is
- * presumptively transient" policy this file already documents does risk retrying a genuine crash
- * signal (e.g. `SIGSEGV`) that a retry won't fix, but the blast radius of that miss is small and
- * bounded: `DEFAULT_SAFE_RUN_RETRY_MAX_ATTEMPTS = 1`, so the cost of being too permissive here is at
- * most one wasted extra attempt, while the cost of the branch's more conservative policy is silently
- * never retrying the dominant legitimate case. `agent-executor.ts`'s own `classifyProcessExitFailure`/
- * `defaultClassifyFailure` exports and their dedicated tests were removed as part of this merge;
- * `FailureClassificationContext`'s `code`/`signal`-only scope note is unaffected (both
- * implementations agreed on that boundary — see this file's now-single classifier for the reasoning).
- *
- * Also merged in from the same branch, independent of the classifier question: real `sideEffects`
- * wiring (`userVisibleOutputSeen`/`toolCallSeen`, derived live from the translated agent-event stream
- * in all three `wire*Lifecycle` drivers) so two of `decideSafeRunRetry`'s four side-effect-suppression
- * guards are now genuinely exercised, not permanently dead code — see `resumableFromProcessExit`'s own
- * doc in `retry.ts` for exactly which two, and why `artifactWriteSeen`/`liveArtifactSeen` still
- * cannot be (no `'artifact'`/`'live_artifact'` event kind exists anywhere in `@jini/protocol`'s
- * `RunAgentEventPayload` union today — a real protocol gap, not an oversight; see this repo's own
- * "A2UI full protocol deferred" scope note). `attemptCount` stays a documented, correct `0`: no
- * automatic same-run retry loop exists anywhere in this codebase yet (gap 4's `resumable` flag is
- * read-only metadata for a host's own later follow-up run, not an auto-retry trigger — see
- * `resumableFromProcessExit`'s doc), so every real call to this classifier genuinely is evaluating a
- * first and only attempt; a future auto-retry loop would need to supply its own real count.
- *
- * **Verified, personally, this session**: `pnpm --dir packages/daemon exec tsc --noEmit` clean;
- * `pnpm --dir packages/daemon run test:coverage` — all tests pass, `retry.ts` and `agent-executor.ts`
- * both 100/100/100/100 after the branch's duplicate export and its 8 dedicated unit tests were
- * removed and the 3 `wire*Lifecycle` drivers' new side-effect tracking got its own coverage.
- *
- * ### The decision: def-declared fields, not an id branch
- *
- * `PROP-plain-format-agent-driving-2026-07-21.md`'s open question 6 asked whether antigravity's
- * divergence stays "an id-keyed special case inside `@jini-ai/daemon` (mirroring OD's own choice to
- * hardcode `def.id === 'antigravity'` in `server.ts`)" or gets a `RuntimeAgentDef`-level field (its
- * "Option C"). **Option C, deliberately** — and the evidence is not a style preference:
- *
- * - `RuntimeAgentDef` already carries **14** optional behavior flags/hooks the executor reads
- *   generically (`promptViaFile`, `promptViaStdin`, `resumesSessionViaCli`,
- *   `capturesSessionIdFromStream`, `resumesSessionViaAcpLoad`, `externalMcpInjection`, `authProbe`,
- *   `acpMcpEnvFormat`, `defaultModelEnvVar`, `inactivityTimeoutMs`, `maxPromptArgBytes`,
- *   `supportsCustomModel`, `promptInputFormat`, `promptViaStdin`'s `permissionMode`-aware `buildArgs`).
- * - There was **zero** precedent anywhere in this package for the executor branching on a literal
- *   agent id to decide *behavior* — the antigravity rejection was the only id branch at all, and it
- *   decided *support*, not behavior.
- * - OD's `server.ts` hardcodes `def.id === 'antigravity'` twice; §2d of the same proposal already
- *   records that OD's *prompt-delivery* call sites, by contrast, key only off declared fields with
- *   zero id branches. The field-driven half is the half that generalized cleanly.
- *
- * Consequence worth stating plainly: a second CLI with either property (prints a secret on stdout and
- * exits 0; or mutates process-global state its own startup reads back) needs **no new executor code**.
- *
- * ## 2026-07-30 addition — post-merge audit fixes (Codex gpt-5.6-sol findings on `9cb4ffc50…085c4799a`)
- *
- * Full verification write-up, per finding, with the observed red/green output:
- * `ADS-memory/reports/post-merge-audit-2026-07-29/daemon-fix-report.md`. Findings list:
- * `daemon-findings.md` in that same directory. All 5 blocking and 2 of 3 non-blocking findings were real
- * — no false positives. Every fix landed behind a test confirmed failing first.
- *
- * **`.mcp.json` is now one file per run.** `mcpServers.jini.env` carries this run's `JINI_RUN_ID` and its
- * bearer `JINI_DAEMON_TOKEN`, and a shared `cwd/.mcp.json` cannot hold two runs' identities at once — a
- * CLI loads its MCP config when it starts its client, not at spawn, so a second run in the same directory
- * overwrote the entry the first run's child had not read yet and that child then called back with the
- * *other* run's id and token. `mcpJsonPathForRun` writes `<cwd>/.mcp.jini-<runId>.json`; `cwd/.mcp.json`
- * is now read-only (still the merge source, so a project's own servers survive, and nothing needs
- * restoring); the run's file is removed through `cleanupStagedFiles` via a new
- * `McpJsonInjectionOptions.removeFile` seam, so a live token no longer outlives the run. Refusing the
- * second run instead was rejected: concurrent runs in one cwd are a documented design point (that is why
- * `credential` is a per-run resolver at all).
- *
- * **One follow-up this leaves open, in `@jini-ai/agent-runtime` rather than here.** The run-scoped path
- * only reaches the child because the def passes it on — `claude.ts` emits
- * `--strict-mcp-config --mcp-config <runtimeContext.mcpJsonPath>`. **`codebuddy.ts`, the other
- * `externalMcpInjection: 'claude-mcp-json'` def, ignores `mcpJsonPath`** and relies on its CLI
- * auto-discovering `cwd/.mcp.json`, so a codebuddy run with `mcpJsonInjection` configured now writes a
- * file nothing reads. That def wants the same two flags under the same guard — deliberately not done
- * blind, because codebuddy's acceptance of those flags is unverified and an unsupported flag fails the
- * run outright, which is worse than losing tools on a path `claude.ts`'s own live 2026-07-30 note says
- * never worked headlessly anyway (auto-discovery needs an interactive trust prompt; the connection sat at
- * `"pending"` forever). Verify with one live codebuddy run, then add the flags.
- *
- * **Resolved the same day, below** — the "the other 3 MCP injection mechanisms" entry closes this
- * exact follow-up (Gap A) plus the two mechanisms nothing implemented at all (Gaps B/C), all through
- * one dispatch point rather than one-off patches.
- *
- * **The `'until-close'` stdout accumulator is bounded.** `DEFAULT_BUFFERED_STDOUT_MAX_BYTES` (8 MiB,
- * overridable via `CreateAgentExecutorOptions.bufferedStdoutMaxBytes`) — an `until-close` child can emit
- * indefinitely or never close, and this driver treats agent CLIs as potentially adversarial elsewhere
- * (SEC-001), so one run could exhaust the daemon heap and take every unrelated run with it. Whole chunks
- * only (no sliced multi-byte characters), everything after the first refusal dropped, and truncation is
- * reported in a host-authored note appended *after* the def's `sanitize` runs — a consumer redactor must
- * not be able to delete the line saying output is missing, and a truncated run emits even when the
- * sanitized text is empty.
- *
- * **Nothing fallible now sits in front of `finish()`.** `buildArgs` is guarded like every other
- * staging→spawn step (it performs real filesystem writes — that is what `runtimeLock` exists for — so
- * EACCES/ENOSPC used to escape `run()` as a bare `Error`, stranding the run *and* holding the
- * process-global mutex forever). In all three close handlers, staged-file cleanup and the host's
- * `classifyFailure` are guarded by `cleanupStagedFilesSafely`/`classifyFailureSafely`: previously either
- * rejection took the terminal transition with it, leaving a `'running'` run whose child was already gone
- * and surfacing only as an unhandled rejection. The finding cited only the child-driven handler; the ACP
- * and pi-rpc handlers had the identical shape and the identical bug. `reportPostCloseFailure` also
- * absorbs a throwing `onCleanupFailure` sink. `AgentCleanupFailurePhase` gains `'staged-file-cleanup'`
- * and `'failure-classification'`; `AgentCleanupFailureContext.pid` widens to `number | undefined`.
- *
- * **`RunLifecycle` no longer exposes uncommitted starts.** `get`/`list` await a pending `startPromise` (a
- * failed durable start reads as "no such run" rather than as a running one no restart could rehydrate),
- * and `waitForTerminal` awaits *and propagates* it before parking a waiter — which is what closes the
- * hang: nothing ever calls `finish()` for an unwound record, so such a waiter was previously never
- * resolved or rejected.
- *
- * **Two smaller ones.** `FrontendSessionRegistry` keys run bindings on the attachment object, not the
- * session id: a session id is reusable by design (a reconnecting tab re-attaches under the same id), so a
- * stale handle's `detach()` used to remove the *replacement* session, its bindings, and the usability of
- * its still-current bind token. `createDefaultRunStartHandler` now forwards `imagePaths`,
- * `extraAllowedDirs` and `uploadRoot` — the same silent-drop failure mode `permissionMode` was already
- * documented for.
- *
- * **Left as a note, not patched:** `remote-tool-bridge.ts` does not dedup on `toolUseId`, so a retried
- * cross-process POST appends duplicate tool events. Real, but every in-reach fix is worse than the bug:
- * the recorder holds only a `RunLifecycle` (no read API, so dedup could only be non-durable in-memory
- * state that a restart defeats), it would need per-run lifetime machinery this module has no hook for,
- * and `delegated-tool-bridge.ts`'s `execute()` does not dedup either — deduping one half would split two
- * paths this module exists to keep byte-identical. The honest fix is idempotency at the
- * `RunLifecycle.emit` (or transport) boundary.
- *
- * Tests: **`@jini-ai/daemon` 654 → 682**, 26 files, zero failures — `agent-executor.test.ts` 189 → 210,
- * `frontend-session-registry.test.ts` 41 → 44, `run-lifecycle.test.ts` 53 → 56,
- * `run-start-handler.test.ts` 7 → 8. No test deleted or weakened; three existing `.mcp.json` tests were
- * updated for the genuinely-changed write path (two of them strengthened — see the report). Coverage:
- * package 99.85/99.93/99.64/99.85, with `agent-executor.ts`, `frontend-session-registry.ts` and
- * `run-start-handler.ts` all fully covered; the only residual gap is the pre-existing, deliberately
- * uncovered `handleInactivityTimeout` guard in `run-lifecycle.ts` that function's own doc already explains.
- * `pnpm typecheck` (package and `-r` workspace-wide, since two exported types changed): clean.
- * `pnpm guard`: clean.
- *
- * ## 2026-07-30 addition — the other 3 MCP injection mechanisms get wired: `acp-merge`, the two `*-env-content` strategies, and codebuddy's missing argv
- *
- * The 2026-07-22 gap-3-part-2 entry above wired exactly one of the four declared
- * `externalMcpInjection` strategies. Its own text named the other three as future work ("a future
- * task wiring those two would extend `wireAcpLifecycle`'s existing `envFormat`/`mcpServers`
- * passthrough or `applyAgentLaunchEnv`'s env composition respectively"). A peer review then confirmed
- * the practical consequence: of 24 defs, only `claude` actually delivered MCP tools end to end. This
- * entry closes all three remaining gaps. **Adding a strategy for a currently-undeclared agent (e.g.
- * `codex`) was explicitly out of scope and was not done.**
- *
- * **The boundary this is organised around** is per-CLI vs per-mechanism. Identity, binary, and
- * model/session/permission argv are genuinely bespoke and stay in each def's own `buildArgs`. MCP
- * staging, ACP server merging, and env-content serialisation are *mechanisms*, and each now has
- * exactly one implementation that every def declaring it flows through.
- *
- * **Gap A — `codebuddy` (`'claude-mcp-json'`).** The executor already computed and staged the same
- * `.mcp.json` for it, but `defs/codebuddy.ts`'s `buildArgs` never read `runtimeContext.mcpJsonPath`,
- * so it was still left on the headless auto-discovery path the claude fix exists to avoid. Rather
- * than copy claude's branch, the flag-building moved into a shared
- * `@jini-ai/agent-runtime` helper — **`buildClaudeMcpConfigArgs` in `src/defs/shared.ts`** — that both
- * defs now call. `--strict-mcp-config` was verified as genuinely supported by CodeBuddy before being
- * added (its own CLI reference documents `--mcp-config <fileOrString>` and `--strict-mcp-config`,
- * "Only use MCP servers in --mcp-config, ignore other MCP configuration"), so codebuddy gets the same
- * strict-isolation guarantee as claude rather than a silently weaker one. `shared.test.ts` pins that
- * both defs emit byte-identical MCP argv for identical input, so a future copy-paste divergence fails
- * there rather than in production.
- *
- * **Gap B — the 8 `'acp-merge'` defs** (devin, hermes, kilo, kimi, kiro, reasonix, trae-cli, vibe),
- * which were getting *zero* MCP tools, not merely a missing flag. `attachAcpSession` has always
- * accepted `mcpServers`; `wireAcpLifecycle` simply never passed any. Fixed once, in that shared
- * function (`WireAcpLifecycleContext.mcpServers` → spread into the attach call when non-empty) —
- * **no per-def file was touched**, because the gap was never in the defs. A 9th def declaring
- * `'acp-merge'` is covered automatically. Each entry's `env` is emitted as a plain object so
- * `buildAcpSessionNewParams` keeps owning the array-vs-map wire-shape fork (reasonix declares
- * `acpMcpEnvFormat: 'map'`).
- *
- * **Gap C — `'opencode-env-content'` / `'mimo-env-content'`.** Two labels, one serialiser: MiMo's own
- * def doc already stated it consumes the same JSON schema as OpenCode's, differing only in env-var
- * namespace, and the tests pin that the emitted content is byte-identical modulo the run id. The
- * difference is one row in `ENV_CONTENT_VAR_BY_STRATEGY` (`OPENCODE_CONFIG_CONTENT` /
- * `MIMOCODE_CONFIG_CONTENT`), not a second code path. `mergeEnvContentMcpConfig` applies the same
- * "merge, never clobber" discipline `mergeMcpJsonContent` does, and for a sharper reason: a host may
- * already be handing the CLI the *user's* configured MCP servers through that very variable.
- *
- * **One dispatch point, one credential.** `buildMcpBridgeDelivery` (pure, exported) is the single
- * place a declared strategy maps to a mechanism, returning a discriminated `McpBridgeDelivery` so a
- * consumer cannot read another mechanism's payload. `run()` resolves the per-run bearer credential
- * exactly once, before `buildArgs`, and hands it to whichever serialiser applies; a rejecting resolver
- * still fails the run before spawn. Keyed off the *strategy*, never off `def.id` — a registry-level
- * test asserts every real def declaring a strategy gets a non-null delivery, so a 25th def with an
- * unhandled strategy fails there.
- *
- * **Security.** The credential reaches every mechanism through an *environment*, never through
- * process arguments (`ps` is readable by other local users): `.mcp.json`'s `env`, the ACP server
- * descriptor's `env` (which the ACP agent applies to the MCP child it spawns), and the env-content
- * config's `environment` key — itself carried in the spawned CLI's own env var, deliberately not a
- * `-c key=value`-style CLI argument. Three dedicated tests assert the secret is absent from argv while
- * still present where it must be, including one driving a real subprocess.
- *
- * **Files changed.** `@jini-ai/agent-runtime`: `src/defs/shared.ts` (new
- * `buildClaudeMcpConfigArgs`), `src/defs/claude.ts` and `src/defs/codebuddy.ts` (both call it).
- * `@jini-ai/daemon`: `src/agent-executor.ts` (new `buildAcpMcpBridgeServers`,
- * `ENV_CONTENT_VAR_BY_STRATEGY`, `mergeEnvContentMcpConfig`, `McpBridgeDelivery`,
- * `buildMcpBridgeDelivery`; `writeMcpJsonForRun` narrowed to consume an already-built delivery;
- * `wireAcpLifecycle` gained `mcpServers`; `run()` composes `childEnv`). `McpJsonInjectionOptions`
- * keeps its name for API compatibility with `@jini-ai/server`'s `agentExecutor` passthrough even
- * though it is no longer `.mcp.json`-specific — a naming-debt item, deliberately not renamed here.
- * Reconciled the same session with the run-scoped-path fix above: `buildMcpBridgeDelivery`'s
- * `'claude-mcp-json'` case calls `mcpJsonPathForRun`, not a shared `cwd/.mcp.json`, so the
- * cross-run credential leak that fix closed stays closed under the generalized dispatch too;
- * `writeMcpJsonForRun` takes `cwd` as an explicit param so it still reads the project's own
- * `.mcp.json` as its merge base while writing the run-scoped path.
- *
- * **Tests / verification, run this session.** `@jini-ai/agent-runtime` **1848 → 1858**
- * (`defs/__tests__/shared.test.ts` +5, `defs/__tests__/codebuddy.test.ts` +5). `@jini-ai/daemon`
- * **654 → 687** (`__tests__/agent-executor.test.ts` +30 across `buildAcpMcpBridgeServers`,
- * `mergeEnvContentMcpConfig`, `buildMcpBridgeDelivery`, the ACP passthrough block and the env-content
- * block; `__tests__/agent-executor-acp.integration.test.ts` +3). Nothing existing regressed. The three
- * integration additions are the closest available analogue to the live smoke check that verified the
- * claude fix: the existing ACP fixture — a **real spawned Node subprocess** speaking real ACP JSON-RPC
- * over real stdio, through the real `attachAcpSession` — now echoes back the `mcpServers` its own
- * `session/new` received, so delivery is asserted from the agent's point of view rather than from a
- * stubbed attach call, in both `array` and `map` env formats. No vendor CLI or credentials were
- * needed, and none of the 24 real agent CLIs were spawned. `tsc --noEmit` and `tsc -p tsconfig.json`
- * (build): clean for both packages; root `pnpm -r typecheck`: clean.
+ * Stateful kernel orchestration: RunLifecycle, the durable EventLog port,
+ * ToolExecutor and the AgentExecutor runtime driver. Feature storage is injected;
+ * ArtifactStore belongs to @jini-ai/artifacts. Routines own scheduling and their
+ * CRUD/run-history port. Terminal sessions own PTY lifecycle, session access and
+ * kill/write/resize locking. Startup data migration belongs here because it must
+ * precede service startup, rather than run inside the pure core interfaces.
+ *
+ * Run contracts:
+ * - cancel records intent; drivers finish after the real outcome is known.
+ *   RunLifecycle does not spawn or signal processes because those mechanics
+ *   belong to the runtime driver. Late cancellation listeners receive the last
+ *   request immediately so asynchronous driver setup cannot miss cancellation.
+ * - resume reuses the same runId and EventLog cursor sequence without a new start
+ *   event. This is distinct from resuming a vendor CLI session. The lifecycle's
+ *   run registry is internal, not a separate RunStore token; durable event replay
+ *   must not be confused with persistence of arbitrary live process state.
+ * - start/finish own start/end events; DriverEmittableInput is an explicit union
+ *   so drivers cannot originate those transitions. Unknown or terminal emits
+ *   throw because they indicate driver bugs. The cancelled/canceled spelling
+ *   bridge preserves the protocol's existing state and payload vocabularies.
+ * - Pending durable starts are awaited before exposing run records or parking
+ *   terminal waiters: a failed append must not expose an uncommitted run.
+ *
+ * Tool security and confirmation:
+ * - Tool policy authorization and user confirmation are separate gates.
+ *   A transport delegate may veto an allowed policy decision, never override a
+ *   denial. ToolExecutor is the invocation boundary; handlers are not exposed.
+ * - A synchronous undefined confirmation parks the promise for
+ *   resumeConfirmation; an async promise resolving to undefined is a denial.
+ *   Audit records and pending confirmations are process-local, so cross-restart
+ *   durability needs a host-owned store. Unknown tool IDs throw as routing bugs;
+ *   denial, timeout, cancellation and handler failure are result variants.
+ * - maxOutputBytes bounds UTF-8 string output; structured output is not a general
+ *   serialization limit. Handler timeout/controller cleanup occurs at settlement
+ *   points; it must not leave an active execution behind.
+ *
+ * Runtime driver invariants:
+ * - Parsed event delivery uses a per-run FIFO and drains before finish so end is
+ *   durably last. A failed emit does not block later queued events. Cancellation
+ *   stops the full descendant process tree because tools may spawn grandchildren.
+ * - Native ACP permission requests fail closed without an injected policy.
+ *   Autonomous CLI tool-use telemetry is observational; delegated Jini calls go
+ *   through ToolExecutor with authorization, confirmation and audit intact.
+ * - Vendor usage is narrowed to protocol fields, rather than inventing wire
+ *   fields; error payloads stay minimal. Session handles and turn-end control
+ *   are runtime/continuation concerns, distinct from RunLifecycle.resume.
+ * - Failure classification belongs to run/core/retry. Signal kills may be
+ *   transient (including OOM/eviction); the conservative side-effect guards and
+ *   one-retry limit bound duplicate work and wasted attempts. Resumability
+ *   metadata does not itself start an automatic retry loop.
+ * - Runtime behavior follows def-declared fields, not agent-ID branches, so a
+ *   second CLI with the same prompt/output/lock behavior needs no driver fork.
+ * - MCP mechanisms have one strategy dispatcher. Per-CLI identity and argv stay
+ *   in runtime defs; mechanism staging, server merging and env serialization
+ *   stay shared. Existing user servers are merged rather than clobbered.
+ * - MCP config files are run-scoped because concurrent runs cannot share bearer
+ *   identity. The project's .mcp.json is only a merge source; staged files are
+ *   removed at cleanup so live credentials do not outlast the run. Credentials
+ *   travel in environments, never argv, which other local users can inspect.
+ * - until-close stdout is bounded because an adversarial child can exhaust the
+ *   daemon heap. Whole chunks preserve multibyte characters; a host truncation
+ *   note follows vendor sanitization so redaction cannot hide missing output.
+ * - Fallible buildArgs, staged-file cleanup, classification and reporting must
+ *   not strand runs or runtime locks; post-close failures cannot prevent finish.
+ * - Frontend session bindings use attachment identity because reconnects reuse
+ *   session IDs; stale detach handles must not remove replacement sessions.
+ *   Run-start adapters forward imagePaths, extraAllowedDirs and uploadRoot.
+ * - Remote/delegated tool events do not establish retry idempotency. A durable
+ *   solution belongs at the lifecycle or transport boundary, rather than a
+ *   restart-unsafe recorder cache that makes the two paths disagree.
+ *
+ * node-pty uses native addons. Linux deployment requires python3, make and a
+ * C/C++ compiler during installation; source compilation is the fallback.
+ * Vendoring foreign prebuilt binaries would create an unowned maintenance burden.
+ * See the owning modules and packages/daemon/README.md for detailed contracts.
  */
 export * from './event-log.js';
 export * from './close-status.js';