mtech-ai-local-runner 0.1.52 → 0.1.54

package/README.md

@@ -1,3 +1,24 @@
+## 0.1.53: separate candidate change, file and payload limits
+
+## 0.1.54: read only the source lines you need
+
+Use `local_search` to locate code, then `local_read({path, start_line, end_line})`. Lines are 1-based and inclusive; supply both bounds, at most 400 lines. The response includes `content`, `start_line`, `end_line` and `total_lines`. Invalid/missing bounds, ranges over 400 lines and ranges past EOF are rejected with `DENIED_READ_RANGE`, `DENIED_READ_RANGE_LIMIT` and `DENIED_READ_RANGE_BOUNDS`. Empty files have 0 lines; a final newline adds no extra line. Original LF/CRLF line endings are preserved. Without bounds the existing `{content}` whole-file result is unchanged. Existing file-size and path protections still apply; no shell permission is added.
+
+
+New `gateway_publish_v1` scopes may explicitly opt into `candidate_limits.version: 2` with
+`max_changed_files`, `max_change_bytes`, `max_file_bytes` and `max_payload_bytes`.
+Change bytes are the exact minimum byte insertions plus deletions from the frozen base;
+file bytes are each resulting decoded file; payload bytes are compact UTF-8 JSON for
+`{files, validation_report?}`, including base64, paths, hashes and the report. HTTP/MCP
+framing and provider multipart overhead remain separate infrastructure limits.
+
+The Runner and Gateway compute these independently. Unknown measurement or unsupported
+modes fail closed. The Gateway bounds frozen-base response streaming and rechecks
+scope/authority before staging. Legacy unversioned `max_diff_bytes` keeps its existing
+meaning. Existing candidates/contracts/Jobs/Loops are not upgraded or published by this
+release. Match new package runtime receipts on both sides and approve a new v2 scope
+before use; a publication-only recovery protocol for retained candidates is separate.
+
 ## 0.1.52: publication diagnostics and candidate cleanup
 
 Publication failures report fixed `publication_step` and `LOCAL_FIX_*` codes;
@@ -15,6 +36,8 @@ model run. Pre-existing forensic candidates are not swept automatically.
 
 ## 0.1.51: open a session for an ask no session can show
 
+0.1.51 was not published to npm; install 0.1.52 or later to get these changes.
+
 Sometimes no live session can show an AI Gateway ask or answer soon: there is no live session, no human prompt for 30
 minutes, an idle Codex session, or an idle Claude session that cannot be woken. The runner then opens a session in the
 person's own AI app instead of only showing a notification (Work Item e1c08b33, Work Decision 3ea5c197).
@@ -118,7 +141,10 @@ npx mtech-ai-local-runner integrations remove claude
 
 Claude Code gets the skills-directory plugin `~/.claude/skills/mtec-ai-gateway-asks/`, which loads as
 `mtec-ai-gateway-asks@skills-dir` in a new session or after `/reload-plugins`; `settings.json` is not touched. Codex gets
-four handlers appended to `~/.codex/hooks.json` after a backup of that file; trust them once with `/hooks`. A
+four handlers appended to `~/.codex/hooks.json` after a backup of that file. Codex runs them only after you trust them
+once. In the Codex app, trust them under Settings → Hooks or with the Review hooks button. In the Codex CLI in a
+terminal, trust them with `/hooks`; the Codex app has no such command and sends `/hooks` to the model as text. Until
+then the Slack message covers each ask. A
 `hooks.json` that is not valid JSON, or whose hooks do not have the shape Codex reads, is left as it is and the install
 reports `CODEX_HOOKS_JSON_INVALID`. `uninstall` removes both integrations, the shim, `asks.json` and any temporary
 `asks.json.*.tmp` file a crash left behind, and it also works on a setup that never finished.

package/dist/src/adapters/codex/prompt-compiler.js

