mcp-server-opencode 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 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.

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

@@ -2,6 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.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
@@ -9,7 +10,7 @@ async function createServer() {
     const instructions = await createDelegateTaskInstructions();
     return new McpServer({
         name: "opencode-mcp",
-        version: "1.0.0",
+        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",
@@ -17,10 +18,20 @@ async function createServer() {
         instructions,
     });
 }
-function shutdown(signal) {
+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.
@@ -28,7 +39,9 @@ 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);
@@ -36,8 +49,8 @@ async function main() {
     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,8BAA8B,EAAE,MAAM,kCAAkC,CAAC;AAClF,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,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,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,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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"}

package/build/src/modules/shared/execution-report.js

@@ -0,0 +1,407 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile, readlink, realpath } from "node:fs/promises";
+import path from "node:path";
+const MAX_FILES = 20_000;
+const MAX_BYTES = 32 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 16 * 1024;
+function insideWorkspace(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)));
+}
+/** @internal Signal a direct check child and its descendants without invoking a shell. */
+export function signalCheckProcess(child, force, platform = process.platform, spawnKiller = spawn) {
+    const signalName = force ? "SIGKILL" : "SIGTERM";
+    const childPid = child.pid;
+    if (platform === "win32" && childPid) {
+        return new Promise((resolve) => {
+            const killer = spawnKiller("taskkill.exe", ["/PID", String(childPid), "/T", ...(force ? ["/F"] : [])], { shell: false, stdio: "ignore", windowsHide: true });
+            killer.once("error", () => {
+                child.kill(signalName);
+                resolve(false);
+            });
+            killer.once("close", (code) => resolve(code === 0));
+            killer.unref();
+        });
+    }
+    if (childPid) {
+        try {
+            process.kill(-childPid, signalName);
+        }
+        catch (error) {
+            if (force && error instanceof Error && "code" in error && error.code === "ESRCH")
+                return Promise.resolve(true);
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH"))
+                return Promise.resolve(false);
+        }
+        return force ? waitForProcessGroupExit(childPid) : Promise.resolve(true);
+    }
+    child.kill(signalName);
+    return Promise.resolve(false);
+}
+const activeChecks = new WeakMap();
+/** Abort in-flight checks and wait until every check process has drained or the deadline expires. */
+export async function abortAndDrainChecks(controller, timeoutMs = 5_000) {
+    controller.abort(new Error("workspace execution is stopping"));
+    const checks = [...(activeChecks.get(controller.signal) ?? [])];
+    if (checks.length === 0)
+        return true;
+    let resolveTimeout;
+    const timeout = new Promise((resolve) => {
+        resolveTimeout = resolve;
+    });
+    const timer = setTimeout(() => resolveTimeout(false), timeoutMs);
+    timer.unref?.();
+    try {
+        return await Promise.race([
+            Promise.all(checks).then((confirmations) => confirmations.every(Boolean)),
+            timeout,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** @internal Confirm process-group termination, with an injectable state probe for tests. */
+export async function waitForProcessGroupExit(pid, timeoutMs = 2_000, readStates = processGroupStates) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            process.kill(-pid, 0);
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ESRCH")
+                return true;
+            const states = await readStates(pid);
+            if (states &&
+                (states.length === 0 ||
+                    states.every((state) => state.startsWith("Z") || state.startsWith("X"))))
+                return true;
+            return false;
+        }
+        const states = await readStates(pid);
+        if (states &&
+            states.length > 0 &&
+            states.every((state) => state.startsWith("Z") || state.startsWith("X")))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    return false;
+}
+/** @internal Read process-group states, with an injectable spawner for failure-path tests. */
+export async function processGroupStates(groupId, spawnProcess = spawn) {
+    return new Promise((resolve) => {
+        const ps = spawnProcess("ps", ["-axo", "pgid=,stat="], {
+            shell: false,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        let output = "";
+        ps.stdout.on("data", (chunk) => {
+            output += chunk.toString("utf8");
+        });
+        ps.once("error", () => resolve(undefined));
+        ps.once("close", (code) => {
+            if (code !== 0)
+                return resolve(undefined);
+            const states = output.split("\n").flatMap((line) => {
+                const [pidText, state] = line.trim().split(/\s+/);
+                return Number(pidText) === groupId && state ? [state] : [];
+            });
+            resolve(states);
+        });
+    });
+}
+export function validateRelativePath(value) {
+    return (value.length > 0 &&
+        !path.isAbsolute(value) &&
+        !value.split(/[\\/]/).includes("..") &&
+        value !== ".");
+}
+export function validateRelativeCwd(value) {
+    return value === "." || value === "" || validateRelativePath(value);
+}
+async function walk(root, dir = root, result = new Map(), budget = { bytes: 0 }) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name === ".git" || entry.name === "node_modules")
+            continue;
+        const full = path.join(dir, entry.name);
+        const rel = path.relative(root, full);
+        if (result.size >= MAX_FILES)
+            throw new Error(`file inventory exceeded ${MAX_FILES} entries`);
+        const info = await lstat(full);
+        if (info.isDirectory())
+            await walk(root, full, result, budget);
+        else {
+            if (!info.isSymbolicLink() && budget.bytes + info.size > MAX_BYTES)
+                throw new Error(`file inventory exceeded ${MAX_BYTES} bytes`);
+            const content = info.isSymbolicLink()
+                ? `symlink:${await readlink(full)}`
+                : await readFile(full);
+            budget.bytes += typeof content === "string" ? Buffer.byteLength(content) : content.length;
+            if (budget.bytes > MAX_BYTES)
+                throw new Error(`file inventory exceeded ${MAX_BYTES} bytes`);
+            result.set(rel, createHash("sha256").update(content).digest("hex"));
+        }
+    }
+    return result;
+}
+export async function captureWorkspace(directory, explicitPaths = []) {
+    const root = await realpath(directory);
+    const files = await walk(root);
+    let explicitBytes = 0;
+    for (const relative of explicitPaths) {
+        if (!validateRelativePath(relative))
+            throw new Error(`invalid expected workspace path: ${relative}`);
+        const full = path.resolve(root, relative);
+        const info = await lstat(full).catch(() => undefined);
+        if (!info || info.isDirectory())
+            continue;
+        const alreadyInventoried = files.has(relative);
+        if (!info.isSymbolicLink() && !alreadyInventoried && explicitBytes + info.size > MAX_BYTES)
+            throw new Error(`explicit files exceeded ${MAX_BYTES} bytes`);
+        let content;
+        if (!info.isSymbolicLink()) {
+            const canonicalFile = await realpath(full);
+            if (!insideWorkspace(root, canonicalFile))
+                throw new Error(`expected workspace path resolves outside the workspace: ${relative}`);
+            if (!alreadyInventoried)
+                explicitBytes += info.size;
+            content = await readFile(full);
+        }
+        else
+            content = `symlink:${await readlink(full)}`;
+        files.set(relative, createHash("sha256").update(content).digest("hex"));
+    }
+    return { root, files };
+}
+export function compareWorkspace(before, after) {
+    const changes = [];
+    for (const [file, hash] of after.files) {
+        const old = before.files.get(file);
+        if (old !== hash)
+            changes.push({
+                path: file,
+                change: old === undefined ? "created" : "modified",
+                evidence: "workspace_delta",
+            });
+    }
+    for (const file of before.files.keys())
+        if (!after.files.has(file))
+            changes.push({ path: file, change: "deleted", evidence: "workspace_delta" });
+    return changes.sort((a, b) => a.path.localeCompare(b.path));
+}
+export async function runCheck(check, workspace, signal) {
+    const started = Date.now();
+    const canonicalWorkspace = await realpath(workspace).catch(() => "");
+    const cwd = check.cwd ? path.resolve(canonicalWorkspace, check.cwd) : canonicalWorkspace;
+    const canonical = await realpath(cwd).catch(() => "");
+    if (!canonicalWorkspace || !canonical || !insideWorkspace(canonicalWorkspace, canonical)) {
+        return {
+            executable: check.executable,
+            argv: check.argv,
+            exit_code: null,
+            signal: null,
+            duration_ms: Date.now() - started,
+            stdout: "",
+            stderr: "",
+            stdout_truncated: false,
+            stderr_truncated: false,
+            error: "check cwd is missing or outside workspace",
+        };
+    }
+    if (signal?.aborted) {
+        return {
+            executable: check.executable,
+            argv: check.argv,
+            exit_code: null,
+            signal: null,
+            duration_ms: Date.now() - started,
+            stdout: "",
+            stderr: "",
+            stdout_truncated: false,
+            stderr_truncated: false,
+            error: "check cancelled",
+        };
+    }
+    let resolveDrain;
+    const drained = new Promise((resolve) => {
+        resolveDrain = resolve;
+    });
+    if (signal) {
+        const checks = activeChecks.get(signal) ?? new Set();
+        checks.add(drained);
+        activeChecks.set(signal, checks);
+    }
+    return new Promise((resolve) => {
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        let settled = false;
+        let timedOut = false;
+        let cancelled = false;
+        let closeResult;
+        let termination;
+        const child = spawn(check.executable, check.argv, {
+            cwd: canonical,
+            shell: false,
+            detached: process.platform !== "win32",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let killTimer;
+        const terminate = () => {
+            if (termination)
+                return;
+            termination = (async () => {
+                const graceful = await signalCheckProcess(child, false);
+                if (graceful) {
+                    await new Promise((resolve) => {
+                        killTimer = setTimeout(resolve, 250);
+                        killTimer.unref?.();
+                    });
+                }
+                killTimer = undefined;
+                return signalCheckProcess(child, true);
+            })();
+            void termination.then((confirmed) => {
+                if (closeResult)
+                    finish(closeResult.code, closeResult.signal, undefined, confirmed);
+            });
+        };
+        const append = (target, chunk, set, truncated) => {
+            const combined = Buffer.concat([target, chunk]);
+            if (combined.length > MAX_OUTPUT_BYTES)
+                truncated();
+            set(combined.subarray(-MAX_OUTPUT_BYTES));
+        };
+        child.stdout.on("data", (chunk) => {
+            append(stdout, chunk, (value) => {
+                stdout = value;
+            }, () => {
+                stdoutTruncated = true;
+            });
+        });
+        child.stderr.on("data", (chunk) => {
+            append(stderr, chunk, (value) => {
+                stderr = value;
+            }, () => {
+                stderrTruncated = true;
+            });
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            terminate();
+        }, check.timeout_ms ?? 30_000);
+        const onAbort = () => {
+            cancelled = true;
+            terminate();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const finish = (code, closeSignal, error, terminationConfirmed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(killTimer);
+            killTimer = undefined;
+            signal?.removeEventListener("abort", onAbort);
+            if (signal) {
+                const checks = activeChecks.get(signal);
+                checks?.delete(drained);
+                if (checks?.size === 0)
+                    activeChecks.delete(signal);
+            }
+            resolveDrain(terminationConfirmed !== false);
+            resolve({
+                executable: check.executable,
+                argv: check.argv,
+                exit_code: code,
+                signal: closeSignal,
+                duration_ms: Date.now() - started,
+                stdout: stdout.toString("utf8"),
+                stderr: stderr.toString("utf8"),
+                stdout_truncated: stdoutTruncated,
+                stderr_truncated: stderrTruncated,
+                timed_out: timedOut,
+                ...(terminationConfirmed === undefined
+                    ? {}
+                    : { termination_confirmed: terminationConfirmed }),
+                ...(cancelled ? { error: "check cancelled" } : {}),
+                ...(terminationConfirmed === false
+                    ? { error: "check process termination could not be confirmed" }
+                    : {}),
+                ...(error ? { error: error.message } : {}),
+            });
+        };
+        child.once("error", (error) => finish(null, null, error));
+        child.once("close", (code, closeSignal) => {
+            closeResult = { code, signal: closeSignal };
+            if (termination) {
+                void termination.then((confirmed) => finish(code, closeSignal, undefined, confirmed));
+            }
+            else
+                finish(code, closeSignal);
+        });
+    });
+}
+const reservations = [];
+export async function reserveWorkspace(directory, exclusive) {
+    const root = await realpath(directory);
+    const overlap = (a, b) => a === b || a.startsWith(`${b}${path.sep}`) || b.startsWith(`${a}${path.sep}`);
+    if (reservations.some((item) => overlap(root, item.root) && (exclusive || item.exclusive)))
+        return undefined;
+    const token = Symbol(root);
+    reservations.push({ root, exclusive, token });
+    return token;
+}
+export function releaseWorkspace(token) {
+    const index = reservations.findIndex((item) => item.token === token);
+    if (index >= 0)
+        reservations.splice(index, 1);
+}
+export async function captureReport(before, expected, checks, execution, signal) {
+    const errors = [];
+    let changes = [];
+    try {
+        changes = compareWorkspace(before, await captureWorkspace(before.root, expected.map((item) => item.path)));
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    const results = [];
+    if (execution !== "cancelled")
+        for (const check of checks)
+            results.push(await runCheck(check, before.root, signal));
+    const missing = expected.filter((item) => !changes.some((actual) => actual.path === item.path && actual.change === item.change));
+    const checksPassed = results.every((result) => result.exit_code === 0 && result.timed_out !== true && !result.error);
+    const state = errors.length
+        ? "unavailable"
+        : execution === "cancelled" || signal?.aborted
+            ? "cancelled"
+            : execution !== "completed"
+                ? "failed"
+                : checksPassed && missing.length === 0
+                    ? "passed"
+                    : "failed";
+    return {
+        changes,
+        verification: {
+            state: checks.length || expected.length ? state : "not_requested",
+            checks: results,
+        },
+        diagnostics: [
+            ...errors,
+            ...missing.map((item) => `expected ${item.change}: ${item.path} was not observed`),
+        ],
+        evidence: {
+            source: "workspace_delta",
+            inventory_scope: "recursive_except_git_and_node_modules_plus_explicit_paths",
+            complete: errors.length === 0,
+            errors,
+            attribution: "uncertain_shared_workspace",
+        },
+    };
+}
+//# sourceMappingURL=execution-report.js.map