@sema-agent/core 7.49.5 → 7.50.1

package/dist/core/runner/policy-throw.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A tool policy that THREW — the one form its failure takes on each of the two surfaces it reaches, for every seat that
+ * consults a policy chain (the gate's target reading, the adjudicate seat, the inherited-constraint station, the two
+ * re-checks of an approved edit).
+ *
+ * The MODEL reads one line of the thrown value inside the seat's deny: secret-shaped runs redacted, then folded to one line
+ * and capped (`inlineUntrusted`, which also neutralizes a reminder fence), so a policy's error text never carries a
+ * credential, a multi-kilobyte body or a forged frame into the conversation. The DEPLOYMENT hears the failure once, on the
+ * seat's hook-failure lane (`onError`, phase `hook`): an error whose message names the seat and the call and carries the
+ * class and the redacted text — and no `cause`, because a host's serializer walks a cause chain and the raw value would
+ * carry the unredacted text there.
+ */
+import type { PermissionResult } from "../tool-policy.js";
+/** The model's line of a thrown policy value: redacted BEFORE the cap (a cut must never leave half a token unredacted),
+ *  one line, at most {@link PROBE_REASON_MAX} code points; never empty. */
+export declare function policyThrowLine(err: unknown): string;
+/** The deny of a judgment whose wait the task's signal ended — a timeout or a cancellation, nothing the policy said. */
+export declare function policyCheckAbortedDeny(): PermissionResult;
+/** The deny of a judgment that FAILED (threw or rejected) while `signal` bounded its wait: the aborted deny when the signal had
+ *  already ended the wait (a cancellation — not reported), else the policy's own throw — its sentence and one line of what it
+ *  threw — reported once through {@link reportPolicyThrow}. A seat that raced the judgment against its signal has told the two
+ *  apart already and passes no signal. */
+export declare function failedJudgmentDeny(err: unknown, signal: AbortSignal | undefined, report: (err: Error) => void, seat: string, call: {
+    readonly toolName: string;
+    readonly toolCallId: string;
+}): PermissionResult;
+/** Hand the deployment, through `report` (the seat's hook-failure lane), the failure of the policy that threw while `seat`
+ *  judged `call`. A rejection that arrives with the judgment's `signal` already aborted is the task ending mid-judgment — a
+ *  cancellation, not a policy defect — and is not reported (the deny it produced stands either way). A report lane that
+ *  throws is swallowed: the fail-closed deny is decided before the report and must not depend on the sink. */
+export declare function reportPolicyThrow(report: (err: Error) => void, seat: string, call: {
+    readonly toolName: string;
+    readonly toolCallId: string;
+}, err: unknown, signal?: AbortSignal): void;

package/dist/core/runner/policy-throw.js

@@ -0,0 +1,25 @@
+import { thrownLabel, thrownText } from "../thrown-value.js";
+import { redactSecrets } from "../untrusted-egress.js";
+import { inlineUntrusted, PROBE_REASON_MAX } from "../untrusted-text.js";
+export function policyThrowLine(err) {
+    const line = inlineUntrusted(redactSecrets(thrownText(err)), PROBE_REASON_MAX);
+    return line === "" ? "(no message)" : line;
+}
+export function policyCheckAbortedDeny() {
+    return { action: "deny", message: "policy check aborted (task timed out or cancelled)" };
+}
+export function failedJudgmentDeny(err, signal, report, seat, call) {
+    if (signal?.aborted === true)
+        return policyCheckAbortedDeny();
+    reportPolicyThrow(report, seat, call, err);
+    return { action: "deny", message: `policy check threw — the tool policy chain failed while judging this call (not a timeout or cancellation), so it was denied fail-closed: ${policyThrowLine(err)}` };
+}
+export function reportPolicyThrow(report, seat, call, err, signal) {
+    if (signal?.aborted === true)
+        return;
+    try {
+        report(new Error(`${seat} threw while judging "${call.toolName}" (toolCallId ${call.toolCallId}); the call was denied fail-closed: ${redactSecrets(thrownLabel(err))}`));
+    }
+    catch {
+    }
+}

package/dist/core/runner/prepare-acquire-reconcile.js

@@ -1,4 +1,6 @@
 import { StoredSession, isSessionConflict } from "../session.js";
+import { userAttachmentOf } from "../../internal/llm.js";
+import { lastAttachmentFrameOf } from "../user-attachment.js";
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { detectConflicts, settleBranchWriteBack } from "./branch-writeback.js";
 import { settleTeardownLeg } from "./teardown-bounded.js";
@@ -57,6 +59,11 @@ export async function prepareAcquireReconcile(input) {
                         e.code = "resume_at.not_a_message";
                         throw e;
                     }
+                    if (userAttachmentOf(msg) !== undefined) {
+                        const e = new Error(`resumeAt entry "${spec.resumeAt}" is an attachment frame that trails a user message; resume at that user message instead`);
+                        e.code = "resume_at.not_a_message";
+                        throw e;
+                    }
                 }
                 if (spec.resumeAtMode === "before") {
                     const role = entry.type === "message" ? entry.message.role : undefined;
@@ -84,7 +91,7 @@ export async function prepareAcquireReconcile(input) {
                         throw e;
                     }
                 }
