mcp-server-opencode 1.1.5 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Releases before `1.2.0` predate this file and are not documented here.
+
+## Unreleased
+
+## [1.3.0] — 2026-10-19
+
+### Added
+
+- Caller-provided expected workspace changes and bounded executable checks, with additive per-run `workspace_delta` reports and verification states.
+- Workspace-wide overlapping-directory leases, report-aware waits, and an independent lifecycle observer for accepted runs.
+- Prompt dispatch now distinguishes definite HTTP 4xx rejection from ambiguous ACK failures. Ambiguous runs remain tracked with their writer lease held and return `dispatch_uncertain`; definite rejection rolls back only the provisional run.
+- Caller message IDs use OpenCode's required `msg_` namespace; the real smoke includes a non-billable bare-UUID runtime probe.
+- Bounded filesystem inventory, check output, and direct `shell: false` execution; report diagnostics disclose incomplete evidence and shared-workspace attribution uncertainty.
+- Historical `run_id` status/result retrieval and cached final text/progress/report; tool getters do not execute checks again.
+- Opt-in real OpenCode stdio smoke command (`pnpm smoke`) using only the exact `openai/gpt-6-luna` model, including directory-scoped permission handling and independent managed worktrees.
+- Each accepted prompt has an additive `run_id` and run-history record. Explicit user-message IDs scope status, progress, and results to the active prompt; earlier assistant turns cannot appear as a pending continuation's output.
+- Continuation dispatches are reserved per task, cancellation state is recorded only after an accepted abort, and accepted continuations clear prior cancellation state.
+- Status and wait share terminal-state rules; `empty` and `cancelled` now finish long polls.
+- SDK HTTP requests use a 30-second abort deadline; long-polling bounds each status read by the remaining total wait deadline.
+- Server/task records optionally retain the canonical server working directory.
+- Status, wait, and result payloads report direct assistant INFO usage with run/session snapshots, provider/model breakdowns, completeness metadata, and immutable per-run historical snapshots; missing metrics remain unknown and cost currency is unspecified.
+- Optional task directories and managed detached Git worktrees bind SDK requests and per-session permission responders to the selected project. Worktree IDs/metadata appear in task history, and `opencode_cleanup_workspace` performs explicit serialized cleanup while preserving cached reports and usage.
+
+### Fixed
+
+- SDK response-level errors are surfaced for prompt dispatch, abort, status/message reads, and permission responses, including HTTP failures returned without throwing.
+- Permission responder diagnostics go to stderr rather than MCP stdio.
+- `opencode_wait_for_task` progress enrichment now shares the absolute wait deadline; a slow enrichment is aborted and returns the last observed task status/progress rather than extending the call.
+
+## [1.2.0] — 2026-08-28
+
+Delegated tasks could hang forever, or report `completed` after doing nothing.
+Both are fixed, and the result payload now carries evidence of what a task
+actually did. See `docs/incident-2026-08-21-silent-noop-tasks.md` for the full
+report this release closes out.
+
+### Behavior changes callers must handle
+
+- `opencode_get_task_status` and `opencode_get_task_result` can now return two
+  new statuses: **`empty`** and **`cancelled`**. Both were previously reported
+  as `completed`. Code that switches exhaustively on task status needs a branch
+  for them; code that only special-cases `completed` will now correctly stop
+  treating a no-op or an aborted task as a success.
+- `opencode_get_task_result` now includes a `progress` object. Previously it
+  returned only `status` and `result`.
+- `opencode_start_server` now reports its permission posture under
+  `permissions` (`{ external_directory, auto_approved }`).
+
+### Added
+
+- **Permission responder for headless servers.** A headless `opencode serve`
+  has no interactive approver, so any permission resolved to `ask` blocked the
+  agent forever — the session stayed genuinely busy and the task neither
+  completed nor failed. `opencode_start_server` now passes a permission config
+  to the OpenCode server *and* subscribes to its event stream to answer every
+  request.
+- **`OPENCODE_MCP_EXTERNAL_DIR`** selects how the delegated agent may touch
+  paths outside the directory the server was launched in. Precedence: env var >
+  `OPENCODE_MCP_EXTERNAL_DIR=<policy>` CLI arg > default.
+  - `read-only` (default) — reads outside the cwd are approved, writes rejected.
+  - `allow` — no boundary.
+  - `deny` — nothing outside the cwd is reachable.
+
+  Inside the cwd everything is auto-approved; the caller already owns that
+  directory. The config is deep-merged per permission key, so existing
+  `read` / `edit` / `bash` deny globs (secrets, keys, `.env`) survive untouched.
+- **Side-effect evidence in `TaskProgress`**: `mutating_tool_calls` and
+  `files_touched`, collected across every assistant turn in the session.
+  `completed` with an empty `files_touched` on a task whose whole purpose was
+  writing files is the signal that catches a silent no-op.
+- **Per-model quota annotations.** `opencode_list_agents` now returns each model
+  as `{ id, quota }` with a `per_5h` estimate and a tier (`high-volume`,
+  `balanced`, `scarce`), scraped from the OpenCode Go docs and cached on disk
+  for 24h. A sibling `models.quota_snapshot` distinguishes "this model has no
+  quota row" from "we never got the table". Overridable with
+  `OPENCODE_MCP_CACHE_DIR` and `OPENCODE_MCP_LIMITS_TTL_MS`; a failed fetch
+  falls back to the stale snapshot, so startup never depends on the network.
+
+### Fixed
+
+- **Tasks no longer hang on a permission prompt.** Previously, any task reading
+  or writing a path outside the server cwd wedged indefinitely with no way for a
+  caller to tell "working" from "stuck".
+- **`completed` is now a work check, not a timestamp check.** An assistant turn
+  that ended with no text and no tool calls reports `empty` instead of
+  `completed` with an empty result. A completed timestamp says the turn ended,
+  not that it did anything.
+- **Evidence is collected across the whole session, not just the last turn.** An
+  agent's edits land in earlier turns while the final turn is usually just
+  "DONE", so reading evidence off the last message alone reported
+  `files_touched: []` for a task that had rewritten the workspace.
+- **Cancelled tasks report `cancelled`.** `opencode_cancel_task` now records the
+  cancellation, and status derivation checks it first. An aborted session keeps
+  its completed timestamp, so a deliberately killed task was previously
+  indistinguishable from one that finished on its own. A cancelled task still
+  returns whatever it produced before the abort, `files_touched` included.
+- **The stall guard covers the empty-turn case.** `PENDING_STALL_MS` was only
+  reachable when no assistant message existed at all; once any message existed —
+  including an empty or aborted one — the guard was bypassed permanently.
+
+### Notes for contributors
+
+- The generated `@opencode-ai/sdk` types lag the running binary. Verified
+  against opencode `1.18.18` with SDK `1.17.20`: the live permission event is
+  `permission.asked` (the SDK declares only `permission.updated`), its kind
+  arrives as `properties.permission` (the SDK says `type`), and the call id is
+  nested under `properties.tool.callID` (the SDK puts it at the top level).
+  Verify wire shapes against a live server before trusting a generated type — a
+  mismatch here fails silently, because a permission that is never answered just
+  hangs.
+- Two bugs in this release passed a green unit suite and were caught only by
+  running against a live server. Mocks reproduce the contract you believe in,
+  not the one the system implements.
+
+### Not addressed
+
+- **F3** from the incident report: there is still no staleness signal on the
+  `running` path. `buildProgress` reports `current_tool` and
+  `current_tool_status` but no timing, so a caller has no field to compare
+  across polls to tell a slow task from a wedged one.

