@sema-agent/core 7.33.7 → 7.34.0

package/dist/core/tool-policy.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { brandPolicyAskClass } from "./ask-class.js";
+import { decisionAskClassesOf, headlessDenialMessage } from "./ask-origin.js";
 import { ownReadRootCandidate, readRootGrantSeat } from "./read-root-grant-screen.js";
 import { decidersNote, settledByPerson } from "./gate-outcome.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
@@ -121,6 +122,26 @@ export const ASK_EVIDENCE_ABSENCE_VALUES = ["not_wired", "not_adjudicated", "una
 export function decisionText(d) {
     return d.message;
 }
+export function toolPolicyPathDenyRules(policies) {
+    return policies.flatMap((p) => (Array.isArray(p?.pathDenyRules) ? p.pathDenyRules : []));
+}
+export function toolPolicyWriteTargetGuard(policies) {
+    const guards = policies.flatMap((p) => (typeof p?.writeTargetGuard === "function" ? [p.writeTargetGuard] : []));
+    if (guards.length === 0)
+        return undefined;
+    return async (target, signal) => {
+        for (const guard of guards) {
+            try {
+                if ((await guard(target, signal)) !== false)
+                    return true;
+            }
+            catch {
+                return true;
+            }
+        }
+        return false;
+    };
+}
 export function namespacedCoveringEntries(entries) {
     return (entries ?? []).filter(isNamespacedCoveringRuleName);
 }
@@ -452,6 +473,8 @@ export function createApprovalPolicy(opts) {
 }
 export function combinePolicies(...policies) {
     const nameSets = policies.flatMap(toolPolicyNameSets);
+    const pathDenyRules = toolPolicyPathDenyRules(policies);
+    const writeTargetGuard = toolPolicyWriteTargetGuard(policies);
     const childProjections = policies.map((p) => p.projection);
     const projectedComponents = [];
     let combinedRemainder = false;
@@ -472,6 +495,8 @@ export function combinePolicies(...policies) {
     return {
         ...(combinedProjection !== undefined ? { projection: combinedProjection } : {}),
         ...(nameSets.length > 0 ? { nameSets } : {}),
+        ...(pathDenyRules.length > 0 ? { pathDenyRules } : {}),
+        ...(writeTargetGuard !== undefined ? { writeTargetGuard } : {}),
         async check(req, signal) {
             let asked;
             let current = req;
@@ -482,6 +507,8 @@ export function combinePolicies(...policies) {
             let probeMandateSeen = false;
             let mandateSeen = false;
             let fallbackSeen;
+            let authoredBySeen = false;
+            const contributors = [];
             for (const p of policies) {
                 const d = refuseOutOfContractDecision(await p.check(current, signal));
                 if (d.action === "deny") {
@@ -516,6 +543,10 @@ export function combinePolicies(...policies) {
                     mandateSeen = true;
                 if (d.action === "ask" && d.denialLimitFallback !== undefined && fallbackSeen === undefined)
                     fallbackSeen = d.denialLimitFallback;
+                if (d.action === "ask" && d.authoredBy === "deployment")
+                    authoredBySeen = true;
+                if (d.action === "ask")
+                    contributors.push(d);
             }
             if (asked) {
                 const merged = rewrite?.updatedInput;
@@ -523,7 +554,14 @@ export function combinePolicies(...policies) {
                 const withMark = probeMandateSeen && withRuleAsk.probeMandated !== true ? { ...withRuleAsk, probeMandated: true } : withRuleAsk;
                 const withMandate = mandateSeen && withMark.mandated !== true ? { ...withMark, mandated: true } : withMark;
                 const withFallback = fallbackSeen !== undefined && withMandate.denialLimitFallback === undefined ? { ...withMandate, denialLimitFallback: fallbackSeen, requiresRealApproval: true } : withMandate;
-                return merged !== undefined ? { ...withFallback, updatedInput: merged } : withFallback;
+                const withAuthor = authoredBySeen && withFallback.authoredBy === undefined ? { ...withFallback, authoredBy: "deployment" } : withFallback;
+                const folded = new Set(withAuthor.foldedAskClasses ?? []);
+                for (const c of contributors)
+                    if (c !== asked)
+                        for (const k of decisionAskClassesOf(c))
+                            folded.add(k);
+                const withClasses = folded.size > 0 ? { ...withAuthor, foldedAskClasses: [...folded] } : withAuthor;
+                return merged !== undefined ? { ...withClasses, updatedInput: merged } : withClasses;
             }
             const allowed = rewrite ?? ALLOW;
             if (!anyRecord)
@@ -829,6 +867,7 @@ export function createUnverifiableDeletePolicy(opts) {
                 action: "ask",
                 decisionReason: "safety",
                 requiresRealApproval: true,
+                guard: "unverifiable_delete",
                 message: `Unverifiable recursive delete (fail-closed unless cleared): ${finding}. ` +
                     `Re-run the delete with the resolved literal path written into the command itself ` +
                     `(or assign the variable in the same command, e.g. \`DIR=/exact/path; rm -rf "$DIR"\`) so the target can be verified.`,
@@ -905,6 +944,7 @@ export function createTranscriptIntegrityPolicy(opts) {
         action: "ask",
         decisionReason: "safety",
         requiresRealApproval: true,
+        guard: "transcript_write",
         message: `Session-transcript write (fail-closed unless cleared): ${what}. Session transcripts (the .jsonl files ` +
             `under the agent data dir's sessions/ directory) are harness-written session state, not agent working ` +
             `files — modifying or deleting them tampers with the run's own audit trail. Reading them (ls/cat/grep ` +
@@ -956,6 +996,7 @@ export function isLiveApproverSeat(onAsk) {
     return typeof onAsk === "function";
 }
 export const DURABLE_MANDATE_SOURCES = ["force_durable_gate", "durable_approval"];
+Object.freeze(DURABLE_MANDATE_SOURCES);
 export function durableMandateSourceOf(args) {
     if (args.forceDurableGate)
         return "force_durable_gate";
@@ -1250,7 +1291,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
     if (onAsk === undefined || onAsk === "deny") {
         return {
             action: "deny",
-            message: `approval required for "${req.toolName}" but no approver is wired (headless auto-deny): ${req.message}`,
+            message: headlessDenialMessage(req.toolName, req.message),
             decisionReason: "mode",
             settlement: settledByNobody("no_approver"),
         };

package/dist/core/tool-registry.d.ts

@@ -28,6 +28,8 @@ export declare function pathConfinableWriteToolNames(): ReadonlySet<string>;
 export declare function skillScopeWriteToolNames(): ReadonlySet<string>;
 /** A-8 — every definition that names a path target at all (read or write): the file-tool glob lane. */
 export declare function pathTargetingToolNames(): ReadonlySet<string>;
+/** The tools whose declared path target is a READ (a file read, a search root): the file read station's membership. */
+export declare function readTargetToolNames(): ReadonlySet<string>;
 /** A-10 — the micro-compaction whitelist (`compactable: true`). */
 export declare function compactableToolNames(): ReadonlySet<string>;
 /** A-5 — the aggregate-budget exemptions (`budgetExempt: true`). */

package/dist/core/tool-registry.js

@@ -31,6 +31,9 @@ export function skillScopeWriteToolNames() {
 export function pathTargetingToolNames() {
     return names((e) => e.face.pathTarget !== undefined);
 }
+export function readTargetToolNames() {
+    return names((e) => e.face.pathTarget?.access === "read");
+}
 export function compactableToolNames() {
     return names((e) => e.face.compactable === true);
 }

package/dist/core/tool-spec.d.ts

@@ -1113,7 +1113,7 @@ export interface ToolExecuteContext {
     /**
      * RB-201 FO-3 (form-one audit, CC 220 `Ipd`/`ein` parity) — the auto-mode classifier decider ARMED
      * for THIS task (auto-mode intent ∧ `RunnerDeps.autoMode` present ∧ `RuntimeCaps.autoMode !== false`
-     * — see {@link TaskSpec.autoModeRequested}; the same
+     * — see {@link TaskSpec.permissionMode}; the same
      * instance `runToolGate`'s per-call ask review already consults, carrying its own live breaker
      * state — not a fresh one built from raw config). Runner-filled, trusted, undefined when auto-mode
      * is not armed or the tool runs outside a Runner task.
@@ -1286,13 +1286,12 @@ export interface ToolExecuteContext {
      */
     requestStopAfterTurn?: () => void;
     /**
-     * design/108 — enter mid-run READ-ONLY plan mode: the rest of THIS run rejects write-effect tool calls
-     * (`effect !== "read"`), while read/research tools and `present_plan` still run. A run-local one-way flag
-     * (NOT durable — a later approve-resume re-prepares with it clear, so the approved plan can write). The
-     * first-party `enter_plan_mode` tool (CC `EnterPlanMode` parity) is the only caller; the engine enforces the
-     * read-only restriction in a dedicated plan-mode tool-call check (separate from the safety gate — plan mode
-     * is a FIDELITY mode, not a security boundary; the real safety gates apply independently). Idempotent; a
-     * no-op for tools that don't call it. The Runner fills it; not a tool arg. Absent outside a Runner.
+     * Enter plan mode mid-run: a steer of the leg's ONE permission-mode seat into `plan` — the same mode the spec's
+     * `permissionMode` and `TaskStream.setPermissionMode` set. For the rest of THIS run the mode gate asks before every
+     * covered write and every call to a tool the engine does not define that is not read-only (the plan sentence; refused
+     * where nobody can answer), while read tools and `ExitPlanMode` run. The word it left is recorded: an approve-resume
+     * returns to it; a rejected plan steers the resumed leg back into `plan`. The first-party `EnterPlanMode`
+     * tool is the only caller. Idempotent. The Runner fills it; not a tool arg. Absent outside a Runner.
      */
-    enterPlanMode?: () => void;
+    enterPlanMode?: () => Promise<void>;
 }

package/dist/core/trace.d.ts

@@ -253,11 +253,12 @@ export type TraceEvent = {
     taskId: string;
     /** Which spec field the skipped entry came from. Absent = `additionalDirectories` (the
      *  original face, kept implicit for existing readers); `"additionalReadDirectories"` = the
-     *  read-only whitelist arm (ruled 2026-08-05). */
-    field?: "additionalReadDirectories";
+     *  read-only whitelist arm (ruled 2026-08-05); `"persistedReadRule"` = a person's persisted `Read(//dir/**)` allow row. */
+    field?: "additionalReadDirectories" | "persistedReadRule";
     /** The spec entry as written (raw, not canonical — canonicalization is what failed). */
     entry: string;
-    /** The canonicalization failure, `code: message` form. */
+    /** Why the entry was skipped, `code: message` form: the canonicalization failure, or (a persisted row only)
+     *  `admits_artifact_store` — the in-flight grant's store rule. */
     reason: string;
     ts: number;
 } | {
@@ -442,9 +443,9 @@ export type TraceEvent = {
     ts: number;
 } | {
     /**
-     * design/179 — the persisted allow-rule store could not be read, so this call was adjudicated with
-     * ZERO rules (it asks, rather than silently behaving like an empty store). A loosening face that
-     * fails must say so.
+     * design/179 — the person's persisted rule store could not be read (at prepare, or for one call), so
+     * that read's rows took no part: the decision it served was made with ZERO persisted rows. The operator's
+     * per-read record; the person hears it once per run (`permission.rule_store_unavailable`).
      */
     kind: "permission.rule_store_unreadable";
     version: 1;

package/dist/core/types.d.ts

@@ -13,7 +13,8 @@ import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVer
 import type { Model, StreamFn } from "../internal/llm.js";
 export type { ModelRef, ModelRole, RoleSpec, ModelRoles, Brain } from "./model-seat.js";
 export { MODEL_ROLES } from "./model-seat.js";
-export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine, ApproverPosture } from "./task-spec.js";
+export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine } from "./task-spec.js";
+export type { PermissionMode } from "./ask-origin.js";
 export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
 export type { AgentDefinition, SkillManifest, SkillSpec } from "./agent-definition.js";

package/dist/core/wiring-manifest.d.ts

@@ -64,8 +64,8 @@ export type ParkLaneReason = "no_checkpoint_store" | "no_durable_approval_opt_in
  * The closed set of auto-mode ARMING outcomes a leg's manifest reports
  * ({@link WiringManifest.autoMode}). Minted from the arming predicate's own three-arm read, as the
  * FIRST failing arm in predicate order:
- *  - `no_intent`      — no `TaskSpec.autoModeRequested` seat and no intent inherited on the chain /
- *                       recorded on the resumed checkpoint (a non-auto run; byte-identical arming).
+ *  - `no_intent`      — the declared permission mode is not `auto` (no `permissionMode: "auto"` seat, none
+ *                       inherited on the chain / recorded on the resumed checkpoint; a non-auto run).
  *  - `no_face`        — intent, but no `RunnerDeps.autoMode` deployment face (the trust gate).
  *  - `denied`         — intent + face, but the organization's deny bit (`RuntimeCaps.autoMode:false`)
  *                       as the resolver STATED it.
@@ -306,7 +306,8 @@ export interface WiringManifest {
      * classifier decider was minted for this leg), and `reason` names the first arm that failed
      * otherwise — see {@link AUTO_MODE_ARM_REASONS}. A serving layer that used to infer the mode from
      * spec shape reads it here instead. The classifier's availability is a per-CALL fact (an unavailable
-     * round is a deny that says so, and the next round is classified afresh), so there is no session-level
+     * round goes on to the approval seat or is refused with a sentence that says so, and the next round is
+     * classified afresh), so there is no session-level
      * breaker face here and nothing about availability enters {@link configFingerprint}.
      */
     autoMode?: AutoModeArmFact;
@@ -369,6 +370,17 @@ export interface WiringManifest {
         mounted: boolean;
         reason?: HandsUnmountedReason;
     };
+    /**
+     * EFFECTIVE half only, ALWAYS present on an engine-minted effective manifest: the leg's PERMISSION MODE as the engine
+     * resolved it — `requested` (the caller's word; absent = declared nothing), `effective` (the mode the leg runs under:
+     * the request clamped under a parent's ceiling, then folded to `default` where the deployment denies it or the
+     * classifier face is absent), `foldedBy` (present iff the two differ: `operator_deny` / `face_absent` /
+     * `inherited_ceiling`). The same three members answer every steer of the mode (`TaskStream.setPermissionMode`) and
+     * ride the fold notice's detail. A shell renders its mode indicator from `effective`, never from what it sent.
+     * ABSENT = an older mint, never a state. Leg-local (excluded from {@link configFingerprint}: a child clamped under its
+     * parent legitimately differs from it).
+     */
+    permissionMode?: import("./mode-policy.js").PermissionModeReceipt;
     /**
      * EFFECTIVE half only, PRESENT IFF this leg compiled a write-protection judge — a deployment that
      * replaced the table with `[]` opted the layer out entirely, and reports nothing here rather than a
@@ -407,8 +419,8 @@ export interface WiringManifest {
      * of one assembly agree.
      *
      * @contract read_deny.builtin_activation_disclosed — WHETHER the built-in sensitive-path read deny
-     * table judges a leg is DISCLOSED, never inferred: the table is a deployment opt-in whose default
-     * selection is empty, the leg that compiles the judge relays the tiers its own resolution materially
+     * table judges a leg is DISCLOSED, never inferred: the tier selection is the deployment's (absent = the default
+     * tiers, an explicit `[]` = none), the leg that compiles the judge relays the tiers its own resolution materially
      * activated, and the manifest carries that section iff at least one built-in row is active (absence
      * = no built-in row judges; an empty array is never emitted — "off" and "on to nothing" are one
      * fact). The disclosure changes no verdict.
@@ -524,6 +536,9 @@ export interface WiringFacts {
         mounted: boolean;
         reason?: HandsUnmountedReason;
     };
+    /** Effective half only — the leg's permission-mode receipt ({@link WiringManifest.permissionMode}); the engine always passes it.
+     *  Screened: `effective` a mode word, `requested` a mode word or absent, `foldedBy` a fold reason or absent. */
+    permissionMode?: import("./mode-policy.js").PermissionModeReceipt;
     /** Effective half only — the compiled write-protection judge's OWN target-view word
      *  ({@link WiringManifest.writeProtection}); absent ⇒ this leg compiled no judge (an emptied table). */
     writeProtectionTargetView?: WriteProtectionTargetView;
@@ -596,6 +611,17 @@ export declare function resolveSubagentTranscriptTier(agentStoreWired: boolean,
  *    else the headless degrade `auto_deny`.
  */
 export declare function deriveAskEffective(form: AskSeamForm, parkEffective: boolean | "unresolved"): AskEffective;
+/**
+ * Does an ask this leg hands on carrying `requiresRealApproval` reach a PERSON — never an automatic yes? The leg's
+ * APPROVAL SEAT, read off the ONE ask derivation above, never re-derived: `human_reachable` (a live approver) and
+ * `park_only` (the durable park; where the park cannot take the ask, a blanket seat behind it refuses the bit) are a
+ * person; `auto_allow`, `auto_deny` and `unresolved` are nobody (the last the fail-closed reading). The auto-mode
+ * classifier stations read it to decide where a classification that could not rule goes: to that person (the ask
+ * carrying the bit), or refused.
+ */
+export declare function askReachesPerson(ask: {
+    readonly effective?: AskEffective;
+}): boolean;
 export declare function deriveWiringManifest(facts: WiringFacts): WiringManifest;
 /** The one ask-seat resolution (`spec` wins over `deps`), shared with the effective half so the
  *  form/provenance read cannot fork. Junk values (a JS caller passing something outside the OnAsk

package/dist/core/wiring-manifest.js

@@ -1,3 +1,5 @@
+import { isPermissionMode } from "./ask-origin.js";
+import { PERMISSION_MODE_FOLD_REASONS } from "./mode-policy.js";
 import { createHash } from "node:crypto";
 import { canonicalize } from "./canonical-json.js";
 import { resolveCheckpointStore } from "./checkpoint-store.js";
@@ -57,6 +59,23 @@ export function deriveAskEffective(form, parkEffective) {
         }
     }
 }
+export function askReachesPerson(ask) {
+    const effective = ask.effective ?? "unresolved";
+    switch (effective) {
+        case "human_reachable":
+        case "park_only":
+            return true;
+        case "auto_allow":
+        case "auto_deny":
+        case "unresolved":
+            return false;
+        default: {
+            const _exhaustive = effective;
+            void _exhaustive;
+            throw new Error(`unreachable ask effective ${String(effective)}`);
+        }
+    }
+}
 function deriveParkLane(facts) {
     if (!facts.parkCapable) {
         return { capable: false, effective: false, reasons: ["no_checkpoint_store"] };
@@ -87,6 +106,13 @@ function readAutoModeFact(fact) {
     }
     return { armed, reason, ...(deniedSource !== undefined ? { deniedSource } : {}) };
 }
+function readPermissionModeFact(fact) {
+    const { requested, effective, foldedBy } = typeof fact === "object" && fact !== null ? fact : { requested: undefined, effective: undefined, foldedBy: undefined };
+    if (!isPermissionMode(effective) || (requested !== undefined && !isPermissionMode(requested)) || (foldedBy !== undefined && !PERMISSION_MODE_FOLD_REASONS.includes(foldedBy))) {
+        throw new Error(`the permission-mode wiring fact is inconsistent (${JSON.stringify(fact)}) — effective must be a permission mode, requested one or absent, foldedBy one of ${PERMISSION_MODE_FOLD_REASONS.join("|")} or absent`);
+    }
+    return { ...(requested !== undefined ? { requested } : {}), effective, ...(foldedBy !== undefined ? { foldedBy } : {}) };
+}
 function readHandsFact(fact) {
     const { mounted, reason } = typeof fact === "object" && fact !== null ? fact : { mounted: undefined, reason: undefined };
     if (typeof mounted !== "boolean" || (mounted ? reason !== undefined : reason !== "no_execution_env")) {
@@ -157,6 +183,7 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.hooks !== undefined && facts.hooks.length > 0 ? { hooks: facts.hooks.map((h) => ({ ...h })) } : {}),
         ...(facts.half === "effective" && facts.lsp !== undefined ? { lsp: { ...facts.lsp } } : {}),
         ...(facts.half === "effective" && facts.hands !== undefined ? { hands: readHandsFact(facts.hands) } : {}),
+        ...(facts.half === "effective" && facts.permissionMode !== undefined ? { permissionMode: readPermissionModeFact(facts.permissionMode) } : {}),
         ...(facts.half === "effective" && facts.writeProtectionTargetView !== undefined ? { writeProtection: { targetView: facts.writeProtectionTargetView } } : {}),
         ...(facts.half === "effective" && facts.readDenyBuiltinTiersActive !== undefined && facts.readDenyBuiltinTiersActive.length > 0
             ? { readDeny: { builtinTiers: [...facts.readDenyBuiltinTiersActive] } }
@@ -169,7 +196,7 @@ export function deriveWiringManifest(facts) {
             : {}),
     };
     if (facts.half === "effective") {
-        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, ...assembly } = manifest;
+        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, permissionMode: _permissionMode, ...assembly } = manifest;
         const { provenance: _askSeat, ...askForHash } = assembly.ask;
         const { provenance: _questionSeat, ...questionForHash } = assembly.question;
         manifest.configFingerprint = createHash("sha256")

package/dist/core/write-protect.d.ts

@@ -20,7 +20,7 @@ export interface WriteProtectedRow {
  * String shorthand: a bare name ≡ `{ name, kind: "segment" }` (the WIDER single-segment kind —
  * over-matching is the fail-safe direction for a tighten); a name containing `/` ≡
  * `{ name, kind: "segment-run" }`. Spell `kind: "basename"` explicitly when last-segment-only
- * matching is the intent.
+ * matching is the intent. A name opening with the home word (`~/…`) refuses: the table places no row at a home.
  */
 export type WriteProtectedEntry = string | WriteProtectedRow;
 /** A table hit: which row matched (the row's canonical name + kind). */
@@ -108,6 +108,13 @@ export interface WriteProtectionJudgeContext {
     readonly base?: string;
     /** Bounds the filesystem probes of the target view. */
     readonly signal?: AbortSignal;
+    /** The path is a CANONICAL key the caller already resolved at the seat its program writes it (the shell read station's
+     *  established write target: where the path lands, or — for a removal or a rename — the entry itself, its canonical
+     *  parent joined with the last name, a link there not followed). It is judged where a key is judged — the readings and
+     *  the canonical data-root exemption — never as a spelling (the lexical passthrough reads a spelling, and a key reached
+     *  through a linked data root does not spell itself inside it) and never followed: no link chain is walked from it, as
+     *  the program walks none from where it writes. Without an environment the key is judged as a spelling (the absence law). */
+    readonly canonical?: true;
 }
 /**
  * WHICH reading of a write's TARGET a compiled judge has — its own word, and the vocabulary the wiring
@@ -258,3 +265,6 @@ export interface WriteProtectionMount {
  * `deny > ask > allow` fold, which is what makes the missing seat cost nothing.
  */
 export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[], opts?: WriteProtectionCompileOptions): WriteProtectionMount | undefined;
+/** {@link createWriteProtectionCheck} over a judge already compiled — the engine's leg compiles once and hands the same
+ *  judge to the call check and to the shell station (engine-internal; not re-exported from the package root). */
+export declare function writeProtectionMountOver(matcher: WriteProtectionMatcher, rootPath: string | undefined): WriteProtectionMount;

package/dist/core/write-protect.js

@@ -3,6 +3,7 @@ import { protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
 import { canonicalDataRootKeys, dataRootSpellings, relativeUnderRoot } from "./sensitive-path-policy.js";
 import { symlinkChainHops } from "./path-identity.js";
+import { readDenyPatternRun } from "../tools/fs/read-deny.js";
 import { thrownText } from "./thrown-value.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
 export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
@@ -57,6 +58,7 @@ export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
     { name: ".gnupg", kind: "segment" },
     { name: ".sema.json", kind: "basename" },
     { name: ".sema", kind: "segment" },
+    { name: "credentials.env", kind: "basename" },
 ]);
 export function foldWriteProtectSegment(s) {
     const cased = s.toLowerCase().replace(/ı/g, "i").replace(/ſ/g, "s");
@@ -91,6 +93,11 @@ function normalizeWriteProtectedEntry(entry) {
         throw new Error(`writeProtectedPaths: entry ${describeEntryValue(entry)} has kind ${describeEntryValue(shape.kind)} — known kinds: ${KINDS.join(", ")}.`);
     }
     const kind = shape.kind;
+    const { homeAnchored, run } = readDenyPatternRun(name);
+    if (homeAnchored) {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} opens with the home word "~", which this table does not place — its names are matched wherever their segments appear. ` +
+            (run.length > 0 ? `Spell the name without it (${describeEntryValue(run)}), which covers the home's file and every same-named one.` : "The home directory itself is not a row; spell the name of what it holds."));
+    }
     if (name.includes("*") || name.includes("?")) {
         throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains a wildcard metacharacter — this table speaks LITERAL names only (a silently-literal "*" would guard less than it reads); pattern semantics live in createSensitivePathPolicy.`);
     }
@@ -254,7 +261,8 @@ export function compileWriteProtection(entries, opts) {
             return judgeSpelling(path, cwd);
         },
         async judge(path, ctx = {}) {
-            const bySpelling = judgeSpelling(path, ctx.cwd);
+            const givenKey = ctx.canonical === true && env !== undefined;
+            const bySpelling = givenKey ? null : judgeSpelling(path, ctx.cwd);
             if (bySpelling !== null)
                 return { kind: "hit", hit: bySpelling, via: "spelling" };
             if (env === undefined)
@@ -268,16 +276,18 @@ export function compileWriteProtection(entries, opts) {
                 noted = true;
                 opts?.onViewAbsent?.({ cause, unresolvedSymlink });
             };
-            let canonKey;
-            try {
-                const canon = await canonicalizeTarget(env, path, ctx.signal, family, base);
-                if (canon.ok)
-                    canonKey = canon.key;
-                else
-                    noteAbsence(canon.message, canon.unresolvedSymlink === true);
-            }
-            catch (err) {
-                noteAbsence(thrownText(err), false);
+            let canonKey = givenKey ? path : undefined;
+            if (!givenKey) {
+                try {
+                    const canon = await canonicalizeTarget(env, path, ctx.signal, family, base);
+                    if (canon.ok)
+                        canonKey = canon.key;
+                    else
+                        noteAbsence(canon.message, canon.unresolvedSymlink === true);
+                }
+                catch (err) {
+                    noteAbsence(thrownText(err), false);
+                }
             }
             try {
                 if (canonKey !== undefined) {
@@ -295,7 +305,7 @@ export function compileWriteProtection(entries, opts) {
                         return { kind: "hit", hit: byTarget, via: "target" };
                     }
                 }
-                for (const hop of await symlinkChainHops(env, path, ctx.signal, family, base, (cause) => noteAbsence(cause, false))) {
+                for (const hop of givenKey ? [] : await symlinkChainHops(env, path, ctx.signal, family, base, (cause) => noteAbsence(cause, false))) {
                     const byHop = judgeSpelled(hop);
                     if (byHop === null)
                         continue;
@@ -346,8 +356,9 @@ export function writeProtectionUnresolved(verdict) {
 }
 export function createWriteProtectionCheck(entries, opts) {
     const matcher = compileWriteProtection(entries, opts);
-    if (matcher === undefined)
-        return undefined;
+    return matcher === undefined ? undefined : writeProtectionMountOver(matcher, opts?.rootPath);
+}
+export function writeProtectionMountOver(matcher, rootPath) {
     const check = (toolName, args, face, cwd, signal) => {
         const call = { toolName, args, ...(face !== undefined ? { face } : {}) };
         const protective = protectivePathTargetOf(call);
@@ -356,7 +367,7 @@ export function createWriteProtectionCheck(entries, opts) {
         const path = writeTargetPath(call, protective);
         if (typeof path !== "string" || path.length === 0)
             return null;
-        return matcher.judge(path, { ...(cwd !== undefined ? { cwd } : {}), ...(signal !== undefined ? { signal } : {}), ...(() => { const b = pathTargetBaseOf(protective, { root: opts?.rootPath, cwd }); return b !== undefined ? { base: b } : {}; })() });
+        return matcher.judge(path, { ...(cwd !== undefined ? { cwd } : {}), ...(signal !== undefined ? { signal } : {}), ...(() => { const b = pathTargetBaseOf(protective, { root: rootPath, cwd }); return b !== undefined ? { base: b } : {}; })() });
     };
     return { check, targetView: matcher.targetView };
 }

package/dist/engine/execution-env/kill-tree.js

@@ -1,4 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
+import { scrubSecretEnv } from "../../core/secret-env.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 const DEFAULT_GRACE_MS = 3000;
@@ -144,6 +145,7 @@ function enumerateDescendantsSync(rootPid) {
     let out;
     try {
         const result = spawnSync("ps", ["-A", "-o", "pid=", "-o", "ppid=", "-o", "etime="], {
+            env: scrubSecretEnv(process.env),
             timeout: PS_ENUMERATION_TIMEOUT_MS,
             encoding: "utf8",
             windowsHide: true,
@@ -209,6 +211,7 @@ function parseEtimeSeconds(etime) {
 function runTaskkill(args) {
     try {
         const child = spawn("taskkill", args, {
+            env: scrubSecretEnv(process.env),
             stdio: "ignore",
             detached: true,
             windowsHide: true,
@@ -268,7 +271,7 @@ function tryMsysGroupKill(bashPath, pid) {
         `[ -n "$g" ] && [ "$g" != "0" ] && kill -9 -"$g" 2>/dev/null; ` +
         `done; exit 0`;
     try {
-        const child = spawn(bashPath, ["-c", script], { stdio: "ignore", detached: true, windowsHide: true });
+        const child = spawn(bashPath, ["-c", script], { env: scrubSecretEnv(process.env), stdio: "ignore", detached: true, windowsHide: true });
         child.on("error", () => { });
         return true;
     }

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

@@ -187,6 +187,9 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     setFileMode(path: string, mode: number, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     canonicalPath(path: string): Promise<Result<string, FileError>>;
+    /** {@link FileSystem.fileIdentity}: `stat` (links followed) read as BIGINT — an inode past 2^53 (an APFS volume root)
+     *  is not exact as a number, and two inodes that collapse to one number would name two directories as one. */
+    fileIdentity(path: string): Promise<Result<string, FileError>>;
     readLink(path: string): Promise<Result<string, FileError>>;
     /**
      * The LEAF symlink chain ({@link FileSystem.canonicalChain}): `readlink` on the whole spelling, then on each

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

@@ -1,13 +1,13 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, statSync, truncateSync, unlinkSync } from "node:fs";
-import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, unlink, writeFile, } from "node:fs/promises";
+import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
 import { killProcessTree, shutdownDebug } from "./kill-tree.js";
-import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, scrubSecretEnv } from "../../core/secret-env.js";
+import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, inheritedHostEnv, scrubSecretEnv } from "../../core/secret-env.js";
 import { physicalPathOfAsync } from "../../core/physical-path.js";
 import { isUncSpelling } from "../../tools/fs/safety.js";
 import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
@@ -119,6 +119,7 @@ async function runCommand(command, args, timeoutMs) {
             child = spawn(command, args, {
                 stdio: ["ignore", "pipe", "ignore"],
                 windowsHide: true,
+                env: scrubSecretEnv(process.env),
             });
         }
         catch {
@@ -203,44 +204,32 @@ export function __resetSecretScrubAnnouncement() {
     __resetSecretEnvScrubNoticeAnnouncement();
 }
 function getShellEnv(inheritEnv, baseEnv, extraEnv, onScrub, onNotice) {
-    let inherited;
-    if (inheritEnv === "all") {
-        inherited = process.env;
-    }
-    else if (Array.isArray(inheritEnv)) {
-        inherited = {};
-        for (const k of inheritEnv)
-            if (process.env[k] !== undefined)
-                inherited[k] = process.env[k];
-    }
-    else {
-        const scrubbed = [];
-        inherited = scrubSecretEnv(process.env, scrubbed, process.platform);
-        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 {
+    const scrubbed = [];
+    const inherited = inheritedHostEnv(inheritEnv, 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, () => {
+                    });
                 }
             }
-            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 {
-                }
+            catch {
             }
-            if (!(typeof onScrub === "function" && onNotice === undefined)) {
-                announceSecretEnvScrub(onNotice, findings);
+        }
+        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 (!(typeof onScrub === "function" && onNotice === undefined)) {
+            announceSecretEnvScrub(onNotice, findings);
+        }
     }
     return {
         ...inherited,
@@ -1021,6 +1010,16 @@ export class NodeExecutionEnv {
             return err(toFileError(error, resolved));
         }
     }
+    async fileIdentity(path) {
+        const resolved = resolvePath(this.cwd, path);
+        try {
+            const s = await stat(resolved, { bigint: true });
+            return ok(`${s.dev}:${s.ino}`);
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
     async readLink(path) {
         const resolved = resolvePath(this.cwd, path);
         try {