mtech-ai-local-runner 0.1.76 → 0.1.79

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

@@ -2,12 +2,21 @@ import { validateLocalReadRange } from './local-read-range.js';
 import { isPatchContent } from './local-edit-content.js';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { lstat, realpath } from 'node:fs/promises';
+import { lstat, opendir, realpath } from 'node:fs/promises';
 import { evaluateCommand } from './command-policy.js';
 import { runSandboxed, runSandboxedMeasured } from './subprocess-sandbox.js';
 import { LOCAL_TOOL_WORKER } from './local-tool-worker.js';
 import { verifyCommandIntegrity } from './registered-command-integrity.js';
 export const LOCAL_TOOL_NAMES = ['local_read', 'local_search', 'local_edit', 'local_replace', 'local_test'];
+/** Named tool inventories (Work Decision f43e7aa0). v1 is the original five, unchanged; v2 adds the read-only local_find.
+ * A job serves exactly one: the one whose fingerprint its reviewed input names (local-tool-server.ts localToolInventoryFor). */
+export const LOCAL_TOOL_INVENTORIES = Object.freeze({ 'local-tools-v1': LOCAL_TOOL_NAMES, 'local-tools-v2': Object.freeze([...LOCAL_TOOL_NAMES, 'local_find']) });
+/** The tool names of one inventory; an unknown id fails closed. */
+export function localToolNames(id = 'local-tools-v1') {
+    if (!Object.hasOwn(LOCAL_TOOL_INVENTORIES, id))
+        throw new Error('DENIED_TOOL_INVENTORY');
+    return LOCAL_TOOL_INVENTORIES[id];
+}
 // Private state/control basenames only: Auth.php, auth/ and mcp.ts are ordinary source.
 const sensitive = (segment) => /^(?:\.git|\.mcp(?:\..*)?|\.npmrc|\.netrc|id_rsa|id_ed25519|\.local-runner|\.runner|\.env(?:\..*)?|\.codex|\.claude|\.ssh|\.aws|\.config|auth\.(?:json|toml|ya?ml)(?:\..*)?|credentials(?:\..*)?|AGENTS\.md|CLAUDE\.md|mcp\.(?:json|toml|ya?ml)(?:\..*)?)$/i.test(segment);
 const contains = (root, file) => file === root || file.startsWith(root + path.sep);
@@ -17,13 +26,29 @@ function scopePath(root, scope) {
         throw new Error('DENIED_UNSUPPORTED_SCOPE');
     return path.resolve(root, directory);
 }
