@sema-agent/core 5.41.0 → 5.43.0

package/dist/core/runner/prepare-task.js

@@ -56,7 +56,8 @@ import { prepareMemory } from "./prepare-memory.js";
 import { limitConfigError, prepareConfigDoors } from "./prepare-config-doors.js";
 import { NAMESPACED_NAME_SHAPES, prepareSafetyScan } from "./prepare-safety-scan.js";
 import { prepareAcquireReconcile } from "./prepare-acquire-reconcile.js";
-import { prepareWorkspaceRestore, rebaseWorkspacePath, remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./prepare-workspace-restore.js";
+import { prepareHandsMount, resolveHandsLessReadFace } from "./prepare-hands-readface.js";
+import { prepareWorkspaceRestore, remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./prepare-workspace-restore.js";
 import { defaultPromptProvider, buildEnvironmentContext, formatLocalDate, isValidTimeZone, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
 import { applyGitFrameGuard, probeGitStatusLane } from "./git-status-frame.js";
 import { assemblePrompt } from "../../prompt-assembly/assemble.js";
@@ -76,7 +77,7 @@ import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.j
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
 import { createMonitorTool } from "../../tools/monitor.js";
 import { createWorktreeTools } from "../../tools/worktree.js";
-import { applyCompactionToReadFileState, bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, isReadDedupStubResult, resolveReadDenyBuiltins, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
+import { applyCompactionToReadFileState, isReadDedupStubResult, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS } from "../../tools/fs/index.js";
 import { decodeTextBytes } from "../../tools/fs/encoding.js";
 import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTool, classifyQuestionOutcome, isLiveQuestionFace, validateAskQuestions, } from "../ask-question.js";
 import { createSchedulerTools } from "../../tools/scheduler-tools.js";
@@ -86,8 +87,7 @@ import { createRunWorkflowTool, RUN_WORKFLOW_TOOL_NAME } from "../../orchestrati
 import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
 import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
 import { resolveKey } from "../../tools/fs/safety.js";
-import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
-import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
+import { BINDING_CHECKPOINT_VERSION, mintCheckpointId, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { countElicitOptIns, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam } from "../wiring-manifest.js";
 import { durableParkGapFor } from "../park-selfcheck.js";
@@ -191,11 +191,7 @@ function announceToolModelGate(onNotice, modelId, gate) {
         }
     }
 }
-const readFaceClampAnnouncedSinks = new WeakSet();
-let readFaceClampConsoleAnnounced = false;
-export function __resetReadFaceClampAnnouncement() {
-    readFaceClampConsoleAnnounced = false;
-}
+export { __resetReadFaceClampAnnouncement } from "./prepare-hands-readface.js";
 const DEFAULT_MAX_SUSPENDS = 5;
 const ULTRA_REASONING_TIERS = new Set(["xhigh", "max"]);
 const DEFAULT_RESOURCE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
@@ -1036,14 +1032,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             resourceSpentMicroUsd: priorLedger?.spentMicroUsd ?? 0,
             suspendCount: priorSuspendCount,
         };
-        let readFileStateForCheckpoint;
-        let seedContextFiles;
-        let handsCwdRef;
-        let workspaceStateSettle;
-        let wsSnapshot;
-        let rebaseWsPath = (p) => p;
         let worktreeSessionRef;
-        let backgroundTaskToolsActive = false;
         let suspendForResource;
         let suspendForPlatformLimit;
         let suspendForReview;
@@ -1209,219 +1198,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         foldProtocolAxes(a2a.toolAxes, "A2A");
         const callIssuedAtRef = {};
         const memoryWriteGateRef = {};
-        const additionalRootsCanonical = [];
-        const additionalReadRootsCanonical = [];
-        let attachmentRootCanonical;
-        let readDenyMatcher;
-        if (handsEnabled) {
-            const rootRaw = taskRootFinal;
-            const canon = await executionEnv.canonicalPath(rootRaw);
-            const rootCanonical = canon.ok ? canon.value : rootRaw;
-            attachmentRootCanonical = rootCanonical;
-            const canonicalizeExtraDirs = async (dirs, field, sink) => {
-                for (const dir of dirs ?? []) {
-                    if (!dir || !dir.trim())
-                        continue;
-                    const c = await executionEnv.canonicalPath(dir);
-                    if (c.ok) {
-                        sink.push(c.value);
-                    }
-                    else {
-                        deps.onError?.(new Error(`${field} entry skipped (cannot canonicalize): ${dir}`), {
-                            phase: "config",
-                            sessionId,
-                        });
-                        emitTrace(deps.tracer, () => ({
-                            kind: "config.additional_directory_skipped",
-                            version: 1,
-                            taskId: hostTaskId,
-                            entry: dir,
-                            ...(field !== "additionalDirectories" ? { field } : {}),
-                            reason: `${c.error.code}: ${c.error.message}`,
-                            ts: Date.now(),
-                        }));
-                    }
-                }
-            };
-            await canonicalizeExtraDirs(spec.additionalDirectories, "additionalDirectories", additionalRootsCanonical);
-            await canonicalizeExtraDirs(spec.additionalReadDirectories, "additionalReadDirectories", additionalReadRootsCanonical);
-            if (spec.envFacts?.scratchpadDir) {
-                let c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
-                if (!c.ok && c.error.code === "not_found") {
-                    const marker = await executionEnv.joinPath([spec.envFacts.scratchpadDir, ".sema-scratchpad"]);
-                    const exclusiveCreate = executionEnv.writeFileExclusive?.bind(executionEnv);
-                    if (marker.ok && exclusiveCreate) {
-                        const w = await exclusiveCreate(marker.value, "");
-                        if (w.ok || w.error.code === "already_exists")
-                            c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
-                    }
-                }
-                if (c.ok)
-                    additionalRootsCanonical.push(c.value);
-            }
-            for (const a of [additionalRootsCanonical, additionalReadRootsCanonical])
-                a.splice(0, a.length, ...new Set(a));
-            const readFileState = new Map((resume?.seed.readFileState ?? []).map(([k, v]) => [rebaseRestoredPath(k), v]));
-            readFileStateForCheckpoint = readFileState;
-            seedContextFiles = async (files) => {
-                for (const f of files) {
-                    const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, resolvedReadFace);
-                    if (rk.ok)
-                        seedReadFileStateFromContext(readFileState, rk.key, f.content);
-                }
-            };
-            const handsIncludeShell = !(executionEnv instanceof StubExecutionEnv);
-            const handsReadOnly = spec.handsReadOnly === true;
-            backgroundTaskToolsActive = handsIncludeShell && !handsReadOnly && hasBackgroundShell(executionEnv);
-            wsSnapshot = resume !== undefined || !(handsIncludeShell && !handsReadOnly) ? undefined : await session.getWorkspaceState().catch(() => undefined);
-            rebaseWsPath = (p) => (wsSnapshot === undefined || wsSnapshot.taskRoot === rootCanonical ? p : rebaseWorkspacePath(p, wsSnapshot.taskRoot, rootCanonical));
-            if (handsIncludeShell && !handsReadOnly) {
-                handsCwdRef = { current: rootCanonical };
-                if (resume?.seed.handsCwd !== undefined)
-                    handsCwdRef.current = rebaseRestoredPath(resume.seed.handsCwd);
-                else if (wsSnapshot?.handsCwd !== undefined)
-                    handsCwdRef.current = rebaseWsPath(wsSnapshot.handsCwd);
-                workspaceStateSettle = {
-                    rootCanonical,
-                    restoredHandsCwd: handsCwdRef.current !== rootCanonical ? handsCwdRef.current : undefined,
-                    ...(resume !== undefined ? { baselineUnknown: true } : {}),
-                };
-            }
-            const seedReadFaceSection = resume?.seed.readFace;
-            const readDenyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seedReadFaceSection?.denyEntries ?? [])];
-            const readDenyBuiltinCfg = {
-                ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: [...deps.readDenyBuiltinTiers] } : {}),
-                ...(deps.readDenyBuiltinExclude !== undefined ? { exclude: [...deps.readDenyBuiltinExclude] } : {}),
-            };
-            readDenyMatcher = compileReadDeny(readDenyAdditions, "readDenyPatterns", readDenyBuiltinCfg);
-            readDenyAdditionsNormalized = compileReadDeny(readDenyAdditions, "readDenyPatterns", { tiers: [] }).entries;
-            let liveReadFace = resolveReadFace({
-                specReadFace: spec.readFace,
-                depsReadFace: deps.readFace,
-                readOnlyMount: handsReadOnly,
-                orgGoverned: deps.permissionRuleOrg !== undefined,
-                fullShellReachable,
-                onDeploymentClamp: () => {
-                    const sink = deps.onNotice;
-                    if (typeof sink === "function") {
-                        if (readFaceClampAnnouncedSinks.has(sink))
-                            return;
-                        readFaceClampAnnouncedSinks.add(sink);
-                    }
-                    else {
-                        if (readFaceClampConsoleAnnounced)
-                            return;
-                        readFaceClampConsoleAnnounced = true;
-                    }
-                    deliverEngineNotice(sink, deploymentReadFaceClampNotice());
-                },
-            });
-            if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
-                liveReadFace = "roots";
-            resolvedReadFace = liveReadFace;
-            if (resume === undefined && spec.sessionId !== undefined) {
-                const prior = await session.buildContext().catch(() => undefined);
-                for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
-                    const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
-                    if (rk.ok)
-                        seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
-                }
-            }
-            const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
-                ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
-                ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
-                ...(readDenyAdditions.length > 0 ? { readDenyPatterns: readDenyAdditions } : {}),
-                ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
-                ...(readDenyBuiltinCfg.exclude !== undefined ? { readDenyBuiltinExclude: readDenyBuiltinCfg.exclude } : {}),
-                readFace: liveReadFace,
-                includeShell: handsIncludeShell,
-                readOnly: handsReadOnly,
-                ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
-                taskRegistry: defaultTaskRegistry,
-                taskOwner: hostTaskId,
-                taskScope,
-                oneShot: spec.oneShot,
-                ...(sessionId !== undefined ? { sessionId } : {}),
-                ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
-                ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
-                ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
-                pdfModelCapabilities: pdfModelCapabilitiesOf(model),
-                ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
-                ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
-                ...(deps.hands?.readImageDownsampler !== undefined ? { readImageDownsampler: deps.hands.readImageDownsampler } : {}),
-                ...(deps.hands?.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: deps.hands.autoBackgroundOnTimeout } : {}),
-                ...(deps.hands?.readCyberReminder !== undefined ? { readCyberReminder: deps.hands.readCyberReminder } : {}),
-                beforeWrite: async (w) => {
-                    const deploymentGate = deps.hands?.beforeWrite;
-                    if (deploymentGate) {
-                        const verdict = await deploymentGate(w);
-                        if (verdict !== undefined && verdict.ok === false)
-                            return verdict;
-                    }
-                    return memoryWriteGateRef.current?.(w);
-                },
-                mountBackgroundTaskTools: false,
-                monitorToolActive: backgroundTaskToolsActive && !(toolFaceSnapshot.exclude?.includes("Monitor") ?? false),
-            });
-            {
-                const bandNames = new Set(band.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
-                const shadowed = (spec.tools ?? []).filter((t) => [t.name, ...(t.aliases ?? [])].some((n) => bandNames.has(n)));
-                if (shadowed.length > 0) {
-                    const names = shadowed.map((t) => `"${t.name}"`).join(", ");
-                    deps.onError?.(new Error(`spec.tools ${shadowed.length > 1 ? "entries" : "entry"} ${names} collide${shadowed.length > 1 ? "" : "s"} with the built-in hands tool band — the built-in wins (registered later; the harness tool Map is last-write-wins) and the caller tool never dispatches this task. Rename the caller tool, or don't inject executionEnv if you intend to replace the band.`), { phase: "config", sessionId });
-                }
-            }
-            tools.push(...band.map((t) => firstPartyOffload(t)));
-            const shellGate = effectiveShellGate;
-            if (shellGate === "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-                deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — no shell safety-axis ` +
-                    `fold applies to this run (commands are adjudicated by the ordinary policy/hook chain only). ` +
-                    `Set spec.shellGate to "classify" or "always" if this deployment expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
-            }
-            if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-                const bashTierBefore = irreversibilityTier.get("Bash");
-                shellGatedBash = !egressTools.has("Bash") && bashTierBefore !== "always" && bashTierBefore !== "maybe";
-                const bashEffectiveTier = shellGate === "always" || bashTierBefore === "always" ? "always" : "maybe";
-                irreversibilityTier.set("Bash", bashEffectiveTier);
-                irreversibleTools.add("Bash");
-                const shellReadBoundary = () => ({
-                    roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
-                    ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
-                    denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
-                    ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
-                });
-                if (shellGate === "classify" && shellGatedBash)
-                    reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
-                if (backgroundTaskToolsActive) {
-                    const monitorTierBefore = irreversibilityTier.get("Monitor");
-                    shellGatedMonitor = !egressTools.has("Monitor") && monitorTierBefore !== "always" && monitorTierBefore !== "maybe";
-                    const monitorEffectiveTier = shellGate === "always" || monitorTierBefore === "always" ? "always" : "maybe";
-                    irreversibilityTier.set("Monitor", monitorEffectiveTier);
-                    irreversibleTools.add("Monitor");
-                    if (shellGate === "classify" && shellGatedMonitor)
-                        reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
-                }
-            }
-        }
-        else {
-            const liveFace = resolveReadFace({
-                specReadFace: spec.readFace,
-                depsReadFace: deps.readFace,
-                readOnlyMount: spec.handsReadOnly === true,
-                orgGoverned: deps.permissionRuleOrg !== undefined,
-                fullShellReachable,
-            });
-            const seed = resume?.seed.readFace;
-            handsLessResolvedFace = resume !== undefined && (seed === undefined || seed.face === "roots") ? "roots" : liveFace;
-            const denyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seed?.denyEntries ?? [])];
-            resolveReadDenyBuiltins({
-                ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: deps.readDenyBuiltinTiers } : {}),
-                ...(deps.readDenyBuiltinExclude !== undefined ? { exclude: deps.readDenyBuiltinExclude } : {}),
-            });
-            if (denyAdditions.length > 0) {
-                readDenyAdditionsNormalized = compileReadDeny(denyAdditions, "readDenyPatterns", { tiers: [] }).entries;
-            }
-        }
+        const handsReadFaceInput = { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, tools, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes };
+        const handsReadFace = handsEnabled ? await prepareHandsMount(handsReadFaceInput) : resolveHandsLessReadFace(handsReadFaceInput);
+        const { readFileStateForCheckpoint, seedContextFiles, handsCwdRef, workspaceStateSettle, wsSnapshot, rebaseWsPath, backgroundTaskToolsActive, additionalRootsCanonical, additionalReadRootsCanonical, attachmentRootCanonical, readDenyMatcher } = handsReadFace;
+        resolvedReadFace = handsReadFace.resolvedReadFace;
+        readDenyAdditionsNormalized = handsReadFace.readDenyAdditionsNormalized;
+        handsLessResolvedFace = handsReadFace.handsLessResolvedFace;
+        shellGatedBash = handsReadFace.shellGatedBash;
+        shellGatedMonitor = handsReadFace.shellGatedMonitor;
         if (backgroundTaskToolsActive || workflowToolsActive) {
             toolEffects.set("TaskOutput", "read");
             toolEffects.set("TaskStop", "write");
@@ -3753,9 +3537,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     return { ok: false, reason };
                 }
             };
-            const publishCommittedSuspend = (token, gate, scope, remoteHandle) => {
+            const publishCommittedSuspend = (token, gate, scope, remoteHandle, checkpointId) => {
                 const ref = gate.kind === "needs_review" || gate.kind === "plan_review" ? reviewRef : suspendRef;
                 ref.token = token;
+                if (checkpointId !== undefined)
+                    ref.checkpointId = checkpointId;
                 ref.gate = gate;
                 if (remoteHandle !== undefined)
                     ref.restoreMode = remoteHandle.restoreMode === "park_only" ? "park_only" : "snapshot";
@@ -3821,6 +3607,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const mintedAt = Date.now();
                 const cp = {
                     token,
+                    checkpointId: mintCheckpointId(),
                     version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : resourceLedgerOut.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : RESOURCE_CHECKPOINT_VERSION,
                     scope,
                     sessionId,
@@ -3840,7 +3627,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 };
                 if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).ok)
                     return false;
-                publishCommittedSuspend(token, gate, scope, remoteHandle);
+                publishCommittedSuspend(token, gate, scope, remoteHandle, cp.checkpointId);
                 try {
                     await sessions.pin?.(sessionId);
                 }
@@ -3903,6 +3690,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     const mintedAt = Date.now();
                     const cp = {
                         token,
+                        checkpointId: mintCheckpointId(),
                         version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : reviewLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                         scope,
                         sessionId,
@@ -3925,7 +3713,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     };
                     if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).ok)
                         return false;
-                    publishCommittedSuspend(token, gate, scope, remoteHandle);
+                    publishCommittedSuspend(token, gate, scope, remoteHandle, cp.checkpointId);
                     try {
                         await sessions.pin?.(sessionId);
                     }
@@ -4164,6 +3952,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const mintedAt = Date.now();
                         cp = {
                             token,
+                            checkpointId: mintCheckpointId(),
                             version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : realApproval !== undefined ? REAL_APPROVAL_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : approvalLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                             scope,
                             sessionId,
@@ -4219,7 +4008,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     if (!committed.ok) {
                         return committed.reason !== undefined ? { parkFailed: committed.reason } : undefined;
                     }
-                    publishCommittedSuspend(token, gate, cp.scope, remoteHandle);
+                    publishCommittedSuspend(token, gate, cp.scope, remoteHandle, cp.checkpointId);
                     try {
                         await sessions.pin?.(sessionId);
                     }

package/dist/core/runner/runtask.js

@@ -1,6 +1,6 @@
 import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
 import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
-import { deliverDelegationLifecycle, deliverEngineNotice } from "../types.js";
+import { deliverDelegationLifecycle, deliverEngineNotice, undrainedUserInputNotices } from "../types.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
 import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, LEGACY_PENDING_STEER_INPUT_ID, MAX_STEER_INPUT_ID_CHARS, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
@@ -2069,12 +2069,9 @@ export class Runner {
                 this.pendingSessionNotifications.pend(notificationSessionId, p);
         };
         prepared.harness.onUndrainedUserInputs = (counts) => {
-            deliverEngineNotice(this.deps.onNotice, {
-                code: "task.user_steer_undrained",
-                message: `${counts.steer + counts.followUp} user input(s) accepted as "queued" were never consumed — the run ended first ` +
-                    `(${counts.steer} steer, ${counts.followUp} follow-up). They are NOT redelivered; re-send against a live run if still wanted.`,
-                detail: { steer: counts.steer, followUp: counts.followUp, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}) },
-            });
+            for (const notice of undrainedUserInputNotices(counts, spec.taskId)) {
+                deliverEngineNotice(this.deps.onNotice, notice);
+            }
         };
         prepared.harness.onEngineNoteConsumed = (p) => {
             const peer = p?.peer;
@@ -3475,6 +3472,7 @@ export class Runner {
                 suspendRef: prepared.suspendRef.token !== undefined && prepared.suspendRef.gate !== undefined
                     ? {
                         token: prepared.suspendRef.token,
+                        ...(prepared.suspendRef.checkpointId !== undefined ? { checkpointId: prepared.suspendRef.checkpointId } : {}),
                         gate: prepared.suspendRef.gate,
                         ...(prepared.suspendRef.restoreMode !== undefined ? { restoreMode: prepared.suspendRef.restoreMode } : {}),
                     }
@@ -3482,6 +3480,7 @@ export class Runner {
                 reviewRef: prepared.reviewRef.token !== undefined && prepared.reviewRef.gate !== undefined
                     ? {
                         token: prepared.reviewRef.token,
+                        ...(prepared.reviewRef.checkpointId !== undefined ? { checkpointId: prepared.reviewRef.checkpointId } : {}),
                         gate: prepared.reviewRef.gate,
                         ...(prepared.reviewRef.restoreMode !== undefined ? { restoreMode: prepared.reviewRef.restoreMode } : {}),
                     }

package/dist/core/types.d.ts

@@ -2881,6 +2881,10 @@ export interface TaskResult {
      * the resume capability, §6). Undefined for every other status.
      */
     checkpointToken?: import("./checkpoint-store.js").CheckpointToken;
+    /** The suspend's NON-SECRET stable identity ({@link import("./checkpoint-store.js").Checkpoint.checkpointId}),
+     *  set beside `checkpointToken` on the suspended/needs_review terminals — the display/correlation key a
+     *  consumer may log or render where the token must not travel. Absent on pre-identity checkpoints. */
+    checkpointId?: string;
     /** Set with `checkpointToken`: who/what must resume (e.g. `{kind:"human", reason, toolName}`), so the
      *  caller knows what decision the suspension is awaiting. */
     checkpointGate?: import("./checkpoint-store.js").CheckpointGate;
@@ -4669,12 +4673,15 @@ export interface EngineNotice {
      *    value IS in force the prepare refuses with the same code as `TaskResult.errorCode` (one
      *    fact, one code, two loudness dialects); `detail: { raw }`.
      *
-     *  - `"task.user_steer_undrained"` (#259) — user steers/follow-ups whose receipts said "queued"
-     *    were still in the queues at agent_end: the run ended before any turn could drain them. They
-     *    are NOT redelivered (a steer aimed at a finished run must not fire at the next one — unlike
-     *    ENGINE notes, which pend per session); the notice is the loud half of the #257 contract's
-     *    "accepted = enqueued, not consumed" sentence; `detail: { steer, followUp, taskId? }`.
-     *    Per-run, at most once (the terminal sweep is a single site).
+     *  - `"task.user_steer_undrained"` / `"task.user_followup_undrained"` (#259) — user steers /
+     *    follow-ups whose receipts said "queued" were still in their queue at agent_end: the run
+     *    ended before any turn could drain them. One notice PER family (a consumer routing on `code`
+     *    alone must not mistake a stranded follow-up for a stranded steer — same split as the settled
+     *    frame's two count keys). They are NOT redelivered (a steer aimed at a finished run must not
+     *    fire at the next one — unlike ENGINE notes, which pend per session); the loud half of the
+     *    #257 contract's "accepted = enqueued, not consumed" sentence;
+     *    `detail: { steer, taskId? }` / `{ followUp, taskId? }`. Per-run, at most once per family
+     *    (the terminal sweep is a single site).
      *
      *  Deliberately NOT a notice family: brain retry/reconnect liveness (a rate limit, a 5xx, a
      *  transient network failure being retried). Those are per-attempt liveness frames with their own
@@ -4709,6 +4716,16 @@ export declare function __resetMalformedNoticeSeatAnnouncement(): void;
  *  · an ABSENT seat prints the historic `console.warn` line verbatim (byte-compat loudness).
  */
 export declare function deliverEngineNotice(onNotice: ((notice: EngineNotice) => void) | undefined, notice: EngineNotice): void;
+/**
+ * #259 loud half, one notice PER FAMILY (`task.user_steer_undrained` / `task.user_followup_undrained`):
+ * a consumer routing on `code` alone must never mistake a stranded follow-up for a stranded steer, so
+ * the code carries exactly the semantics its name claims — the same two-key split the settled frame
+ * uses. Pure (the terminal sweep race window is not constructible deterministically; this seam is).
+ */
+export declare function undrainedUserInputNotices(counts: {
+    steer: number;
+    followUp: number;
+}, taskId?: string): EngineNotice[];
 /** Runtime dependencies shared across tasks. */
 export interface RunnerDeps {
     brain: Brain;

package/dist/core/types.js

@@ -49,3 +49,23 @@ export function deliverEngineNotice(onNotice, notice) {
     }
     console.warn(notice.message);
 }
+export function undrainedUserInputNotices(counts, taskId) {
+    const tid = taskId !== undefined ? { taskId } : {};
+    const tail = `accepted as "queued" were never consumed — the run ended first. They are NOT redelivered; re-send against a live run if still wanted.`;
+    const out = [];
+    if (counts.steer > 0) {
+        out.push({
+            code: "task.user_steer_undrained",
+            message: `${counts.steer} user steer(s) ${tail}`,
+            detail: { steer: counts.steer, ...tid },
+        });
+    }
+    if (counts.followUp > 0) {
+        out.push({
+            code: "task.user_followup_undrained",
+            message: `${counts.followUp} user follow-up(s) ${tail}`,
+            detail: { followUp: counts.followUp, ...tid },
+        });
+    }
+    return out;
+}

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -1,4 +1,5 @@
 import { type ExecResult, type ExecutionEnv, ExecutionError, type ExecutionEnvExecOptions, FileError, type FileInfo, type Result } from "../harness/types.js";
+import { type SecretEnvFinding } from "../../core/secret-env.js";
 import type { BackgroundShellCapability, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions } from "../../core/background-shell.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary } from "../../core/scheduler.js";
@@ -18,6 +19,8 @@ export declare function getShellConfig(customShellPath?: string): Promise<Result
     shell: string;
     args: string[];
 }, ExecutionError>>;
+/** test seam (mirrors the notice-seat announce reset): the once-per-process fallback latches. */
+export declare function __resetSecretScrubAnnouncement(): void;
 /** RB-235 ([1937] BB2): the spool-reclaim decision, extracted PURE so every rule is unit-pinnable.
  *  Both reclaim sites (foreground `reclaimSpool`, background `syncSpool`) route through this one
  *  function so they cannot drift apart.
@@ -83,6 +86,7 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     private readonly bgShells;
     private bgCounter;
     private readonly retainBackgroundProcesses;
+    private readonly onSecretEnvScrub?;
     /** design/128 T1-1: lazily-created env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). */
     private bgSpoolDir?;
     readonly backgroundCapabilities: BackgroundShellCapability["backgroundCapabilities"];
@@ -108,6 +112,10 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
          * deployments (their pre-suspend dispose becomes a no-op too — do not combine).
          */
         retainBackgroundProcesses?: boolean;
+        /** The D1 scrub decision's observation seat: called with every NON-EMPTY finding set the default
+         *  "scrub" leg withholds from a shell child. Absent ⇒ a once-per-process console summary (loud
+         *  enough to notice, quiet enough not to spam). Never called on the "all"/allowlist legs. */
+        onSecretEnvScrub?: (findings: readonly SecretEnvFinding[]) => void;
     });
     get schedulerCapabilities(): SchedulerCapability["schedulerCapabilities"];
     schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{

package/dist/engine/execution-env/node-execution-env.js

@@ -188,7 +188,13 @@ export async function getShellConfig(customShellPath) {
     return ok({ shell: "sh", args: ["-c"] });
 }
 const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
-function getShellEnv(inheritEnv, baseEnv, extraEnv) {
+let secretScrubConsoleAnnounced = false;
+let secretScrubSeatDefectAnnounced = false;
+export function __resetSecretScrubAnnouncement() {
+    secretScrubConsoleAnnounced = false;
+    secretScrubSeatDefectAnnounced = false;
+}
+function getShellEnv(inheritEnv, baseEnv, extraEnv, onScrub) {
     let inherited;
     if (inheritEnv === "all") {
         inherited = process.env;
@@ -200,7 +206,36 @@ function getShellEnv(inheritEnv, baseEnv, extraEnv) {
                 inherited[k] = process.env[k];
     }
     else {
-        inherited = scrubSecretEnv(process.env);
+        const scrubbed = [];
+        inherited = scrubSecretEnv(process.env, scrubbed);
+        const findings = scrubbed.filter((f) => baseEnv?.[f.key] === undefined && extraEnv?.[f.key] === undefined);
+        if (findings.length > 0) {
+            if (typeof onScrub === "function") {
+                try {
+                    const r = onScrub(findings);
+                    if (typeof r?.then === "function") {
+                        r.then(undefined, () => {
+                        });
+                    }
+                }
+                catch {
+                }
+            }
+            else {
+                if (onScrub !== undefined && !secretScrubSeatDefectAnnounced) {
+                    secretScrubSeatDefectAnnounced = true;
+                    try {
+                        console.warn(`onSecretEnvScrub seat holds ${onScrub === null ? "null" : typeof onScrub} — not a function; scrub findings fall back to the console summary (once per process)`);
+                    }
+                    catch {
+                    }
+                }
+                if (!secretScrubConsoleAnnounced) {
+                    secretScrubConsoleAnnounced = true;
+                    console.warn(`secret_env_scrubbed: ${findings.length} env key(s) withheld from the shell child (${findings.map((f) => f.key).join(", ")}) — once per process; wire onSecretEnvScrub for per-exec telemetry`);
+                }
+            }
+        }
     }
     return {
         ...inherited,
@@ -254,6 +289,7 @@ export class NodeExecutionEnv {
     bgShells = new Map();
     bgCounter = 0;
     retainBackgroundProcesses;
+    onSecretEnvScrub;
     bgSpoolDir;
     backgroundCapabilities;
     constructor(options) {
@@ -263,6 +299,7 @@ export class NodeExecutionEnv {
         this.inheritEnv = options.inheritEnv ?? "scrub";
         this.scheduler = options.scheduler;
         this.retainBackgroundProcesses = options.retainBackgroundProcesses ?? false;
+        this.onSecretEnvScrub = options.onSecretEnvScrub;
         this.backgroundCapabilities = {
             supported: true,
             maxConcurrent: 8,
@@ -420,7 +457,7 @@ export class NodeExecutionEnv {
                 child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
                     cwd,
                     detached: process.platform !== "win32",
-                    env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env),
+                    env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub),
                     stdio: execSpoolFds ? ["ignore", execSpoolFds[0], execSpoolFds[1]] : ["ignore", "pipe", "pipe"],
                     windowsHide: true,
                 });
@@ -1114,7 +1151,7 @@ export class NodeExecutionEnv {
             child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
                 cwd: options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd,
                 detached: process.platform !== "win32",
-                env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env),
+                env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub),
                 stdio: spoolFds ? ["ignore", spoolFds[0], spoolFds[1]] : ["ignore", "pipe", "pipe"],
                 windowsHide: true,
             });

package/dist/index.d.ts

@@ -93,7 +93,7 @@ export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY
 export { deploymentReadFaceClampNotice, resolveReadFace, type ReadFace, type ReadFaceInputs } from "./tools/fs/index.js";
 export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, type WriteProtectedEntry, type WriteProtectedRow, type WriteProtectedKind, type WriteProtectedHit, type WriteProtectionMatcher, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
-export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type ProbeCause, type ProbeCauseOperands, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
+export { InMemoryCheckpointStore, CheckpointError, mintCheckpointId, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type ProbeCause, type ProbeCauseOperands, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";

package/dist/index.js

@@ -73,7 +73,7 @@ export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY
 export { deploymentReadFaceClampNotice, resolveReadFace } from "./tools/fs/index.js";
 export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } from "./core/tool-result-store.js";
-export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
+export { InMemoryCheckpointStore, CheckpointError, mintCheckpointId, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";

package/dist/tools/fs/fs-search-tools.d.ts

@@ -2,6 +2,14 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import type { ToolEffect } from "../../core/types.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
 import type { ReadFace } from "./read-face.js";
+/**
+ * The Grep card's details assembly, PURE over the engine text ({mode, offset} from the request) —
+ * exported so the text→structured mapping is pinnable with synthetic texts (the byte-truncation and
+ * fenced-partial shapes are impractical to construct through a live tool call). Follow-up #313 will
+ * replace the text parsing with structured rows from runGrep; until then this seam is the honesty
+ * boundary.
+ */
+export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number, structuredRows?: readonly import("./search.js").GrepRow[]): Record<string, unknown>;
 export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;
 export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;
 /** Static side-effect class of every hand tool, by name (design/44 §3). Used by prepare-task to (a) feed