@sema-agent/core 7.17.0 → 7.17.1

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

@@ -1,13 +1,14 @@
 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, realpath, rename, rm, unlink, writeFile, } from "node:fs/promises";
+import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, unlink, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } 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 { scrubSecretEnv } from "../../core/secret-env.js";
+import { physicalPathOfAsync } from "../../core/physical-path.js";
 import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import { SchedulerError } from "../../core/scheduler.js";
@@ -802,7 +803,7 @@ export class NodeExecutionEnv {
                 let hop;
                 try {
                     const link = await readlink(resolved);
-                    const parentReal = await realpath(resolve(resolved, "..")).catch(() => resolve(resolved, ".."));
+                    const parentReal = await physicalPathOfAsync(resolve(resolved, "..")).catch(() => resolve(resolved, ".."));
                     hop = isAbsolute(link) ? link : resolve(parentReal, link);
                 }
                 catch {
@@ -1004,7 +1005,7 @@ export class NodeExecutionEnv {
     async canonicalPath(path) {
         const resolved = resolvePath(this.cwd, path);
         try {
-            return ok(await realpath(resolved));
+            return ok(await physicalPathOfAsync(resolved));
         }
         catch (error) {
             return err(toFileError(error, resolved));

package/dist/index.d.ts

@@ -83,6 +83,7 @@ export { getShellConfig, isWslBashLauncher } from "./engine/execution-env/node-e
 export { isSecretEnvKey, scrubSecretEnv } from "./core/secret-env.js";
 export type { SecretEnvFinding, SecretEnvFindingKind } from "./core/secret-env.js";
 export { MAX_EXEC_OUTPUT_BYTES, RollingTailBuffer, markTruncated } from "./core/exec-output-tail.js";
+export { physicalPathOf, physicalPathOfExisting } from "./core/physical-path.js";
 export type { ExecutionEnv, FileInfo, Result, FileErrorCode, ExecutionErrorCode, WriteExpectation, WriteReceipt } from "./internal/harness.js";
 export type { ExecResult } from "./internal/harness.js";
 export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, missingRestoreSurface, isRetryableRemoteErrorCode, RETRYABLE_REMOTE_ERROR_CODES, } from "./core/remote-env.js";

package/dist/index.js

@@ -68,6 +68,7 @@ export { killProcessTree, signalProcessTree } from "./engine/execution-env/kill-
 export { getShellConfig, isWslBashLauncher } from "./engine/execution-env/node-execution-env.js";
 export { isSecretEnvKey, scrubSecretEnv } from "./core/secret-env.js";
 export { MAX_EXEC_OUTPUT_BYTES, RollingTailBuffer, markTruncated } from "./core/exec-output-tail.js";
+export { physicalPathOf, physicalPathOfExisting } from "./core/physical-path.js";
 export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, missingRestoreSurface, isRetryableRemoteErrorCode, RETRYABLE_REMOTE_ERROR_CODES, } from "./core/remote-env.js";
 export { withRetry } from "./core/with-retry.js";
 export { addWorktree, pruneWorktrees, WORKTREE_PARENT } from "./core/git-worktree-env.js";

package/dist/orchestration/workflow-script-store.js

@@ -1,5 +1,6 @@
-import { mkdirSync, readFileSync, realpathSync, writeFileSync, existsSync } from "node:fs";
-import { basename, dirname, join, resolve, sep } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { physicalPathOfExisting } from "../core/physical-path.js";
 import { sanitizeScope } from "../stores/file/fs-atomic.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -33,23 +34,6 @@ function safeFileStem(id) {
 function containedBy(root, p) {
     return p === root || p.startsWith(root + sep);
 }
-function canonicalizeDeepestExisting(p) {
-    let cur = p;
-    const missingTail = [];
-    for (;;) {
-        try {
-            const real = realpathSync(cur);
-            return missingTail.length === 0 ? real : join(real, ...[...missingTail].reverse());
-        }
-        catch {
-            const parent = dirname(cur);
-            if (parent === cur)
-                return undefined;
-            missingTail.push(basename(cur));
-            cur = parent;
-        }
-    }
-}
 export function createFileWorkflowScriptStore(dir) {
     const root = resolve(dir);
     const scopeDir = (scope) => join(root, sanitizeScope(scope));
@@ -71,17 +55,17 @@ export function createFileWorkflowScriptStore(dir) {
             if (!containedBy(base, full)) {
                 throw new Error(`workflow script store: scriptPath is outside this scope's script partition`);
             }
-            const physRoot = canonicalizeDeepestExisting(root);
-            const physBase = canonicalizeDeepestExisting(base);
-            const physFull = canonicalizeDeepestExisting(full);
+            const physRoot = physicalPathOfExisting(root);
+            const physBase = physicalPathOfExisting(base);
+            const physFull = physicalPathOfExisting(full);
             const refusePhysical = () => {
                 throw new Error(`workflow script store: scriptPath is outside this scope's script partition after symlink resolution`);
             };
-            if (physRoot !== undefined && physBase !== undefined && !containedBy(physRoot, physBase))
+            if (!containedBy(physRoot, physBase))
                 refusePhysical();
-            if (physBase !== undefined && physFull !== undefined && !containedBy(physBase, physFull))
+            if (!containedBy(physBase, physFull))
                 refusePhysical();
-            return readFileSync(physFull ?? full, "utf-8");
+            return readFileSync(physFull, "utf-8");
         },
         resolveName(name) {
             if (/^wf_/i.test(name))

package/dist/orchestration/workflow.js

@@ -460,6 +460,9 @@ export const workflowResumeClaimFallback = {
             table.delete(key);
     },
 };
+function parkLaneArmed(opts) {
+    return opts.store !== undefined && opts.checkpointStore !== undefined;
+}
 export function startWorkflow(runner, fn, opts = {}, internals) {
     const alsDepth = currentWorkflowDepth();
     const internalDepth = internals?.workflowDepth;
@@ -472,10 +475,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     if (opts.resumeFromRunId !== undefined && opts.journalStore === undefined) {
         throw new Error("runWorkflow: resumeFromRunId requires a journalStore to load the prior run's journal");
     }
-    if (opts.checkpointStore !== undefined && opts.store === undefined) {
+    if (opts.checkpointStore !== undefined && !parkLaneArmed(opts)) {
         throw new WorkflowParkRefusal("workflow.park_requires_run_store", "runWorkflow: checkpointStore (the store this run's children park in) requires a WorkflowRunStore — a workflow child's park is recorded on its wa* row and proven against the checkpoint store at the next resume, and without a run store there is no durable row for a host to route the parked approval by", {});
     }
-    if (opts.defaultDurableApproval !== undefined && (opts.store === undefined || opts.checkpointStore === undefined)) {
+    if (opts.defaultDurableApproval !== undefined && !parkLaneArmed(opts)) {
         throw new WorkflowParkRefusal("workflow.park_requires_run_store", "runWorkflow: defaultDurableApproval requires a WorkflowRunStore and a checkpointStore — a workflow child's park is recorded on its wa* row and read back from the checkpoint store at the next resume; without both there is no durable row for a host to route the parked approval by, or no way for a resume to prove the park", {});
     }
     if (opts.parkedResume !== undefined && opts.resumeFromRunId === undefined) {
@@ -917,7 +920,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         const seat = s.checkpointStore;
         if (seat === undefined || seat === "disabled")
             return;
-        if (parkSeat === undefined) {
+        if (!parkLaneArmed(opts)) {
             throw new WorkflowParkRefusal("workflow.park_requires_run_store", "workflow agent: the child's checkpointStore would let it park where this workflow cannot read the park back — a workflow whose children can park needs a WorkflowRunStore and that checkpoint store as its read seat (RunWorkflowOptions.store + checkpointStore); wire both, or leave the child's seat unset.", {});
         }
         if (seat !== parkSeat) {

package/dist/stores/cc/task-list-store.js

@@ -2,21 +2,13 @@ import { readFileSync, readdirSync, mkdirSync, unlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { assertJsonMetadata, normalizeTaskShape } from "../../tools/task-list.js";
 import { atomicWriteFile } from "../file/fs-atomic.js";
-import { realpathSync } from "node:fs";
-function realpathSyncSafe(p) {
-    try {
-        return realpathSync(p);
-    }
-    catch {
-        return p;
-    }
-}
+import { physicalPathOf } from "../../core/physical-path.js";
 import { withCcLock } from "./lockfile.js";
 export function createCcFileTaskListStore(listDir) {
     const dir = resolve(listDir);
     mkdirSync(dir, { recursive: true });
     const hwmPath = join(dir, ".highwatermark");
-    const lockTarget = realpathSyncSafe(dir);
+    const lockTarget = physicalPathOf(dir);
     const CC_TASK_ID_RE = /^[A-Za-z0-9_-]+$/;
     const validId = (id) => CC_TASK_ID_RE.test(id);
     const taskPath = (id) => {

package/dist/stores/file/fs-atomic.d.ts

@@ -11,10 +11,8 @@ export declare function sanitizePathComponent(raw: string): string;
  * on-disk dir name, never the stored data. Never `path.join` a raw scope.
  */
 export declare function sanitizeScope(scope: string): string;
-/**
- * Resolve the data root (CC `getClaudeConfigHomeDir` analog): `$AGENT_DATA_DIR ?? ~/.ai-agent`,
- * NFC-normalized, and `realpath`-canonicalized once the dir exists. Creates the dir (0o700) if absent.
- */
+/** Resolve the data root (CC `getClaudeConfigHomeDir` analog): `$AGENT_DATA_DIR ?? ~/.ai-agent`,
+ *  NFC-normalized, canonicalized once the dir exists. Creates the dir (0o700) if absent. */
 export declare function resolveDataRoot(explicit?: string): string;
 /** Ensure a directory exists with 0o700 perms (idempotent). */
 /**
@@ -59,25 +57,24 @@ export declare function readJsonlRecords<T>(path: string, onCorrupt?: (info: {
  * append (the checkpoint commit point ALWAYS fsyncs; session/memory cadence is the caller's `fsyncEvery`).
  */
 /**
- * RB-144 (2026-07-25, 按面收口): THE canonical key for "one authority per physical location".
- *
- * Every file backend keeps a module-level table so that N instances over one directory collapse into one
- * CAS authority. Getting the KEY wrong reopens the exact defect the table exists to close — and this repo
- * has now paid for that four separate times: RB-62 taught the mailbox to realpath, RB-101 taught the
- * session store, RB-119 added case folding there, and a defect hunt then found the agent store, the run store
- * and the task-list still keying on a lexical `resolve()` while two of them cite the mailbox as the
- * precedent they copied. Point fixes kept missing siblings, so the rule now lives in ONE place that all of
- * them call.
+ * RB-144: THE canonical key for "one authority per physical location". Every file backend keeps a
+ * module-level table so that N instances over one directory collapse into one CAS authority; getting the
+ * KEY wrong reopens the defect the table exists to close, which this repo paid for four times (mailbox,
+ * session store, then the agent/run/task-list stores still keying on a lexical `resolve()`). Point fixes
+ * kept missing siblings, so the rule lives in ONE place they all call.
  *
  * Two normalizations, each for a demonstrated failure:
- *  - REALPATH — a symlinked data dir (`/var` → `/private/var` on macOS, a container bind-mount, a linked
+ *  - PHYSICAL PATH — a symlinked data dir (`/var` → `/private/var` on macOS, a bind-mount, a linked
  *    `~/.ai-agent`) otherwise yields two authorities for one directory, and both writers win the CAS.
- *  - CASE FOLD — on a case-insensitive filesystem (macOS/Windows default) `Foo/` and `foo/` are the same
- *    directory; `realpath` does NOT fold case there, so realpath alone is not enough (measured).
+ *  - CASE FOLD — on a case-insensitive filesystem `Foo/` and `foo/` are the same directory. The mint
+ *    answers with the on-disk spelling, which folds the two only where the entry EXISTS; the fold here
+ *    also covers a not-yet-created tail, and folding a PATH would name a different directory on a
+ *    case-SENSITIVE volume (see the cc task-list store's lock target, which must not fold) — so it stays
+ *    at this call site, which keys, rather than inside the mint, which answers about paths.
  *
  * The key is used ONLY for table lookup — never for I/O, so the on-disk name stays verbatim. A path that
- * does not exist yet resolves through its parent directory; if even that fails, the lexical form is used
- * (a store must not fail to construct because canonicalization is unavailable).
+ * does not exist yet resolves through its deepest existing ancestor; a path with no resolvable ancestor at
+ * all keys on its lexical form (a store must not fail to construct because canonicalization is unavailable).
  */
 export declare function canonicalStoreKey(p: string): string;
 export declare class AppendLog {

package/dist/stores/file/fs-atomic.js

@@ -1,9 +1,10 @@
-import { closeSync, constants as FS, existsSync, fstatSync, linkSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, truncateSync, unlinkSync, writeFileSync, writeSync, fsyncSync, } from "node:fs";
+import { closeSync, constants as FS, existsSync, fstatSync, linkSync, mkdirSync, openSync, readFileSync, readSync, renameSync, truncateSync, unlinkSync, writeFileSync, writeSync, fsyncSync, } from "node:fs";
 import { homedir, hostname, uptime } from "node:os";
 import { hrtime } from "node:process";
 import { basename, dirname, join, resolve as resolvePath } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { execFileSync } from "node:child_process";
+import { physicalPathOf, physicalPathOfExisting } from "../../core/physical-path.js";
 const SAFE_COMPONENT = /^[A-Za-z0-9_.-]+$/;
 export function sanitizePathComponent(raw) {
     if (raw === "" || raw === "." || raw === ".." || !SAFE_COMPONENT.test(raw)) {
@@ -18,7 +19,7 @@ export function sanitizeScope(scope) {
 export function resolveDataRoot(explicit) {
     const raw = (explicit ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent")).normalize("NFC");
     mkdirSync(raw, { recursive: true, mode: 0o700 });
-    return realpathSync(raw);
+    return physicalPathOf(raw);
 }
 export function writeThenLink(target, content) {
     ensureDir(dirnameOf(target));
@@ -134,18 +135,7 @@ export function readJsonlRecords(path, onCorrupt) {
     return out;
 }
 export function canonicalStoreKey(p) {
-    const abs = resolvePath(p);
-    try {
-        return realpathSync(abs).toLowerCase();
-    }
-    catch {
-        try {
-            return join(realpathSync(dirname(abs)), basename(abs)).toLowerCase();
-        }
-        catch {
-            return abs.toLowerCase();
-        }
-    }
+    return physicalPathOfExisting(p).toLowerCase();
 }
 export class AppendLog {
     fd;

package/dist/stores/file/mailbox-store.d.ts

@@ -81,17 +81,13 @@ export declare class FileMailboxStore implements MailboxStore {
     /**
      * The canonical mutex / shared-state key — instance-independent (X-5).
      *
-     * RB-162 (2026-07-26): this went through `realpath` (RB-62) but NOT the case fold (RB-67/RB-119), even
-     * though the module header above claims "the shared-state KEY goes through `canonicalStoreKey`, which
-     * also folds case". It did not — that name appeared exactly once in this file, inside that sentence.
-     * The handle component was folded by `boxPath`, but the ROOT was not: two spellings of the same
-     * directory on a case-insensitive filesystem produced two shared-state slots over one physical file, and
-     * each allocated its own `seq` — the very contract violation the realpath comment above describes,
-     * reached by the other half of the same canonicalization.
-     *
-     * Worse for the record: the enumerative guard written for this exact family tested
-     * `src.includes("canonicalStoreKey")`, which that one comment satisfied. The guard was green because the
-     * file talked about the rule.
+     * RB-162: this went through the physical path but NOT the case fold, even though the module header
+     * claimed otherwise. The handle component was folded by `boxPath` while the ROOT was not, so two
+     * spellings of one directory on a case-insensitive filesystem produced two shared-state slots over one
+     * physical file, each allocating its own `seq` — the same contract violation the RB-62 comment above
+     * describes, reached by the other half of the same canonicalization. The enumerative guard written for
+     * this family tested `src.includes("canonicalStoreKey")`, which the CLAIM satisfied: a guard that reads
+     * prose is green while the code diverges.
      */
     private lockKey;
     /**

package/dist/stores/file/mailbox-store.js

@@ -1,18 +1,11 @@
 import { join, resolve, sep } from "node:path";
 import { randomBytes } from "node:crypto";
 import { assertRetentionPolicy } from "../../core/retention-policy.js";
-import { existsSync, linkSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { detachMailboxMessage, newestSentAt, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
+import { physicalPathOf } from "../../core/physical-path.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
-function realpathSyncSafe(p) {
-    try {
-        return realpathSync(p);
-    }
-    catch {
-        return p;
-    }
-}
 function diskMarkOf(path) {
     try {
         const st = statSync(path);
@@ -361,8 +354,8 @@ export class FileMailboxStore {
         const lexicalTmp = resolve(join(root, "tmp"));
         ensureDir(lexicalDir);
         ensureDir(lexicalTmp);
-        this.dir = realpathSyncSafe(lexicalDir);
-        this.tmpDir = realpathSyncSafe(lexicalTmp);
+        this.dir = physicalPathOf(lexicalDir);
+        this.tmpDir = physicalPathOf(lexicalTmp);
     }
     boxPath(scope, handle) {
         return join(this.dir, sanitizeScope(scope), `${sanitizePathComponent(handle).toLowerCase()}.jsonl`);

package/dist/tools/artifact/local-stub.js

@@ -1,7 +1,8 @@
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import {} from "../../core/artifact-host.js";
+import { physicalPathOf } from "../../core/physical-path.js";
 import { acquireStoreDirLock } from "../../stores/file/fs-atomic.js";
 import { normalizePublishedPath } from "./artifact-tool.js";
 export const EVAL_STUB_URL_PREFIX = "eval-stub://artifact/";
@@ -112,9 +113,9 @@ export class LocalArtifactStub {
     }
     #snapshotOf(row) {
         const base = this.#versionDir(row.slug, row.version);
-        const realBase = realpathSync(base);
+        const realBase = physicalPathOf(base);
         const files = row.files.map((f) => {
-            const target = realpathSync(resolve(base, ...f.path.split("/")));
+            const target = physicalPathOf(resolve(base, ...f.path.split("/")));
             if (!target.startsWith(realBase + sep))
                 throw new Error(`artifact stub ledger is corrupt (a file resolves outside its version directory): ${this.#ledgerPath()}`);
             return { path: f.path, content: new Uint8Array(readFileSync(target)), ...(f.mediaType !== undefined ? { mediaType: f.mediaType } : {}) };

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -321,9 +321,18 @@ export interface CompoundReadonlyVerdict {
      * (`cd -`, bare `cd`, a pattern). The STRUCTURAL form of the unresolvable sentence: `reason` carries the
      * first one's sentence, this member every one of them, and both survive whatever other sentence (a shape
      * refusal) takes precedence. CONSUMER CONTRACT: non-empty ⇒ the boundary could not read where the command
-     * reads — a fail-closed ask (plain: nothing was declared), never a vouch.
+     * reads — a fail-closed ask, never a vouch (plain on the classify seat, whose classifier asks beside it; MANDATED on the
+     * boundary-only seat, where nothing else would ask).
      */
     unresolvedOperands?: readonly string[];
+    /**
+     * The grammar gate refused the WHOLE command before the walk ran (an escape, a substitution, a subshell, a
+     * redirection, a line break — see {@link rejectedSansRedirection} and the compound gate): no operand was judged,
+     * and what the shell would run is not knowable from the text (a reader can be spelled `ca\t`, fed by `<`, or hidden
+     * in `$(…)`). CONSUMER CONTRACT: present ⇒ the boundary judged nothing — MANDATED on both probe seats (a name-reading
+     * arm or a stored allow rule must not retire a read nobody judged). Structure, never the sentence.
+     */
+    refusedWhole?: true;
     /**
      * Operands of a RECURSIVE/EXPANDING read form (`grep -r`, `ls -R`, `du`, … — see
      * {@link RECURSIVE_READ_FORMS}) judged with a {@link BashReadonlyRootBoundary.denyMatch} seat wired.
@@ -380,6 +389,13 @@ export declare function formatOutOfRootReadApprovalOption(directory: string): st
  *  has no filesystem and stays lexical, and a REMOTE env keeps the lexical behaviour (its
  *  `canonicalPath` is an RPC per candidate). */
 export declare function resolveOperandLexically(base: string | undefined, operand: string, homeDir: string | undefined): string | undefined;
+/** Whether a command the grammar gate REFUSED WHOLE carries evidence that it may READ: a listed reader or a shell
+ *  re-entry program anywhere in it, a substitution where a program name stands (`$C /etc/passwd`), or a stdin
+ *  redirection from a non-literal target (`cat < $F`). The out-of-root and base-mover readings over its literal path
+ *  tokens are the containment gate's, asked separately. A refused command with none of these — a write through a
+ *  redirection (`echo hi > out.txt`), a function definition — names no read for the boundary to mandate: the syntax
+ *  refusal stays the classify seat's own plain ask. */
+export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>): boolean;
 /**
  * The home directory's VARIABLE spellings, SUBSTITUTED with the declared value before a read face segments the
  * command: `$HOME` / `${HOME}` at the START of a word (an empty quote pair before it included), unquoted or

package/dist/tools/fs/bash-readonly-classifier.js

@@ -1,4 +1,4 @@
-import { isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, pathFamilyOf, withinAnyRoot } from "./safety.js";
+import { isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf, withinAnyRoot } from "./safety.js";
 export const NOT_AUTO_ALLOWED = "— not auto-allowed";
 export const BASH_READONLY_DEFAULT_ALLOW = [
     "ls", "cat", "head", "tail", "wc", "pwd", "echo", "whoami", "uname",
@@ -224,6 +224,8 @@ export function resolveOperandLexically(base, operand, homeDir) {
         return undefined;
     }
     const family = base === undefined ? undefined : pathFamilyOf({ root: base });
+    if (!win32NamespaceScreen(raw, family).ok)
+        return undefined;
     if (isAbsoluteForFamily(family, raw))
         return normalizeAbsPathLexically(nativeUncSpellingOf(family, raw));
     if (base === undefined || family === undefined || !isAbsoluteForFamily(family, base))
@@ -232,6 +234,78 @@ export function resolveOperandLexically(base, operand, homeDir) {
         return undefined;
     return normalizeAbsPathLexically(joinForFamily(family, base, raw));
 }
+function reheadSegment(toks, head, from = 0) {
+    return { folded: [head, ...toks.folded.slice(from + 1)], raw: [head, ...toks.raw.slice(from + 1)] };
+}
+const SHELL_CONTROL_PREFIXES = new Set(["!", "if", "then", "elif", "else", "while", "until", "do", "time"]);
+const SHELL_BLOCK_WORDS = new Set(["for", "select", "case", "esac", "fi", "done", "function", "coproc", "[[", "]]", "in"]);
+function isBareControlWord(toks, i, words) {
+    const word = toks.folded[i];
+    return word !== undefined && toks.raw[i] === word && words.has(word);
+}
+function tokensMoveBase(toks, allow) {
+    let from = 0;
+    while (from < toks.folded.length && isBareControlWord(toks, from, SHELL_CONTROL_PREFIXES))
+        from++;
+    const head = toks.folded[from];
+    if (head === undefined)
+        return false;
+    if (toks.raw[from] !== head)
+        return true;
+    if (head === "cd")
+        return true;
+    if (!COMMAND_LAUNCHERS.has(head))
+        return false;
+    const unwrapped = unwrapLauncher(toks.folded.slice(from), allow);
+    return unwrapped.kind === "refused" || (unwrapped.kind === "reader" && unwrapped.head === "cd");
+}
+const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi)?sh|eval|source|\.)$/;
+export function refusedCommandMayRead(command, allow) {
+    for (const m of command.matchAll(/(?<![<>&\d])<(?![<&])\s*(\S*)/g)) {
+        const target = (m[1] ?? "").replace(/^["']+|["']+$/g, "");
+        if (target === "" || /^[$`(~]/.test(target))
+            return true;
+    }
+    const fold = (w) => w.replace(/\\(.)/g, "$1").replace(/["']/g, "");
+    const programOf = (w) => {
+        const inner = fold(w).replace(/^[$`(]+|[)`]+$/g, "");
+        return inner.includes("/") ? inner.slice(inner.lastIndexOf("/") + 1) : inner;
+    };
+    for (const word of command.split(/[\s<>|;&()]+/)) {
+        const base = programOf(word);
+        if (base === "")
+            continue;
+        if ((allow.has(base) && !NO_PATH_OPERAND_COMMANDS.has(base)) || SHELL_REENTRY_PROGRAM_RE.test(base))
+            return true;
+    }
+    for (const segment of command.split(/\n|;|&&|\|\||\||(?<![>&\d])&(?![>&])/)) {
+        for (const raw of segment.trim().split(/\s+/)) {
+            const word = fold(raw);
+            if (word === "")
+                continue;
+            if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word) || SHELL_CONTROL_PREFIXES.has(word) || SHELL_BLOCK_WORDS.has(word) || word === "{" || word === "}" || COMMAND_LAUNCHERS.has(programOf(word)) || word.startsWith("-"))
+                continue;
+            if (/^[$`(]/.test(word))
+                return true;
+            break;
+        }
+    }
+    return false;
+}
+function unwrapLauncher(folded, allow) {
+    for (let i = 1; i < folded.length; i++) {
+        const t = folded[i];
+        if (ASSIGNMENT_WORD.test(t) || /^\d+[smhd]?$/.test(t) || COMMAND_LAUNCHERS.has(t))
+            continue;
+        if (t.startsWith("-"))
+            return { kind: "refused", reason: `"${folded[0]}" is given an option before the program it runs — which program runs is not readable without the launcher's option table ${NOT_AUTO_ALLOWED}` };
+        const head = t.includes("/") ? t.slice(t.lastIndexOf("/") + 1) : t;
+        if (SHELL_CONTROL_PREFIXES.has(head) || SHELL_BLOCK_WORDS.has(head))
+            return { kind: "refused", reason: `"${folded[0]}" is given shell control syntax ("${head}") where the program it runs would be ${NOT_AUTO_ALLOWED}` };
+        return allow.has(head) || head === "cd" ? { kind: "reader", index: i, head } : { kind: "unlisted" };
+    }
+    return { kind: "unlisted" };
+}
 function tokenizeSegment(segment) {
     const raw = splitWordsQuoteAware(segment);
     return { folded: raw.map((r) => { const f = foldQuoteRemovalToken(r); return tildeIsLiteral(r) ? literalTildeSpelling(f) : f; }), raw };
@@ -803,12 +877,51 @@ function segmentCompoundForReadonly(command, homeDir) {
 export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts) {
     const split = segmentCompoundForReadonly(command, boundary?.homeDir);
     if ("reject" in split)
-        return { reason: split.reject };
+        return { reason: split.reject, refusedWhole: true };
     const { segments, pipeFed } = split;
-    for (const segment of segments) {
-        const reason = coarseReadonlyCheck(segment, allow, { quotedOperatorsAreText: true });
-        if (reason !== undefined)
-            return { reason };
+    let nameRefusal;
+    const unlistedSegments = new Set();
+    const reheaded = new Map();
+    for (let si = 0; si < segments.length; si++) {
+        const toks = tokenizeSegment(segments[si]);
+        const folded = toks.folded;
+        let from = 0;
+        while (from < folded.length && isBareControlWord(toks, from, SHELL_CONTROL_PREFIXES))
+            from++;
+        const written = folded[from];
+        if (written === undefined)
+            return { reason: "empty command" };
+        if (isBareControlWord(toks, from, SHELL_BLOCK_WORDS)) {
+            unlistedSegments.add(si);
+            nameRefusal ??= `command "${written}" is not in the read-only allowlist`;
+            continue;
+        }
+        const parsed = parseLeadingCommandName(toks.raw.slice(from).join(" "), { quotedOperatorsAreText: true, pathPrefixedNameIsText: true });
+        if ("reject" in parsed)
+            return { reason: parsed.reject, refusedWhole: true };
+        const pathPrefixed = parsed.name.includes("/");
+        const name = pathPrefixed ? parsed.name.slice(parsed.name.lastIndexOf("/") + 1) : parsed.name;
+        if (pathPrefixed)
+            nameRefusal ??= "the command must be a bare name resolved via PATH (no path prefix)";
+        if (allow.has(name)) {
+            if (pathPrefixed || from > 0)
+                reheaded.set(si, { from, head: name });
+            if (from > 0)
+                nameRefusal ??= `command "${folded[0]}" is not in the read-only allowlist`;
+            continue;
+        }
+        nameRefusal ??= `command "${parsed.name}" is not in the read-only allowlist`;
+        if (COMMAND_LAUNCHERS.has(name)) {
+            const unwrapped = unwrapLauncher(folded.slice(from), allow);
+            if (unwrapped.kind === "refused")
+                return { reason: unwrapped.reason, refusedWhole: true };
+            if (unwrapped.kind === "unlisted")
+                unlistedSegments.add(si);
+            else
+                reheaded.set(si, { from: from + unwrapped.index, head: unwrapped.head });
+            continue;
+        }
+        unlistedSegments.add(si);
     }
     const HEAD_AUTO_ALLOW_MAX = 1_000_000;
     const headBoundIsSmall = (name, toks) => {
@@ -840,9 +953,12 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     };
     const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity, diff: 2, cmp: 2, comm: 2, sed: 2 };
     const foldedSegments = [];
-    let shapeRefusal;
+    let shapeRefusal = nameRefusal;
     for (let si = 0; si < segments.length; si++) {
-        const segmentTokens = tokenizeSegment(segments[si]);
+        if (unlistedSegments.has(si))
+            continue;
+        const rehead = reheaded.get(si);
+        const segmentTokens = rehead === undefined ? tokenizeSegment(segments[si]) : reheadSegment(tokenizeSegment(segments[si]), rehead.head, rehead.from);
         const toks = segmentTokens.folded;
         if (toks.length === 0)
             continue;
@@ -1187,10 +1303,7 @@ export function classifyBoundedReadonlyPollLoopDetailed(command, allow, boundary
     if (readSegments.length === 0) {
         return { reason: "the loop body has no read command — a sleep-only loop observes nothing and is not auto-allowed" };
     }
-    const bodyHasCd = readSegments.some((seg) => {
-        const p = parseLeadingCommandName(seg);
-        return "name" in p && p.name === "cd";
-    });
+    const bodyHasCd = readSegments.some((seg) => tokensMoveBase(tokenizeSegment(seg), allow));
     const modelled = bodyHasCd ? Array.from({ length: beats }, () => readSegments.join("; ")).join("; ") : readSegments.join("; ");
     const verdict = classifyCompoundReadonlyDetailed(modelled, allow, boundary, { iterated: bodyHasCd });
     if (verdict.reason !== undefined)