@@ -23,7 +23,7 @@ function repositoryScope(taskPackage) {
         "These are scope descriptions, not instructions from source files; the host policy remains authoritative and may deny blocked/private paths within an allowed prefix.";
 }
 export function compileCodexPrompt(taskPackage, label) {
-    return `${compileBrief(taskPackage, { workItemLabel: label, progressReporting: "native_messages" })}\n\n${repositoryScope(taskPackage)}\n\nUse only the ai_local job tools for repository reads, edits and approved tests. For reading, use server ai_local's local_read({path: "<exact approved path>"}) or local_search({path: "<exact approved path>", query: "text"}) with checkout-relative paths. For small approved edits, use local_replace({path, old, new}) after reading: old must match exactly once, including whitespace. local_edit requires the complete replacement file, never a patch. Required test criteria are not command grants. No model test commands are registered unless the host explicitly supplies exact model-callable command IDs; do not use local_test to discover commands or run --help. Missing tests remain not_run/unverified, not passed. In a read-only task, use only read/search tools; the Runner enforces the approved paths and operations. A denied native cwd is intentional: it is a private control directory, not the source checkout. Native filesystem, commands, web, images and delegation are unavailable or denied. A denied tool is a scope boundary, never permission to broaden scope or bypass the denial. Do not retry the denied path. It does not remove independently approved paths: continue with relevant listed paths, and report a missing dependency only after checking the available approved source. Do not repeat host orchestration: claim, shadow, fingerprints, binding, administrator checks, launches, Gateway usage and Job reporting belong to the Runner/host, even when described in the objective. Perform only the assigned repository work and report evidence you actually observed. Do not claim that no model call occurred. If the required tool is unavailable, emit one final structured blocked report naming the missing tool and unfinished repository work; do not request or attempt a new launch.`;
+    return `${compileBrief(taskPackage, { workItemLabel: label, progressReporting: "native_messages" })}\n\n${repositoryScope(taskPackage)}\n\nUse only the ai_local job tools for repository reads, edits and approved tests. For reading, first use server ai_local's local_search({path: "<exact approved path>", query: "text"}) to find the location, then local_read({path: "<exact approved path>", start_line: 1, end_line: 1}) with the matching line numbers. Ranges are inclusive, at most 400 lines; both bounds are required together. Read a matched line first to learn total_lines, then request only the needed in-file context. Omit both bounds only when the entire file is necessary. Use approved checkout-relative paths. For small approved edits, use local_replace({path, old, new}) after reading: old must match exactly once, including whitespace. local_edit requires the complete replacement file, never a patch. Required test criteria are not command grants. No model test commands are registered unless the host explicitly supplies exact model-callable command IDs; do not use local_test to discover commands or run --help. Missing tests remain not_run/unverified, not passed. In a read-only task, use only read/search tools; the Runner enforces the approved paths and operations. A denied native cwd is intentional: it is a private control directory, not the source checkout. Native filesystem, commands, web, images and delegation are unavailable or denied. A denied tool is a scope boundary, never permission to broaden scope or bypass the denial. Do not retry the denied path. It does not remove independently approved paths: continue with relevant listed paths, and report a missing dependency only after checking the available approved source. Do not repeat host orchestration: claim, shadow, fingerprints, binding, administrator checks, launches, Gateway usage and Job reporting belong to the Runner/host, even when described in the objective. Perform only the assigned repository work and report evidence you actually observed. Do not claim that no model call occurred. If the required tool is unavailable, emit one final structured blocked report naming the missing tool and unfinished repository work; do not request or attempt a new launch.`;
 }
 export const CODEX_REPORT_SCHEMA = {
     type: "object", additionalProperties: false, required: ["status", "report", "evidence", "pending_work"],

package/dist/src/asks/commands.js

@@ -5,7 +5,9 @@ import { installIntegration, integrationStatus, removeIntegration, removeShimIfU
 import { APPS, isApp } from "./types.js";
 const NEXT_STEP = {
     claude: "Start a new Claude Code session, or run /reload-plugins in an open one, to load mtec-ai-gateway-asks@skills-dir.",
-    codex: "Open Codex and trust the four AI Gateway hooks once with /hooks. Until then Codex skips them and the Slack message covers the gap.",
+    // /hooks is a command of the Codex CLI in a terminal only: the Codex app sends it to the model as text.
+    codex: "Codex runs the four AI Gateway hooks only after you trust them once. In the Codex app, trust them under Settings → Hooks "
+        + "or with the Review hooks button. In the Codex CLI in a terminal, trust them with /hooks. Until then the Slack message covers each ask.",
 };
 function errorCode(error) {
     const code = error?.code;

package/dist/src/asks/doctor.js

@@ -10,7 +10,9 @@ const CLAUDE_NOT_LOADED = `Claude Code does not load ${PLUGIN_ID}. Managed setti
     + "(strictPluginOnlyCustomization, a strictKnownMarketplaces list without the skills-dir source, or blockedMarketplaces): "
     + "ask your administrator, or install the plugin from a directory marketplace your organization allows (claude plugin marketplace add <dir>). "
     + "A Claude Code release without skills-directory plugins does not load it either.";
-const CODEX_TRUST = "Codex runs these hooks only after you trust them once with /hooks; until then the Slack message covers each ask.";
+// /hooks is a command of the Codex CLI in a terminal only: the Codex app sends it to the model as text.
+const CODEX_TRUST = "Codex runs these hooks only after you trust them once. In the Codex app, trust them under Settings → Hooks "
+    + "or with the Review hooks button. In the Codex CLI in a terminal, trust them with /hooks. Until then the Slack message covers each ask.";
 /** Runs the Claude CLI with the environment doctor was given on top of the process's own (CLAUDE_CONFIG_DIR, for one). */
 const defaultRun = (env) => (file, args) => new Promise((resolve, reject) => {
     execFile(file, args, { encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024, env: { ...process.env, ...env } }, (error, stdout) => (error ? reject(error) : resolve({ stdout })));

package/dist/src/publication/candidate-limits.js

@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto';
+const issued = new WeakMap();
+const reject = (code) => { const error = Error('CANDIDATE_LIMIT_REJECTED'); issued.set(error, code); throw error; };
+export function trustedCandidateLimitCode(error) { return error && typeof error === 'object' ? issued.get(error) : undefined; }
+export function candidateLimits(value, publish) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return reject('LIMIT_SCHEMA_REJECTED');
+    const l = value;
+    if (l.version !== undefined) {
+        const keys = ['version', 'max_changed_files', 'max_change_bytes', 'max_file_bytes', 'max_payload_bytes'];
+        if (!publish || l.version !== 2 || Object.keys(l).sort().join() !== keys.sort().join() || keys.slice(0).filter(k => k !== 'version').some(k => !Number.isSafeInteger(l[k]) || Number(l[k]) < 1 || Number(l[k]) > (k === 'max_changed_files' ? 50 : 1000000)))
+            return reject('LIMIT_SCHEMA_REJECTED');
+        return { ...l };
+    }
+    if ('max_change_bytes' in l || 'max_payload_bytes' in l || ['max_changed_files', 'max_diff_bytes', 'max_file_bytes'].some(k => !Number.isSafeInteger(l[k]) || Number(l[k]) < 1))
+        return reject('LIMIT_SCHEMA_REJECTED');
+    return { ...l };
+}
+/** Exact byte insertion/deletion distance. Fixed work exhaustion never becomes a guessed count. */
+export function changedBytes(before, after) {
+    if (before.length > 1000000 || after.length > 1000000)
+        return reject('CHANGE_MEASUREMENT_REJECTED');
+    let start = 0, n = before.length, m = after.length, work = 0;
+    const tick = () => { if (++work > 2000000)
+        reject('CHANGE_MEASUREMENT_REJECTED'); };
+    while (start < n && start < m && before[start] === after[start]) {
+        tick();
+        start++;
+    }
+    while (n > start && m > start && before[n - 1] === after[m - 1]) {
+        tick();
+        n--;
+        m--;
+    }
+    n -= start;
+    m -= start;
+    if (!n || !m)
+        return n + m;
+    let frontier = new Map([[1, 0]]);
+    for (let d = 0; d <= n + m; d++) {
+        const next = new Map();
+        for (let k = -d; k <= d; k += 2) {
+            tick();
+            const left = frontier.get(k - 1) ?? -1, down = frontier.get(k + 1) ?? -1;
+            let x = k === -d || (k !== d && left < down) ? down : left + 1;
+            if (x < 0)
+                continue;
+            let y = x - k;
+            while (x < n && y < m && y >= 0 && before[start + x] === after[start + y]) {
+                tick();
+                x++;
+                y++;
+            }
+            if (x >= n && y >= m)
+                return d;
+            next.set(k, x);
+        }
+        frontier = next;
+    }
+    return reject('CHANGE_MEASUREMENT_REJECTED');
+}
+export function candidatePayloadBytes(files, report) { return Buffer.byteLength(JSON.stringify({ files, ...(report === undefined ? {} : { validation_report: report }) }), 'utf8'); }
+export function measureSplitDelta(diff, limits, report) {
+    const delta = JSON.parse(diff);
+    if (delta?.format !== 'local-candidate-binary-diff-v1' || !Array.isArray(delta.changes) || !delta.changes.length || delta.changes.length > limits.max_changed_files)
+        reject('FILE_COUNT_REJECTED');
+    let changes = 0, maxFile = 0;
+    const decode = (v) => { if (typeof v !== 'string')
+        return reject('CHANGE_MEASUREMENT_REJECTED'); const b = Buffer.from(v, 'base64'); if (b.toString('base64') !== v || b.length > 1000000 || b.includes(0) || !Buffer.from(b.toString('utf8')).equals(b))
+        return reject('CHANGE_MEASUREMENT_REJECTED'); return b; };
+    const files = delta.changes.map((c) => {
+        if (!c || typeof c.path !== 'string' || !['added', 'modified', 'deleted'].includes(c.status) || c.status === 'added' && c.before !== null || c.status === 'deleted' && c.after !== null)
+            reject('CHANGE_MEASUREMENT_REJECTED');
+        const before = c.status === 'added' ? Buffer.alloc(0) : decode(c.before), after = c.status === 'deleted' ? Buffer.alloc(0) : decode(c.after);
+        maxFile = Math.max(maxFile, after.length);
+        if (maxFile > limits.max_file_bytes)
+            reject('FILE_LIMIT_REJECTED');
+        changes += changedBytes(before, after);
+        if (changes > limits.max_change_bytes)
+            reject('CHANGE_LIMIT_REJECTED');
+        return { path: c.path, status: c.status, content_base64: c.status === 'deleted' ? null : after.toString('base64'), content_sha256: c.status === 'deleted' ? null : createHash('sha256').update(after).digest('hex') };
+    });
+    if (!changes)
+        reject('CHANGE_MEASUREMENT_REJECTED');
+    const payload = candidatePayloadBytes(files, report);
+    if (payload > limits.max_payload_bytes)
+        reject('PAYLOAD_LIMIT_REJECTED');
+    return { metrics: { version: 2, change_bytes: changes, max_file_bytes: maxFile, payload_bytes: payload }, files };
+}

package/dist/src/publication/failure.js

@@ -1,6 +1,6 @@
 import { PublicationOutcomeUnknownError } from './publisher.js';
 export const PUBLICATION_STEPS = ['validation_report', 'current_fence', 'snapshot_observe', 'snapshot_materialize', 'candidate_limits', 'delta_format', 'delta_modes', 'delta_scope', 'candidate_files', 'journal', 'security_receipt', 'stage', 'advance', 'result', 'cleanup'];
-export const PUBLICATION_CODES = ['LOCAL_FIX_CHECK_REJECTED', 'LOCAL_FIX_REPORT_REJECTED', 'LOCAL_FIX_DIFF_LIMIT_REJECTED', 'LOCAL_FIX_FILE_COUNT_REJECTED', 'LOCAL_FIX_FILE_LIMIT_REJECTED', 'LOCAL_FIX_FILE_ENCODING_REJECTED', 'LOCAL_FIX_PUBLICATION_OUTCOME_UNKNOWN', 'LOCAL_FIX_CLEANUP_FAILED'];
+export const PUBLICATION_CODES = ['LOCAL_FIX_CHANGE_LIMIT_REJECTED', 'LOCAL_FIX_PAYLOAD_LIMIT_REJECTED', 'LOCAL_FIX_CHANGE_MEASUREMENT_REJECTED', 'LOCAL_FIX_CHECK_REJECTED', 'LOCAL_FIX_REPORT_REJECTED', 'LOCAL_FIX_DIFF_LIMIT_REJECTED', 'LOCAL_FIX_FILE_COUNT_REJECTED', 'LOCAL_FIX_FILE_LIMIT_REJECTED', 'LOCAL_FIX_FILE_ENCODING_REJECTED', 'LOCAL_FIX_PUBLICATION_OUTCOME_UNKNOWN', 'LOCAL_FIX_CLEANUP_FAILED'];
 const issued = new WeakMap();
 const cleanupFailures = new WeakSet();
 /** Host vocabulary only; serialized fields/messages never carry diagnostic authority. */

package/dist/src/publication/production-host.js

@@ -55,6 +55,8 @@ export function createProductionLocalFixHost(options) {
             } };
             const frozenCurrent = async () => lifecycle.isFrozen() && await current();
             const limits = scope.candidate_limits;
+            if (['version', 'max_change_bytes', 'max_payload_bytes'].some(k => k in limits))
+                throw denied();
             const snapshots = new GitSnapshotHost({ root: input.checkoutPath, privateRoot: root, git: options.git, baseCommitSha: binding.base_commit_sha, workingBranch: binding.working_branch, maxFileBytes: SNAPSHOT_TREE_MAX_BYTES, maxTotalBytes: SNAPSHOT_TREE_MAX_BYTES });
             const isolated = createSealedIsolatedVerifier({ host: snapshots, allowedPaths: verificationPaths, blockedPaths: ['.env', '.env.*', '.git/**', '.ssh/**', '.aws/**'], commands, current: frozenCurrent });
             const verifier = new CandidateVerifier({ binding, root: input.checkoutPath, allowedPaths: allowed, blockedPaths: ['.env', '.env.*', '.git/**', '.ssh/**', '.aws/**'], maxFiles: limits.max_changed_files, maxDiffBytes: limits.max_diff_bytes, maxFileBytes: limits.max_file_bytes, commands, current: frozenCurrent, assertRetainedSeal: async () => { const seal = isolated.materialized(); if (!seal)

package/dist/src/publication/server-ci-host.js

@@ -1,3 +1,4 @@
+import { candidateLimits, measureSplitDelta, trustedCandidateLimitCode } from './candidate-limits.js';
 import { publicationError, publicationCleanupFailure, trustedPublicationFailure } from './failure.js';
 import { ServerCiPublicationError } from './server-ci-error.js';
 export { ServerCiPublicationError } from './server-ci-error.js';
@@ -67,10 +68,11 @@ export function createServerCiLocalFixHost(options) {
             const lifecycle = input.lifecycle;
             if (!lifecycle)
                 throw denied();
-            const { job } = input, pkg = job.taskPackage, scope = pkg.local_fix_scope, repo = pkg.repository, limits = scope?.candidate_limits, allowed = scope?.allowed_paths;
+            const { job } = input, pkg = job.taskPackage, scope = pkg.local_fix_scope, repo = pkg.repository, rawLimits = scope?.candidate_limits, allowed = scope?.allowed_paths;
             const root = await realpath(options.privateRoot), st = await lstat(root);
-            if (!lifecycle.isCurrent() || pkg.runtime_adapter !== 'codex_cli' || !scope || scope.verification_mode !== mode || scope.ci_profile_fingerprint !== registration.ci_profile_fingerprint || protocolHash(scope.ci_profile) !== protocolHash(registration.ci_profile) || !Array.isArray(scope.required_commands) || scope.required_commands.length || !scope.registered_tests || typeof scope.registered_tests !== 'object' || Object.keys(scope.registered_tests).length || !Array.isArray(allowed) || !allowed.length || allowed.some(p => typeof p !== 'string' || !(safePath(p) || p.endsWith('/**') && safePath(p.slice(0, -3)))) || protocolHash(allowed) !== protocolHash(pkg.allowed_paths) || repo.key !== registration.project || job.gatewayTaskPackageFingerprint !== protocolHash(pkg) || Object.entries(registration.receipt).some(([k, v]) => scope[k] !== v) || !limits || ['max_changed_files', 'max_diff_bytes', 'max_file_bytes'].some(k => !Number.isSafeInteger(limits[k]) || limits[k] < 1) || root !== options.privateRoot || !st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 || (process.getuid && st.uid !== process.getuid()) || root === input.checkoutPath || root.startsWith(input.checkoutPath + path.sep))
+            if (!lifecycle.isCurrent() || pkg.runtime_adapter !== 'codex_cli' || !scope || scope.verification_mode !== mode || scope.ci_profile_fingerprint !== registration.ci_profile_fingerprint || protocolHash(scope.ci_profile) !== protocolHash(registration.ci_profile) || !Array.isArray(scope.required_commands) || scope.required_commands.length || !scope.registered_tests || typeof scope.registered_tests !== 'object' || Object.keys(scope.registered_tests).length || !Array.isArray(allowed) || !allowed.length || allowed.some(p => typeof p !== 'string' || !(safePath(p) || p.endsWith('/**') && safePath(p.slice(0, -3)))) || protocolHash(allowed) !== protocolHash(pkg.allowed_paths) || repo.key !== registration.project || job.gatewayTaskPackageFingerprint !== protocolHash(pkg) || Object.entries(registration.receipt).some(([k, v]) => scope[k] !== v) || root !== options.privateRoot || !st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 || (process.getuid && st.uid !== process.getuid()) || root === input.checkoutPath || root.startsWith(input.checkoutPath + path.sep))
                 throw denied();
+            const limits = candidateLimits(rawLimits, mode === 'gateway_publish_v1');
             const fence = { jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, launchGrant: job.launchGrant, bindingId: input.bindingId };
             const binding = bindingProof((await options.gateway.localPublicationContext(fence)).context);
             if (binding.runner_id !== options.runnerId || binding.binding_id !== input.bindingId || binding.job_id !== job.id || binding.generation !== job.generation || binding.work_loop_id !== job.workLoopId || binding.repository_key !== repo.key || binding.base_commit_sha !== repo.base_commit_sha || binding.working_branch !== repo.working_branch || binding.working_branch !== `ai-work/local/${binding.attempt_id}` || binding.attempt_id !== scope.attempt_id || binding.contract_fingerprint !== job.gatewayContractFingerprint || binding.task_package_fingerprint !== job.gatewayTaskPackageFingerprint || binding.launch_fingerprint !== job.launchFingerprint)
@@ -99,7 +101,17 @@ export function createServerCiLocalFixHost(options) {
                         phase = 'snapshot_observe';
                         const observed = await host.observe();
                         phase = 'candidate_limits';
-                        if (Buffer.byteLength(observed.diff) > limits.max_diff_bytes)
+                        let split;
+                        if (limits.version === 2) {
+                            try {
+                                split = measureSplitDelta(observed.diff, limits, report);
+                            }
+                            catch (error) {
+                                const code = trustedCandidateLimitCode(error);
+                                throw publicationError(phase, code === 'CHANGE_LIMIT_REJECTED' ? 'LOCAL_FIX_CHANGE_LIMIT_REJECTED' : code === 'PAYLOAD_LIMIT_REJECTED' ? 'LOCAL_FIX_PAYLOAD_LIMIT_REJECTED' : code === 'FILE_LIMIT_REJECTED' ? 'LOCAL_FIX_FILE_LIMIT_REJECTED' : code === 'FILE_COUNT_REJECTED' ? 'LOCAL_FIX_FILE_COUNT_REJECTED' : 'LOCAL_FIX_CHANGE_MEASUREMENT_REJECTED');
+                            }
+                        }
+                        if (limits.version !== 2 && Buffer.byteLength(observed.diff) > limits.max_diff_bytes)
                             throw publicationError(phase, 'LOCAL_FIX_DIFF_LIMIT_REJECTED');
                         if (!observed.changed_files.length || observed.changed_files.length > limits.max_changed_files)
                             throw publicationError(phase, 'LOCAL_FIX_FILE_COUNT_REJECTED');
@@ -156,7 +168,7 @@ export function createServerCiLocalFixHost(options) {
                                     if (!s.isFile() || s.nlink !== 1n || s.dev !== before.dev || s.ino !== before.ino || s.size !== before.size || s.mtimeNs !== before.mtimeNs || s.ctimeNs !== before.ctimeNs || s.mode !== before.mode)
                                         throw denied();
                                 bytes += content.length;
-                                if (bytes > limits.max_diff_bytes)
+                                if (limits.version !== 2 && bytes > limits.max_diff_bytes)
                                     throw publicationError(phase, 'LOCAL_FIX_DIFF_LIMIT_REJECTED');
                                 if (content.includes(0) || !Buffer.from(content.toString('utf8'), 'utf8').equals(content))
                                     throw publicationError(phase, 'LOCAL_FIX_FILE_ENCODING_REJECTED');
@@ -166,6 +178,8 @@ export function createServerCiLocalFixHost(options) {
                                 await fd.close();
                             }
                         }
+                        if (split && protocolHash(split.files) !== protocolHash(files))
+                            throw publicationError('candidate_files');
                         phase = 'journal';
                         const journal = new FilePublicationJournal(root), key = protocolHash({ mode, binding }), deltaFingerprint = protocolHash({ binding, files, profile: registration.ci_profile_fingerprint, ...(report ? { validation_report: report } : {}) });
                         return journal.exclusive(key, async () => {

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/package.json

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