package/README.md

@@ -27,15 +27,16 @@ See [Installation](#installation) for manual config, and from-source options.
 
 | Tool                       | Description                                                                                               |
 | --------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `opencode_start_server`    | Start (or attach to) an OpenCode server instance                                                          |
+| `opencode_start_server`    | Start a new OpenCode server instance in the MCP process working directory                                 |
 | `opencode_stop_server`     | Stop a running OpenCode server instance                                                                   |
-| `opencode_list_agents`     | List agents/models available on a server instance                                                         |
+| `opencode_list_agents`     | List agents/models available on a server instance (optional `directory` selects a project)                 |
 | `opencode_start_task`      | Delegate a task to an agent by starting a new session and prompt (optional `agent` / `model` override)    |
 | `opencode_continue_task`   | Send a follow-up prompt to an existing task's session for iterative back-and-forth with the subagent      |
 | `opencode_cancel_task`     | Abort a running delegated task by cancelling its session                                                  |
-| `opencode_get_task_status` | Poll the status of a delegated task (`pending` / `running` / `completed` / `failed`); optional `include_progress` adds a partial output snippet and the currently running tool while it's still running |
+| `opencode_cleanup_workspace` | Explicitly remove an owned Git worktree after task reports finalize; dirty worktrees require opt-in discard |
+| `opencode_get_task_status` | Poll the status of a delegated task (`pending` / `running` / `completed` / `failed` / `empty` / `cancelled`); optional `include_progress` adds a partial output snippet and the currently running tool while it's still running |
 | `opencode_get_task_result` | Fetch the final result of a completed task                                                                |
-| `opencode_wait_for_task`   | Long-poll one or more delegated tasks until they finish (`mode: "all"` or `"any"`) or the timeout elapses; optional `include_progress` enriches any still-unfinished tasks in the final result with a partial output snippet and the currently running tool |
+| `opencode_wait_for_task`   | Long-poll one or more delegated tasks until they finish (`mode: "all"` or `"any"`) or the timeout elapses; optional `include_progress` best-effort enriches unfinished tasks within the same deadline, falling back to the last observed status/progress when time runs out |
 
 | Prompt          | Description                                                                                          |
 | --------------- | ---------------------------------------------------------------------------------------------------- |
@@ -44,7 +45,35 @@ See [Installation](#installation) for manual config, and from-source options.
 ## How it works
 ![opencode mcp architecture](./opencode-architecture.svg)
 
-Task delegation is **asynchronous**: starting a task returns immediately with a `task_id` instead of blocking until the subagent finishes. This lets Claude Code fire multiple `opencode_start_task` calls in parallel — each one opens an isolated OpenCode `Session` — without hitting MCP client timeouts on long-running work. Status and results are fetched separately via polling.
+Task delegation is **asynchronous**: starting a task returns immediately with a `task_id` instead of blocking until the subagent finishes. This lets hosts fire multiple `opencode_start_task` calls in parallel — each opens an isolated OpenCode `Session` — without hitting MCP client timeouts on long-running work. Tasks use the selected directory directly by default; managed Git worktrees are an explicit opt-in. Status and results are fetched separately via polling. If the prompt ACK transport is lost after OpenCode may have accepted the request, the tool returns `dispatch_uncertain` with task/run IDs and retains its lease; poll that task or cancel it rather than retrying the prompt as a new task. Definite HTTP 4xx rejection rolls back provisional run state and lease.
+
+Each accepted start or continuation prompt also receives a `run_id`. Status, progress, and results are scoped to that prompt's explicit message ID, while progress evidence remains cumulative across turns in the same run. `empty` and `cancelled` are terminal outcomes. A cancelled task can be continued; the accepted continuation becomes the current run and clears the previous cancellation state. Concurrent continuation dispatches for the same task are rejected with `dispatch_in_progress`.
+
+OpenCode 1.18.34 requires caller message IDs to start with `msg`; the MCP uses `msg_${randomUUID()}` for both start and continuation prompts. The opt-in harness also probes a bare UUID through the installed SDK/runtime using an invalid provider/model so the identifier contract can be checked without a paid request.
+
+### Execution reports and caller checks
+
+`opencode_start_task` and `opencode_continue_task` accept optional `expected_changes` (`[{ path, change }]`, where `change` is `created`, `modified`, or `deleted`) and `checks` (`[{ executable, argv, cwd?, timeout_ms? }]`). Paths and check working directories are relative to the server workspace; checks run directly with `shell: false`. Reports are additive on status/result as `run_id`, `changes`, `verification`, `diagnostics`, and `evidence`. `opencode_get_task_result` and `opencode_get_task_status` accept an optional `run_id` to retrieve a historical run; omitted means the current run.
+
+### Shared directories and managed worktrees
+
+`opencode_start_task` accepts `directory` (relative to the server directory, defaulting to it), `workspace_mode` (`shared` by default or `worktree`), and `base_ref` (worktree mode only, default `HEAD`). The selected directory must already exist. Shared mode runs directly in that canonical directory. Worktree mode creates a unique detached Git worktree at the selected committed ref; source modifications and untracked files are neither copied nor altered. When the selected base does not contain the requested nested source directory, the request fails instead of silently changing the execution directory.
+
+Start, status, result, wait, and historical-run payloads expose a `workspace` object with source and execution directories, mode, managed state, and (for worktrees) `workspace_id`, base commit, source dirty state, and lifecycle state. SDK requests are bound to the selected directory through OpenCode's directory routing. Permission responders are keyed by server and canonical directory and answer only sessions registered to that scope.
+
+Accepted worktrees are retained after task completion. Call `opencode_cleanup_workspace` with the returned `workspace_id` after reports are finalized. Cleanup serializes against task continuation/dispatch, rejects unfinished reports and dirty worktrees, and removes only worktrees provisioned by this MCP process. Set `discard_changes: true` only when changes inside that owned worktree should be discarded. Cleanup never removes source files; cached results, usage, and historical runs remain readable after the worktree is removed.
+
+### Usage reporting
+
+Status, wait, and result payloads include an additive `usage` snapshot. Its `run` summary selects direct assistant messages whose `parentID` matches that run's user-message ID; `session` summarizes all direct assistant messages observed in the session snapshot. Neither includes descendants or separate subagent sessions. Per-provider/model breakdowns preserve raw input, output, reasoning, cache-read, cache-write, and OpenCode-reported cost independently; token categories are not combined into a potentially overlapping total. Step-finish part metrics are excluded.
+
+Each metric has a nullable `value`, `complete` flag, and `missing_messages` count. Missing, invalid, or negative values remain unknown; explicit zero is known. Empty snapshots do not claim zero consumption. Cost is labeled as OpenCode-reported, with currency unspecified; it is not an invoice total. `captured_at` and `snapshot_kind` identify the observation. A finalized run caches its own run and session snapshot, so retrieving an older `run_id` after a continuation returns the historical session snapshot from that run's finalization—not a current cumulative total. Failed message reads return `report: null` with a diagnostic.
+
+The MCP server captures a bounded workspace inventory before accepted dispatch and after execution. The inventory recursively hashes workspace files except `.git` and `node_modules`; caller-declared expected paths are also checked explicitly, including paths inside otherwise skipped directories. Created/untracked, modified (including pre-existing dirty files changed since baseline), deleted, binary, and symlink entries are reported. Changes are labeled `workspace_delta`: concurrent or unmanaged writers can still make attribution uncertain. A verified run holds an exclusive lease across the canonical workspace and overlapping directories; it blocks verified and ordinary MCP task writers and conflicts fail fast with `workspace_busy`. Ordinary unverified runs may share a workspace. `session.diff` is not used as task provenance. Capture errors, missing expected changes, and scope limits are disclosed. `opencode_wait_for_task` supports `until: "execution"` (default) or `until: "report"`; report waits end on finalized failed, unavailable, or cancelled reports while respecting the whole-call timeout.
+
+Each accepted run retains its own baseline, criteria, lease, result, report, and finalized usage snapshot. Checks are executed once by the background lifecycle observer after terminal execution. Their result includes exit code/signal, duration, bounded output and exact truncation flags; timeout/cancellation terminates the child process group. Verification may be `not_requested`, `pending`, `running`, `passed`, `failed`, `unavailable`, or `cancelled`; execution success alone does not mean verification passed. Final task text/progress, reports, and usage snapshots are cached, so result queries do not rerun checks and historical results remain available after a continuation or backend removal. Workspace inventories are capped at 20,000 entries and 32 MiB of file content; check output is capped at 16 KiB per stream. These limits and shared-workspace attribution mean the report is evidence, not proof of exclusive authorship.
+
+Run the opt-in real OpenCode stdio smoke harness with `pnpm smoke`. It uses only `openai/gpt-6-luna` for its paid prompts, creates and removes temporary fixtures, and checks real reports/usage, historical retrieval, no-change and cancellation continuations, two detached worktrees editing the same relative file independently, an external read permission in a scoped worktree session, continuation in that worktree, dirty-cleanup refusal, explicit discard, and cached history after removal. The no-model identifier probe is also runnable with `node --experimental-strip-types scripts/smoke.ts --message-id-only`. The paid smoke is intentionally not part of default CI because it requires configured credentials.
 
 ## Installation
 

package/build/src/index.js

@@ -1,23 +1,37 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { DELEGATE_TASK_INSTRUCTIONS } from "./modules/shared/instructions.js";
+import { createDelegateTaskInstructions } from "./modules/shared/instructions.js";
+import { stopRunObservers } from "./modules/shared/run-observer.js";
 import { killAllServers } from "./modules/shared/server-registry.js";
 import { registerTools } from "./modules/tools/index.js";
 // Create server instance
-const server = new McpServer({
-    name: "opencode-mcp",
-    version: "1.0.0",
-    title: "OpenCode MCP",
-    description: "MCP server that drives an OpenCode instance and delegates work asynchronously to its agents",
-    websiteUrl: "https://opencode-mcp.alejandrotechnology.com",
-}, {
-    instructions: DELEGATE_TASK_INSTRUCTIONS,
-});
-function shutdown(signal) {
+async function createServer() {
+    const instructions = await createDelegateTaskInstructions();
+    return new McpServer({
+        name: "opencode-mcp",
+        version: "1.2.0",
+        title: "OpenCode MCP",
+        description: "MCP server that drives an OpenCode instance and delegates work asynchronously to its agents",
+        websiteUrl: "https://opencode-mcp.alejandrotechnology.com",
+    }, {
+        instructions,
+    });
+}
+let shuttingDown = false;
+async function shutdown(signal, exitCode = 0) {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
     console.error(`Received ${signal}, stopping tracked OpenCode servers...`);
+    const checksDrained = await stopRunObservers();
+    if (!checksDrained) {
+        console.error("One or more check process groups could not be confirmed stopped; OpenCode servers remain active and shutdown can be retried.");
+        shuttingDown = false;
+        return;
+    }
     killAllServers();
-    process.exit(0);
+    process.exit(exitCode);
 }
 // Terminal closed (SIGHUP), Ctrl+C (SIGINT), or a normal kill (SIGTERM):
 // make sure no `opencode serve` child keeps running after we die.
@@ -25,15 +39,18 @@ process.on("SIGHUP", shutdown);
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);
 // Safety net for any other exit path (uncaught exception, process.exit elsewhere).
-process.on("exit", killAllServers);
+process.on("exit", () => {
+    killAllServers();
+});
 async function main() {
+    const server = await createServer();
     registerTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("OpenCode MCP Server running on stdio");
 }
-main().catch((error) => {
+main().catch(async (error) => {
     console.error("Fatal error in main():", error);
-    process.exit(1);
+    await shutdown("SIGTERM", 1);
 });
 //# sourceMappingURL=index.js.map

package/build/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,yBAAyB;AACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;IACE,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,cAAc;IACrB,WAAW,EACT,6FAA6F;IAC/F,UAAU,EAAE,8CAA8C;CAC3D,EACD;IACE,YAAY,EAAE,0BAA0B;CACzC,CACF,CAAC;AAEF,SAAS,QAAQ,CAAC,MAAsB;IACtC,OAAO,CAAC,KAAK,CAAC,YAAY,MAAM,wCAAwC,CAAC,CAAC;IAC1E,cAAc,EAAE,CAAC;IACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,yEAAyE;AACzE,kEAAkE;AAClE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC/B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAChC,mFAAmF;AACnF,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEnC,KAAK,UAAU,IAAI;IACjB,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;AACxD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;IAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,8BAA8B,EAAE,MAAM,kCAAkC,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,yBAAyB;AACzB,KAAK,UAAU,YAAY;IACzB,MAAM,YAAY,GAAG,MAAM,8BAA8B,EAAE,CAAC;IAC5D,OAAO,IAAI,SAAS,CAClB;QACE,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,6FAA6F;QAC/F,UAAU,EAAE,8CAA8C;KAC3D,EACD;QACE,YAAY;KACb,CACF,CAAC;AACJ,CAAC;AAED,IAAI,YAAY,GAAG,KAAK,CAAC;AAEzB,KAAK,UAAU,QAAQ,CAAC,MAAsB,EAAE,QAAQ,GAAG,CAAC;IAC1D,IAAI,YAAY;QAAE,OAAO;IACzB,YAAY,GAAG,IAAI,CAAC;IACpB,OAAO,CAAC,KAAK,CAAC,YAAY,MAAM,wCAAwC,CAAC,CAAC;IAC1E,MAAM,aAAa,GAAG,MAAM,gBAAgB,EAAE,CAAC;IAC/C,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,CAAC,KAAK,CACX,8HAA8H,CAC/H,CAAC;QACF,YAAY,GAAG,KAAK,CAAC;QACrB,OAAO;IACT,CAAC;IACD,cAAc,EAAE,CAAC;IACjB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED,yEAAyE;AACzE,kEAAkE;AAClE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC/B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAChC,mFAAmF;AACnF,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;IACtB,cAAc,EAAE,CAAC;AACnB,CAAC,CAAC,CAAC;AAEH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,MAAM,YAAY,EAAE,CAAC;IACpC,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;AACxD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;IAC3B,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC"}

package/build/src/modules/shared/execution-report.d.ts

@@ -0,0 +1,66 @@
+import { type ChildProcess, spawn } from "node:child_process";
+export type ExpectedChange = {
+    path: string;
+    change: "created" | "modified" | "deleted";
+};
+export type VerificationCheck = {
+    executable: string;
+    argv: string[];
+    cwd?: string;
+    timeout_ms?: number;
+};
+export type WorkspaceSnapshot = {
+    root: string;
+    files: Map<string, string>;
+};
+export type FileChange = ExpectedChange & {
+    evidence: "workspace_delta";
+};
+export type VerificationState = "not_requested" | "pending" | "running" | "passed" | "failed" | "unavailable" | "cancelled";
+export type CheckResult = {
+    executable: string;
+    argv: string[];
+    exit_code: number | null;
+    signal: NodeJS.Signals | null;
+    duration_ms: number;
+    stdout: string;
+    stderr: string;
+    stdout_truncated: boolean;
+    stderr_truncated: boolean;
+    timed_out?: boolean;
+    termination_confirmed?: boolean;
+    error?: string;
+};
+export type ExecutionReport = {
+    changes: FileChange[];
+    verification: {
+        state: VerificationState;
+        checks: CheckResult[];
+        execution_state?: string;
+    };
+    diagnostics: string[];
+    evidence: {
+        source: "workspace_delta";
+        inventory_scope: "recursive_except_git_and_node_modules_plus_explicit_paths";
+        complete: boolean;
+        errors: string[];
+        attribution: "uncertain_shared_workspace";
+    };
+};
+/** @internal Signal a direct check child and its descendants without invoking a shell. */
+export declare function signalCheckProcess(child: Pick<ChildProcess, "pid" | "kill">, force: boolean, platform?: NodeJS.Platform, spawnKiller?: typeof spawn): Promise<boolean>;
+/** Abort in-flight checks and wait until every check process has drained or the deadline expires. */
+export declare function abortAndDrainChecks(controller: AbortController, timeoutMs?: number): Promise<boolean>;
+/** @internal Confirm process-group termination, with an injectable state probe for tests. */
+export declare function waitForProcessGroupExit(pid: number, timeoutMs?: number, readStates?: (groupId: number) => Promise<string[] | undefined>): Promise<boolean>;
+/** @internal Read process-group states, with an injectable spawner for failure-path tests. */
+export declare function processGroupStates(groupId: number, spawnProcess?: typeof spawn): Promise<string[] | undefined>;
+export declare function validateRelativePath(value: string): boolean;
+export declare function validateRelativeCwd(value: string): boolean;
+export declare function captureWorkspace(directory: string, explicitPaths?: string[]): Promise<WorkspaceSnapshot>;
+export declare function compareWorkspace(before: Awaited<ReturnType<typeof captureWorkspace>>, after: Awaited<ReturnType<typeof captureWorkspace>>): FileChange[];
+export declare function runCheck(check: VerificationCheck, workspace: string, signal?: AbortSignal): Promise<CheckResult>;
+export declare function reserveWorkspace(directory: string, exclusive: boolean): Promise<symbol | undefined>;
+export declare function releaseWorkspace(token: symbol): void;
+export declare function captureReport(before: Awaited<ReturnType<typeof captureWorkspace>>, expected: ExpectedChange[], checks: VerificationCheck[], execution: string, signal?: AbortSignal): Promise<ExecutionReport>;
+//# sourceMappingURL=execution-report.d.ts.map

package/build/src/modules/shared/execution-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-report.d.ts","sourceRoot":"","sources":["../../../../src/modules/shared/execution-report.ts"],"names":[],"mappings":"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"}