mtech-ai-local-runner 0.1.2 → 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

@@ -184,7 +184,7 @@ export async function main(argv, env, io = {}) {
     const fetchFn = io.fetchFn || fetch;
     if (isServiceConfig(config)) {
         const localStore = new FileLocalConfigStore(config.stateRoot);
-        const launchd = io.launchdService ?? new LaunchdService({ home: env.HOME ?? "", uid: process.getuid?.() ?? 0 });
+        const launchd = io.launchdService ?? new LaunchdService({ home: env.HOME ?? "", uid: process.getuid?.() ?? 0, path: env.PATH });
         try {
             if (config.mode === "setup") {
                 if (process.platform !== "darwin")
@@ -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.2",
+                    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/job-poller.js

@@ -10,6 +10,7 @@ export class JobPoller {
         if (this.stopped)
             return;
         try {
+            await this.deps.heartbeat?.();
             const claim = await this.deps.wait();
             this.failures = 0;
             if (claim.status === "claimed" && claim.job)

package/dist/src/daemon/process-lock.js

@@ -1,4 +1,4 @@
-import { mkdir, open, rm } from "node:fs/promises";
+import { mkdir, open, rm, readFile, unlink } from "node:fs/promises";
 import { dirname } from "node:path";
 export class ProcessLock {
     path;
@@ -8,15 +8,41 @@ export class ProcessLock {
     }
     async acquire() {
         await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const guard = `${this.path}.acquire`;
         try {
-            this.handle = await open(this.path, "wx", 0o600);
+            await mkdir(guard, { mode: 0o700 });
         }
         catch (error) {
             if (error.code === "EEXIST")
                 throw new Error("local runner daemon is already running");
             throw error;
         }
-        await this.handle.writeFile(String(process.pid));
+        try {
+            try {
+                const stored = (await readFile(this.path, "utf8")).trim();
+                const pid = Number(stored);
+                if (!/^\d+$/.test(stored) || !Number.isSafeInteger(pid) || pid <= 0)
+                    throw new Error("local runner daemon lock has an invalid owner");
+                try {
+                    process.kill(pid, 0);
+                    throw new Error("local runner daemon is already running");
+                }
+                catch (error) {
+                    if (error.code !== "ESRCH")
+                        throw error;
+                }
+                await unlink(this.path);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            this.handle = await open(this.path, "wx", 0o600);
+            await this.handle.writeFile(String(process.pid));
+        }
+        finally {
+            await rm(guard, { recursive: true });
+        }
     }
     async release() {
         await this.handle?.close();

package/dist/src/daemon/runtime.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { hostname } from "node:os";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { mkdirSync, writeFileSync, chmodSync } from "node:fs";
 import { McpGatewayClient } from "../gateway-client.js";
@@ -14,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) {
@@ -52,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 })]);
@@ -72,6 +76,12 @@ export async function buildDaemon(input) {
         state,
     });
     const poller = new JobPoller({
+        heartbeat: () => gateway.heartbeatLocalRunner({
+            deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
+            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),
         wait: async () => {
             const claim = await gateway.waitForLocalJob(versions, 25);
             if (claim.status !== "claimed" || !claim.job || !claim.task_package || !claim.lease_token || !claim.launch_grant)
@@ -96,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

@@ -403,9 +403,37 @@ export class McpGatewayClient {
             capabilities: input.capabilities,
         });
     }
+    async heartbeatLocalRunner(input) {
+        return this.callTool("local_agent_runner_heartbeat", {
+            runner_id: this.runnerId,
+            runner: {
+                device_fingerprint: input.deviceFingerprint,
+                display_name: input.displayName,
+                package_version: input.packageVersion,
+                capabilities: input.capabilities,
+            },
+        });
+    }
     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/dist/src/platform/macos/launchd.js

@@ -31,6 +31,7 @@ export class LaunchdService {
 <plist version="1.0"><dict>
 <key>Label</key><string>${LAUNCHD_LABEL}</string>
 <key>ProgramArguments</key><array><string>${xml(process.execPath)}</string><string>${xml(executablePath)}</string><string>run</string><string>--state-root=${xml(stateRoot)}</string></array>
+<key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(this.deps.path ?? process.env.PATH ?? "/usr/bin:/bin:/usr/sbin:/sbin")}</string></dict>
 <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
 <key>ProcessType</key><string>Background</string>
 </dict></plist>

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "mtech-ai-local-runner",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "license": "UNLICENSED",
-  "bin": {"mtec-ai-local-runner": "dist/src/cli.js"},
-  "files": ["dist/src", "README.md", "LICENSE"],
+  "bin": {
+    "mtec-ai-local-runner": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
-  "engines": {"node": ">=20"},
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsc",
     "prepack": "npm run build && chmod 755 dist/src/cli.js",