mtech-ai-local-runner 0.1.53 → 0.1.55

package/dist/src/guide/runtime.js

@@ -0,0 +1,173 @@
+import { GUIDE_SHIM_FILE, refreshShim } from "../asks/shim.js";
+import { aggregateDay } from "./aggregate.js";
+import { confirmPolicyCache, deleteGuideState, dropDay, eventDays, lastEventAt, markReported, pruneGuideFiles, readEventLines, readPolicyCache, utcDate, writePolicyCache } from "./files.js";
+import { codexGuideTrust, guideHookClientScript, guideStatus } from "./integrations.js";
+import { GUIDE_APPS, parseGuidancePolicy } from "./types.js";
+const PASS_INTERVAL_MS = 3_600_000;
+/** A UTC day is reported once it ended this long ago, so a hook that was still writing has finished. */
+const REPORT_GRACE_MS = 2 * 3_600_000;
+/** A sync that confirms the same version moves the cache's confirmation at most this often. */
+const CONFIRM_REFRESH_MS = 3_600_000;
+const GUIDE_OFF = "Guidance is off for this actor.";
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : "GUIDE_FAILED";
+}
+export class GuideRuntime {
+    deps;
+    controller = new AbortController();
+    timer = null;
+    passing = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() { return this.deps.now?.() ?? Date.now(); }
+    log(event) {
+        try {
+            this.deps.log?.(event);
+        }
+        catch { /* Logging never stops guide. */ }
+    }
+    /** Never throws. Points an installed guide shim at this release, then runs the pass now and hourly. */
+    async start() {
+        try {
+            await refreshShim({ stateRoot: this.deps.stateRoot, file: GUIDE_SHIM_FILE, feature: "guide", clientPath: guideHookClientScript() });
+        }
+        catch (error) {
+            this.log({ event: "guide_shim_refresh_failed", code: errorCode(error) });
+        }
+        this.schedule(0);
+    }
+    async stop() {
+        this.controller.abort();
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.timer = null;
+        await this.passing?.catch(() => undefined);
+    }
+    schedule(delayMs) {
+        if (this.controller.signal.aborted)
+            return;
+        this.timer = setTimeout(() => {
+            this.passing = this.pass().finally(() => {
+                this.passing = null;
+                this.schedule(this.deps.passIntervalMs ?? PASS_INTERVAL_MS);
+            });
+        }, delayMs);
+        this.timer.unref?.();
+    }
+    /** The cached policy's version, for local_agent_runner_sync. */
+    async policyVersion() {
+        return (await readPolicyCache(this.deps.stateRoot, this.now()))?.policy.version;
+    }
+    /** Takes the guide keys of one sync result. Never throws. */
+    async handleSync(result) {
+        try {
+            if ("guidancePolicy" in result) {
+                if (result.guidancePolicy === null) {
+                    if (await readPolicyCache(this.deps.stateRoot, this.now()) !== null)
+                        this.log({ event: "guide_off" });
+                    await deleteGuideState(this.deps.stateRoot);
+                    return;
+                }
+                if (parseGuidancePolicy(result.guidancePolicy) === null) {
+                    this.log({ event: "guide_policy_invalid", code: "GUIDE_POLICY_INVALID" });
+                    return;
+                }
+                await writePolicyCache(this.deps.stateRoot, result.guidancePolicy, this.now());
+                return;
+            }
+            if (result.guidancePolicyVersion === undefined)
+                return;
+            const cached = await readPolicyCache(this.deps.stateRoot, this.now());
+            if (cached !== null && cached.policy.version === result.guidancePolicyVersion && this.now() - cached.confirmedAt >= CONFIRM_REFRESH_MS) {
+                await confirmPolicyCache(this.deps.stateRoot, this.now());
+            }
+        }
+        catch (error) {
+            this.log({ event: "guide_sync_failed", code: errorCode(error) });
+        }
+    }
+    /** heartbeat runner.guidance, or undefined while there is neither a policy nor a guide hook on this Mac. Never throws. */
+    async advertisement() {
+        try {
+            const cached = await readPolicyCache(this.deps.stateRoot, this.now());
+            const apps = {};
+            for (const app of GUIDE_APPS) {
+                const status = await guideStatus(app, this.deps.env, this.deps.stateRoot).catch(() => null);
+                if (status === null || status.state === "not_installed")
+                    continue;
+                const last = await lastEventAt(this.deps.stateRoot, app);
+                apps[app] = app === "codex" ? { state: status.state, last_event_at: last, trusted: await codexGuideTrust(this.deps.env) }
+                    : { state: status.state, last_event_at: last };
+            }
+            if (cached === null && Object.keys(apps).length === 0)
+                return undefined;
+            return { version: 1, policy_version: cached?.policy.version ?? null, apps };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** One report and prune pass. Never throws. */
+    async pass() {
+        try {
+            const now = this.now();
+            if (await readPolicyCache(this.deps.stateRoot, now) !== null)
+                await this.reportDays(now);
+            await pruneGuideFiles(this.deps.stateRoot, now);
+        }
+        catch (error) {
+            this.log({ event: "guide_pass_failed", code: errorCode(error) });
+        }
+    }
+    async reportDays(now) {
+        const cutoff = utcDate(now - REPORT_GRACE_MS);
+        const days = [...(await eventDays(this.deps.stateRoot))].sort(([left], [right]) => left.localeCompare(right));
+        for (const [date, files] of days) {
+            if (date >= cutoff || files.fresh === undefined)
+                continue;
+            // Every line of the day, reported or not, so a repeat replaces the Gateway's row with the full total.
+            const lines = await readEventLines([files.reported, files.fresh].filter((path) => path !== undefined));
+            try {
+                for (const [key, counts] of aggregateDay(lines)) {
+                    const [app, projectKey] = key.split("|");
+                    await this.deps.report({ date, app, projectKey, counts }, this.controller.signal);
+                }
+            }
+            catch (error) {
+                if (errorCode(error) === "GATEWAY_TOOL_REJECTED" && error instanceof Error && error.message.includes(GUIDE_OFF)) {
+                    // The Gateway refuses while guide is off for this person: nothing that waits here is ever sent (spec section 8).
+                    this.log({ event: "guide_report_refused", code: "GUIDE_OFF" });
+                    await deleteGuideState(this.deps.stateRoot);
+                    return;
+                }
+                if (errorCode(error) === "GATEWAY_TOOL_REJECTED") {
+                    this.log({ event: "guide_report_refused", code: "GUIDE_DAY_DROPPED" });
+                    await dropDay(this.deps.stateRoot, date);
+                    continue;
+                }
+                this.log({ event: "guide_report_failed", code: errorCode(error) });
+                return;
+            }
+            await markReported(this.deps.stateRoot, date);
+        }
+    }
+}
+/** The daemon's side loops with guide started before them and stopped after them, like withAsks. */
+export function withGuide(guide, loop) {
+    return {
+        async run() {
+            await guide.start();
+            try {
+                await loop.run();
+            }
+            finally {
+                await guide.stop();
+            }
+        },
+        stop() {
+            loop.stop();
+        },
+    };
+}

package/dist/src/guide/templates.js

@@ -0,0 +1,22 @@
+/*
+ * Every sentence a guide hook adds to a session (spec section 3.4). Nothing from the Gateway, no colleague text, path,
+ * host or command reaches a session: only these sentences and the Gateway tool names below.
+ */
+export const SESSION_GUIDANCE_TEXT = 'AI Gateway: if its tools are available, call workspace_getting_started (response_mode "brief") at task start. '
+    + "Search with knowledge_search (limit 5) before opening a KnowledgeBase file you do not already know you need.";
+export const KB_SEARCH_FIRST_TEXT = "AI Gateway: if its tools are available and you do not already know this KnowledgeBase file is the one you need, "
+    + "search with knowledge_search (limit 5) first.";
+export const DB_WRITE_TEXT = "AI Gateway: this looks like a direct database write, which no Gateway tool covers. Confirm it with the employee before you run it.";
+/** The Gateway tool each CLI rule names (spec section 3.2). cli_db_write names none. */
+export const CLI_RULE_TOOLS = Object.freeze({
+    cli_aws_logs: "aws_log_events_search",
+    cli_aws_s3_read: "s3_objects_list",
+    cli_db_read: "db_read_query",
+    cli_ssh: "server_read",
+    cli_vapor_deploy: "deployment_execute",
+});
+export function cliRuleText(rule) {
+    if (rule === "cli_db_write")
+        return DB_WRITE_TEXT;
+    return `AI Gateway: if its tools are available, prefer ${CLI_RULE_TOOLS[rule]}: it covers this with the Gateway's own access and an audit record.`;
+}

package/dist/src/guide/types.js

@@ -0,0 +1,95 @@
+/*
+ * Guide hooks (Work Item d38d60f9, docs/superpowers/specs/2026-10-25-gateway-guide-hooks-design.md). Names shared by
+ * the guide hook client, its integrations, the daemon's guide runtime and doctor. This module imports nothing, so the
+ * hook client stays cheap to load. The Gateway sends rule modes, workspace and repository names, project keys and tool
+ * names only; every sentence a session sees comes from templates.ts.
+ */
+export const GUIDE_APPS = ["claude", "codex"];
+export const GUIDE_EVENTS = ["session-start", "pre-tool"];
+/** In the Gateway's order (AiOpsGuidancePolicy::RULES). */
+export const RULE_IDS = ["session_guidance", "kb_search_first", "cli_aws_logs", "cli_aws_s3_read", "cli_db_read", "cli_db_write",
+    "cli_ssh", "cli_vapor_deploy"];
+/** There is no block mode (owner decision 2026-10-25): a guide hook never sends permissionDecision. */
+export const MODES = ["off", "observe", "warn"];
+export const OUTCOMES = ["observed", "warned"];
+/** In the Gateway's order (AiOpsGuidanceCounts::COUNT_KEYS). */
+export const COUNT_KEYS = ["sessions", "sessions_with_kb_read", "sessions_with_search", "sessions_with_both", "knowledge_search_calls",
+    "gateway_tool_calls", "kb_reads_read_tool", "kb_reads_search_tool", "kb_reads_shell", "kb_read_bytes", "injected_chars", "undecidable"];
+export const POLICY_VERSION = /^[a-f0-9]{16}$/;
+/** What a Claude or Codex session id may look like locally. It never leaves this Mac. */
+export const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+export const PROJECT_KEY = /^[a-z0-9][a-z0-9_.-]{0,190}$/;
+const WORKSPACE = /^[a-z0-9][a-z0-9_.-]{0,62}$/;
+const REPOSITORY = /^[a-z0-9][a-z0-9_.-]{0,99}$/;
+const TOOL_NAME = /^[a-z][a-z0-9_]{1,63}$/;
+/** A session in a folder that holds company clones, such as ~/Projects. */
+export const MULTI_REPOSITORY = "multi_repository";
+/** A company repository that the registry does not list. */
+export const UNREGISTERED = "unregistered";
+/** A policy the Gateway has not confirmed for this long turns every warn into observe (spec section 6). */
+export const STALE_POLICY_MS = 7 * 24 * 60 * 60 * 1000;
+/** The most hook input the client reads from stdin. */
+export const MAX_HOOK_INPUT_BYTES = 64 * 1024;
+/** <stateRoot>/guide holds everything guide keeps on the Mac. */
+export const GUIDE_DIR = "guide";
+function oneOf(values, value) {
+    return typeof value === "string" && values.includes(value);
+}
+export function isGuideApp(value) { return oneOf(GUIDE_APPS, value); }
+export function isGuideEvent(value) { return oneOf(GUIDE_EVENTS, value); }
+export function isRuleId(value) { return oneOf(RULE_IDS, value); }
+export function isMode(value) { return oneOf(MODES, value); }
+export function isOutcome(value) { return oneOf(OUTCOMES, value); }
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** The guidance_policy of a sync result, or null when anything in it is missing or malformed. */
+export function parseGuidancePolicy(input) {
+    if (!isRecord(input))
+        return null;
+    const { version, issued_at: issuedAt, rules, company_workspaces: workspaces, repositories, gateway_tool_names: tools } = input;
+    if (typeof version !== "string" || !POLICY_VERSION.test(version))
+        return null;
+    if (typeof issuedAt !== "number" || !Number.isSafeInteger(issuedAt) || issuedAt < 0)
+        return null;
+    if (!isRecord(rules))
+        return null;
+    const modes = {};
+    for (const rule of RULE_IDS) {
+        const mode = rules[rule];
+        if (!isMode(mode))
+            return null;
+        modes[rule] = mode;
+    }
+    if (!Array.isArray(workspaces) || workspaces.length > 20 || !workspaces.every(item => typeof item === "string" && WORKSPACE.test(item)))
+        return null;
+    const repositoryMap = {};
+    // PHP encodes an empty map as [].
+    if (Array.isArray(repositories)) {
+        if (repositories.length > 0)
+            return null;
+    }
+    else if (isRecord(repositories)) {
+        const entries = Object.entries(repositories);
+        if (entries.length > 1000)
+            return null;
+        for (const [name, key] of entries) {
+            if (!REPOSITORY.test(name) || typeof key !== "string" || !PROJECT_KEY.test(key))
+                return null;
+            repositoryMap[name] = key;
+        }
+    }
+    else {
+        return null;
+    }
+    if (!Array.isArray(tools) || tools.length > 2000 || !tools.every(item => typeof item === "string" && TOOL_NAME.test(item)))
+        return null;
+    return { version, issuedAt, rules: modes, companyWorkspaces: [...workspaces], repositories: repositoryMap,
+        gatewayToolNames: [...tools] };
+}
+/** Zero counts for one day, app and project, every key present. */
+export function emptyDayCounts() {
+    const counts = Object.fromEntries(COUNT_KEYS.map(key => [key, 0]));
+    const rules = Object.fromEntries(RULE_IDS.map(rule => [rule, { observed: 0, warned: 0 }]));
+    return { ...counts, rules };
+}

package/dist/src/safety/job-tool-dispatcher.js

@@ -1,3 +1,4 @@
+import { validateLocalReadRange } from './local-read-range.js';
 import { localToolInventory } from './local-tool-server.js';
 const rejected = () => new Error('JOB_TOOL_DISPATCH_REJECTED');
 function record(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
@@ -35,10 +36,16 @@ export class JobToolDispatcher {
                 throw rejected();
             const tool = localToolInventory().find(t => t.name === envelope.tool);
             const properties = tool?.inputSchema.properties;
-            if (!record(properties) || !keys(envelope.args, Object.keys(properties))
-                || Object.values(envelope.args).some(value => typeof value !== 'string')
+            const required = tool?.inputSchema.required;
+            if (!record(properties) || !Array.isArray(required) || required.some(key => typeof key !== 'string' || !Object.hasOwn(envelope.args, key))
+                || Object.entries(envelope.args).some(([key, value]) => {
+                    const schema = properties[key];
+                    return !record(schema) || (schema.type === 'integer' ? typeof value !== 'number' || !Number.isSafeInteger(value) || (typeof schema.minimum === 'number' && value < schema.minimum) : schema.type !== 'string' || typeof value !== 'string');
+                })
                 || Buffer.byteLength(JSON.stringify(envelope.args)) > 1024 * 1024)
                 throw rejected();
+            if (envelope.tool === 'local_read')
+                validateLocalReadRange(envelope.args);
             this.#lastRequest = BigInt(envelope.requestId);
             const result = await this.policy.call(envelope.tool, envelope.args);
             if (this.#revoked || !this.active())

package/dist/src/safety/local-read-range.js

@@ -0,0 +1,13 @@
+/** Kept standalone so the isolated worker repeats the same validation. */
+export function validateLocalReadRange(input) {
+    if (!Object.hasOwn(input, 'start_line') && !Object.hasOwn(input, 'end_line'))
+        return;
+    const start = input.start_line, end = input.end_line;
+    if (typeof start !== 'number' || typeof end !== 'number'
+        || !Number.isSafeInteger(start) || !Number.isSafeInteger(end)
+        || start < 1 || end < start)
+        throw new Error('DENIED_READ_RANGE');
+    if (end - start + 1 > 400)
+        throw new Error('DENIED_READ_RANGE_LIMIT');
+    return { start_line: start, end_line: end };
+}

package/dist/src/safety/local-tool-policy.js

@@ -1,3 +1,4 @@
+import { validateLocalReadRange } from './local-read-range.js';
 import { isPatchContent } from './local-edit-content.js';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -44,6 +45,7 @@ export class LocalToolPolicy {
             throw new Error('DENIED_READ_ONLY');
         if (tool === 'local_test')
             return this.test(input);
+        const readRange = tool === 'local_read' ? validateLocalReadRange(input) : undefined;
         const file = await this.authorizedFile(input.path, tool === 'local_edit');
         if (tool === 'local_replace') {
             if (typeof input.old !== 'string' || !input.old || Buffer.byteLength(input.old) > 1024 * 1024)
@@ -60,10 +62,12 @@ export class LocalToolPolicy {
         if (tool === 'local_search' && (typeof input.query !== 'string' || input.query.length > 4096))
             throw new Error('DENIED_QUERY');
         const temp = file + '.runner-edit-' + randomBytes(16).toString('hex');
-        const output = await runSandboxed({ executable: process.execPath, argv: ['--no-addons', '--no-global-search-paths', '--eval', LOCAL_TOOL_WORKER, JSON.stringify({ tool, path: file, temp, content: input.content, query: input.query, old: input.old, new: input.new })], readFiles: (tool === 'local_edit' || tool === 'local_replace') ? [file, temp] : [file], writeFiles: (tool === 'local_edit' || tool === 'local_replace') ? [file, temp] : [], timeoutMs: 10000, signal: this.abort.signal });
+        const output = await runSandboxed({ executable: process.execPath, argv: ['--no-addons', '--no-global-search-paths', '--eval', LOCAL_TOOL_WORKER, JSON.stringify({ tool, path: file, temp, content: input.content, query: input.query, old: input.old, new: input.new, ...readRange })], readFiles: (tool === 'local_edit' || tool === 'local_replace') ? [file, temp] : [file], writeFiles: (tool === 'local_edit' || tool === 'local_replace') ? [file, temp] : [], timeoutMs: 10000, signal: this.abort.signal });
         if (this.abort.signal.aborted)
             throw new Error('DENIED_REVOKED');
         const result = JSON.parse(output);
+        if (tool === 'local_read' && ['DENIED_READ_RANGE', 'DENIED_READ_RANGE_LIMIT', 'DENIED_READ_RANGE_BOUNDS'].includes(result.denied))
+            throw new Error(result.denied);
         if (tool === 'local_replace' && ['DENIED_REPLACE_NOT_FOUND', 'DENIED_REPLACE_AMBIGUOUS', 'DENIED_SIZE'].includes(result.denied))
             throw new Error(result.denied);
         return result;

package/dist/src/safety/local-tool-server.js

@@ -21,7 +21,7 @@ export function localEndpointObservations(url, token) {
 }
 const MAX_BODY = 1024 * 1024;
 const schemas = {
-    local_read: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false },
+    local_read: { type: 'object', properties: { path: { type: 'string' }, start_line: { type: 'integer', minimum: 1, description: 'First line (1-based, inclusive). Supply with end_line; maximum 400 lines.' }, end_line: { type: 'integer', minimum: 1, description: 'Last line (inclusive). Must not exceed total_lines; supply with start_line.' } }, required: ['path'], additionalProperties: false },
     local_search: { type: 'object', properties: { path: { type: 'string' }, query: { type: 'string' } }, required: ['path', 'query'], additionalProperties: false },
     local_edit: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string', description: 'The complete new contents of the entire file. Do not send a diff, patch, hunk, or edit instructions.' } }, required: ['path', 'content'], additionalProperties: false },
     local_replace: { type: 'object', properties: { path: { type: 'string' }, old: { type: 'string', minLength: 1 }, new: { type: 'string' } }, required: ['path', 'old', 'new'], additionalProperties: false },
@@ -29,7 +29,7 @@ const schemas = {
 };
 /** Same immutable-by-copy inventory used by native admission and MCP discovery. */
 export function localToolInventory() {
-    return LOCAL_TOOL_NAMES.map(name => ({ name, description: name === 'local_edit' ? 'Replace the entire file at path with content (or create it). Read the current file first and include all unchanged text in content. This is not a diff or patch tool; patch headers and hunks are rejected.' : name === 'local_replace' ? 'Replace exactly one occurrence of old with new in the file at path. Read the file first; old must match exactly, including whitespace, and appear once. Prefer this for small changes; use local_edit only to write a whole file.' : `Scoped ${name} operation`, inputSchema: structuredClone(schemas[name]) }));
+    return LOCAL_TOOL_NAMES.map(name => ({ name, description: name === 'local_read' ? 'Find locations with local_search first, then use local_read with start_line and end_line to read only the needed inclusive range (maximum 400 lines). Both range arguments are required together; invalid or beyond-EOF ranges are rejected, never widened. Returns content, start_line, end_line and total_lines for ranges; omit both for the entire file.' : name === 'local_edit' ? 'Replace the entire file at path with content (or create it). Read the current file first and include all unchanged text in content. This is not a diff or patch tool; patch headers and hunks are rejected.' : name === 'local_replace' ? 'Replace exactly one occurrence of old with new in the file at path. Read the file first; old must match exactly, including whitespace, and appear once. Prefer this for small changes; use local_edit only to write a whole file.' : `Scoped ${name} operation`, inputSchema: structuredClone(schemas[name]) }));
 }
 /** Job-only JSON MCP endpoint; intentionally has no Gateway transport or discovery. */
 export class LocalToolServer {

package/dist/src/safety/local-tool-worker.js

@@ -1,9 +1,11 @@
+import { validateLocalReadRange } from './local-read-range.js';
 import { isPatchContent } from './local-edit-content.js';
 /** Standalone worker: --eval avoids ambient module/config lookup. All paths are host-supplied. */
 export const LOCAL_TOOL_WORKER = String.raw `
 const fs = require('node:fs');
 const input = JSON.parse(process.argv[1]);
 const isPatchContent = ${isPatchContent.toString()};
+const validateLocalReadRange = ${validateLocalReadRange.toString()};
 if (input.tool === 'local_edit' && isPatchContent(input.content)) throw Error('DENIED_PATCH_CONTENT');
 if (input.tool === 'local_replace') {
   if (typeof input.old !== 'string' || !input.old || Buffer.byteLength(input.old) > 1048576) throw Error('DENIED_REPLACE_OLD');
@@ -11,6 +13,7 @@ if (input.tool === 'local_replace') {
   if (isPatchContent(input.new)) throw Error('DENIED_PATCH_CONTENT');
 }
 try {
+const readRange = input.tool === 'local_read' ? validateLocalReadRange(input) : undefined;
 let current = '';
 for (const part of input.path.split('/').filter(Boolean)) {
   current += '/' + part;
@@ -72,12 +75,19 @@ try {
     const count = fs.readSync(fd, buffer, 0, buffer.length, 0);
     if (count > 1048576) throw Error('DENIED_SIZE');
     const content = buffer.subarray(0, count).toString('utf8');
-    result = input.tool === 'local_search' ? {matches: content.split('\n').flatMap((line, index) => line.includes(input.query) ? [{line: index + 1, text: line}] : [])} : {content};
+    if (readRange) {
+      // Retain each original line terminator; a final newline adds no phantom line.
+      const lines = content.match(/[^\n]*\n|[^\n]+$/g) || [];
+      if (readRange.end_line > lines.length) throw Error('DENIED_READ_RANGE_BOUNDS');
+      result = {content: lines.slice(readRange.start_line - 1, readRange.end_line).join(''), ...readRange, total_lines: lines.length};
+    } else result = input.tool === 'local_search' ? {matches: content.split('\n').flatMap((line, index) => line.includes(input.query) ? [{line: index + 1, text: line}] : [])} : {content};
   }
   process.stdout.write(JSON.stringify(result));
 } finally { if (fd !== null) fs.closeSync(fd); }
 } catch (error) {
-  if (input.tool !== 'local_replace' || !['DENIED_REPLACE_NOT_FOUND','DENIED_REPLACE_AMBIGUOUS','DENIED_SIZE'].includes(error.message)) throw error;
+  const rangeDenied = input.tool === 'local_read' && ['DENIED_READ_RANGE','DENIED_READ_RANGE_LIMIT','DENIED_READ_RANGE_BOUNDS'].includes(error.message);
+  const replaceDenied = input.tool === 'local_replace' && ['DENIED_REPLACE_NOT_FOUND','DENIED_REPLACE_AMBIGUOUS','DENIED_SIZE'].includes(error.message);
+  if (!rangeDenied && !replaceDenied) throw error;
   process.stdout.write(JSON.stringify({denied: error.message}));
 }
 `;

package/dist/src/transport/sync-dispatch.js

@@ -65,6 +65,18 @@ export function createSyncDispatcher(deps) {
         }
     };
     return async (result) => {
+        // Guide first: it only writes or deletes the local policy cache.
+        if (deps.guide) {
+            try {
+                await deps.guide.handleSync({
+                    ...("guidancePolicy" in result ? { guidancePolicy: result.guidancePolicy } : {}),
+                    ...(result.guidancePolicyVersion !== undefined ? { guidancePolicyVersion: result.guidancePolicyVersion } : {}),
+                });
+            }
+            catch (error) {
+                fail("guide", "GUIDE_DISPATCH_FAILED", error);
+            }
+        }
         // Asks first: they are local and quick, while each open can spend seconds on report retries.
         if (deps.asks) {
             try {

package/package.json

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

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

@@ -1,42 +0,0 @@
-export class JobPoller {
-    deps;
-    stopped = false;
-    failures = 0;
-    constructor(deps) {
-        this.deps = deps;
-    }
-    stop() { this.stopped = true; }
-    async tick() {
-        if (this.stopped)
-            return;
-        let stage = "heartbeat";
-        try {
-            await this.deps.heartbeat?.();
-            stage = "wait";
-            const claim = await this.deps.wait();
-            stage = "execute";
-            if (claim.status === "claimed" && claim.job)
-                await this.deps.execute(claim.job);
-            this.failures = 0;
-        }
-        catch {
-            try {
-                this.deps.reportError?.({ stage, code: stage === "execute" ? "EXECUTION_UNACKNOWLEDGED" : "GATEWAY_UNAVAILABLE" });
-            }
-            catch { /* Observational logging cannot bypass stop/backoff or discard recovery state. */ }
-            // 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)());
-            await this.deps.delay(base + jitter);
-        }
-    }
-    async run() {
-        while (!this.stopped)
-            await this.tick();
-    }
-}

package/dist/src/daemon/session-open-poller.js

@@ -1,123 +0,0 @@
-const MINIMUM_CYCLE_MS = 1000;
-/** Pauses before the second and third report attempts. The server treats a repeat report as idempotent. */
-const REPORT_RETRY_DELAYS_MS = [1000, 2000];
-/** The caught error's own failure code (a GatewayToolError code such as GATEWAY_HTTP_401), never its message, which may carry server text. */
-function causeOf(error) {
-    const code = error?.code;
-    return typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : undefined;
-}
-/** Resolves after the delay or at once on abort, and never leaves a listener on a long-lived signal. */
-export function abortableDelay(milliseconds, signal) {
-    return new Promise(resolve => {
-        if (signal.aborted) {
-            resolve();
-            return;
-        }
-        const onAbort = () => { clearTimeout(timer); resolve(); };
-        const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, milliseconds);
-        signal.addEventListener("abort", onAbort, { once: true });
-    });
-}
-export class SessionOpenPoller {
-    deps;
-    controller = new AbortController();
-    failures = 0;
-    constructor(deps) {
-        this.deps = deps;
-    }
-    stop() { this.controller.abort(); }
-    fail(stage, error, code = `SESSION_OPEN_${stage.toUpperCase()}_FAILED`) {
-        const cause = causeOf(error);
-        try {
-            this.deps.reportError?.({ stage, code, ...(cause ? { cause } : {}) });
-        }
-        catch { /* Logging cannot stop the loop. */ }
-    }
-    async pause(milliseconds, signal) {
-        await this.deps.delay(milliseconds, signal).catch(() => undefined);
-    }
-    /** Opens one claimed request and reports it. A failure here never reaches the rest of the batch. */
-    async handle(request, signal) {
-        let result;
-        try {
-            result = await this.deps.open(request);
-        }
-        catch (error) {
-            if (!signal.aborted)
-                this.fail("open", error);
-            return;
-        }
-        const openId = request?.open_id;
-        if (typeof openId !== "string" || openId === "")
-            return;
-        for (let attempt = 0;; attempt += 1) {
-            try {
-                await this.deps.report(openId, result, signal);
-                return;
-            }
-            catch (error) {
-                if (signal.aborted)
-                    return;
-                const retryDelay = REPORT_RETRY_DELAYS_MS[attempt];
-                if (retryDelay === undefined) {
-                    this.fail("report", error);
-                    return;
-                }
-                await this.pause(retryDelay, signal);
-                if (signal.aborted)
-                    return;
-            }
-        }
-    }
-    async tick() {
-        const signal = this.controller.signal;
-        if (signal.aborted)
-            return;
-        const now = this.deps.now ?? (() => performance.now());
-        const started = now();
-        let opens;
-        let retryAfterSeconds;
-        try {
-            ({ opens, retryAfterSeconds } = await this.deps.wait(signal));
-        }
-        catch (error) {
-            if (signal.aborted)
-                return;
-            this.fail("wait", error);
-            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)());
-            await this.pause(base + jitter, signal);
-            return;
-        }
-        this.failures = 0;
-        const claimed = Array.isArray(opens) ? opens : [];
-        for (const request of claimed) {
-            if (signal.aborted)
-                return;
-            await this.handle(request, signal);
-        }
-        if (claimed.length > 0 || signal.aborted)
-            return;
-        // A wait that returns at once with nothing (a Gateway wait of 0) must not become a hot loop, and while the Gateway's
-        // session open switch is off it asks for a longer pause (retry_after_seconds). The clock is monotonic and clamped.
-        const elapsed = Math.max(0, now() - started);
-        const remainder = elapsed < MINIMUM_CYCLE_MS ? MINIMUM_CYCLE_MS - elapsed : 0;
-        const wanted = retryAfterSeconds === undefined ? remainder : Math.max(remainder, retryAfterSeconds * 1000);
-        if (wanted > 0)
-            await this.pause(wanted, signal);
-    }
-    async run() {
-        const signal = this.controller.signal;
-        while (!signal.aborted) {
-            try {
-                await this.tick();
-            }
-            catch {
-                this.fail("wait", undefined, "SESSION_OPEN_LOOP_FAILED");
-                if (!signal.aborted)
-                    await this.pause(1000, signal);
-            }
-        }
-    }
-}