import { type BeforeWriteHook, type CwdRef, type PathRuleDenyRow, type ContainmentFace } from "../../tools/fs/index.js"; import { type ReadFileState } from "../../tools/fs/safety.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"; import type { RunnerDeps, ShellGateDoctrine, TaskSpec } from "../types.js"; import type { Model } from "../../internal/llm.js"; import type { AgentHarness, AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js"; import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js"; import { type ArtifactStoreRef, type GrantReadRoot } from "./read-root-grant.js"; import type { StoredSession } from "../session.js"; import type { IrreversibilityTier, PrepareResume, ReversibilityProbes, RunInternals, ToolFaceSnapshot, ToolProgressLane, WriteFaceSeat } from "./contracts.js"; import type { ToolOccurrenceTable } from "./tool-occurrence.js"; import { RosterBuilder } from "../tool-roster.js"; import type { PermissionMode } from "../ask-origin.js"; /** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code. * Deliberately asymmetric — it resets only the console latch: the WeakSet arm needs no seam * because a test resets it by minting a fresh sink function (identity IS the ledger key), while * the console arm's key is the process itself, which only this seam can refresh. Moved WITH the * phase; prepare-task.ts keeps a re-export so the existing import sites stand. */ export declare function __resetReadFaceClampAnnouncement(): void; export interface PrepareHandsReadFaceInput { /** owned (value) — `ownedEnv !== undefined || deps.executionEnv !== undefined`, computed in the * driver: the phase's own branch condition (hands mount vs the hands-less resolver arm). */ handsEnabled: boolean; /** borrowed-readonly (the ownership-ref PROTOCOL stays with the driver — D-8 案① posture, same * as B-4): the effective env (`ownedEnv ?? deps.executionEnv ?? stub`). This phase drives it * (canonicalPath/joinPath/writeFileExclusive probe/instanceof screens) and closes tool bands * over it, but NEVER rebinds or destroys it. */ executionEnv: ExecutionEnv; /** borrowed-readonly — B-4's settled root (T6 FINAL semantics); the containment root every face * in this phase canonicalizes from. */ taskRootFinal: string; /** borrowed-readonly — the same root, resolved to the spelling the fence compares with, by the ONE * resolver at the driver's root receiving point ({@link import("./task-root-canonical.js").resolveTaskRootCanonical}): * taken as an input, never re-canonicalized here, so the fence and the root notice cannot disagree. */ taskRootCanonical: string; /** borrowed-readonly — B-4's checkpoint-path rebaser (T7): identity unless a divergent restore * armed it; applied to the readFileState seed keys and the handsCwd seed. */ rebaseRestoredPath: (p: string) => string; /** borrowed-readonly — the durable-resume seat this phase reads: `seed` only (readFileState / * handsCwd / readFace section). Presence also gates the leg forks (T11: replay never runs on a * resume; the workspace_state rung is skipped; the face fold goes stricter-wins). */ resume: Pick | undefined; /** borrowed-readonly — the acquired session (B-3 output), as a Pick (相 API 规则件 R-4: receiver * preserved): `getWorkspaceState` feeds the continuation rung; `buildContext` feeds * the transcript replay; `getStorage`/`getEntry` feed the seat-anchor verification (one * leaf read per prepare + a bounded parent walk on the inherit leg only). */ session: Pick; /** borrowed-readonly — the acquired session's id, for error/notice tags and the band's session * registration. */ sessionId: string; /** borrowed-readonly — the host task id: trace frames + the band's task-registry owner. */ hostTaskId: string; /** 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 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 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: { readonly current: PermissionMode; }; /** borrowed-readonly — the D-6 spec-time full-shell reachability precomputation; an input to the * face resolver on BOTH arms (the driver's post-exclusion roster assertion pins it to the * mounted truth — that assertion is driver-side, after this phase). */ fullShellReachable: boolean; /** borrowed-readonly — the operator's shell FLOOR (`"always"`: the spec's, or the chain's), or undefined (no floor: * the shape tier installs on its own and the permission mode arbitrates its asks). */ effectiveShellGate: ShellGateDoctrine | undefined; /** borrowed-readonly — B-1's frozen task-start face snapshot; only `.exclude` is read here (the * Monitor-mount honesty bit for the gh rate-limit hint). */ toolFaceSnapshot: ToolFaceSnapshot; /** borrowed-readonly — B-1's resolved main model; read ONLY for its pdf capability profile * (the Read tool's document-degradation fork). */ model: Model; /** borrowed-readonly — the task-spec seats this phase reads, as a Pick over the SAME spec object * (R-4). `tools` feeds only the band shadow check; `envFacts` only the advertised scratchpad; * `retainBackgroundProcesses` only the band's retain lane (Bash's lifetime sentence + row stamp). */ spec: Pick; /** borrowed-readonly — the deployment seats this phase reads, as a Pick over the SAME deps * object (R-4: `deps.onError?.()` keeps its receiver; a new deps read must widen this Pick). * `readDenyBuiltinTiers`/`readDenyBuiltinExclude` are SNAPSHOTTED before the first await that * precedes the toolkit compile (the caller retains these arrays by reference). */ deps: Pick; /** borrowed-readonly — the trusted spawn-side seats the band forwards: the finished-command * notification lane, the mid-flight detach hub, and the Runner's per-session * read-state seats (absent on a standalone prepare ⇒ the transcript-replay rung covers alone). */ internals: Pick | undefined; /** borrowed-mutable — the harness seat, read LIVE by the band's queued-human-input predicate (the shell's * auto-backgrounding leg asks it mid-command). Late-bound: the band is built here, the harness later. */ harnessRef: { current?: AgentHarness; }; /** borrowed-mutable — the tool-progress lane's cell, read LIVE by the band's progress seat; same * late-binding contract as {@link harnessRef}. Unbound ⇒ every tick through it is a silent no-op. */ toolProgressRef: { current?: ToolProgressLane; }; /** borrowed-mutable — the leg's occurrence table; writer here: the shell read station's refused-admission callback. */ toolOccurrences: ToolOccurrenceTable; /** borrowed-readonly — ABSOLUTE paths this prepare's restore wrote, deleted, * or failed to write. Every read-state seed above describes the PRE-restore tree, so these keys are * dropped from the map: the engine replaced those bytes itself, and a surviving entry makes the * next refusal blame "the user or a linter" for the engine's own write. Absent (the common case) * when no file restore ran. Fail-closed by construction — dropping a read record only ever * produces refusals. */ restoredFilePaths?: readonly string[]; /** borrowed-readonly — the memory write gate the memory phase minted (it runs BEFORE this phase: the memory root * must be known before the toolkit compiles), composed into the band's beforeWrite below; undefined for a * memory-less run (every write passes the engine half). */ memoryWriteGate: BeforeWriteHook | undefined; /** borrowed-mutable — the advertised-writable-directory seat (see its module header for the one * rule). Present on the hands leg only (a fence exists). The memory phase, which runs BEFORE this one, * has already admitted its write root through it; this phase admits the deployment's scratchpad and * folds `roots` into the write-capable containment allowlist before the toolkit compiles. */ advertisedWritableDirs?: AdvertisedWritableDirs; /** borrowed-readonly — the driver's per-tool offload wrapper (posture + policy); the * band rides through it exactly as caller/MCP tools do. */ firstPartyOffload: (tool: AgentTool) => AgentTool; /** borrowed-mutable — the SHARED mount array (§4.4: later refs alias it; identity is the * contract, never map/copy). This phase pushes the hands band IN PLACE (after caller tools / * built-ins / MCP / A2A, before the background-task mounts — T22 order). Mutation owners after * this phase: P11 background/Monitor/worktree pushes, the driver's excludeTools splice, the * refresh seam's runtime splice/push. The array is builder-private: this phase `mountAll`s the band. */ roster: RosterBuilder; /** borrowed-readonly HERE (census divergence #5 vs the design row): this phase only reads * `.has("Bash")`/`.has("Monitor")` for the provenance bits — its mutation owners are B-2/P8/P9 * (+refresh seam)/P11/P22, per the B-2 Result's mutation-owner table. */ egressTools: ReadonlySet; /** borrowed-mutable — the shellGate fold's tier write-back (`.get` for the provenance bit, * monotonic `.set` — tighten-only). Same object B-2 returned; owner table lives on the B-2 * Result. */ irreversibilityTier: IrreversibilityTier; /** borrowed-mutable — the shellGate fold `.add`s Bash/Monitor here. Same-object contract as * above. */ irreversibleTools: Set; /** borrowed-mutable — the shape tier's probe installs (`.set`, only where the shell seat * owns the tier). Same-object contract as above. */ reversibilityProbes: ReversibilityProbes; /** borrowed-readonly — the run's reminder provenance mark (minted/adopted * by the driver's adoption ladder); threaded into the hands band so the fs-side engine mints * (the Read dedup/offset/empty reminders, the gh rate-limit hint) stamp the same mark the * system-prompt declaration names. */ reminderMark: string; /** borrowed-mutable — the leg's disclosure trigger counters; the hands * 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; /** borrowed-readonly — the mutation lane's LANDED observation seat (the accumulator behind * `TaskResult.editedFiles`); threaded to the write band's onFileEdited seat. Unlike * `trackFileEdit` it does NOT depend on a wired history store: it observes what this run's hands * did, so it is present on every run that mounts the band. */ onFileEdited?: import("../types.js").FileEditedHook; } /** The phase's outputs (相 API 规则件 four-class form) — ALL settled before the return; the driver * binds them as fresh consts (R-5) except the inverted-closure trio and the two shellGated bits, * which write back into the driver's pre-existing `let`s (D-3 hold / driver-owned seats — see the * module header). */ export interface PrepareHandsReadFaceResult { /** owned — the per-task read-before-write state, exposed for the suspend closure's checkpoint * serialization (§15.2 net-add #8) and the compaction faces. Undefined ⇔ hands-less. The MAP * keeps being mutated by tool executes / compaction at run time — object identity carried. */ readFileStateForCheckpoint: ReadFileState | undefined; /** owned — parity-204 (CC seededFromContext): seeds declared context files through the SAME * resolveKey containment as a real Read. CREATED here; CALLED by the driver's memory-seed and * loadProjectMemory blocks (T10 — the forever-cross-phase edge; this module does not claim the * call order). Undefined on a hands-less task (nothing to seed). Reads the phase-local * `resolvedReadFace` call-time — settled before this function returns. */ seedContextFiles: ((files: ReadonlyArray<{ path: string; content: string; }>) => Promise) | undefined; /** owned — the per-task logical cwd ref (observable `cd`), minted when a real * writable shell mounts. The driver stamps it into checkpoints, threads it into worktree tools * and gate cwd reads; tools mutate `.current` at run time. Undefined when no shell / readOnly. */ handsCwdRef: CwdRef | undefined; /** owned — the settle-side snapshot base (what the cwd/worktree refs were RESTORED * to), so runtask's settle write diffs against it. The driver's G4 worktree mount writes * `.restoredWorktreeDir` after this phase — object identity carried. */ workspaceStateSettle: { rootCanonical: string; restoredHandsCwd?: string; restoredWorktreeDir?: string; baselineUnknown?: boolean; } | undefined; /** owned — the branch-nearest `workspace_state` entry, fetched ONCE here and shared * with the driver's worktree seed (the G4 mount reads `.activeWorktree` through it). */ wsSnapshot: WorkspaceState | undefined; /** owned — the wsSnapshot path rebaser (identity when no snapshot / same root); the G4 worktree * seed applies it to the snapshot's worktree paths. */ rebaseWsPath: (p: string) => string; /** owned — real shell + write hands + background-capable env: gates the driver's TaskOutput/ * TaskStop/Monitor/SendMessage mounts (P11) and the Monitor arm of the shellGate fold here. */ backgroundTaskToolsActive: boolean; /** owned — this run's READ STATIONS as the one gate input (`ToolGateInput.shellReadCheck`): the shell's (ONE judgment of * where a shell command reads, for every shell face this leg mounts, under every mode and floor) and the file tools' * (an out-of-root Read / Grep / Glob target is a question). ⇔ hands with a real shell, or hands with an approval face. */ shellReadCheck: ShellReadCheck | undefined; /** owned — the shell read station is mounted (⇔ a real shell): the wiring manifest's cell. */ shellReadStationArmed: boolean; /** 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). */ resolvedReadFace: ContainmentFace | undefined; /** write-back — the run's WRITE face in force where hands mount, read per call ({@link writeFaceReader}); undefined ⇔ * no hands (the hands-less reader is `handsLessResolvedWriteFace`). The read seat's twin, resolved by the SAME order on * its OWN seats — the two never read each other. */ resolvedWriteFace: WriteFaceSeat | undefined; /** write-back — the hands-LESS legs' write face in force (the posture is a property of the RUN, not the mount): the * delegation carriers and the checkpoint mint read it on every leg. */ handsLessResolvedWriteFace: WriteFaceSeat | undefined; /** write-back (D-3 hold) — the NORMALIZED deny-set additions in force (deployment ∪ task ∪ * resume-seed; zero-builtin compile — the persisted/carrier form, never the judged union's * post-dedup remainder). Driver assigns onto its outer `let`. */ readDenyAdditionsNormalized: ReadonlyArray<{ pattern: string; caseSensitive: boolean; }>; /** owned — the built-in deny TIERS this leg MATERIALLY activated, off the same snapshot the compile * judged with; empty ⇒ none. Relayed to the wiring manifest, never re-derived from `deps` there. */ readDenyBuiltinTiersActive: readonly string[]; /** write-back (D-3 hold) — the hands-LESS legs' resolved face (the read posture is a * property of the RUN, not the mount). Driver assigns onto its outer `let`. */ handsLessResolvedFace: ContainmentFace | undefined; /** owned — the canonicalized write-capable extra roots (additionalDirectories + the advertised * scratchpad), deduped; the driver's envFacts advertisement and attachment readers share the * ARRAY identity. Settled here (no mutation after return). */ additionalRootsCanonical: string[]; /** owned — the read-only arm of the fence widening (2026-08-05 both-arms ruling); same identity * contract as above, and the run's LIVE read-root set: {@link grantReadRoot} is its one writer after prepare, * and every read face reads it per call (never a copy). */ additionalReadRootsCanonical: string[]; /** owned — widen {@link additionalReadRootsCanonical} by one granted candidate (an approver's in-flight * `readRootGrant`); undefined ⇔ hands-less (no read face to widen). */ grantReadRoot: GrantReadRoot | undefined; /** owned — the store cell {@link grantReadRoot} judges against; the driver threads it to its one writer, the Artifact phase. */ artifactStoreRef: ArtifactStoreRef | undefined; /** 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 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 * boundary): `shellGatedTools.has(toolName)`. Minted here, never grown afterwards; empty when the seat fold * did not run (no real writable shell). */ shellGatedTools: ReadonlySet; /** owned — the ENV-HAND tool names, minted AT THE MOUNT: every tool this * phase mounted over the ExecutionEnv (the fs/bash band), later grown by the driver's own env * mounts (Monitor, the worktree pair — the SAME Set identity, mutated at those mount sites). * Consumed by the O9a external-content-target fold: these are the tools whose RESULTS are the * target's bytes, so membership must be what actually mounted on the env — never a static table * (the wake/resume reconciliation table lists TaskOutput/TaskStop, which are orchestration, and * misses Monitor/worktree, which are hands — both directions wrong for this consumer). Empty on * a hands-less leg (nothing mounts on the env; the driver's env mounts are hands-gated too). */ envHandToolNames: Set; /** owned — the settle-time SEAT SEAL: re-anchors the session seat to the * task's OWN last-committed entry (see {@link import("./session-read-file-states.js").SessionReadFileStates.reanchor}). The driver calls * it once at the run's settle (every terminal, suspend included), under the session lock, passing * the last entryId ITS OWN run committed (the message_committed lane) — never a re-read of the * shared session leaf, which a concurrent writer on another Runner could have moved onto a branch * this task's reads were never on. No commits observed ⇒ no-op (the adopt-time anchor * stands). Synchronous, never throws. Undefined ⇔ hands-less / no seat channel. */ sealReadStateSeat: ((ownCommittedTailEntryId: string | undefined) => void) | undefined; } export declare function resolveHandsLessReadFace(input: PrepareHandsReadFaceInput): PrepareHandsReadFaceResult; /** The hands-MOUNT branch — the async half of the phase (see the module header for the contract). * The driver awaits this ONLY on the hands leg (`handsEnabled === true`); the hands-less leg goes * through the synchronous {@link resolveHandsLessReadFace} instead. Two seams, one boolean * dispatch — no `Promise`-identity guard (r3). */ export declare function prepareHandsMount(input: PrepareHandsReadFaceInput): Promise;