-                const storage = session.getStorage(), leafBefore = await storage.getLeafId(), leafSet = spec.resumeAtMode === "before" ? entry.parentId : spec.resumeAt;
+                const storage = session.getStorage(), leafBefore = await storage.getLeafId(), leafSet = spec.resumeAtMode === "before" ? entry.parentId : entry.type === "message" && entry.message.role === "user" ? lastAttachmentFrameOf(await session.getEntries(), spec.resumeAt) : spec.resumeAt;
                 await storage.setLeafId(leafSet);
                 own.ids = new Set();
                 branch = { storage, leafBefore, leafSet, own };

package/dist/core/runner/prepare-artifact.d.ts

@@ -20,7 +20,8 @@ import { RosterBuilder } from "../tool-roster.js";
 import type { AgentTool, RunnerDeps } from "../types.js";
 import type { ContainmentFace } from "../../tools/fs/index.js";
 import type { PlacedReadDenyMatcher } from "../../tools/fs/read-deny-home.js";
-import { type ArtifactStoreRef } from "./read-root-grant.js";
+import type { ArtifactStoreRef } from "./read-root-grant.js";
+import type { ReadRootsSeat } from "./person-path-rows.js";
 import type { Prepared } from "./contracts.js";
 import type { ToolOccurrenceTable } from "./tool-occurrence.js";
 export interface PrepareArtifactInput {
@@ -48,8 +49,9 @@ export interface PrepareArtifactInput {
     /** borrowed-readonly — the canonical task root the fs fence contains reads to; undefined ⇒ no local-file publish. */
     rootCanonical: string | undefined;
     /** borrowed-readonly — the extra containment roots (write and read-only) the fence admits, read per call (the run's
-     *  live set: an in-flight read-root grant widens it). */
-    additionalRootsCanonical: () => readonly string[];
+     *  live set: an in-flight read-root grant widens it); `ready` settles once the run's newest tables are compiled — this
+     *  reader is no call, and reads them only then. */
+    additionalRootsCanonical: (() => readonly string[]) & Pick<ReadRootsSeat, "ready">;
     /** borrowed-readonly — the read-deny matcher in force for the run, when any. */
     readDenyMatcher: PlacedReadDenyMatcher | undefined;
     /** borrowed-readonly — the resolved read face (`"open"` lifts root containment for reads). */

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

@@ -5,9 +5,7 @@ import { RosterBuilder } from "../tool-roster.js";
 import { defineTool } from "../tools.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { physicalPathOfExisting } from "../physical-path.js";
-import { resolveKey, violationDetails, violationText } from "../../tools/fs/safety.js";
-import { rootAdmittingArtifactStore, withdrawStandingGrantsAdmitting } from "./read-root-grant.js";
-import { emitTrace } from "../trace.js";
+import { resolveKey, rootAdmittingArtifactStore, violationDetails, violationText } from "../../tools/fs/safety.js";
 import { createArtifactTool } from "../../tools/artifact/artifact-tool.js";
 import { thrownText } from "../thrown-value.js";
 export function prepareArtifact(input) {
@@ -30,11 +28,6 @@ export function prepareArtifact(input) {
     const storePhysical = storageDir !== undefined && rootCanonical !== undefined ? physicalPathOfExisting(storageDir) : undefined;
     if (artifactStoreRef !== undefined)
         artifactStoreRef.current = storePhysical;
-    if (artifactStoreRef !== undefined && storePhysical !== undefined) {
-        for (const entry of withdrawStandingGrantsAdmitting(storePhysical, artifactStoreRef)) {
-            emitTrace(deps.tracer, () => ({ kind: "config.additional_directory_skipped", version: 1, taskId, entry, field: "persistedReadRule", reason: `admits_artifact_store: the local artifact store ${storageDir} lies inside it or it inside the store — the Artifact tool's ledger and stored files stay outside every root the file tools reach`, ts: Date.now() }));
-        }
-    }
     if (storePhysical !== undefined && rootCanonical !== undefined) {
         const overlapping = rootAdmittingArtifactStore(storePhysical, [rootCanonical, ...additionalRootsCanonical()]);
         if (overlapping !== undefined)
@@ -49,6 +42,7 @@ export function prepareArtifact(input) {
     const readLocalFile = async (path, maxBytes, signal) => {
         if (rootCanonical === undefined)
             return { ok: false, reason: "refused", text: "Error (Artifact): this task has no filesystem root, so a local file cannot be published." };
+        await additionalRootsCanonical.ready(signal);
         const rk = await resolveKey(executionEnv, rootCanonical, path, signal, handsCwdRef?.current, additionalRootsCanonical, undefined, readDenyMatcher, resolvedReadFace);
         if (!rk.ok)
             return { ok: false, reason: "refused", text: violationText("Artifact", rk.violation), details: violationDetails(rk.violation) };

package/dist/core/runner/prepare-ask-lane.d.ts

@@ -93,7 +93,8 @@ export interface PrepareAskLaneInput {
     hooks: Hooks | undefined;
     /** borrowed-readonly — the validated per-prepare hook seat bound (the deny observer's timeout). */
     hookTimeoutMs: number;
-    /** borrowed-readonly — the own hook-crash reporter (the deny observer's swallow-guarded report sink). */
+    /** borrowed-readonly — the own hook-failure lane (`onError`, phase `hook`, swallow-guarded): the deny observer's report sink,
+     *  the gate's crashing-PreToolUse sink and the adjudicate seat's report of a policy chain that threw. */
     notifyOwnHookCrash: (err: unknown) => void;
     /** borrowed-readonly — the hands phase's in-flight read-root widening (an approver's accepted `readRootGrant`), or undefined (hands-less). */
     grantReadRoot: GrantReadRoot | undefined;

package/dist/core/runner/prepare-ask-lane.js

@@ -3,13 +3,13 @@ import { primaryActivityArg } from "../arg-summary.js";
 import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
 import { advertisedWritableRootsSeat, exemptRootsSeat, attest, attestationOf, isLiveApproverSeat, resolveAsk } from "../tool-policy.js";
 import { boundInputHashOf } from "../canonical-json.js";
-import { composeCallSignal, raceAbort } from "./abort-race.js";
+import { composeCallSignal, raceSettlementAgainstSignal } from "./abort-race.js";
+import { failedJudgmentDeny, policyCheckAbortedDeny } from "./policy-throw.js";
 import { askMandateMember } from "../ask-origin.js";
 import { approvalCardMemberOf } from "../tool-roster.js";
 import { gateAskCarry, lateAskSettlementObserver } from "./denial-limit-arms.js";
 import { consumeInheritedAskGrant } from "./inherited-ask-grants.js";
 import { settleReadRootGrant } from "./read-root-grant.js";
-import { asThrownError } from "../thrown-value.js";
 function createDenyObserverNotifier(hooks, hookTimeoutMs, signal, report) {
     if (hooks?.permissionDenied === undefined)
         return undefined;
@@ -66,14 +66,19 @@ export function prepareAskLane(input) {
         return { askLane: undefined };
     const composedCallSignal = (callSignal) => composeCallSignal(abortController.signal, callSignal);
     const adjudicate = effectivePolicy
-        ? (req, callSignal) => {
+        ? async (req, callSignal) => {
             const signal = composedCallSignal(callSignal);
             const stampedReq = () => ({ ...req, budget: budgetSnapshot, ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}), ...(handsRoot !== undefined ? { root: handsRoot } : {}), ...advertisedWritableRootsSeat(advertisedWritableDirs), ...exemptRootsSeat(exemptRoots) });
-            const withReading = stampCallTarget?.(stampedReq(), signal);
-            return raceAbort(withReading === undefined ? Promise.resolve(effectivePolicy.check(stampedReq(), signal)) : withReading.then((r) => effectivePolicy.check(r, signal)), signal, () => ({
-                action: "deny",
-                message: "policy check aborted (task timed out or cancelled)",
-            }));
+            const judged = (async () => {
+                const withReading = stampCallTarget?.(stampedReq(), signal);
+                return withReading === undefined ? effectivePolicy.check(stampedReq(), signal) : effectivePolicy.check(await withReading, signal);
+            })();
+            const raced = await raceSettlementAgainstSignal(judged, signal);
+            if (raced.tag === "value")
+                return raced.value;
+            if (raced.tag === "aborted")
+                return policyCheckAbortedDeny();
+            return failedJudgmentDeny(raced.error, undefined, notifyOwnHookCrash, "the tool policy chain", req);
         }
         : undefined;
     const approvalPreviewOf = (toolName, args) => resolveApprovalPreview(tools, toolName, args);
@@ -138,12 +143,5 @@ export function prepareAskLane(input) {
         return resolved;
     };
     const notifyPermissionDenied = createDenyObserverNotifier(hooks, hookTimeoutMs, abortController.signal, notifyOwnHookCrash);
-    const notifyHookError = (err) => {
-        try {
-            deps.onError?.(asThrownError(err), { phase: "hook", sessionId });
-        }
-        catch {
-        }
-    };
-    return { askLane: { composedCallSignal, adjudicate, approvalPreviewOf, resolveAskBound, notifyPermissionDenied, notifyHookError } };
+    return { askLane: { composedCallSignal, adjudicate, approvalPreviewOf, resolveAskBound, notifyPermissionDenied, notifyHookError: notifyOwnHookCrash } };
 }

package/dist/core/runner/prepare-caps-and-workflow.d.ts

@@ -114,8 +114,9 @@ export interface PrepareCapsAndWorkflowInput {
      *  arming facts (the deny bits, the face, the re-entrant arm) are bound onto it here. */
     permissionMode: PermissionModeController;
     /** borrowed-readonly — LATE-BOUND: the effective read-deny table the hands phase compiles (the rows the classifier's deny
-     *  paragraph renders); read at ARMING, which the driver runs after that phase — never at this phase's own call. */
-    readDenyEntries: () => {
+     *  paragraph renders); read at ARMING, which the driver runs after that phase — never at this phase's own call — once the
+     *  run's newest tables are compiled (an arming is no call). */
+    readDenyEntries: () => Promise<{
         readonly entries: ReadonlyArray<{
             readonly pattern: string;
             readonly caseSensitive?: boolean;
@@ -124,7 +125,7 @@ export interface PrepareCapsAndWorkflowInput {
             readonly tool: string;
             readonly pattern: string;
         }>;
-    };
+    }>;
     /** borrowed-readonly — the peer lane's mount verdict (the classifier's cross-session rule fills only while mounted). */
     peerLaneActive: boolean;
     /** borrowed-readonly — the leg's effective delegation fact (`effectiveDelegationFacts`): the classifier window shows its user lane as the launching agent's. */

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -226,7 +226,7 @@ export async function prepareCapsAndWorkflow(input) {
         }
         announceClassifierRoleDefaulted({ onNotice: deps.onNotice, seat: { ...classifierSeat, model: classifierModel }, ...(sessionId !== undefined ? { sessionId } : {}), ...(runId !== undefined ? { runId } : {}) });
         const classifierLaneRule = peerLaneActive && peerSendMessageBuiltIn;
-        const table = readDenyEntries();
+        const table = await readDenyEntries();
         const derivedDenyRules = readDenyClassifierRules(table.entries, table.ruleRows);
         let classifierSystemPromptMemo;
         const classifierSystemPrompt = () => (classifierSystemPromptMemo ??= buildAutoModePrompt({ ...am, derivedDenyRules, ...(classifierLaneRule ? { crossSessionMessagesRule: CROSS_SESSION_CLASSIFIER_RULE } : {}) }));

package/dist/core/runner/prepare-context-lane.js

@@ -2,7 +2,7 @@ import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens } from "../../internal/h
 import { TOOL_TURN_REPAIR_DROPS } from "../../internal/llm.js";
 import { clearStaleToolResults, createClearedProjectionLedger, dropEmptyFailureAssistants, editBudget, replayClearedProjection, resolveTriggerWindow } from "../context-edit.js";
 import { guardBudget, insertTrimNotice, protectGitFrame, trimToBudget } from "../context-guard.js";
-import { AGGREGATE_MEDIA_BUDGET_BYTES, capAggregateMediaBytes } from "../media-byte-cap.js";
+import { capAggregateMediaBytes, mediaBudgetBytes } from "../media-byte-cap.js";
 import { capAggregateToolResults } from "../tool-result-budget.js";
 import { createOffloadPersist } from "../tool-result-store.js";
 import { emitTrace } from "../trace.js";
@@ -50,7 +50,7 @@ export function prepareContextLane(input) {
                 }))),
             });
             const mediaCapped = capAggregateMediaBytes(capped, {
-                limitBytes: deps.mediaByteCapBytes ?? AGGREGATE_MEDIA_BUDGET_BYTES,
+                limitBytes: mediaBudgetBytes(deps.mediaByteCapBytes),
                 onStripped: (info) => {
                     const onMediaStripped = deps.onMediaStripped;
                     if (onMediaStripped !== undefined)

package/dist/core/runner/prepare-gate-stations.d.ts

@@ -155,9 +155,9 @@ export interface PrepareGateStationsInput {
     handsCwdRef: CwdRef | undefined;
     /** borrowed-readonly — the leg's target-reading stamp, or undefined (hands-less): the gate stamps its request with it. */
     stampCallTarget: CallTargetStamp | undefined;
-    /** borrowed-readonly — the leg's read-deny table in force, read at a release: the active built-in tiers and the rows
-     *  beside them (the deployment's and the task's patterns, the read-face rule rows). Empty ⇒ no table. */
-    readDenyInForce: () => {
+    /** borrowed-readonly — the read-deny table the released call was judged with, read at its release: the active built-in
+     *  tiers and the rows beside them (the deployment's and the task's patterns, the read-face rule rows). Empty ⇒ no table. */
+    readDenyInForce: (toolCallId: string) => {
         readonly tiers: readonly string[];
         readonly rows: readonly string[];
     };

package/dist/core/runner/prepare-gate-stations.js

@@ -50,7 +50,7 @@ export function prepareGateStations(input) {
     const gatePreToolUse = ownGatePreToolUse !== undefined ? (name, args, ctx) => ownGatePreToolUse(name, args, { ...ctx, permissionMode: permissionMode.observed }) : undefined;
     const releasesAnnounced = new Map();
     const onModeReleased = (info) => {
-        const table = info.readUnestablished === true ? input.readDenyInForce() : undefined;
+        const table = info.readUnestablished === true ? input.readDenyInForce(info.toolCallId) : undefined;
         if (table !== undefined && table.tiers.length + table.rows.length > 0) {
             const named = [...(table.tiers.length > 0 ? [`built-in tiers ${table.tiers.join(", ")}`] : []), ...table.rows.slice(0, 8), ...(table.rows.length > 8 ? [`${table.rows.length - 8} more`] : [])].join("; ");
             deliverEngineNotice(deps.onNotice, {

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -1,6 +1,6 @@
 import { type BeforeWriteHook, type CwdRef, type PathRuleDenyRow, type ContainmentFace } from "../../tools/fs/index.js";
 import { type ReadFileState } from "../../tools/fs/safety.js";
-import { type PlacedReadDenyMatcher } from "../../tools/fs/read-deny-home.js";
+import { type PathTablesFacade, type PersonPathRows, type ReadRootsSeat } from "./person-path-rows.js";
 import type { HeadLeads } from "../path-rule-binding.js";
 import { type ShellReadAdmission, type ShellReadCheck } from "../../tools/fs/shell-read-check.js";
 import type { ShellReadBoundary } from "../../tools/fs/shell-read-judge.js";
@@ -56,19 +56,17 @@ export interface PrepareHandsReadFaceInput {
     /** borrowed-readonly — the registry scope (`internals?.registryScope ?? spec.principal ??
      *  "default"`, computed in the driver); the band's task-registry scope. */
     taskScope: string;
-    /** borrowed-readonly — the deny tables' permission-rule rows: the face-keyed path deny rules of the leg's caller policy and
-     *  of every ancestor's, each bound where it was installed (`toolPolicyPathRules`), and the person's deny rows; joined to the
-     *  read face's matcher and to the shell station's write face. */
+    /** borrowed-readonly — the leg's own deny-table rows: the face-keyed path deny rules of the leg's caller policy and of every
+     *  ancestor's, each bound where it was installed (`toolPolicyPathRules`); the person's join them per read ({@link personRows}). */
     denyRuleRows: readonly PathRuleDenyRow[];
+    /** borrowed-readonly — the run's one reader of the person's rules: the run's tables are compiled here over it. */
+    personRows: PersonPathRows;
     /** borrowed-readonly — the leg's one resolution of where rule heads lead (the rows' twins, the same the gate's lanes read). */
     headLeads: HeadLeads;
     /** borrowed-readonly — the ONE judgment a shell command's write targets meet for the mode's file-command placement: the
      *  leg's write judgment over the write-protection table and the chain's guarded write rows (read per judgment — it is
      *  compiled at the manifest phase, before any gate is mounted). Absent ⇒ none (a standalone phase drive). */
     writeTargetJudge?: () => ShellReadBoundary["writeTargetJudge"];
-    /** borrowed-readonly — the directories of the person's persisted `Read(//dir/**)` allow rows: read directories of this
-     *  run, canonicalized and admitted exactly as `additionalReadDirectories` entries are. */
-    persistedReadDirectories?: readonly string[];
     /** borrowed-readonly — the leg's mode seat, read LIVE by the write face ({@link writeFaceReader}): its mode's face
      *  is the resolver's row 3′ on every write. */
     permissionMode: {
@@ -160,6 +158,11 @@ export interface PrepareHandsReadFaceInput {
      *  band's Read/notebook/PDF trailer outlets bump keys on it at tool-execute time (the driver owns
      *  the object and folds it into result stats). */
     reminderDisclosureCounts: import("../reminder-disclosure.js").ReminderDisclosureCounts;
+    /** borrowed-mutable — where the band hands out the leg's one file reader (the Read tool's), for the leg's other
+     *  carriers of a file (attachment frames): written once at mount, left empty when hands do not mount. */
+    modelFileReaderSeat?: {
+        current?: import("../../tools/fs/fs-read.js").ModelFileReader;
+    };
     /** borrowed-readonly — the first-touch history hook prepare built (present iff the run records file history into a
      *  wired store and mounts a real fs env); threaded to the write band's trackFileEdit seat. */
     trackFileEdit?: import("../types.js").TrackFileEditHook;
@@ -218,6 +221,8 @@ export interface PrepareHandsReadFaceResult {
     /** owned — the same station's pre-spawn ADMISSION, published for the P11 face that spawns a shell command
      *  and mounts LATER than the band (`Monitor`): the SAME function the band's shell faces got. ⇔ a real shell. */
     shellReadAdmission: ShellReadAdmission | undefined;
+    /** owned — the file read station's admission (`FileReadStation.admitted`) the band's read tools got, for the read tools mounted later (LSP). */
+    readAdmission: ((toolCallId: string | undefined, canonicalKey: string) => boolean) | undefined;
     /** write-back (D-3 hold) — the run's RESOLVED read face where hands mount; undefined ⇔ no hands
      *  (the hands-less value lives in `handsLessResolvedFace`). The driver assigns this onto its
      *  outer `let` for the call-time closures (ctx enrichment / checkpoint mint / envFacts). */
@@ -258,9 +263,13 @@ export interface PrepareHandsReadFaceResult {
     /** owned — the canonical containment root, published so the working-file ATTACHMENT
      *  reader applies the same containment the hands tools do. Undefined ⇔ hands-less. */
     attachmentRootCanonical: string | undefined;
-    /** owned — the ONE compiled deny judge per prepare (built-ins ∪ deployment ∪
-     *  task additions), carrying the home views of its placement. Undefined ⇔ hands-less (its consumers only exist with hands). */
-    readDenyMatcher: PlacedReadDenyMatcher | undefined;
+    /** owned — the run's read deny table ({@link pathTables}' facade: the run's latest, `forCall` a call's own). Undefined ⇔
+     *  hands-less (its consumers only exist with hands). */
+    readDenyMatcher: PathTablesFacade["readDeny"] | undefined;
+    /** owned — the read face's root set per judgment: write roots, read roots with grants, the person's read directories. */
+    readRoots: ReadRootsSeat;
+    /** owned — the run's path tables ({@link PathTablesFacade}); undefined ⇔ hands-less. */
+    pathTables: PathTablesFacade | undefined;
     /** owned — the shell-seat PROVENANCE set: the shell-running tools whose tier the engine's shell seat (read
      *  boundary + shape tier + shellGate floor) is the SOLE POSITIVE source of — no explicit deployment mark on that name.
      *  The one seat every consumer reads (risk grading, the gate's tighten attribution, the persisted-rule mandate

package/dist/core/runner/prepare-hands-readface.js

@@ -2,17 +2,19 @@ import { emitTrace } from "../trace.js";
 import { StubExecutionEnv } from "../stub-env.js";
 import { hasBackgroundShell } from "../background-shell.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { bashReversibilityProbe, activeReadDenyBuiltinTiers, readDenyBuiltinConfigOf, compileReadDeny, compileWriteDeny, rowsWhereTheyLead, readDenySeat, createHandsToolkit, deploymentFaceClampNotice, pdfModelCapabilitiesOf, inheritSessionReadFileState, backgroundOutputReadExemption, resolveContainmentFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
-import { resolveKey, sha256 } from "../../tools/fs/safety.js";
-import { placeReadDenyAtHome } from "../../tools/fs/read-deny-home.js";
+import { bashReversibilityProbe, activeReadDenyBuiltinTiers, readDenyBuiltinConfigOf, compileReadDeny, createHandsToolkit, deploymentFaceClampNotice, pdfModelCapabilitiesOf, inheritSessionReadFileState, backgroundOutputReadExemption, resolveContainmentFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { resolveKey, rootAdmittingArtifactStore, sha256 } from "../../tools/fs/safety.js";
+import { thrownText } from "../thrown-value.js";
+import { carryReadFace } from "../../tools/fs/read-deny-home.js";
+import { EMPTY_READ_ROOTS, afterCallTables, denySeatsOf, onPinnedRead, pathTablesCompile, readRootsOver } from "./person-path-rows.js";
 import { createShellOverflowSpoolFence } from "../../tools/fs/fs-shared.js";
 import { createShellReadStation } from "../../tools/fs/shell-read-check.js";
-import { composeReadChecks, createFileReadStation } from "../../tools/fs/file-read-check.js";
+import { createFileReadStation } from "../../tools/fs/file-read-check.js";
 import { isShellFaceToolName, predictMountedToolNames, readTargetToolNames } from "../tool-registry.js";
 import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
 import { deliverEngineNotice } from "../types.js";
-import { readRootGrantOver, rootAdmittingArtifactStore } from "./read-root-grant.js";
+import { readRootGrantOver } from "./read-root-grant.js";
 import { sessionSeatAnchorHolds } from "./session-read-file-states.js";
 import { rebaseWorkspacePath } from "./workspace-path.js";
 import { RosterBuilder } from "../tool-roster.js";
@@ -101,6 +103,7 @@ export function resolveHandsLessReadFace(input) {
         shellReadCheck: undefined,
         shellReadStationArmed: false,
         shellReadAdmission: undefined,
+        readAdmission: undefined,
         resolvedReadFace: undefined,
         resolvedWriteFace: undefined,
         readDenyAdditionsNormalized,
@@ -113,6 +116,8 @@ export function resolveHandsLessReadFace(input) {
         artifactStoreRef: undefined,
         attachmentRootCanonical: undefined,
         readDenyMatcher: undefined,
+        readRoots: EMPTY_READ_ROOTS,
+        pathTables: undefined,
         envHandToolNames: new Set(),
         shellGatedTools: new Set(),
         sealReadStateSeat: undefined,
@@ -148,6 +153,8 @@ export async function prepareHandsMount(input) {
     const artifactStoreRef = { current: undefined };
     let attachmentRootCanonical;
     let readDenyMatcher;
+    let pathTables;
+    let readRoots = EMPTY_READ_ROOTS;
     if (handsEnabled) {
         const rootCanonical = taskRootCanonical;
         attachmentRootCanonical = rootCanonical;
@@ -178,10 +185,6 @@ export async function prepareHandsMount(input) {
         };
         await canonicalizeExtraDirs(spec.additionalDirectories, "additionalDirectories", additionalRootsCanonical);
         await canonicalizeExtraDirs(spec.additionalReadDirectories, "additionalReadDirectories", additionalReadRootsCanonical);
-        const standingCanonical = [];
-        await canonicalizeExtraDirs(input.persistedReadDirectories, "persistedReadRule", standingCanonical);
-        artifactStoreRef.standing = { keys: standingCanonical.filter((k) => !additionalReadRootsCanonical.includes(k) && !additionalRootsCanonical.includes(k)), readRoots: additionalReadRootsCanonical };
-        additionalReadRootsCanonical.push(...standingCanonical);
         if (advertisedWritableDirs !== undefined) {
             if (spec.envFacts?.scratchpadDir)
                 await advertisedWritableDirs.admit({ path: spec.envFacts.scratchpadDir, advertiser: "scratchpad", materializeMarker: ".sema-scratchpad" });
@@ -194,7 +197,7 @@ export async function prepareHandsMount(input) {
         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);
+                const rk = await readRoots.ready().then(() => resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, readRoots(), undefined, undefined, resolvedReadFace));
                 if (rk.ok)
                     seedReadFileStateFromContext(readFileState, rk.key, f.content);
             }
@@ -220,9 +223,12 @@ export async function prepareHandsMount(input) {
         const seedReadFaceSection = resume?.seed.readFace;
         const readDenyAdditions = unionAddOnly("readDenyPatterns", deps.readDenyPatterns, spec.readDenyPatterns, seedReadFaceSection?.denyEntries);
         const readDenyBuiltinCfg = readDenyBuiltinConfigOf({ tiers: deps.readDenyBuiltinTiers, exclude: deps.readDenyBuiltinExclude });
-        const denyRuleRows = rowsWhereTheyLead(input.denyRuleRows, await input.headLeads.resolve(input.denyRuleRows));
-        const readDenyPlacement = await placeReadDenyAtHome(executionEnv, (homes, linked) => compileReadDeny(readDenyAdditions, "readDenyPatterns", readDenyBuiltinCfg, denyRuleRows, homes, linked), undefined, undefined, deps.agentConfigDir);
-        readDenyMatcher = readDenyPlacement.matcher;
+        const canonicalize = async (dirs) => { const out = []; for (const d of dirs)
+            await canonicalizeExtraDirs([d], "persistedReadRule", out).catch((err) => deps.onError?.(new Error(`persistedReadRule entry skipped (its lookup threw): ${d}: ${thrownText(err)}`), { phase: "config", sessionId })); return out; };
+        const tables = (pathTables = await input.personRows.attachTables(pathTablesCompile({ env: executionEnv, additions: readDenyAdditions, builtin: readDenyBuiltinCfg, legRows: input.denyRuleRows, leads: input.headLeads, configRoot: deps.agentConfigDir, canonicalize })));
+        readDenyMatcher = tables.readDeny;
+        readRoots = readRootsOver({ own: () => [...additionalRootsCanonical, ...additionalReadRootsCanonical], tables, ready: input.personRows.tablesReady, store: () => artifactStoreRef.current,
+            onHeld: (entry, store) => emitTrace(deps.tracer, () => ({ kind: "config.additional_directory_skipped", version: 1, taskId: hostTaskId, entry, field: "persistedReadRule", reason: `admits_artifact_store: the local artifact store ${store} lies inside it or it inside the store — the Artifact tool's ledger and stored files stay outside every root the file tools reach`, ts: Date.now() })) });
         readDenyBuiltinTiersActive = activeReadDenyBuiltinTiers(readDenyBuiltinCfg);
         readDenyAdditionsNormalized = compileReadDeny(readDenyAdditions, "readDenyPatterns", { tiers: [] }).entries;
         let liveReadFace = resolveContainmentFace({
@@ -247,7 +253,7 @@ export async function prepareHandsMount(input) {
             seatLeafId = undefined;
         }
         const judgeKey = async (path) => {
-            const rk = await resolveKey(executionEnv, rootCanonical, path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
+            const rk = await readRoots.ready().then(() => resolveKey(executionEnv, rootCanonical, path, undefined, undefined, readRoots(), undefined, undefined, liveReadFace));
             return rk.ok ? rk.key : undefined;
         };
         if (resume === undefined && spec.sessionId !== undefined) {
@@ -262,8 +268,12 @@ export async function prepareHandsMount(input) {
                 const prior = await session.buildContext().catch(() => undefined);
                 for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
                     const rk = await judgeKey(rec.path);
-                    if (rk !== undefined)
+                    if (rk === undefined)
+                        continue;
+                    if ("content" in rec)
                         seedReadFileStateFromTranscript(readFileState, rk, rec.content, rec.at);
+                    else
+                        readFileState.set(rk, { ...rec.observation, lastReadAt: rec.at });
                 }
             }
         }
@@ -290,30 +300,36 @@ export async function prepareHandsMount(input) {
                         sessionSeats.reanchor(sessionId, readFileState, ownCommittedTailEntryId);
                 }
                 : undefined;
-        const denySeat = readDenySeat(readDenyMatcher);
-        const writeDeny = compileWriteDeny(denyRuleRows);
-        const writeDenySeat = writeDeny.ruleRows.length > 0 ? { writeDenyMatch: (p) => writeDeny.matchPath(p)?.pattern ?? null } : {};
-        const shellReadBoundary = () => ({
-            roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
-            ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
-            ...(executionEnv.homeDir !== undefined ? { homeDir: executionEnv.homeDir } : {}),
-            ...denySeat,
-            ...writeDenySeat,
-            writeRoots: [rootCanonical, ...additionalRootsCanonical],
-            ...(resolvedWriteFace !== undefined ? { writeFace: resolvedWriteFace.inForce() } : {}),
-            ...((judge) => (judge !== undefined ? { writeTargetJudge: judge } : {}))(input.writeTargetJudge?.()),
-            ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
-        });
+        const shellReadBoundary = (toolCallId) => {
+            const { read: denySeat, write: writeDenySeat } = denySeatsOf(tables.forCall(toolCallId));
+            return {
+                roots: [rootCanonical, ...readRoots.forCall(toolCallId)()],
+                ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+                ...(executionEnv.homeDir !== undefined ? { homeDir: executionEnv.homeDir } : {}),
+                ...denySeat,
+                ...writeDenySeat,
+                ...(input.personRows.unreadFor(toolCallId) ? { unreadPartitions: true } : {}),
+                writeRoots: [rootCanonical, ...additionalRootsCanonical],
+                ...(resolvedWriteFace !== undefined ? { writeFace: resolvedWriteFace.inForce() } : {}),
+                ...((judge) => (judge !== undefined ? { writeTargetJudge: judge } : {}))(input.writeTargetJudge?.()),
+                ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
+            };
+        };
         if (handsIncludeShell) {
             const spoolFence = handsReadOnly ? createShellOverflowSpoolFence(executionEnv) : undefined;
-            const readonlyBoundary = () => spoolFence !== undefined ? { roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical], cwd: rootCanonical, ...denySeat, ...writeDenySeat, alsoInside: spoolFence } : undefined;
+            const readonlyBoundary = (toolCallId) => {
+                if (spoolFence === undefined)
+                    return undefined;
+                const { read: denySeat, write: writeDenySeat } = denySeatsOf(tables.forCall(toolCallId));
+                return { roots: [rootCanonical, ...readRoots.forCall(toolCallId)()], cwd: rootCanonical, ...denySeat, ...writeDenySeat, ...(input.personRows.unreadFor(toolCallId) ? { unreadPartitions: true } : {}), alsoInside: spoolFence };
+            };
             shellReadTools = new Set(shellFaceHere);
             shellReadStation = createShellReadStation({
                 env: executionEnv,
                 tools: shellReadTools,
                 seatOf: () => (handsReadOnly ? "readonly" : "full_shell"),
-                boundaryOf: () => readonlyBoundary() ?? shellReadBoundary(), rootsCanonical: true,
-                homeViews: readDenyPlacement.matcher.homeViews,
+                boundaryOf: (_tool, _cwd, toolCallId) => readonlyBoundary(toolCallId) ?? shellReadBoundary(toolCallId), rootsCanonical: true,
+                homeViews: tables.readDeny.homeViews,
                 onAdmissionRefused: (toolCallId) => void input.toolOccurrences.refuse(toolCallId, "read_boundary"),
             });
         }
@@ -322,8 +338,8 @@ export async function prepareHandsMount(input) {
             fileReadStation = createFileReadStation({
                 env: executionEnv,
                 rootCanonical,
-                roots: () => [...additionalRootsCanonical, ...additionalReadRootsCanonical],
-                ...(readDenyMatcher !== undefined ? { readDeny: readDenyMatcher } : {}),
+                roots: readRoots,
+                readDeny: tables.readDeny,
                 ...(liveReadFace !== undefined ? { readFace: liveReadFace } : {}),
                 ...("homeDir" in executionEnv && executionEnv.homeDir !== undefined ? { homeDir: executionEnv.homeDir } : {}),
                 tools: readTargetToolNames(),
@@ -333,17 +349,12 @@ export async function prepareHandsMount(input) {
         }
         const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
             ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
-            additionalReadRoots: additionalReadRootsCanonical,
-            ...(readDenyAdditions.length > 0 ? { readDenyPatterns: readDenyAdditions } : {}),
-            ...(denyRuleRows.length > 0 ? { pathDenyRules: denyRuleRows } : {}),
-            readDenyHomes: readDenyPlacement.homes,
-            readDenyHomeLinks: readDenyPlacement.linked,
-            ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
-            ...(readDenyBuiltinCfg.exclude !== undefined ? { readDenyBuiltinExclude: readDenyBuiltinCfg.exclude } : {}),
+            readDenyHomes: carryReadFace([], { readDeny: tables.readDeny, writeDeny: tables.writeDeny, readRoots }),
             readFace: liveReadFace,
             writeFaceLive: resolvedWriteFace.inForce,
             reminderMark: input.reminderMark,
             reminderDisclosureCounts: input.reminderDisclosureCounts,
+            ...(input.modelFileReaderSeat !== undefined ? { modelFileReaderSeat: input.modelFileReaderSeat } : {}),
             ...(input.trackFileEdit !== undefined ? { trackFileEdit: input.trackFileEdit } : {}),
             ...(input.onFileEdited !== undefined ? { onFileEdited: input.onFileEdited } : {}),
             includeShell: handsIncludeShell,
@@ -387,7 +398,7 @@ export async function prepareHandsMount(input) {
                 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 });
             }
         }
-        roster.mountAll(band.map((t) => (envHandToolNames.add(t.name), firstPartyOffload(t))), { source: "builtin", mountedBy: "hands" });
+        roster.mountAll(band.map((t) => (envHandToolNames.add(t.name), firstPartyOffload(afterCallTables(input.personRows, t)))), { source: "builtin", mountedBy: "hands" });
         const shellFloor = effectiveShellGate;
         if (!(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
             const installShellSeat = (name) => {
@@ -413,9 +424,10 @@ export async function prepareHandsMount(input) {
         wsSnapshot,
         rebaseWsPath,
         backgroundTaskToolsActive,
-        shellReadCheck: composeReadChecks([...(shellReadStation !== undefined ? [{ check: shellReadStation.check, tools: shellReadTools }] : []), ...(fileReadStation !== undefined ? [fileReadStation] : [])]),
+        shellReadCheck: onPinnedRead(input.personRows, [...(shellReadStation !== undefined ? [{ check: shellReadStation.check, tools: shellReadTools }] : []), ...(fileReadStation !== undefined ? [fileReadStation] : [])]),
         shellReadStationArmed: shellReadStation !== undefined,
         shellReadAdmission: shellReadStation?.admit,
+        readAdmission: fileReadStation?.admitted,
         resolvedReadFace,
         resolvedWriteFace,
         handsLessResolvedWriteFace,
@@ -428,6 +440,8 @@ export async function prepareHandsMount(input) {
         artifactStoreRef,
         attachmentRootCanonical,
         readDenyMatcher,
+        readRoots,
+        pathTables,
         envHandToolNames,
         shellGatedTools,
         sealReadStateSeat,