mtech-ai-local-runner 0.1.3 → 0.1.4

package/README.md

@@ -7,3 +7,19 @@ npx mtech-ai-local-runner setup
 ```
 
 The package stores safe runner configuration locally and keeps OAuth refresh credentials in macOS Keychain when available.
+
+Public npm installation requires no npm account or publishing OTP. Setup requires Gateway OAuth login, and local Claude Code must already be authenticated (`claude auth status`).
+
+## 0.1.4
+
+- Independently verify the approved contract payload and task-package fingerprints before creating a runtime binding.
+- Include actual diff and changed-file manifest hashes in terminal events, with a final checkpoint before completion.
+- Fail closed on missing terminal events, failed launches, unavailable evidence, or rejected event reports.
+- Read and acknowledge supervisor controls; preserve the terminal status when reconciling a daemon restart.
+
+Existing employees can upgrade their installed daemon with:
+
+```bash
+npx mtech-ai-local-runner@0.1.4 setup
+npx mtech-ai-local-runner@0.1.4 doctor
+```

package/dist/src/cli.js

@@ -203,7 +203,7 @@ export async function main(argv, env, io = {}) {
                 const authenticated = await runFile(binary, ["auth", "status"], { encoding: "utf8" }).then(() => true).catch(() => false);
                 const registered = await gateway.registerLocalRunner({
                     deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${config.gatewayMcpUrl}`).digest("hex"),
-                    displayName: runnerDisplayName(), packageVersion: "0.1.3",
+                    displayName: runnerDisplayName(), packageVersion: "0.1.4",
                     capabilities: [{ adapter: "claude_code_cli", version: "1", capabilities: ["repository_read", "repository_edit", "shell_test", "git_diff"], authenticated }],
                 });
                 await localStore.save({ schemaVersion: 1, gatewayMcpUrl: config.gatewayMcpUrl, runnerId: registered.runner.id, workspaceRoot: config.workspaceRoot, concurrency: 1 });

