mtech-ai-local-runner 0.1.7 → 0.1.8

package/README.md

@@ -10,6 +10,13 @@ The package stores safe runner configuration locally and keeps OAuth refresh cre
 
 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.8 (release candidate)
+
+- Report safe preparation stage/tool/error categories and settle known failures instead of silently reclaiming the same job forever.
+- Bound preparation to 15 minutes, retain terminal receipts across connection failures, and halt on unknown binding outcomes until reconciled.
+- Pair with Gateway cancellation propagation and three-delivery preparation bounds. Actual approved unbounded employee-local Claude execution remains unbounded.
+- Prepared locally; npm publication and daemon upgrade are separate actions. Keep a stopped runner stopped until its cancelled job is confirmed terminal on Gateway.
+
 ## 0.1.7
 
 - Accept one fenced final JSON report after an explanatory preamble while preserving status, evidence, length and pending-work validation. Reject ambiguous multiple code blocks.
@@ -42,3 +49,30 @@ Existing employees can upgrade their installed daemon with:
 npx mtech-ai-local-runner@0.1.7 setup
 npx mtech-ai-local-runner@0.1.7 doctor
 ```
+
+### Cancellation and preparation failures
+
+Cancelling a Work Loop also cancels its non-terminal local jobs. Repeating the
+cancellation repairs jobs left by an earlier Gateway version; terminal results
+are preserved. Claim/reclaim and lease-gated launch checks reject cancelled
+Loops. An active adapter stops when the next lease heartbeat fails; cancellation
+is not an immediate process-kill acknowledgement.
+
+Before binding, the Gateway permits at most three queue deliveries and a
+15-minute preparation window from the first claim. The daemon also bounds its
+workspace/probe/shadow/binding preparation to 15 minutes. A known preparation
+failure is reported as `blocked` immediately, with a safe stage, tool name when
+available, and error category. Tokens, grants, arguments and raw error responses
+are excluded from these diagnostics. Unacknowledged terminal receipts remain in
+private state for reconciliation before polling continues.
+
+A binding request whose outcome is unknown is retained as `binding_uncertain`;
+the daemon stops polling and requires authoritative reconciliation of the
+recorded job/generation and deterministic binding reference before restart.
+It neither repeats the binding request nor assumes the server did not create it.
+Do not delete that state to force another execution.
+
+These preparation controls end at binding and do not impose time, turn, token
+or cost termination limits on an approved unbounded employee-local Claude run.
+Existing generation fencing, scope restrictions, cancellation and audit remain
+in force.

package/dist/src/cli.js

@@ -182,7 +182,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.7",
+                    displayName: runnerDisplayName(), packageVersion: "0.1.8",
                     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,3 +1,4 @@
+import { GatewayToolError } from "../gateway-client.js";
 import { createHash } from "node:crypto";
 import { PROTOCOL_VERSION, isTerminalEventType, validateEvent, MAX_EVENT_SUMMARY_CHARS } from "../protocol.js";
 function canonical(value) {
@@ -28,30 +29,84 @@ function text(value, label) {
         throw new Error(`task package is missing ${label}`);
     return value;
 }
+class PreparationDeadlineError extends Error {
+}
 export class ExecutionCoordinator {
     deps;
     constructor(deps) {
         this.deps = deps;
     }
     async execute(job) {
-        const pkg = job.taskPackage;
-        const repository = pkg.repository;
-        const adapterId = text(pkg.runtime_adapter, "runtime adapter");
-        const adapterVersion = text(pkg.runtime_adapter_version, "runtime adapter version");
-        const expectedContractFingerprint = text(pkg.contract_fingerprint, "contract fingerprint");
-        const workspace = await this.deps.workspaces.create({
-            jobId: job.id,
-            repositoryKey: text(repository?.key, "repository key"),
-            providerUrl: text(repository?.provider_url, "repository provider URL"),
-            baseCommitSha: text(repository?.base_commit_sha, "repository SHA"),
-        });
-        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 (contractFingerprint(gatewayShadow.contractPayload) !== expectedContractFingerprint || gatewayShadow.contractFingerprint !== expectedContractFingerprint || gatewayShadow.taskPackageFingerprint !== fingerprint(pkg)) {
-            throw new Error("contract or task-package fingerprint mismatch before binding");
+        let stage = "package";
+        let workspace;
+        let adapter;
+        let binding;
+        const deadline = Date.now() + (this.deps.preparationTimeoutMs ?? 900_000);
+        const step = async (operation) => {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new PreparationDeadlineError();
+            let timer;
+            try {
+                return await Promise.race([operation(), new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new PreparationDeadlineError()), remaining);
+                    })]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        };
+        try {
+            const pkg = job.taskPackage;
+            const repository = pkg.repository;
+            const adapterId = text(pkg.runtime_adapter, "runtime adapter");
+            const adapterVersion = text(pkg.runtime_adapter_version, "runtime adapter version");
+            const expectedContractFingerprint = text(pkg.contract_fingerprint, "contract fingerprint");
+            stage = "workspace";
+            workspace = await step(() => this.deps.workspaces.create({
+                jobId: job.id,
+                repositoryKey: text(repository?.key, "repository key"),
+                providerUrl: text(repository?.provider_url, "repository provider URL"),
+                baseCommitSha: text(repository?.base_commit_sha, "repository SHA"),
+            }));
+            stage = "adapter";
+            adapter = await step(() => 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 });
+            stage = "shadow";
+            const gatewayShadow = await step(() => this.deps.gateway.shadow(job));
+            stage = "fingerprint";
+            if (contractFingerprint(gatewayShadow.contractPayload) !== expectedContractFingerprint || gatewayShadow.contractFingerprint !== expectedContractFingerprint || gatewayShadow.taskPackageFingerprint !== fingerprint(pkg)) {
+                throw new Error("contract or task-package fingerprint mismatch before binding");
+            }
+            stage = "binding";
+            await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: "binding" });
+            binding = await step(() => this.deps.gateway.createBinding({ ...job, checkoutPath: workspace.path }));
+        }
+        catch (error) {
+            const diagnostic = { stage, code: "PREPARATION_FAILED" };
+            if (error instanceof PreparationDeadlineError)
+                diagnostic.code = "PREPARATION_DEADLINE_EXCEEDED";
+            if (error instanceof GatewayToolError) {
+                diagnostic.tool = error.toolName;
+                diagnostic.code = error.code;
+            }
+            this.deps.reportPreparationFailure?.(diagnostic);
+            if (stage === "binding" && !(error instanceof GatewayToolError && error.code === "GATEWAY_TOOL_REJECTED")) {
+                // The server may have committed the binding. Never fabricate a blocked result
+                // or repeat the mutation before the deterministic binding reference is reconciled.
+                await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken,
+                    phase: "binding_uncertain", preparationFailure: diagnostic });
+                throw new Error("Binding outcome requires reconciliation");
+            }
+            // Retain this exact safe terminal payload until Gateway acknowledges it.
+            await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken,
+                phase: "preparation_failed", preparationFailure: diagnostic });
+            await this.deps.gateway.complete({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken,
+                status: "blocked", result: { preparation_failure: { ...diagnostic } } });
+            await this.deps.state.clear();
+            return;
         }
-        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 });
         let heartbeatFailure = null;
         let requestedTerminal;

package/dist/src/daemon/job-poller.js

@@ -9,14 +9,23 @@ export class JobPoller {
     async tick() {
         if (this.stopped)
             return;
+        let stage = "heartbeat";
         try {
             await this.deps.heartbeat?.();
+            stage = "wait";
             const claim = await this.deps.wait();
-            this.failures = 0;
+            stage = "execute";
             if (claim.status === "claimed" && claim.job)
                 await this.deps.execute(claim.job);
+            this.failures = 0;
         }
         catch {
+            this.deps.reportError?.({ stage, code: stage === "execute" ? "EXECUTION_UNACKNOWLEDGED" : "GATEWAY_UNAVAILABLE" });
+            // Unknown execution/terminal outcomes must reconcile before any new claim.
+            if (stage === "execute") {
+                this.stop();
+                return;
+            }
             this.failures += 1;
             const base = Math.min(30_000, 1000 * (2 ** Math.min(5, this.failures - 1)));
             const jitter = Math.floor(base * 0.2 * (this.deps.random ?? Math.random)());

package/dist/src/daemon/runtime.js

@@ -48,6 +48,7 @@ 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({
+        reportPreparationFailure: (diagnostic) => { process.stderr.write(`${JSON.stringify({ event: "preparation_failed", ...diagnostic })}\n`); },
         terminalEvidenceCollector: buildTerminalEvidenceCollector(),
         gateway: {
             shadow: (job) => gateway.localJobShadow({ workLoopId: job.workLoopId,
@@ -70,9 +71,10 @@ export async function buildDaemon(input) {
         state,
     });
     const poller = new JobPoller({
+        reportError: (diagnostic) => { process.stderr.write(`${JSON.stringify({ event: "poller_failed", ...diagnostic })}\n`); },
         heartbeat: () => gateway.heartbeatLocalRunner({
             deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
-            displayName: runnerDisplayName(), packageVersion: "0.1.7",
+            displayName: runnerDisplayName(), packageVersion: "0.1.8",
             capabilities: probes.map((probe) => ({ adapter: probe.id, version: probe.version,
                 capabilities: probe.capabilities, authenticated: probe.available && probe.authenticated })),
         }).then(() => undefined),
@@ -103,6 +105,10 @@ export async function buildDaemon(input) {
         lock: new ProcessLock(join(input.stateRoot, "daemon.lock")), state,
         reconcile: async (stored) => {
             const previous = stored;
+            if (await reconcilePreparationState(previous, {
+                complete: (result) => gateway.completeLocalJob(result), clear: () => state.clear(),
+            }))
+                return;
             if (previous.bindingId && previous.jobId && previous.generation && previous.leaseToken) {
                 try {
                     const receipt = await gateway.readBindingEvents(previous.bindingId, previous.eventCursor ?? 0);
@@ -131,3 +137,18 @@ export async function buildDaemon(input) {
         } } };
 }
 export function runnerDisplayName() { return `${hostname()} local AI`; }
+/** Unknown mutation outcomes halt polling; known failures replay only their terminal receipt. */
+export async function reconcilePreparationState(previous, deps) {
+    if (previous.phase === "binding" || previous.phase === "binding_uncertain") {
+        throw new Error("Binding outcome requires reconciliation before runner polling");
+    }
+    if (!previous.preparationFailure)
+        return false;
+    if (!previous.jobId || !previous.generation || !previous.leaseToken) {
+        throw new Error("Preparation receipt is missing its job fence");
+    }
+    await deps.complete({ jobId: previous.jobId, generation: previous.generation,
+        leaseToken: previous.leaseToken, status: "blocked", result: { preparation_failure: previous.preparationFailure } });
+    await deps.clear();
+    return true;
+}

package/dist/src/gateway-client.js

@@ -2,6 +2,16 @@ import { createHash } from "node:crypto";
 import { v5 as uuidv5 } from "uuid";
 import { bindingApprovalIdFromEnv, redact } from "./config.js";
 import { isTerminalEventType } from "./protocol.js";
+/** Safe diagnostic metadata: never includes arguments, response bodies or credentials. */
+export class GatewayToolError extends Error {
+    toolName;
+    code;
+    constructor(message, toolName, code) {
+        super(message);
+        this.toolName = toolName;
+        this.code = code;
+    }
+}
 function nested(value, path) {
     return path.split(".").reduce((current, key) => {
         if (!current || typeof current !== "object")
@@ -113,6 +123,7 @@ export class McpGatewayClient {
         throw new Error("No token provider or static token configured");
     }
     async callTool(name, args) {
+        let failureCode = "GATEWAY_TRANSPORT_ERROR";
         try {
             const token = await this.resolveToken();
             const response = await this.fetchFn(this.mcpUrl, {
@@ -122,14 +133,17 @@ export class McpGatewayClient {
             });
             const body = (await response.json());
             if (!response.ok || body.error) {
+                failureCode = !response.ok ? `GATEWAY_HTTP_${response.status}` : "GATEWAY_RPC_ERROR";
                 throw new Error(`Gateway MCP ${name} failed with status ${response.status}: ${JSON.stringify(body.error ?? body)}`);
             }
             const text = nested(body, "result.content.0.text");
-            if (nested(body, "result.isError") || typeof text !== "string") {
+            if (typeof text !== "string") {
+                failureCode = "GATEWAY_INVALID_TOOL_RESULT";
                 throw new Error(`Gateway MCP ${name} returned an invalid tool result`);
             }
             const envelope = JSON.parse(text);
-            if (envelope.status !== "completed") {
+            if (envelope.status !== "completed" || nested(body, "result.isError")) {
+                failureCode = envelope.status === "failed" ? "GATEWAY_TOOL_REJECTED" : "GATEWAY_INVALID_TOOL_RESULT";
                 throw new Error(`Gateway MCP ${name} did not complete: ${JSON.stringify(envelope)}`);
             }
             return nested(envelope, "result.data");
@@ -148,7 +162,7 @@ export class McpGatewayClient {
             }
             const leaseToken = this.context?.leaseToken ?? this.initialLeaseToken ?? "";
             sanitized = redact(sanitized, leaseToken);
-            throw new Error(redact(sanitized, this.bindingApprovalId ?? ""));
+            throw new GatewayToolError(redact(sanitized, this.bindingApprovalId ?? ""), name, failureCode);
         }
     }
     async resolveCompatibility(input) {
@@ -421,6 +435,8 @@ export class McpGatewayClient {
         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");
+        if (shown.loop.status === "cancelled")
+            throw new GatewayToolError("Work Loop is cancelled", "work_loop_show", "WORK_LOOP_CANCELLED");
         const result = await this.callTool("work_execution_contract_show", {
             contract_id: requiredString(shown.loop.work_execution_contract_id, "execution contract ID"),
         });

package/package.json

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