-function blockedScopeContains(root, scope, file) {
+function exactBlockedScopeContains(root, scope, file) {
     // The compiled repository policy includes this private-file family. Handle
     // it only as a denial, never as a wildcard grant or an ignored block.
     if (scope === '.env.*')
         return file.startsWith(path.join(root, '.env.'));
     return contains(scopePath(root, scope), file);
 }
+// APFS and HFS+ resolve names regardless of case and Unicode normalization, so app/secrets reaches a blocked
+// app/Secrets. A block therefore also matches the folded spelling: a variant can only be refused, never granted.
+const fold = (value) => value.normalize('NFC').toLowerCase();
+function blockedScopeContains(root, scope, file) {
+    return exactBlockedScopeContains(root, scope, file) || exactBlockedScopeContains(fold(root), fold(scope), fold(file));
+}
+/** local_find bounds (design 2026-10-30-local-claude-file-discovery). Reaching one returns `truncated: true`, never an error. */
+export const LOCAL_FIND_BOUNDS = Object.freeze({ depth: 16, entries: 20_000, candidates: 2_000, candidateBytes: 32 * 1024 * 1024, fileBytes: 1024 * 1024,
+    lineChars: 300, resultBytes: 64 * 1024, timeMs: 10_000,
+    /** Not in the design: Seatbelt compile time grows faster than the number of read grants (2,000 take 4 to 8 s), so
+     * the candidates are searched by one sandboxed worker per batch, each granted exactly its batch. */
+    batchFiles: 250,
+    /** Kept for sandbox startup and exit inside the overall time. */
+    workerReserveMs: 1_500 });
+const FIND_KEYS = ['path', 'name', 'text', 'max_results'];
+const DEPENDENCY_DIRECTORIES = ['vendor', 'node_modules'];
 export class LocalToolPolicy {
     options;
     abort = new AbortController();
@@ -31,16 +56,19 @@ export class LocalToolPolicy {
         this.options = structuredClone(options);
         if (!path.isAbsolute(options.worktreeRoot))
             throw new Error('DENIED_ROOT');
+        localToolNames(options.inventory);
     }
     revoke() { this.abort.abort(); }
     async call(tool, args) {
         if (this.abort.signal.aborted)
             throw new Error('DENIED_REVOKED');
-        if (!LOCAL_TOOL_NAMES.includes(tool))
+        if (!localToolNames(this.options.inventory).includes(tool))
             throw new Error('DENIED_TOOL');
         if (!args || typeof args !== 'object' || Array.isArray(args))
             throw new Error('DENIED_ARGUMENTS');
         const input = args;
+        if (tool === 'local_find')
+            return this.find(input);
         if ((tool === 'local_edit' || tool === 'local_replace') && this.options.access !== 'write')
             throw new Error('DENIED_READ_ONLY');
         if (tool === 'local_test')
@@ -104,6 +132,204 @@ export class LocalToolPolicy {
             throw new Error('DENIED_SIZE');
         return file;
     }
+    /** The scope rules of authorizedFile, for a directory: inside an allowed scope or above one, never blocked. */
+    async authorizedDirectory(value) {
+        const root = path.resolve(this.options.worktreeRoot);
+        if (value !== undefined && (typeof value !== 'string' || !value || value.includes('\0') || path.isAbsolute(value) || value.split(/[\\/]/).some(p => p === '..' || sensitive(p))))
+            throw new Error('DENIED_PATH');
+        const directory = value === undefined ? root : path.resolve(root, value);
+        if (!contains(root, directory) || !this.options.allowedPaths.some(scope => { const allowed = scopePath(root, scope); return contains(allowed, directory) || contains(directory, allowed); })
+            || this.options.blockedPaths.some(scope => blockedScopeContains(root, scope, directory)))
+            throw new Error('DENIED_SCOPE');
+        if (await realpath(root) !== root)
+            throw new Error('DENIED_ROOT');
+        let component = root;
+        for (const segment of path.relative(root, directory).split(path.sep).filter(Boolean)) {
+            component = path.join(component, segment);
+            if ((await lstat(component)).isSymbolicLink())
+                throw new Error('DENIED_SYMLINK');
+        }
+        const stat = await lstat(directory, { bigint: true });
+        if (!stat.isDirectory())
+            throw new Error('DENIED_FILE');
+        return { root, directory, dev: stat.dev, ino: stat.ino };
+    }
+    /** Read-only discovery. Names are walked on the host with opendir and lstat only, under the scope rules of
+     * authorizedFile, never following a symlink. File content is read only by the sandboxed worker, with a read grant
+     * for exactly the bounded candidate list, and each file re-checked there as local_read does. */
+    async find(input) {
+        const bounds = { ...LOCAL_FIND_BOUNDS, ...this.options.findBounds }, deadline = Date.now() + bounds.timeMs;
+        if (Object.keys(input).some(key => !FIND_KEYS.includes(key)))
+            throw new Error('DENIED_ARGUMENTS');
+        const { name, text } = input;
+        if (name !== undefined && (typeof name !== 'string' || !name || name.length > 256) || text !== undefined && (typeof text !== 'string' || !text || text.length > 4096) || name === undefined && text === undefined)
+            throw new Error('DENIED_QUERY');
+        const max = input.max_results ?? 100;
+        if (!Number.isSafeInteger(max) || max < 1 || max > 200)
+            throw new Error('DENIED_ARGUMENTS');
+        const limit = max, needle = typeof name === 'string' ? name.toLowerCase() : undefined;
+        const start = await this.authorizedDirectory(input.path), root = start.root;
+        const allowed = this.options.allowedPaths.map(scope => scopePath(root, scope));
+        const blocked = (file) => this.options.blockedPaths.some(scope => blockedScopeContains(root, scope, file));
+        // vendor/ and node_modules/ are walked only when the requested directory is inside one of them.
+        const dependencies = path.relative(root, start.directory).split(path.sep).some(segment => DEPENDENCY_DIRECTORIES.includes(segment));
+        const names = [], candidates = [];
+        let visited = 0, files = 0, truncated = false;
+        const stack = [{ directory: start.directory, depth: 0, dev: start.dev, ino: start.ino }];
+        walk: while (stack.length) {
+            const next = stack.pop();
+            if (this.abort.signal.aborted)
+                throw new Error('DENIED_REVOKED');
+            if (Date.now() >= deadline || visited >= bounds.entries) {
+                truncated = true;
+                break;
+            }
+            // The directory must still be the inode its parent listed, before and after reading it: opendir follows a symlink.
+            const same = async () => { try {
+                const s = await lstat(next.directory, { bigint: true });
+                return s.isDirectory() && s.dev === next.dev && s.ino === next.ino;
+            }
+            catch {
+                return false;
+            } };
+            if (!await same())
+                continue;
+            const entries = [];
+            // A directory this user cannot read is left out, like any entry the walk skips.
+            const handle = await opendir(next.directory, { bufferSize: 64 }).catch(() => undefined);
+            if (!handle)
+                continue;
+            try {
+                for (;;) {
+                    const entry = await handle.read();
+                    if (!entry)
+                        break;
+                    if (visited + entries.length >= bounds.entries) {
+                        truncated = true;
+                        break;
+                    }
+                    entries.push(entry.name);
+                }
+            }
+            finally {
+                await handle.close();
+            }
+            if (!await same())
+                continue;
+            visited += entries.length;
+            const directories = [];
+            for (const entry of entries.sort()) {
+                if (Date.now() >= deadline) {
+                    truncated = true;
+                    break walk;
+                }
+                const file = path.join(next.directory, entry);
+                if (entry.split(/[\\/]/).some(p => p === '..' || sensitive(p)) || blocked(file))
+                    continue;
+                let stat;
+                try {
+                    stat = await lstat(file, { bigint: true });
+                }
+                catch {
+                    continue;
+                }
+                if (stat.isSymbolicLink())
+                    continue;
+                if (stat.isDirectory()) {
+                    if (!dependencies && DEPENDENCY_DIRECTORIES.includes(entry) || !allowed.some(scope => contains(scope, file) || contains(file, scope)))
+                        continue;
+                    if (next.depth >= bounds.depth) {
+                        truncated = true;
+                        continue;
+                    }
+                    directories.push({ directory: file, depth: next.depth + 1, dev: stat.dev, ino: stat.ino });
+                    continue;
+                }
+                if (!stat.isFile() || !allowed.some(scope => contains(scope, file)))
+                    continue;
+                const rel = path.relative(root, file);
+                if (text === undefined) {
+                    files++;
+                    if (rel.toLowerCase().includes(needle))
+                        names.push(rel);
+                    continue;
+                }
+                if (needle !== undefined && !rel.toLowerCase().includes(needle) || stat.nlink !== 1n || stat.size > BigInt(bounds.fileBytes))
+                    continue;
+                candidates.push({ rel, file, dev: stat.dev, ino: stat.ino, size: stat.size });
+            }
+            stack.push(...directories.reverse());
+        }
+        // Bounds cut in path order, after sorting, so a result always holds the first paths (the walk is bounded by entries).
+        if (text === undefined) {
+            names.sort();
+            if (names.length > limit) {
+                truncated = true;
+                names.length = limit;
+            }
+            return this.boundedFind(names.map(rel => ({ path: rel })), truncated, files);
+        }
+        candidates.sort((a, b) => a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0);
+        let bytes = 0n, kept = 0;
+        for (const candidate of candidates) {
+            if (kept >= bounds.candidates || bytes + candidate.size > BigInt(bounds.candidateBytes)) {
+                truncated = true;
+                break;
+            }
+            bytes += candidate.size;
+            kept++;
+        }
+        candidates.length = kept;
+        const matches = [];
+        let scanned = 0, size = 0;
+        for (let offset = 0; offset < candidates.length; offset += bounds.batchFiles) {
+            const remaining = deadline - Date.now(), batch = candidates.slice(offset, offset + bounds.batchFiles), slots = limit - matches.length;
+            if (remaining <= bounds.workerReserveMs) {
+                truncated = true;
+                break;
+            }
+            let output;
+            try {
+                output = await runSandboxed({ executable: process.execPath, argv: ['--no-addons', '--no-global-search-paths', '--eval', LOCAL_TOOL_WORKER, JSON.stringify({ tool: 'local_find', text, max_results: slots,
+                            budget_ms: remaining - bounds.workerReserveMs, files: batch.map(c => [c.file, String(c.dev), String(c.ino)]) })], readFiles: batch.map(c => c.file), timeoutMs: remaining, signal: this.abort.signal });
+            }
+            catch (error) {
+                // A batch stopped at the overall time limit is the time bound: keep what was found and say truncated.
+                if (!this.abort.signal.aborted && Date.now() >= deadline - 50) {
+                    truncated = true;
+                    break;
+                }
+                throw error;
+            }
+            if (this.abort.signal.aborted)
+                throw new Error('DENIED_REVOKED');
+            const result = JSON.parse(output);
+            if (!Array.isArray(result.matches) || result.matches.length > slots || !Number.isSafeInteger(result.scanned) || result.scanned < 0 || result.scanned > batch.length
+                || result.matches.some(m => !Array.isArray(m) || !Number.isSafeInteger(m[0]) || m[0] < 0 || m[0] >= batch.length || !Number.isSafeInteger(m[1]) || m[1] < 1 || typeof m[2] !== 'string'))
+                throw new Error('LOCAL_FIND_RESULT_REJECTED');
+            scanned += result.scanned;
+            for (const [index, line, value] of result.matches) {
+                const match = { path: batch[index].rel, line, text: value.slice(0, bounds.lineChars) };
+                matches.push(match);
+                size += Buffer.byteLength(JSON.stringify(match)) + 1;
+            }
+            if (result.truncated === true || size > bounds.resultBytes) {
+                truncated = true;
+                break;
+            }
+        }
+        return this.boundedFind(matches, truncated, scanned);
+    }
+    /** At most 64 KiB of JSON: matches are dropped from the end, which is the end of the path order. */
+    boundedFind(matches, truncated, scanned) {
+        const result = { matches, truncated, scanned_files: scanned };
+        let size = Buffer.byteLength(JSON.stringify(result));
+        while (size > LOCAL_FIND_BOUNDS.resultBytes) {
+            size -= Buffer.byteLength(JSON.stringify(matches.pop())) + 1;
+            result.truncated = true;
+        }
+        return result;
+    }
     async prepareTest(input) {
         if (this.abort.signal.aborted)
             throw new Error('DENIED_REVOKED');

package/dist/src/safety/local-tool-self-test.js

@@ -0,0 +1,44 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { LocalToolPolicy } from './local-tool-policy.js';
+import { runSandboxedMeasured } from './subprocess-sandbox.js';
+const PROBE = 'runner doctor probe\n';
+/**
+ * Reads and searches a probe file with the same LocalToolPolicy and sandbox a job's local_read and
+ * local_search use, in a fresh directory under the workspace root that holds job checkouts, then
+ * removes it (Work Item 6f9e64ae: every file tool call failed on one employee's Mac, and a job
+ * reports only LOCAL_TOOL_FAILED). No repository content is read.
+ */
+export async function localToolSelfTest(workspaceRoot, deps = {}) {
+    const node = process.execPath;
+    const parent = path.join(workspaceRoot, 'doctor');
+    await mkdir(parent, { recursive: true, mode: 0o700 });
+    const root = await mkdtemp(path.join(parent, 'local-tools-'));
+    let tool = 'local_read';
+    try {
+        await mkdir(path.join(root, 'src'), { mode: 0o700 });
+        await writeFile(path.join(root, 'src', 'probe.txt'), PROBE, { mode: 0o600 });
+        const policy = deps.createPolicy?.(root)
+            ?? new LocalToolPolicy({ worktreeRoot: root, access: 'read', allowedPaths: ['src/**'], blockedPaths: [], requiredCommands: [] });
+        const read = await policy.call('local_read', { path: 'src/probe.txt' });
+        if (read?.content !== PROBE)
+            throw new Error('local_read returned different content');
+        tool = 'local_search';
+        const search = await policy.call('local_search', { path: 'src/probe.txt', query: 'probe' });
+        if (!Array.isArray(search?.matches) || search.matches.length !== 1)
+            throw new Error('local_search returned different matches');
+        return { status: 'passed', node };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const result = { status: 'failed', tool, detail, node };
+        if (detail.startsWith('LOCAL_SANDBOX_UNAVAILABLE')) {
+            const measured = await runSandboxedMeasured({ executable: node, argv: ['--version'], readFiles: [], timeoutMs: 10000 });
+            result.sandbox = { status: measured.status, ...(measured.reason ? { reason: measured.reason } : {}), exit_code: measured.exit_code };
+        }
+        return result;
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}

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

@@ -1,7 +1,7 @@
 import { createServer } from 'node:http';
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import path from 'node:path';
-import { LOCAL_TOOL_NAMES } from './local-tool-policy.js';
+import { LOCAL_TOOL_INVENTORIES, localToolNames } from './local-tool-policy.js';
 const discoveryScopes = new WeakMap();
 export function localDiscoveryScopeMatches(scope, endpoint, token) {
     if (!scope || typeof scope !== 'object')
@@ -26,10 +26,20 @@ const schemas = {
     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 },
     local_test: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'], additionalProperties: false },
+    // Every property is optional, so no `required`; the policy refuses a call with neither name nor text (DENIED_QUERY).
+    local_find: { type: 'object', properties: { path: { type: 'string', description: 'Checkout-relative directory to search below; omit it for the whole checkout.' }, name: { type: 'string', maxLength: 256, description: 'Literal, case-insensitive part of the checkout-relative file path.' }, text: { type: 'string', maxLength: 4096, description: 'Literal, case-sensitive part of one line.' }, max_results: { type: 'integer', minimum: 1, maximum: 200, description: 'Most matches returned; default 100.' } }, additionalProperties: false },
 };
-/** 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_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]) }));
+export const LOCAL_TOOL_INVENTORY_IDS = Object.freeze(Object.keys(LOCAL_TOOL_INVENTORIES));
+/** Same immutable-by-copy inventory used by native admission and MCP discovery. Without an id it is local-tools-v1, the
+ * inventory every caller not selected per job keeps. Descriptions and schemas are part of each inventory's fingerprint:
+ * changing them changes what the Gateway pins, so a change is a new inventory, never an edit of a listed one. */
+export function localToolInventory(id = 'local-tools-v1') {
+    return localToolNames(id).map(name => ({ name, description: name === 'local_find' ? 'Find files inside the approved scope by name (a literal, case-insensitive part of the checkout-relative file path), by text (a literal, case-sensitive part of a line) or by both. path is a directory to search below; vendor/ and node_modules/ are skipped unless path is inside them. Returns matches sorted by path, each with line and text for a text match, the files scanned, and truncated: true when a search bound was reached. Then use local_search and local_read on a file found.' : 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]) }));
+}
+/** The inventory whose fingerprint under `hash` is `sha256`, or undefined: a job serves only an inventory its reviewed
+ * input names. Codex descriptors hash with `fingerprint`, Claude pins with `claudeCanonicalSha256` (same canonical JSON). */
+export function localToolInventoryFor(sha256, hash) {
+    return typeof sha256 === 'string' && /^[a-f0-9]{64}$/.test(sha256) ? LOCAL_TOOL_INVENTORY_IDS.find(id => hash({ tools: localToolInventory(id) }) === sha256) : undefined;
 }
 /** Job-only JSON MCP endpoint; intentionally has no Gateway transport or discovery. */
 export class LocalToolServer {
@@ -69,7 +79,9 @@ export class LocalToolServer {
     discoveryScope = Object.freeze({ kind: 'local_discovery_scope' });
     constructor(options) {
         this.options = options;
+        this.tools = localToolNames(options.inventory);
     }
+    tools;
     revoke() { const first = !this.revoked; this.revoked = true; this.token = null; if (first)
         this.observe('revoked'); this.options.policy.revoke?.(); }
     observe(event) { try {
@@ -183,7 +195,7 @@ export class LocalToolServer {
                 if (rpc.method === 'tools/list') {
                     res.once('finish', () => { if (!this.revoked)
                         this.observe('inventory_response'); });
-                    send({ tools: localToolInventory() });
+                    send({ tools: localToolInventory(this.options.inventory) });
                     return;
                 }
                 if (rpc.method !== 'tools/call' || !rpc.params || typeof rpc.params !== 'object' || Array.isArray(rpc.params)) {
@@ -195,7 +207,7 @@ export class LocalToolServer {
                     return;
                 }
                 const params = rpc.params;
-                if (!LOCAL_TOOL_NAMES.includes(params.name)) {
+                if (typeof params.name !== 'string' || !this.tools.includes(params.name)) {
                     reply(403, { error: 'Forbidden tool' });
                     return;
                 }

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

@@ -12,6 +12,48 @@ if (input.tool === 'local_replace') {
   if (typeof input.new !== 'string' || Buffer.byteLength(input.new) > 1048576) throw Error('DENIED_CONTENT');
   if (isPatchContent(input.new)) throw Error('DENIED_PATCH_CONTENT');
 }
+// local_find: only the host's candidate list, each [path, dev, ino] as the host saw it. A file that fails a local_read
+// check, has a NUL byte in its first 8 KiB or cannot be read here is skipped, not reported.
+const findText = (input) => {
+  const deadline = Date.now() + input.budget_ms, buffer = Buffer.alloc(1048577), matches = [];
+  let scanned = 0, size = 0, truncated = false;
+  const content = ([file, dev, ino]) => {
+    try {
+      let current = '';
+      for (const part of file.split('/').filter(Boolean)) {
+        current += '/' + part;
+        if (fs.lstatSync(current).isSymbolicLink()) return null;
+      }
+      const before = fs.lstatSync(file, {bigint: true});
+      if (!before.isFile() || before.nlink !== 1n || before.size > 1048576n || String(before.dev) !== dev || String(before.ino) !== ino) return null;
+      const fd = fs.openSync(file, fs.constants.O_NOFOLLOW | fs.constants.O_RDONLY);
+      try {
+        const actual = fs.fstatSync(fd, {bigint: true}), final = fs.lstatSync(file, {bigint: true});
+        if (actual.ino !== before.ino || actual.dev !== before.dev || final.ino !== before.ino || final.dev !== before.dev || actual.nlink !== 1n) return null;
+        const count = fs.readSync(fd, buffer, 0, buffer.length, 0);
+        if (count > 1048576 || buffer.subarray(0, Math.min(count, 8192)).includes(0)) return null;
+        return buffer.subarray(0, count).toString('utf8');
+      } finally { fs.closeSync(fd); }
+    } catch { return null; }
+  };
+  files: for (let index = 0; index < input.files.length; index++) {
+    if (Date.now() >= deadline) { truncated = true; break; }
+    const data = content(input.files[index]);
+    if (data === null) continue;
+    scanned++;
+    const lines = data.split('\n');
+    for (let line = 0; line < lines.length; line++) {
+      if (!lines[line].includes(input.text)) continue;
+      const match = [index, line + 1, lines[line].slice(0, 300)];
+      size += JSON.stringify(match).length + 1;
+      if (matches.length >= input.max_results || size > 65536) { truncated = true; break files; }
+      matches.push(match);
+    }
+  }
+  return {matches, scanned, truncated};
+};
+if (input.tool === 'local_find') process.stdout.write(JSON.stringify(findText(input)));
+else {
 try {
 const readRange = input.tool === 'local_read' ? validateLocalReadRange(input) : undefined;
 let current = '';
@@ -90,4 +132,5 @@ try {
   if (!rangeDenied && !replaceDenied) throw error;
   process.stdout.write(JSON.stringify({denied: error.message}));
 }
+}
 `;

package/dist/src/safety/pre-tool-use-hook.js

@@ -1,4 +1,19 @@
-export const CLAUDE_LOCAL_MCP_TOOLS = Object.freeze(["local_read", "local_search", "local_edit", "local_replace", "local_test"].map(name => `mcp__ai_local__${name}`));
+const localMcp = (names) => Object.freeze(names.map(name => `mcp__ai_local__${name}`));
+const V1_TOOLS = ["local_read", "local_search", "local_edit", "local_replace", "local_test"];
+/** Job-local MCP names of each tool inventory (local-tool-policy.ts LOCAL_TOOL_INVENTORIES, Work Decision f43e7aa0). The
+ * hook script does not load the policy module, so a test keeps the two equal. A job's policy allows only its own. */
+export const CLAUDE_LOCAL_MCP_INVENTORIES = Object.freeze({
+    "local-tools-v1": localMcp(V1_TOOLS), "local-tools-v2": localMcp([...V1_TOOLS, "local_find"])
+});
+/** The local-tools-v1 names, what a job without a named inventory runs. */
+export const CLAUDE_LOCAL_MCP_TOOLS = CLAUDE_LOCAL_MCP_INVENTORIES["local-tools-v1"];
+const KNOWN_LOCAL_MCP_TOOLS = new Set(Object.values(CLAUDE_LOCAL_MCP_INVENTORIES).flat());
+/** The names of one inventory; an unknown id fails closed. */
+export function claudeLocalMcpTools(id = "local-tools-v1") {
+    if (!Object.hasOwn(CLAUDE_LOCAL_MCP_INVENTORIES, id))
+        throw new Error("DENIED_TOOL_INVENTORY");
+    return CLAUDE_LOCAL_MCP_INVENTORIES[id];
+}
 function allow(reasonCode) {
     return {
         hookSpecificOutput: {
@@ -30,6 +45,6 @@ export function evaluateHookEvent(input, policy) {
     if (typeof toolName !== "string" || toolName.length === 0) {
         return deny("DENIED_MALFORMED_INPUT");
     }
-    return CLAUDE_LOCAL_MCP_TOOLS.includes(toolName) && policy.allowedMcpTools.includes(toolName)
+    return KNOWN_LOCAL_MCP_TOOLS.has(toolName) && policy.allowedMcpTools.includes(toolName)
         ? allow("ALLOWED_LOCAL_TOOL") : deny("DENIED_TOOL_NOT_ALLOWED");
 }

package/dist/src/workspace/git-client.js

@@ -1,13 +1,17 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+/** The employee's own Git environment with prompts off: a job's Git never waits for a person. */
+export function gitEnvironment() {
+    return { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+}
 export class GitClient {
     async run(args, options = {}) {
         const result = await execFileAsync("git", args, {
             cwd: options.cwd,
             encoding: "utf8",
             maxBuffer: 10 * 1024 * 1024,
-            env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+            env: gitEnvironment(),
         });
         return { stdout: result.stdout, stderr: result.stderr };
     }

package/dist/src/workspace/repository-access.js

@@ -0,0 +1,95 @@
+import { spawn } from "node:child_process";
+import { gitEnvironment } from "./git-client.js";
+export class RepositoryAccessError extends Error {
+    code;
+    constructor(code) {
+        super(code === "REPOSITORY_ACCESS_DENIED" ? "Git could not read the registered repository without a credential prompt" : "Git could not reach the registered repository");
+        this.code = code;
+    }
+}
+// No credential (GIT_TERMINAL_PROMPT=0 refused to ask), a refused one, or an account without access to the repository.
+const DENIED = [
+    /terminal prompts disabled/i, /could not read (?:username|password)/i, /authentication failed/i, /invalid credentials/i,
+    /permission denied \(publickey/i, /host key verification failed/i, /returned error: 40[13]\b/i,
+    /you may not have access to this repository/i, /repository '[^'\n]*' not found/i, /repository not found/i,
+];
+// Name resolution, routing or a connection that never completed; ssh and https word these differently.
+const UNREACHABLE = [
+    /could not resolve host/i, /failed to connect to/i, /couldn't connect to server/i, /connection timed out/i,
+    /operation timed out/i, /connection refused/i, /network is unreachable/i,
+];
+/** The access code a failed Git command's stderr shows, or undefined for any other failure. */
+export function repositoryAccessFailure(error) {
+    const stderr = typeof error === "object" && error !== null ? error.stderr : undefined;
+    if (typeof stderr !== "string" || stderr === "")
+        return undefined;
+    if (DENIED.some(pattern => pattern.test(stderr)))
+        return "REPOSITORY_ACCESS_DENIED";
+    if (UNREACHABLE.some(pattern => pattern.test(stderr)))
+        return "REPOSITORY_UNREACHABLE";
+    return undefined;
+}
+/**
+ * `git ls-remote <url> HEAD` with the environment a job's clone uses, so a missing credential shows before a job runs.
+ * It runs in its own session, so neither Git nor ssh can open the terminal to ask, and the whole group ends at the
+ * deadline. It reads refs only and writes nothing.
+ */
+export function probeRepositoryAccess(providerUrl, options = {}) {
+    return new Promise(resolve => {
+        // "--" keeps a URL from ever reading as an option such as --upload-pack.
+        const child = spawn("git", ["ls-remote", "--exit-code", "--", providerUrl, "HEAD"], { detached: true, stdio: ["ignore", "ignore", "pipe"], env: gitEnvironment() });
+        let stderr = "", settled = false;
+        const finish = (result) => { if (settled)
+            return; settled = true; clearTimeout(deadline); resolve(result); };
+        const deadline = setTimeout(() => {
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch { /* The group already ended. */ }
+            finish({ status: "unreachable", code: "REPOSITORY_UNREACHABLE" });
+        }, options.timeoutMs ?? 30_000);
+        child.stderr.setEncoding("utf8").on("data", (chunk) => { if (stderr.length < 64 * 1024)
+            stderr += chunk; });
+        child.on("error", () => finish({ status: "failed" }));
+        child.on("close", code => {
+            // Exit 2 is --exit-code's "no HEAD": the credential worked.
+            if (code === 0 || code === 2)
+                return finish({ status: "readable" });
+            const access = repositoryAccessFailure({ stderr });
+            finish(access === "REPOSITORY_ACCESS_DENIED" ? { status: "denied", code: access } : access === "REPOSITORY_UNREACHABLE" ? { status: "unreachable", code: access } : { status: "failed" });
+        });
+    });
+}
+const KEY = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+// The Gateway's registered clone URLs: https, no account in the URL, nothing a shell or Git option parser could read.
+const URL_PATTERN = /^https:\/\/[A-Za-z0-9.-]+\/[A-Za-z0-9._\/-]+$/;
+/** The Gateway's list of Fix repositories from local_agent_runner_status, or undefined when this Gateway has none. */
+export function fixRepositoryList(runner) {
+    const list = typeof runner === "object" && runner !== null ? runner.fix_repositories : undefined;
+    if (!Array.isArray(list))
+        return undefined;
+    return list.slice(0, 100).filter((entry) => typeof entry === "object" && entry !== null
+        && typeof entry.repository_key === "string" && KEY.test(entry.repository_key)
+        && typeof entry.provider_url === "string" && URL_PATTERN.test(entry.provider_url))
+        .map(entry => ({ repository_key: entry.repository_key, provider_url: entry.provider_url }));
+}
+/** Probe each asked repository the Gateway lists, at most four at a time, and say what to do about each failure. */
+export async function checkRepositoryAccess(keys, listed, probe = probeRepositoryAccess) {
+    const checks = [];
+    for (let start = 0; start < keys.length; start += 4) {
+        checks.push(...await Promise.all(keys.slice(start, start + 4).map(async (key) => {
+            const url = listed.find(entry => entry.repository_key === key)?.provider_url;
+            if (url === undefined)
+                return { repository_key: key, status: "not_registered", action: `${key} has no reviewed Fix profile on the Gateway; check the repository key.` };
+            const result = await probe(url);
+            const check = `git ls-remote ${url} HEAD`;
+            switch (result.status) {
+                case "readable": return { repository_key: key, status: "readable" };
+                case "denied": return { repository_key: key, status: "denied", action: `Set up a Bitbucket login for git on this Mac so that this prints a commit without a prompt: ${check}` };
+                case "unreachable": return { repository_key: key, status: "unreachable", action: `Check the network or VPN, then run: ${check}` };
+                default: return { repository_key: key, status: "failed", action: `Run ${check} to see why git cannot read it.` };
+            }
+        })));
+    }
+    return checks;
+}

package/dist/src/workspace/workspace-manager.js

@@ -5,6 +5,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { resolve, join, sep, dirname } from "node:path";
 import { assertOwnedGitObjectStorage, RegisteredSubmoduleMaterializer } from './registered-submodules.js';
 import { isP1WorkingBranch } from '../publication/git-snapshot.js';
+import { repositoryAccessFailure, RepositoryAccessError } from './repository-access.js';
 export class WorkspaceManager {
     deps;
     submodules;
@@ -84,19 +85,26 @@ export class WorkspaceManager {
             return this.deps.git.run([...(attempt ? ['--no-replace-objects'] : []), ...args]);
         };
         if (await this.exists(mirrorPath)) {
-            const remote = (await managedGit(["--git-dir", mirrorPath, "remote", "get-url", "origin"])).stdout.trim();
+            // The stored URL, not `remote get-url`: that expands the employee's url.<x>.insteadOf, so a Mac that reaches the
+            // registered https URL over SSH would fail every job after its first clone (Work Decision 2ae1acc1).
+            const remote = (await managedGit(["--git-dir", mirrorPath, "config", "--get", "remote.origin.url"])).stdout.trim();
             if (remote !== input.providerUrl)
                 throw new Error("Managed repository remote does not match the registered provider");
         }
         else {
-            await managedGit(["clone", "--mirror", input.providerUrl, mirrorPath]);
+            try {
+                await managedGit(["clone", "--mirror", input.providerUrl, mirrorPath]);
+            }
+            catch (error) {
+                throw this.accessError(error) ?? error;
+            }
         }
         try {
             await managedGit(["--git-dir", mirrorPath, "fetch", "--prune", "origin", input.baseCommitSha]);
             await managedGit(["--git-dir", mirrorPath, "cat-file", "-e", `${input.baseCommitSha}^{commit}`]);
         }
-        catch {
-            throw new Error(`Repository revision ${input.baseCommitSha} is unavailable`);
+        catch (error) {
+            throw this.accessError(error) ?? new Error(`Repository revision ${input.baseCommitSha} is unavailable`);
         }
         if (!await this.exists(workspacePath)) {
             await managedGit(["--git-dir", mirrorPath, "worktree", "add", "--detach", workspacePath, input.baseCommitSha]);
@@ -190,6 +198,11 @@ export class WorkspaceManager {
             await handle.close();
         }
     }
+    /** A credential or network failure keeps its code (Work Item 6f9e64ae); anything else stays the caller's error. */
+    accessError(error) {
+        const code = repositoryAccessFailure(error);
+        return code === undefined ? undefined : new RepositoryAccessError(code);
+    }
     assertContained(root, candidate) {
         const resolved = resolve(candidate);
         if (resolved !== root && !resolved.startsWith(`${root}${sep}`))