mixdog 0.9.87 → 0.9.89

package/src/runtime/agent/orchestrator/tools/builtin/rg-runner.mjs

@@ -30,14 +30,14 @@ const execFileAsync = promisify(execFile);
 // for this change and intentionally not added per-spawn.
 
 // ── rg --threads cap ─────────────────────────────────────────────────────
-// Each rg process otherwise fans out across EVERY core; with several agents
-// running grep at once the box over-saturates and the whole batch trips the
-// 20s deadline together. Use the larger half-CPU cap only when the spawn gate
-// has spare capacity; otherwise retain the conservative quarter-CPU cap.
-// Internal dynamic default; env override only — deliberately NOT exposed on
-// any tool schema / parameter surface.
+// Each rg process otherwise fans out across EVERY core. Keep every independent
+// tool call fully parallel, but bound the threads INSIDE each rg process so a
+// broad explorer wave does not multiply half-machine thread pools (8 calls on
+// a 20-core host previously created ~80 rg workers and made every call slower).
+// This does not queue or limit calls; it only prevents per-process
+// oversubscription. Env override remains available for operator tuning.
 let _rgDefaultThreadCap = null;
-export function _rgThreadCap(spareCapacity = false) {
+export function _rgThreadCap(_spareCapacity = false) {
     const override = Number(process.env.MIXDOG_RG_THREADS);
     if (Number.isFinite(override) && override >= 1) return Math.floor(override);
     if (_rgDefaultThreadCap === null) {
@@ -46,9 +46,7 @@ export function _rgThreadCap(spareCapacity = false) {
         _rgDefaultThreadCap = cpus || 4;
     }
     const cpus = _rgDefaultThreadCap;
-    return spareCapacity
-        ? Math.max(4, Math.ceil(cpus / 2))
-        : Math.max(2, Math.ceil(cpus / 4));
+    return Math.max(2, Math.min(4, Math.ceil(cpus / 4)));
 }
 
 // Walk rg options once for all thread-argument helpers. Values of these
@@ -370,6 +368,14 @@ function _boxPartialRgString(s, rgStderrText = '') {
     return boxed;
 }
 
+function _rgAbortError(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof Error) return reason;
+    const error = new Error(String(reason || 'rg canceled'));
+    error.code = 'ABORT_ERR';
+    return error;
+}
+
 function _armRgForceSettle({ timeoutMs, isSettled, timers, proc, onForceSettle }) {
     if (timers.forceSettle) clearTimeout(timers.forceSettle);
     timers.forceSettle = setTimeout(() => {
@@ -412,6 +418,15 @@ function spawnRg(argsList, execOptions) {
         let stdoutBytes = 0;
         let stdoutTruncated = false;
         const timers = { timeout: null, killGrace: null, forceSettle: null };
+        let aborted = false;
+        let onAbort = null;
+        const clearAll = () => {
+            _clearRgTimers(timers);
+            if (onAbort && gateSignal) {
+                try { gateSignal.removeEventListener('abort', onAbort); } catch { /* ignore */ }
+                onAbort = null;
+            }
+        };
         timers.timeout = setTimeout(() => {
             timedOut = true;
             killReason = 'timeout';
@@ -430,10 +445,33 @@ function spawnRg(argsList, execOptions) {
                 e.code = 'ETIMEDOUT';
                 if (settled) return;
                 settled = true;
-                _clearRgTimers(timers);
+                clearAll();
                 reject(e);
             },
         });
+        if (gateSignal) {
+            onAbort = () => {
+                if (settled || aborted) return;
+                aborted = true;
+                killReason = 'abort';
+                _clearRgTimeoutOnly(timers);
+                _killRgProc(proc, timers);
+                _armRgForceSettle({
+                    timeoutMs: 0,
+                    isSettled: () => settled,
+                    timers,
+                    proc,
+                    onForceSettle: () => {
+                        if (settled) return;
+                        settled = true;
+                        clearAll();
+                        reject(_rgAbortError(gateSignal));
+                    },
+                });
+            };
+            if (gateSignal.aborted) onAbort();
+            else gateSignal.addEventListener('abort', onAbort, { once: true });
+        }
         proc.stdout.setEncoding('utf-8');
         proc.stderr.setEncoding('utf-8');
         proc.stdout.on('data', (d) => {
@@ -466,13 +504,16 @@ function spawnRg(argsList, execOptions) {
         proc.on('error', (err) => {
             if (settled) return;
             settled = true;
-            _clearRgTimers(timers);
+            clearAll();
             reject(err);
         });
         proc.on('close', (code) => {
             if (settled) return;
             settled = true;
-            _clearRgTimers(timers);
+            clearAll();
+            if (aborted || killReason === 'abort') {
+                return reject(_rgAbortError(gateSignal));
+            }
             if (timedOut && killReason === 'timeout') {
                 if (stdout.length > 0) {
                     return resolve(_boxPartialRgString(stdout, stderr.trim()));
@@ -562,6 +603,15 @@ function spawnRgWindowedLines(argsList, execOptions, opts = {}) {
         let settled = false;
         const timers = { timeout: null, killGrace: null, forceSettle: null };
         const lines = [];
+        let aborted = false;
+        let onAbort = null;
+        const clearAll = () => {
+            _clearRgTimers(timers);
+            if (onAbort && gateSignal) {
+                try { gateSignal.removeEventListener('abort', onAbort); } catch { /* ignore */ }
+                onAbort = null;
+            }
+        };
         timers.timeout = setTimeout(() => {
             timedOut = true;
             killReason = 'timeout';
@@ -579,7 +629,7 @@ function spawnRgWindowedLines(argsList, execOptions, opts = {}) {
                 if (lines.length > 0) {
                     if (settled) return;
                     settled = true;
-                    _clearRgTimers(timers);
+                    clearAll();
                     resolve({
                         lines,
                         complete: false,
@@ -594,10 +644,33 @@ function spawnRgWindowedLines(argsList, execOptions, opts = {}) {
                 e.code = 'ETIMEDOUT';
                 if (settled) return;
                 settled = true;
-                _clearRgTimers(timers);
+                clearAll();
                 reject(e);
             },
         });
+        if (gateSignal) {
+            onAbort = () => {
+                if (settled || aborted) return;
+                aborted = true;
+                killReason = 'abort';
+                _clearRgTimeoutOnly(timers);
+                _killRgProc(proc, timers);
+                _armRgForceSettle({
+                    timeoutMs: 0,
+                    isSettled: () => settled,
+                    timers,
+                    proc,
+                    onForceSettle: () => {
+                        if (settled) return;
+                        settled = true;
+                        clearAll();
+                        reject(_rgAbortError(gateSignal));
+                    },
+                });
+            };
+            if (gateSignal.aborted) onAbort();
+            else gateSignal.addEventListener('abort', onAbort, { once: true });
+        }
         const stopEarly = () => {
             if (stoppedEarly) return;
             stoppedEarly = true;
@@ -656,17 +729,20 @@ function spawnRgWindowedLines(argsList, execOptions, opts = {}) {
         proc.on('error', (err) => {
             if (settled) return;
             settled = true;
-            _clearRgTimers(timers);
+            clearAll();
             reject(err);
         });
         proc.on('close', (code) => {
             if (settled) return;
             settled = true;
-            _clearRgTimers(timers);
+            clearAll();
             if (!stoppedEarly && buffer.length > 0) {
                 pushLine(buffer);
                 buffer = '';
             }
+            if (aborted || killReason === 'abort') {
+                return reject(_rgAbortError(gateSignal));
+            }
             if (timedOut && killReason === 'timeout') {
                 if (lines.length > 0) {
                     return resolve({

package/src/runtime/agent/orchestrator/tools/builtin/search-path-diagnostics.mjs

@@ -154,12 +154,17 @@ export async function tryReadFamilyEnoentRedirect({
     errCode,
     options,
     rerun,
+    onRedirect,
     cache = null,
 }) {
     if (options?._enoentRedirectFrom) return null;
     const target = resolveUniqueEnoentRedirect(workDir, resolvedPath, errCode, cache);
     if (!target) return null;
     const body = await rerun(target, { ...options, _enoentRedirectFrom: resolvedPath });
+    if (!(typeof body === 'string' && /^\s*Error[\s:[]/i.test(body))
+        && typeof onRedirect === 'function') {
+        try { onRedirect(resolvedPath, target); } catch { /* best-effort proof recording */ }
+    }
     const shown = requestedPath ?? resolvedPath;
     return redirectedFromPrefix(shown) + body;
 }

package/src/runtime/agent/orchestrator/tools/builtin/search-tool.mjs

@@ -588,7 +588,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                 ? GREP_CONTEXT_LINE_HARD_CAP
                 : Math.min(GREP_CONTEXT_LINE_HARD_CAP, Math.max(200, blockBudget * Math.max(1, perBlock) + 8));
             let ctxPartialSuffix = '';
-            const streamed = await runRgWindowedLines(rgArgs, { cwd: rgSpawnCwd }, { offset: 0, limit: lineCap, summaryLimit: 0 });
+            const streamed = await runRgWindowedLines(rgArgs, { cwd: rgSpawnCwd, signal: options.signal }, { offset: 0, limit: lineCap, summaryLimit: 0 });
             const allLines = streamed.lines;
             let ctxTotalKnown = streamed.complete;
             if (streamed.partial) {
@@ -635,7 +635,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
         let rgPartialSuffix = '';
         if (effectiveHeadLimit !== Infinity) {
             const summaryLimit = outputMode === 'content' ? 120 : 0;
-            const streamed = await runRgWindowedLines(rgArgs, { cwd: rgSpawnCwd }, {
+            const streamed = await runRgWindowedLines(rgArgs, { cwd: rgSpawnCwd, signal: options.signal }, {
                 offset,
                 limit: effectiveHeadLimit,
                 summaryLimit,
@@ -652,7 +652,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                     : '\n[warning] rg exit 2 (partial results)';
             }
         } else {
-            const stdout = await runRg(rgArgs, { cwd: rgSpawnCwd });
+            const stdout = await runRg(rgArgs, { cwd: rgSpawnCwd, signal: options.signal });
             const allLines = String(stdout).split('\n').filter(Boolean);
             windowed = offset > 0 ? allLines.slice(offset) : allLines;
             totalWindowed = windowed.length;
@@ -718,7 +718,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                         fileType,
                         onlyMatching: false,
                     });
-                    const probeOut = await runRg(probeArgs, { cwd: rgSpawnCwd });
+                    const probeOut = await runRg(probeArgs, { cwd: rgSpawnCwd, signal: options.signal });
                     if (String(probeOut).split('\n').some(Boolean)) {
                         body += ' (case-insensitive would match — try -i)';
                     }
@@ -781,7 +781,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                     let totalKnown = true;
                     let rgPartialSuffix = '';
                     if (effectiveHeadLimit !== Infinity) {
-                        const streamed = await runRgWindowedLines(fallbackArgs, { cwd: rgSpawnCwd }, {
+                        const streamed = await runRgWindowedLines(fallbackArgs, { cwd: rgSpawnCwd, signal: options.signal }, {
                             offset,
                             limit: effectiveHeadLimit,
                             summaryLimit: outputMode === 'content' ? 120 : 0,
@@ -798,7 +798,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                                 : '\n[warning] rg exit 2 (partial fixed-string fallback results)';
                         }
                     } else {
-                        const stdout = await runRg(fallbackArgs, { cwd: rgSpawnCwd });
+                        const stdout = await runRg(fallbackArgs, { cwd: rgSpawnCwd, signal: options.signal });
                         const allLines = String(stdout).split('\n').filter(Boolean);
                         windowed = offset > 0 ? allLines.slice(offset) : allLines;
                         totalWindowed = windowed.length;
@@ -1073,7 +1073,7 @@ export async function executeGlobTool(args, workDir, options = {}) {
             };
         }
         try {
-            const stdout = await runRg(rgArgs, { cwd: rgCwd, timeout: 10000 });
+            const stdout = await runRg(rgArgs, { cwd: rgCwd, timeout: 10000, signal: options.signal });
             const stdoutTruncated = Boolean(stdout && typeof stdout === 'object' && stdout.truncated);
             const stdoutPartial = Boolean(stdout && typeof stdout === 'object' && stdout.partial);
             const paths = [];

package/src/runtime/agent/orchestrator/tools/builtin/shell-job-paths.mjs

@@ -113,7 +113,7 @@ async function sweepStaleShellJobs(dir) {
     });
     await Promise.all([
         ...expired.flatMap((jobId) =>
-            ['.json', '.done', '.exit', '.enforced', '.exit.cmd.sh', '.exit.cmd.ps1', '.exit.user.ps1', '.stdout.log', '.stderr.log'].map((ext) =>
+            ['.json', '.done', '.exit', '.enforced', '.guardian', '.exit.cmd.sh', '.exit.cmd.ps1', '.exit.user.ps1', '.stdout.log', '.stderr.log'].map((ext) =>
                 fsPromises.unlink(join(dir, jobId + ext)).catch(() => {}),
             ),
         ),
@@ -212,6 +212,11 @@ export function shellJobDonePath(jobId) { return join(getShellJobsDir(), `${jobI
 // wrapper's own env/cwd resolution). PS jobs don't need it — their wrapper
 // enforces unconditionally and records detail.timeoutEnforced:true.
 export function shellJobEnforcedPath(jobId) { return join(getShellJobsDir(), `${jobId}.enforced`); }
+// Guardian kill receipt: written by the detached child-guardian immediately
+// before it force-kills the job tree (host memory floor / orphaned parent).
+// Its existence lets refreshShellJob attribute a marker-less death to the
+// guardian instead of reporting an unexplained unknown exit.
+export function shellJobGuardianReceiptPath(jobId) { return join(getShellJobsDir(), `${jobId}.guardian`); }
 // Owner sidecar marker: a zero-byte file whose NAME encodes the owning CC host
 // (claude.exe) pid — `<jobId>.owner-<pid>`. It lets the statusline owner-filter
 // jobs from a SINGLE directory listing (no per-job JSON read) so the filter can

package/src/runtime/agent/orchestrator/tools/builtin/shell-job-spawn.mjs

@@ -27,6 +27,7 @@ import {
     shellJobExitPath,
     shellJobDonePath,
     shellJobEnforcedPath,
+    shellJobGuardianReceiptPath,
     resolveJobOwnerHostPid,
     trimShellJobSpill,
     writeShellJobDetail,
@@ -71,7 +72,13 @@ globalThis.__mixdogShellJobsRuntimeLoaded = true;
 // Poll cadence for the adopted-job output-cap self-tick (mirrors the
 // foreground sizeWatchdog in shell-command.mjs).
 
-import { refreshShellJob, trackChildUntilConfirmedExit, releaseShellJobOwnershipWhenQuiescent, TIMER_MAX_MS } from './shell-jobs.mjs';
+import {
+    refreshShellJob,
+    trackChildUntilConfirmedExit,
+    releaseShellJobOwnershipWhenQuiescent,
+    reconcileShellJobAfterQuiescence,
+    TIMER_MAX_MS,
+} from './shell-jobs.mjs';
 
 export async function _startBackgroundShellJobImpl({
     command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellArgs,
@@ -261,6 +268,8 @@ export async function _startBackgroundShellJobImpl({
         childPid: child.pid,
         childGroupPid: child.pid,
         label: 'shell-job',
+        protectHostMemory: true,
+        receiptPath: shellJobGuardianReceiptPath(jobId),
     });
     _installShellJobsExitHook();
     _registerLiveJobPid(child.pid, jobId);
@@ -268,6 +277,10 @@ export async function _startBackgroundShellJobImpl({
     releaseShellJobOwnershipWhenQuiescent(jobId, child.pid, {
         allowLateLease: true,
         deferUntilRootExit: true,
+        // Exit-event ownership (CC-aligned): when the whole tree is gone but
+        // the wrapper never published markers, settle the job honestly instead
+        // of leaving a permanently-'running' or falsely-'failed' record.
+        onConfirmed: () => { try { reconcileShellJobAfterQuiescence(jobId); } catch { /* best-effort */ } },
     });
     // Deadline cleanup poke only when a timeout is enforced; an unlimited
     // (timeoutMs<=0) job has no deadline — completion is observed via the
@@ -503,6 +516,8 @@ async function startBackgroundPowerShellJob({
         childPid,
         childGroupPid: childPid,
         label: 'shell-job-powershell',
+        protectHostMemory: true,
+        receiptPath: shellJobGuardianReceiptPath(jobId),
     });
     _installShellJobsExitHook();
     _registerLiveJobPid(childPid, jobId);
@@ -510,6 +525,7 @@ async function startBackgroundPowerShellJob({
     releaseShellJobOwnershipWhenQuiescent(jobId, childPid, {
         allowLateLease: true,
         deferUntilRootExit: true,
+        onConfirmed: () => { try { reconcileShellJobAfterQuiescence(jobId); } catch { /* best-effort */ } },
     });
     if (Number(timeoutMs) > 0) {
         const timer = setTimeout(() => { refreshShellJob(jobId); }, Math.min(TIMER_MAX_MS, timeoutMs + 25));

package/src/runtime/agent/orchestrator/tools/builtin/shell-jobs.mjs

@@ -27,6 +27,7 @@ import {
     shellJobExitPath,
     shellJobDonePath,
     shellJobEnforcedPath,
+    shellJobGuardianReceiptPath,
     resolveJobOwnerHostPid,
     trimShellJobSpill,
     writeShellJobDetail,
@@ -134,6 +135,65 @@ export function killShellJob(jobId) {
     return { ...attachJobInsights(detail), killed: true };
 }
 
+// CC-aligned verdict for a job whose tracked root process died WITHOUT the
+// wrapper publishing the done marker. Evidence order:
+//   1. exit file — the wrapper writes exit BEFORE done, so a kill in that
+//      window still left the real exit code; recover it instead of guessing.
+//   2. guardian receipt — the child-guardian records why it force-killed the
+//      tree (host memory floor / orphaned parent) before killing.
+//   3. otherwise — honest unknown: terminal 'failed' with exitCode null and
+//      an explicit "exit status unknown" error; spilled output is preserved
+//      and the completion notification carries its tail.
+function finalizeMarkerlessShellJob(detail) {
+    const jobId = detail.jobId;
+    detail.finishedAt = new Date().toISOString();
+    let recoveredExit = null;
+    try {
+        const raw = readFileSync(shellJobExitPath(jobId), 'utf-8').trim();
+        const parsed = parseInt(raw, 10);
+        if (Number.isFinite(parsed)) recoveredExit = parsed;
+    } catch { /* no exit file */ }
+    if (recoveredExit !== null) {
+        detail.status = recoveredExit === 0 ? 'completed' : 'failed';
+        detail.exitCode = recoveredExit;
+        detail.note = 'done marker missing; exit code recovered from exit file';
+    } else {
+        let receipt = null;
+        try {
+            receipt = JSON.parse(readFileSync(shellJobGuardianReceiptPath(jobId), 'utf-8'));
+        } catch { /* no guardian receipt */ }
+        detail.status = 'failed';
+        detail.exitCode = 137;
+        if (receipt?.reason === 'host-memory-floor') {
+            const freeMb = Math.round(Number(receipt.freeBytes || 0) / (1024 * 1024));
+            const floorMb = Math.round(Number(receipt.minFreeMemoryBytes || 0) / (1024 * 1024));
+            detail.killedByGuardian = true;
+            detail.error = `killed by child guardian: host free memory ${freeMb} MB fell below the ${floorMb} MB floor — job tree force-killed to protect the host; retry with lower concurrency or after memory recovers`;
+        } else if (receipt?.reason === 'parent-exit') {
+            detail.killedByGuardian = true;
+            detail.error = 'killed by child guardian: owning runtime process exited (session cleanup)';
+        } else {
+            detail.exitCode = null;
+            detail.error = 'exit status unknown — tracked process exited without reporting an exit code; spilled output preserved (see stdout tail)';
+        }
+    }
+    trimShellJobSpill(detail);
+    writeShellJobDetail(detail);
+    releaseShellJobOwnershipWhenQuiescent(jobId, detail.pid);
+    return detail;
+}
+
+// Quiescence-deferred reconcile for the owning runtime: called when the
+// spawn-time process-tree tracker confirms the whole tree is gone. If the
+// wrapper never published markers (e.g. it was force-killed while detached
+// descendants kept running), settle the job honestly now.
+export function reconcileShellJobAfterQuiescence(jobId) {
+    const detail = readShellJobDetail(jobId);
+    if (!detail || detail.status !== 'running') return detail;
+    if (existsSync(shellJobDonePath(jobId))) return refreshShellJob(jobId);
+    return finalizeMarkerlessShellJob(detail);
+}
+
 export function refreshShellJob(jobId) {
     const detail = readShellJobDetail(jobId);
     if (!detail) return null;
@@ -207,11 +267,31 @@ export function refreshShellJob(jobId) {
         return detail;
     }
     if (detail.pid && !isPidAlive(detail.pid)) {
-        detail.status = 'failed';
-        detail.finishedAt = new Date().toISOString();
-        detail.error = 'process exited without completion marker';
-        writeShellJobDetail(detail);
-        releaseShellJobOwnershipWhenQuiescent(jobId, detail.pid);
+        // Root process died without markers. If this runtime owns a live
+        // process-tree tracker that still sees descendants (a killed wrapper
+        // whose real workload survived — observed with detached grandchildren),
+        // the JOB is still running: keep status 'running', flag the root exit,
+        // and let tree quiescence settle it via reconcileShellJobAfterQuiescence.
+        const trackerEntry = shellJobQuiescenceTrackers.get(jobId);
+        if (trackerEntry?.tracker?.pending) {
+            if (!detail.rootExitedAt) {
+                detail.rootExitedAt = new Date().toISOString();
+                detail.note = 'root process exited without an exit report; descendants still running — tracking tree to completion';
+                writeShellJobDetail(detail);
+                // Belt-and-braces for jobs without a spawn-time onConfirmed
+                // (adopted/legacy): settle once the tree is confirmed gone.
+                // Guarded by the rootExitedAt stamp so poll ticks cannot grow
+                // the callback set unboundedly.
+                trackerEntry.callbacks.add(() => reconcileShellJobAfterQuiescence(jobId));
+            }
+            // Root death is now observed: let the deferred tracker start
+            // confirming tree quiescence (idempotent past the first call).
+            trackerEntry.tracker.rootExited?.();
+            return detail;
+        }
+        // No live tracker (cross-process reader or tree already quiescent):
+        // settle now with the strongest available evidence.
+        return finalizeMarkerlessShellJob(detail);
     }
     return detail;
 }

package/src/runtime/agent/orchestrator/tools/builtin/snapshot-store.mjs

@@ -9,6 +9,16 @@ import { resolvePluginData } from '../../../../shared/plugin-paths.mjs';
 // worker A's read satisfy worker B's edit-gate across sessions via a persisted
 // __global__.json).
 const readFilesByScope = new Map(); // scope → Map(fullPath → { mtimeMs, size, ...meta })
+// Same-process, same-scope aliases established only after a successful
+// read-family ENOENT redirect. These are intentionally not persisted: an
+// apply_patch call may reuse a path correction proven by a read in the live
+// session, but must never inherit a guessed redirect from another process.
+const readRedirectsByScope = new Map(); // scope → Map(requestedPathKey → targetPath)
+
+function snapshotPathKey(fullPath) {
+    const value = String(fullPath || '');
+    return process.platform === 'win32' ? value.toLowerCase() : value;
+}
 
 // ── Disk-persisted snapshot store ────────────────────────────────────────
 // Mirror the in-memory readFilesByScope to per-scope JSON files under
@@ -160,6 +170,14 @@ export function deleteReadSnapshotPathEverywhere(fullPath) {
     for (const [scopeKey, readFiles] of readFilesByScope.entries()) {
         if (readFiles.delete(fullPath)) scheduleScopePersist(scopeKey);
     }
+    const deletedKey = snapshotPathKey(fullPath);
+    for (const redirects of readRedirectsByScope.values()) {
+        for (const [requestedKey, targetPath] of redirects.entries()) {
+            if (requestedKey === deletedKey || snapshotPathKey(targetPath) === deletedKey) {
+                redirects.delete(requestedKey);
+            }
+        }
+    }
     if (!SNAPSHOT_DIR) return;
     let entries;
     try { entries = readdirSync(SNAPSHOT_DIR); }
@@ -209,6 +227,40 @@ export function readScopeKey(scope) {
     return scope ? String(scope) : null;
 }
 
+export function recordReadPathRedirect(requestedFullPath, targetFullPath, scope) {
+    const scopeKey = readScopeKey(scope);
+    if (scopeKey === null) return false;
+    const requested = String(requestedFullPath || '');
+    const target = String(targetFullPath || '');
+    if (!requested || !target || snapshotPathKey(requested) === snapshotPathKey(target)) return false;
+    // The redirect is trusted only after the target produced a scoped read
+    // snapshot. A search/list-only redirect cannot authorize a later edit.
+    if (!readFilesForScope(scope).has(target)) return false;
+    let redirects = readRedirectsByScope.get(scopeKey);
+    if (!redirects) {
+        redirects = new Map();
+        readRedirectsByScope.set(scopeKey, redirects);
+    }
+    redirects.set(snapshotPathKey(requested), target);
+    return true;
+}
+
+export function resolveReadPathRedirect(requestedFullPath, scope) {
+    const scopeKey = readScopeKey(scope);
+    if (scopeKey === null) return null;
+    const redirects = readRedirectsByScope.get(scopeKey);
+    if (!redirects) return null;
+    const requestedKey = snapshotPathKey(requestedFullPath);
+    const target = redirects.get(requestedKey);
+    if (!target) return null;
+    // Fail closed if the proving snapshot was cleared after a mutation.
+    if (!readFilesForScope(scope).has(target)) {
+        redirects.delete(requestedKey);
+        return null;
+    }
+    return target;
+}
+
 export function readFilesForScope(scope) {
     const key = readScopeKey(scope);
     if (key === null) {