package/dist/src/daemon/execution-coordinator.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { PROTOCOL_VERSION } from "../protocol.js";
+import { PROTOCOL_VERSION, isTerminalEventType, validateEvent, MAX_EVENT_SUMMARY_CHARS } from "../protocol.js";
 function canonical(value) {
     if (Array.isArray(value))
         return value.map(canonical);
@@ -12,6 +12,17 @@ export function fingerprint(value) {
         .replace(/[\u007f-\uffff]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
     return createHash("sha256").update(json).digest("hex");
 }
+export function contractFingerprint(payload) {
+    const unsigned = structuredClone(payload);
+    if (unsigned.provenance && typeof unsigned.provenance === "object") {
+        delete unsigned.provenance.compiled_at;
+    }
+    // Contract compiler uses PHP JSON's default escaped slashes. Job packages
+    // use JSON_UNESCAPED_SLASHES; the two hashing domains must stay distinct.
+    const json = JSON.stringify(canonical(unsigned)).replace(/\//g, "\\/")
+        .replace(/[\u007f-\uffff]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+    return createHash("sha256").update(json).digest("hex");
+}
 function text(value, label) {
     if (typeof value !== "string" || value.length === 0)
         throw new Error(`task package is missing ${label}`);
@@ -27,7 +38,7 @@ export class ExecutionCoordinator {
         const repository = pkg.repository;
         const adapterId = text(pkg.runtime_adapter, "runtime adapter");
         const adapterVersion = text(pkg.runtime_adapter_version, "runtime adapter version");
-        const contractFingerprint = text(pkg.contract_fingerprint, "contract fingerprint");
+        const expectedContractFingerprint = text(pkg.contract_fingerprint, "contract fingerprint");
         const workspace = await this.deps.workspaces.create({
             jobId: job.id,
             repositoryKey: text(repository?.key, "repository key"),
@@ -37,45 +48,129 @@ export class ExecutionCoordinator {
         const adapter = await this.deps.registry.select(adapterId, adapterVersion, { worktreePath: workspace.path, jobId: job.id });
         await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: "shadow", workspaceManifest: workspace.manifest });
         const gatewayShadow = await this.deps.gateway.shadow(job);
-        if (gatewayShadow.contractFingerprint !== contractFingerprint || gatewayShadow.taskPackageFingerprint !== fingerprint(pkg)) {
+        if (contractFingerprint(gatewayShadow.contractPayload) !== expectedContractFingerprint || gatewayShadow.contractFingerprint !== expectedContractFingerprint || gatewayShadow.taskPackageFingerprint !== fingerprint(pkg)) {
             throw new Error("contract or task-package fingerprint mismatch before binding");
         }
         const binding = await this.deps.gateway.createBinding({ ...job, checkoutPath: workspace.path });
         await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: "running", bindingId: binding.bindingId, workspaceManifest: workspace.manifest });
-        await adapter.start({ bindingId: binding.bindingId, sessionId: binding.bindingId, taskPackage: binding.taskPackage, resolvedModelId: binding.resolvedModelId });
         let heartbeatFailure = null;
-        const heartbeatTimer = this.deps.gateway.heartbeat ? setInterval(() => {
-            void this.deps.gateway.heartbeat?.(binding.bindingId, job).catch(async (error) => {
+        let requestedTerminal;
+        let commandCursor = 0;
+        let controlsStopped = false;
+        let controlsInFlight;
+        const readControls = async () => {
+            if (!this.deps.gateway.readCommands || controlsStopped || requestedTerminal)
+                return;
+            if (controlsInFlight)
+                return controlsInFlight;
+            controlsInFlight = (async () => {
+                for (const command of await this.deps.gateway.readCommands(binding.bindingId, commandCursor)) {
+                    if (controlsStopped)
+                        return;
+                    if (["cancel", "pause", "request_replan"].includes(command.command)) {
+                        requestedTerminal = { eventType: command.command === "cancel" ? "cancelled" : "blocked", summary: `supervisor ${command.command} acknowledged` };
+                        await adapter.cancel();
+                    }
+                    else {
+                        await adapter.command(command);
+                    }
+                    if (!this.deps.gateway.acknowledgeCommand)
+                        throw new Error("daemon command acknowledgement is unavailable");
+                    await this.deps.gateway.acknowledgeCommand(binding.bindingId, command.sequence);
+                    commandCursor = command.sequence;
+                    if (requestedTerminal)
+                        break;
+                }
+            })();
+            try {
+                await controlsInFlight;
+            }
+            finally {
+                controlsInFlight = undefined;
+            }
+        };
+        const heartbeatTimer = this.deps.gateway.heartbeat || this.deps.gateway.readCommands ? setInterval(() => {
+            void (async () => { await this.deps.gateway.heartbeat?.(binding.bindingId, job); await readControls(); })().catch(async (error) => {
                 heartbeatFailure = error instanceof Error ? error : new Error(String(error));
                 await adapter.cancel().catch(() => undefined);
             });
         }, 30_000) : undefined;
         heartbeatTimer?.unref();
-        let terminal = { eventType: "completed", summary: "adapter completed" };
+        let terminal;
         let sequence = 0;
+        let checkpointSeen = false;
+        const append = async (event) => {
+            let payload = event.payload;
+            if (isTerminalEventType(event.eventType)) {
+                const evidence = this.deps.terminalEvidenceCollector.collect({ checkoutPath: workspace.path, baseSha: workspace.baseCommitSha });
+                payload = { ...payload, diff_hash: evidence.diffHash, changed_file_manifest_hash: evidence.changedFileManifestHash };
+            }
+            const normalized = {
+                protocolVersion: PROTOCOL_VERSION, bindingId: binding.bindingId,
+                sequence: sequence + 1, eventType: event.eventType,
+                summary: event.summary.slice(0, MAX_EVENT_SUMMARY_CHARS),
+                ...(payload ? { payload } : {}),
+                idempotencyKey: `${binding.bindingId}:${sequence + 1}`, occurredAt: new Date().toISOString(),
+            };
+            validateEvent(normalized);
+            if (!this.deps.gateway.appendEvent)
+                throw new Error("daemon event reporting is unavailable");
+            await this.deps.gateway.appendEvent(binding.bindingId, normalized);
+            sequence = normalized.sequence;
+            if (event.eventType === "checkpoint_ready")
+                checkpointSeen = true;
+            await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: "running", bindingId: binding.bindingId, eventCursor: sequence, ...(isTerminalEventType(event.eventType) ? { terminalEventType: event.eventType } : {}), workspaceManifest: workspace.manifest });
+        };
         try {
-            if (adapter.events) {
+            await adapter.start({ bindingId: binding.bindingId, sessionId: binding.bindingId, taskPackage: binding.taskPackage, resolvedModelId: binding.resolvedModelId });
+            await readControls();
+            if (adapter.events && !requestedTerminal) {
                 for await (const event of adapter.events()) {
                     if (heartbeatFailure)
                         throw heartbeatFailure;
-                    terminal = event;
-                    sequence += 1;
-                    await this.deps.gateway.appendEvent?.(binding.bindingId, {
-                        protocolVersion: PROTOCOL_VERSION,
-                        bindingId: binding.bindingId,
-                        sequence,
-                        eventType: event.eventType,
-                        summary: event.summary,
-                        ...(event.payload ? { payload: event.payload } : {}),
-                        idempotencyKey: `${binding.bindingId}:${sequence}`,
-                        occurredAt: new Date().toISOString(),
-                    });
-                    if (["completed", "failed", "cancelled", "blocked", "scope_conflict"].includes(event.eventType))
+                    if (requestedTerminal)
+                        break;
+                    if (event.eventType === "completed" && !checkpointSeen) {
+                        await append({ eventType: "checkpoint_ready", summary: "final checkpoint ready" });
+                    }
+                    if (isTerminalEventType(event.eventType)) {
+                        if (controlsInFlight)
+                            await controlsInFlight;
+                        if (requestedTerminal)
+                            break;
+                        controlsStopped = true;
+                    }
+                    await append(event);
+                    if (isTerminalEventType(event.eventType) || ["blocked", "scope_conflict"].includes(event.eventType)) {
+                        controlsStopped = true;
+                        terminal = event;
                         break;
+                    }
+                    await readControls();
                 }
             }
+            if (controlsInFlight)
+                await controlsInFlight;
+            if (requestedTerminal) {
+                terminal = requestedTerminal;
+                await append(terminal);
+            }
+            if (heartbeatFailure)
+                throw heartbeatFailure;
+            if (!terminal) {
+                terminal = { eventType: "failed", summary: "adapter ended without a terminal event" };
+                await append(terminal);
+            }
+        }
+        catch (error) {
+            await adapter.cancel().catch(() => undefined);
+            // Do not complete a job whose terminal evidence was not acknowledged.
+            // A safe bounded reason prevents raw adapter/transport errors leaking.
+            terminal = { eventType: "failed", summary: "daemon execution or event reporting failed" };
+            await append(terminal);
         }
         finally {
+            controlsStopped = true;
             if (heartbeatTimer)
                 clearInterval(heartbeatTimer);
         }

package/dist/src/daemon/runtime.js

@@ -15,6 +15,7 @@ import { ExecutionCoordinator } from "./execution-coordinator.js";
 import { JobPoller } from "./job-poller.js";
 import { ProcessLock } from "./process-lock.js";
 import { Daemon } from "./daemon.js";
+import { buildTerminalEvidenceCollector } from "../safety/terminal-evidence.js";
 import { McpRelay } from "../auth/mcp-relay.js";
 const execFileAsync = promisify(execFile);
 export async function buildDaemon(input) {
@@ -53,15 +54,17 @@ export async function buildDaemon(input) {
     const versions = Object.fromEntries(probes.filter((probe) => probe.available && probe.authenticated).map((probe) => [probe.id, probe.version]));
     const state = new FileDaemonStateStore(input.stateRoot);
     const coordinator = new ExecutionCoordinator({
+        terminalEvidenceCollector: buildTerminalEvidenceCollector(),
         gateway: {
-            shadow: async (job) => ({
+            shadow: (job) => gateway.localJobShadow({ workLoopId: job.workLoopId,
                 contractFingerprint: job.gatewayContractFingerprint ?? "",
-                taskPackageFingerprint: job.gatewayTaskPackageFingerprint ?? "",
-            }),
+                taskPackageFingerprint: job.gatewayTaskPackageFingerprint ?? "" }),
             createBinding: async (job) => gateway.createLocalJobBinding({
                 jobId: job.id, generation: job.generation, jobLeaseToken: job.leaseToken,
                 launchGrant: job.launchGrant, workLoopId: job.workLoopId, checkoutPath: job.checkoutPath,
             }),
+            readCommands: (bindingId, cursor) => gateway.readCommands(bindingId, cursor),
+            acknowledgeCommand: (bindingId, sequence) => gateway.acknowledgeCommand(bindingId, sequence),
             appendEvent: (bindingId, event) => gateway.appendEvent(bindingId, event),
             heartbeat: async (bindingId, job) => {
                 await Promise.all([gateway.heartbeat(bindingId), gateway.heartbeatLocalJob({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken })]);
@@ -75,7 +78,7 @@ export async function buildDaemon(input) {
     const poller = new JobPoller({
         heartbeat: () => gateway.heartbeatLocalRunner({
             deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
-            displayName: runnerDisplayName(), packageVersion: "0.1.3",
+            displayName: runnerDisplayName(), packageVersion: "0.1.4",
             capabilities: probes.map((probe) => ({ adapter: probe.id, version: probe.version,
                 capabilities: probe.capabilities, authenticated: probe.available && probe.authenticated })),
         }).then(() => undefined),
@@ -103,8 +106,8 @@ export async function buildDaemon(input) {
                 try {
                     const receipt = await gateway.readBindingEvents(previous.bindingId, previous.eventCursor ?? 0);
                     const status = receipt.terminal
-                        ? receipt.terminalEventType === "completed" ? "completed"
-                            : receipt.terminalEventType === "cancelled" ? "cancelled" : "failed"
+                        ? (receipt.terminalEventType ?? previous.terminalEventType) === "completed" ? "completed"
+                            : (receipt.terminalEventType ?? previous.terminalEventType) === "cancelled" ? "cancelled" : "failed"
                         : "failed";
                     await gateway.completeLocalJob({
                         jobId: previous.jobId, generation: previous.generation, leaseToken: previous.leaseToken, status,

package/dist/src/gateway-client.js

@@ -417,6 +417,23 @@ export class McpGatewayClient {
     async localRunnerStatus() {
         return this.callTool("local_agent_runner_status", { runner_id: this.runnerId });
     }
+    async localJobShadow(input) {
+        const shown = await this.callTool("work_loop_show", { work_loop_id: input.workLoopId });
+        if (shown.loop.environment !== "development")
+            throw new Error("local agent runtime is development-only");
+        const result = await this.callTool("work_execution_contract_show", {
+            contract_id: requiredString(shown.loop.work_execution_contract_id, "execution contract ID"),
+        });
+        if (result.contract.status !== "approved")
+            throw new Error("execution contract is not approved");
+        const payload = result.contract.contract_payload;
+        if (!payload || typeof payload !== "object" || Array.isArray(payload))
+            throw new Error("Gateway response is missing contract payload");
+        const storedFingerprint = requiredString(result.contract.content_fingerprint, "contract fingerprint");
+        if (storedFingerprint !== input.contractFingerprint)
+            throw new Error("claimed contract fingerprint differs from approved contract");
+        return { contractFingerprint: storedFingerprint, taskPackageFingerprint: input.taskPackageFingerprint, contractPayload: payload };
+    }
     async createLocalJobBinding(input) {
         const clientSessionReference = uuidv5(`local-agent-job:${input.jobId}:${input.generation}`, uuidv5.URL);
         const result = await this.callTool("local_agent_job_binding_create", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtech-ai-local-runner",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "license": "UNLICENSED",
   "bin": {