@sema-agent/core 7.23.0 → 7.23.2

package/dist/orchestration/workflow.js

@@ -23,6 +23,7 @@ import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
 import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
 import { STALL_CONNECT_MS, STALL_FIRST_TOKEN_MS } from "../brain/timeout.js";
+import { asThrownError, thrownText } from "../core/thrown-value.js";
 export * from "./workflow-types.js";
 const MAX_TRANSCRIPT_CHARS = 4000;
 const WORKFLOW_RESULT_MAX = 4000;
@@ -193,7 +194,7 @@ function foldFanOutSettled(settled, lane, errorsOut, emitRunLog) {
         }
         rethrowIfMaxAgents(s.e);
         errorsOut?.push(workflowFanOutSlotError(s.i, s.e));
-        emitRunLog(`${lane}[${s.i}] failed: ${boundedRedactedSummary(s.e instanceof Error ? s.e.message : String(s.e), 300)}`);
+        emitRunLog(`${lane}[${s.i}] failed: ${boundedRedactedSummary(thrownText(s.e), 300)}`);
         return null;
     });
     if (dropped > 0)
@@ -203,7 +204,7 @@ function foldFanOutSettled(settled, lane, errorsOut, emitRunLog) {
 function workflowFanOutSlotError(index, e) {
     const code = e?.code;
     const kind = typeof code === "string" && code.length > 0 ? code : e instanceof Error ? e.name : "Error";
-    return { index, kind, message: boundedRedactedSummary(e instanceof Error ? e.message : String(e), 300) };
+    return { index, kind, message: boundedRedactedSummary(thrownText(e), 300) };
 }
 export class WorkflowResultTooLargeError extends Error {
     size;
@@ -841,7 +842,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     };
     const parkSeat = opts.checkpointStore;
     const parkedByOrdinal = [];
-    const errText = (err) => (err instanceof Error ? err.message : String(err));
+    const errText = (err) => (thrownText(err));
     const withoutToken = (text, token) => (token === "" ? text : text.split(token).join("<token>"));
     const parkBindingBroken = (ordinal, why) => new WorkflowParkRefusal("workflow.park_binding_broken", `workflow resume: ordinal ${ordinal}'s park cannot be bound to its checkpoint (${why}) — the recorded park is inconsistent. Decide the checkpoint through the deployment's approval channel and start a fresh run.`, { ordinal });
     const readParkTruth = async (seat, key, ordinal) => {
@@ -980,7 +981,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             }
             catch (err) {
                 if (dbg)
-                    console.error(`[sema:wf-journal] runId=${runId} callKey=${callKey} TOMBSTONE-ERROR ${err instanceof Error ? err.message : String(err)}`);
+                    console.error(`[sema:wf-journal] runId=${runId} callKey=${callKey} TOMBSTONE-ERROR ${thrownText(err)}`);
             }
             return;
         }
@@ -993,7 +994,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         }
         catch (err) {
             if (dbg)
-                console.error(`[sema:wf-journal] runId=${runId} callKey=${callKey} APPEND-ERROR ${err instanceof Error ? err.message : String(err)}`);
+                console.error(`[sema:wf-journal] runId=${runId} callKey=${callKey} APPEND-ERROR ${thrownText(err)}`);
             throw err;
         }
     };
@@ -1271,7 +1272,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 inheritedModelSnap = opts.defaultModel?.();
             }
             catch (err) {
-                inheritedModelError = err instanceof Error ? err : new Error(String(err));
+                inheritedModelError = asThrownError(err);
             }
         }
         const inheritedThinkingSnap = spec.thinking === undefined ? opts.defaultThinking?.() : undefined;
@@ -1781,17 +1782,17 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     const journaled = journalAppend(callKey, salvaged ?? {
                         taskId: callKey,
                         sessionId: "",
-                        result: boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500),
+                        result: boundedRedactedSummary(thrownText(err), 500),
                         terminal: {
                             kind: "failed",
                             ...(err instanceof WorkflowAgentBlockedError ? { code: WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } : err instanceof WorkflowBudgetExceededError ? { code: err.code } : {}),
-                            message: boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500),
+                            message: boundedRedactedSummary(thrownText(err), 500),
                         },
                         stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
                     }, label).catch(() => undefined);
                     if (!((err instanceof WorkflowBudgetExceededError || err instanceof WorkflowAgentParkedError) && rec.startedAt === undefined))
                         await journaled;
-                    bceTerminal(callKey, "failed", rec.output ?? (err instanceof Error ? err.message : String(err)), rec.sessionId, rec.stats);
+                    bceTerminal(callKey, "failed", rec.output ?? (thrownText(err)), rec.sessionId, rec.stats);
                 }
                 throw err;
             }
@@ -1969,7 +1970,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 }
                 recordFailed();
                 releaseLeg();
-                bceTerminal(callKey, "failed", err instanceof Error ? err.message : String(err), undefined, undefined);
+                bceTerminal(callKey, "failed", thrownText(err), undefined, undefined);
                 throw err;
             }
             if (childSessionId !== undefined && !finalized) {
@@ -2012,11 +2013,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     void journalAppend(callKey, {
                         taskId: callKey,
                         sessionId: "",
-                        terminal: { kind: "failed", message: boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500) },
-                        result: boundedRedactedSummary(err instanceof Error ? err.message : String(err), 500),
+                        terminal: { kind: "failed", message: boundedRedactedSummary(thrownText(err), 500) },
+                        result: boundedRedactedSummary(thrownText(err), 500),
                         stats: { turns: partialSpend?.turns ?? 0, tokens: partialSpend?.tokens ?? 0, costMicroUsd: partialSpend?.costMicroUsd ?? 0 },
                     }).catch(() => undefined);
-                    bceTerminal(callKey, "failed", err instanceof Error ? err.message : String(err), undefined, rec.stats);
+                    bceTerminal(callKey, "failed", thrownText(err), undefined, rec.stats);
                     throw err;
                 }
                 rollbackUsageBeat();
@@ -2377,7 +2378,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             run.endedAt = now();
             if (parkedLeg !== undefined && !(err instanceof WorkflowAgentParkedError))
                 err = parkedError();
-            run.error = err instanceof Error ? err.message : String(err);
+            run.error = thrownText(err);
             closeAbandonedAgents(run.endedAt);
             {
                 let thrownCode;

package/dist/server/http.js

@@ -1,4 +1,5 @@
 import http from "node:http";
+import { thrownText } from "../core/thrown-value.js";
 const DEFAULT_MAX_BODY = 5 * 1024 * 1024;
 class HttpError extends Error {
     status;
@@ -25,7 +26,7 @@ async function readJson(req, maxBytes) {
         return JSON.parse(Buffer.concat(chunks).toString("utf8"));
     }
     catch (e) {
-        throw new HttpError(400, `invalid JSON request body: ${e instanceof Error ? e.message : String(e)}`);
+        throw new HttpError(400, `invalid JSON request body: ${thrownText(e)}`);
     }
 }
 function setCors(res, origin) {
@@ -47,7 +48,7 @@ export function createTaskServer(opts) {
         void handle(req, res).catch((err) => {
             if (!res.headersSent) {
                 const status = err instanceof HttpError ? err.status : 500;
-                sendJson(res, status, { error: err instanceof Error ? err.message : String(err) });
+                sendJson(res, status, { error: thrownText(err) });
             }
             else {
                 res.end();

package/dist/stores/file/adoption/adopt.js

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { adoptFilePermissionRuleStore } from "../permission-rule-adopt.js";
 import { BootLock, atomicWriteFile, ensureDir, sanitizeScope } from "../fs-atomic.js";
+import { thrownText } from "../../../core/thrown-value.js";
 import { AdoptionError, NOT_MIGRATED_BY_DESIGN, readRootAdoptionFile, writeRootAdoptionFile, } from "./marker.js";
 const CONFIG_ACCOUNT_FILE = "adoption-configs.json";
 function baselineConfigs(toPrincipal) {
@@ -491,7 +492,7 @@ export async function adoptLocalDataRoot(opts) {
                 catch (err) {
                     if (err instanceof AdoptionError)
                         throw err;
-                    throw new AdoptionError("adoption_rule_leg_refused", `the permission-rule leg refused: ${err instanceof Error ? err.message : String(err)}`);
+                    throw new AdoptionError("adoption_rule_leg_refused", `the permission-rule leg refused: ${thrownText(err)}`);
                 }
                 if (nested.status === "stalled") {
                     return {
@@ -533,7 +534,7 @@ export async function adoptLocalDataRoot(opts) {
                     return {
                         status: "stalled",
                         phase: 4,
-                        error: `the "${leg.store}" carriage leg failed: ${err instanceof Error ? err.message : String(err)} — resume when it is healthy`,
+                        error: `the "${leg.store}" carriage leg failed: ${thrownText(err)} — resume when it is healthy`,
                     };
                 }
                 if (rows !== undefined && (!Number.isSafeInteger(rows) || rows < 0)) {

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

@@ -5,6 +5,7 @@ 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";
+import { thrownText } from "../../core/thrown-value.js";
 const SAFE_COMPONENT = /^[A-Za-z0-9_.-]+$/;
 export function sanitizePathComponent(raw) {
     if (raw === "" || raw === "." || raw === ".." || !SAFE_COMPONENT.test(raw)) {
@@ -411,7 +412,7 @@ export class BootLock {
         }
         catch (err) {
             throw new FileStoreLockError("store.lock_unreadable", `file store: this process still owns the lock file at ${this.lockPath} from an earlier release that ` +
-                `could not remove it, and removing it now failed too (${String(err.message)}); ` +
+                `could not remove it, and removing it now failed too (${thrownText(err)}); ` +
                 `remove it manually`, this.lockPath, process.pid);
         }
         abandonedLocks.delete(this.abandonKey);

package/dist/stores/file/permission-rule-adopt.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { writerOf } from "../../core/permission-rule-store.js";
 import { createPermissionRuleStoreProvider } from "../../core/permission-rule-provider.js";
 import { syncPermissionRules } from "../../core/permission-rule-sync.js";
+import { thrownText } from "../../core/thrown-value.js";
 import { FileDurableRulePartitionProvider, LOCAL_OWNER_FILE, principalRuleFileName, readRuleAdoptionFile, writeRuleAdoptionFile, } from "./permission-rule-store.js";
 export async function adoptFilePermissionRuleStore(opts) {
     if (typeof opts.toPrincipal !== "string" || opts.toPrincipal === "") {
@@ -63,7 +64,7 @@ export async function adoptFilePermissionRuleStore(opts) {
                 });
             }
             catch (err) {
-                return { status: "stalled", phase: 4, error: `the first sync round failed: ${err instanceof Error ? err.message : String(err)}` };
+                return { status: "stalled", phase: 4, error: `the first sync round failed: ${thrownText(err)}` };
             }
             if (!syncResult.ok) {
                 return {

package/dist/stores/file/permission-rule-store.js

@@ -6,6 +6,7 @@ import { PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDel
 import { canonicalize } from "../../core/canonical-json.js";
 import { BootLock } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
+import { thrownText } from "../../core/thrown-value.js";
 function isRuleFile(v) {
     const p = v;
     return typeof p === "object" && p !== null && p.schemaVersion === 4 && Array.isArray(p.rules) && Array.isArray(p.tombstones) && typeof p.rev === "number" && (p.quarantined === undefined || Array.isArray(p.quarantined));
@@ -139,7 +140,7 @@ class FileDurableRulePartition {
             const e = err;
             if (e?.code === "ENOENT")
                 return { absent: true };
-            const why = `could not read ${this.file}: ${e?.message ?? String(err)}; loading zero rules`;
+            const why = `could not read ${this.file}: ${thrownText(err)}; loading zero rules`;
             this.disclose(why);
             return { unreadable: why };
         }

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

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { BaseSessionStorage, StoredSession, SessionError, getEntriesToFork, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
+import { thrownText } from "../../core/thrown-value.js";
 function containSinkThenable(r) {
     if (typeof r?.then === "function") {
         r.then(undefined, () => {
@@ -171,7 +172,7 @@ export class FileSessionRepo {
             }
             catch (err) {
                 if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${err instanceof Error ? err.message : String(err)}) — skipped from the listing`);
+                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the listing`);
                 }
             }
         }
@@ -200,7 +201,7 @@ export class FileSessionRepo {
             }
             catch (err) {
                 if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${err instanceof Error ? err.message : String(err)}) — skipped from the placed listing`);
+                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the placed listing`);
                 }
                 continue;
             }
@@ -238,7 +239,7 @@ export class FileSessionRepo {
             rmSync(this.pathFor(metadata.id), { force: true });
         }
         catch (err) {
-            throw new SessionError("storage", `session ${metadata.id} could not be deleted: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : undefined);
+            throw new SessionError("storage", `session ${metadata.id} could not be deleted: ${thrownText(err)}`, err instanceof Error ? err : undefined);
         }
     }
     async fork(sourceMetadata, options = {}) {

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

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { atomicWriteFile } from "./fs-atomic.js";
 import { createSafeNotifier, observeThenableRejection } from "../../core/safe-notify.js";
+import { thrownText } from "../../core/thrown-value.js";
 import { MAX_STRATEGY_INJECTION_TOTAL_BYTES, MAX_STRATEGY_TEXT_BYTES, compileStrategyQuery, resolveCapacityCap, resolveFindLimit, scoreStoredStrategy, storedStrategyShapeIssue, strategyDedupKey, validateStrategyForWrite, } from "../../core/strategy-store.js";
 function configRefusal(message, code) {
     const e = new Error(message);
@@ -32,14 +33,14 @@ export class FileStrategyStore {
             mkdirSync(root, { recursive: true, mode: 0o700 });
         }
         catch (err) {
-            throw configRefusal(`FileStrategyStore: cannot create root ${root}: ${String(err.message ?? err)}`, "config.strategy_root_invalid");
+            throw configRefusal(`FileStrategyStore: cannot create root ${root}: ${thrownText(err)}`, "config.strategy_root_invalid");
         }
         let st;
         try {
             st = statSync(root);
         }
         catch (err) {
-            throw configRefusal(`FileStrategyStore: cannot stat root ${root}: ${String(err.message ?? err)}`, "config.strategy_root_invalid");
+            throw configRefusal(`FileStrategyStore: cannot stat root ${root}: ${thrownText(err)}`, "config.strategy_root_invalid");
         }
         if (!st.isDirectory()) {
             throw configRefusal(`FileStrategyStore: root ${root} exists and is not a directory`, "config.strategy_root_invalid");
@@ -145,7 +146,7 @@ export class FileStrategyStore {
             catch (err) {
                 if (err.code === "ENOENT")
                     continue;
-                this.incident({ op: "find", error: `unstat-able entry skipped: ${String(err.message ?? err)}`, path: p });
+                this.incident({ op: "find", error: `unstat-able entry skipped: ${thrownText(err)}`, path: p });
                 continue;
             }
             if (!fst.isFile()) {
@@ -163,7 +164,7 @@ export class FileStrategyStore {
             catch (err) {
                 if (err.code === "ENOENT")
                     continue;
-                this.incident({ op: "find", error: `unreadable entry skipped: ${String(err.message ?? err)}`, path: p });
+                this.incident({ op: "find", error: `unreadable entry skipped: ${thrownText(err)}`, path: p });
                 continue;
             }
             let parsed;
@@ -217,7 +218,7 @@ export class FileStrategyStore {
             this.incident({ op: "parse", error: `corrupt entry quarantined (${reason})`, path: p });
         }
         catch (err) {
-            this.incident({ op: "parse", error: `corrupt entry skipped (${reason}); quarantine rename failed: ${String(err.message ?? err)}`, path: p });
+            this.incident({ op: "parse", error: `corrupt entry skipped (${reason}); quarantine rename failed: ${thrownText(err)}`, path: p });
         }
     }
     writeEntry(dir, path, entry) {
@@ -286,7 +287,7 @@ export class FileStrategyStore {
             catch (err) {
                 if (err.code === "ENOENT")
                     continue;
-                this.incident({ op: "evict", error: String(err.message ?? err), id: le.entry.id, path: le.path });
+                this.incident({ op: "evict", error: thrownText(err), id: le.entry.id, path: le.path });
             }
         }
     }

package/dist/tools/artifact/artifact-tool.js

@@ -7,6 +7,7 @@ import { errorResult } from "../../core/tools.js";
 import { inlineUntrusted } from "../../core/untrusted-text.js";
 import { actionDescription, artifactDescription, PARAM_TEXT, urlDescription } from "./artifact-text.js";
 import { ARTIFACT_REJECT_BREAKER_THRESHOLD, artifactRejectBannerFor, artifactRejectKeyOf, createArtifactRejectBreaker } from "./reject-breaker.js";
+import { thrownText } from "../../core/thrown-value.js";
 export const MAX_FILES_PER_PUBLISH = 255;
 const LIST_LIMIT_DEFAULT = 25;
 const LIST_LIMIT_MAX = 100;
@@ -93,10 +94,10 @@ function callHost(action, fn, signal) {
         }
         catch (err) {
             signal?.removeEventListener("abort", onAbort);
-            resolve({ ok: false, kind: "threw", message: err instanceof Error ? err.message : String(err) });
+            resolve({ ok: false, kind: "threw", message: thrownText(err) });
             return;
         }
-        p.then((value) => resolve(OUTCOME_SHAPE[action](value) ? { ok: true, value } : { ok: false, kind: "malformed", message: `the ${action} answer was outside the host contract` }), (err) => resolve({ ok: false, kind: "threw", message: err instanceof Error ? err.message : String(err) })).finally(() => signal?.removeEventListener("abort", onAbort));
+        p.then((value) => resolve(OUTCOME_SHAPE[action](value) ? { ok: true, value } : { ok: false, kind: "malformed", message: `the ${action} answer was outside the host contract` }), (err) => resolve({ ok: false, kind: "threw", message: thrownText(err) })).finally(() => signal?.removeEventListener("abort", onAbort));
     });
 }
 function buildSchema(caps) {

package/dist/tools/artifact/conformance.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { thrownText } from "../../core/thrown-value.js";
 import { readArtifactHostCapabilities, } from "../../core/artifact-host.js";
 class Violation extends Error {
 }
@@ -25,7 +26,7 @@ async function publish(h, r, attemptId) {
         return await h.host.publish(r, ctxOf(h, attemptId));
     }
     catch (err) {
-        return fail(`publish threw: ${err instanceof Error ? err.message : String(err)}`);
+        return fail(`publish threw: ${thrownText(err)}`);
     }
 }
 async function publishOk(h, r, what, attemptId) {
@@ -282,7 +283,7 @@ define({ id: "read.unknown_url_typed", describe: "`read` of a url this host neve
         out = await h.host.read({ url: FOREIGN_URL }, ctxOf(h));
     }
     catch (err) {
-        return fail(`read threw: ${err instanceof Error ? err.message : String(err)}`);
+        return fail(`read threw: ${thrownText(err)}`);
     }
     check(!out.ok && (out.code === "not_found" || out.code === "forbidden"), `an unknown url answered ${out.ok ? "ok" : out.code}`);
     return out.ok ? "" : out.code;
@@ -340,7 +341,7 @@ export async function runArtifactConformance(host, opts = {}) {
             row = { id: v.id, status: "pass", detail: await v.run(h) };
         }
         catch (err) {
-            row = { id: v.id, status: "fail", detail: err instanceof Violation ? err.message : `threw: ${err instanceof Error ? err.message : String(err)}` };
+            row = { id: v.id, status: "fail", detail: err instanceof Violation ? err.message : `threw: ${thrownText(err)}` };
         }
         results.push(row);
     }

package/dist/tools/fs/bash-lexer.d.ts

@@ -92,20 +92,27 @@ export interface SegmentTokens {
 /** What a substitution leaves in a word's FOLDED spelling: a marker no argv word can spell, so a consumer that
  *  judges words sees "this word carries text the shell computes" rather than the computing text itself. */
 export declare const SUBSTITUTION_PLACEHOLDER = " subst";
+export type QuoteOpen = '"' | "'" | undefined;
 /**
- * Which characters of `s` sit inside a QUOTED region, by the same pairing rule the lexer walks with. The pairing
- * quote characters themselves are reported as quoted — they are not operators either way.
+ * Which QUOTE holds each character of `s`, by the same pairing rule the lexer walks with, and the boolean view
+ * of it. The pairing quote characters themselves belong to the region they bound — they are not operators
+ * either way — so `openedBy` names that region's quote character at their own index too.
+ *
+ * `quoted` is a VIEW of `openedBy`, minted in the same step: a consumer asking only "is this inside quotes"
+ * reads it, one asking WHICH quote (single quotes suppress every expansion, double quotes suppress neither `$`
+ * nor the backtick) reads `openedBy`, and the two cannot drift.
  *
  * `balanced` is false when a region is still open at the end of the string. Callers must then NOT use the mask:
  * an unterminated quote is a string bash itself cannot parse, and every consumer falls back to the quote-BLIND
  * reading, which is the stricter one.
  *
  * EXACTNESS. This models bash only for the residual character space the strict faces operate in, where backslash
- * escapes, `$`, backticks, and subshells are rejected outright — there `'` and `"` pairing is the whole of
- * quoting, so a region computed here is exactly a region bash quotes. It is NOT a general shell quoting parser
- * and must not be used before those characters are excluded.
+ * escapes and subshells are rejected outright — there `'` and `"` pairing is the whole of quoting, so a region
+ * computed here is exactly a region bash quotes. A caller deciding about `$` or a backtick on this mask owes
+ * the argument in `bash-readonly-classifier.ts`. It is NOT a general shell quoting parser.
  */
 export declare function quoteMask(s: string): {
+    openedBy: readonly QuoteOpen[];
     quoted: readonly boolean[];
     balanced: boolean;
 };

package/dist/tools/fs/bash-lexer.js

@@ -5,14 +5,17 @@ function quoteStep(open, ch) {
     return open === ch ? undefined : open;
 }
 export function quoteMask(s) {
+    const openedBy = new Array(s.length).fill(undefined);
     const quoted = new Array(s.length).fill(false);
     let open;
     for (let i = 0; i < s.length; i++) {
         const before = open;
         open = quoteStep(open, s[i]);
-        quoted[i] = before !== undefined || open !== undefined;
+        const holds = before ?? open;
+        openedBy[i] = holds;
+        quoted[i] = holds !== undefined;
     }
-    return { quoted, balanced: open === undefined };
+    return { openedBy, quoted, balanced: open === undefined };
 }
 export function literalTildeSpelling(word) {
     return word.startsWith("~") ? `./${word}` : word;

package/dist/tools/fs/bash-program-position.d.ts

@@ -114,6 +114,9 @@ export type ProgramPositionRefusal = {
     readonly kind: "control_syntax_at_program_position";
     readonly owner: string;
     readonly word: string;
+    /** Not a DECLINE ({@link programPositionRunsShell}): the row WAS read and a SHELL stands at the program
+     *  position. Absent ⇒ genuine control syntax, which IS one. */
+    readonly runsShell?: true;
 };
 export interface ProgramPosition {
     /** Indices of the bare control words stripped in front (`!`, `if`, `time`, …), in order; their declared options
@@ -159,5 +162,20 @@ export declare function readProgramPosition(toks: SegmentTokens): ProgramPositio
  *  stdin AND the program it runs is not one the caller accepts as a stream target. ONE reading, shared by every
  *  consumer; WHICH targets are accepted is the caller's declaration, not this reader's. */
 export declare function argvReentryUnjudged(pos: ProgramPosition, acceptedTargets: ReadonlySet<string>): boolean;
+/**
+ * The two ways this reader DECLINES rather than judges — a CLOSED set, because which of them a seat reads as
+ * evidence is a table each seat declares against (`fs-bash.ts`, where the argument is), not a boolean buried
+ * in a caller. `unreadable_program_position`: the walk cannot name the program bash will run (`env -- ls`).
+ * `stream_fed_operands`: the operands arrive on a STREAM it never saw (`… | xargs cat`). Neither names a WORD.
+ */
+export declare const SHELL_SCAN_DECLINES: readonly ["unreadable_program_position", "stream_fed_operands"];
+export type ShellScanDecline = (typeof SHELL_SCAN_DECLINES)[number];
+/** Does a SHELL stand where this segment's program would be — as the program itself (`sh -c`), or as a launcher
+ *  ROW handing its operands to one (`watch "…"`)? ONE predicate for the re-entry class, so the two spellings
+ *  cannot be answered differently; which names are shells is the caller's declaration. Not a decline. */
+export declare function programPositionRunsShell(pos: ProgramPosition, shellProgram: RegExp): boolean;
+/** Which decline, if any, this program position raises — ONE reading of the two facts above, so no consumer
+ *  re-derives either. A refusal that says a SHELL runs is NOT one: it names what runs. */
+export declare function shellScanDeclineOf(pos: ProgramPosition, acceptedStreamTargets: ReadonlySet<string>): ShellScanDecline | undefined;
 /** ONE sentence per refusal kind, minted here and nowhere else. */
 export declare function programPositionRefusalSentence(refusal: ProgramPositionRefusal): string;

package/dist/tools/fs/bash-program-position.js

@@ -107,7 +107,7 @@ export function readProgramPosition(toks) {
     }
     const launchers = [{ index: i, name: basename }];
     const owner = head;
-    const shellRefusal = () => ({ kind: "control_syntax_at_program_position", owner, word: "sh" });
+    const shellRefusal = () => ({ kind: "control_syntax_at_program_position", owner, word: "sh", runsShell: true });
     let owedOperands = LAUNCHER_TABLE.get(basename)?.requiredOperands ?? 0;
     let lastRow = LAUNCHER_TABLE.get(basename);
     const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal });
@@ -158,6 +158,18 @@ export function argvReentryUnjudged(pos, acceptedTargets) {
     const runs = pos.program?.basename ?? (pos.runsDefaultProgram ? ARGV_REENTRY_DEFAULT_PROGRAM : undefined);
     return runs === undefined || !acceptedTargets.has(runs);
 }
+export const SHELL_SCAN_DECLINES = ["unreadable_program_position", "stream_fed_operands"];
+export function programPositionRunsShell(pos, shellProgram) {
+    if (pos.refusal !== undefined)
+        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true;
+    return pos.program !== undefined && shellProgram.test(pos.program.basename);
+}
+export function shellScanDeclineOf(pos, acceptedStreamTargets) {
+    if (pos.refusal !== undefined) {
+        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true ? undefined : "unreadable_program_position";
+    }
+    return argvReentryUnjudged(pos, acceptedStreamTargets) ? "stream_fed_operands" : undefined;
+}
 export function programPositionRefusalSentence(refusal) {
     switch (refusal.kind) {
         case "option_at_program_position":

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

@@ -1,4 +1,5 @@
 import { type ShellSegmentConnector } from "./bash-lexer.js";
+import { type ShellScanDecline } from "./bash-program-position.js";
 /**
  * Bare command names `bash_readonly` permits out of the box, ALSO the default reversible set for the
  * The {@link import("./fs-bash.js").bashReversibilityProbe} classifier. **Coarse first filter, NOT a security
@@ -31,7 +32,6 @@ import { type ShellSegmentConnector } from "./bash-lexer.js";
  * value-taking options defeat the stdin-floor operand count without a per-verb option-value model
  * — those are a follow-on slice, not a silent drop.
  */
-export { NOT_AUTO_ALLOWED } from "./bash-program-position.js";
 export type { ShellSegmentConnector } from "./bash-lexer.js";
 export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
 /**
@@ -174,7 +174,7 @@ export interface ShellCompoundSegments {
  * drift in a segmentation is drift in what a deny rule is even looking at.
  *
  * Three steps, in this order and load-bearing:
- *  1. WHOLE-STRING hard reject of {@link SHELL_SEGMENT_HARD_REJECT} — redirection, substitution,
+ *  1. WHOLE-STRING hard reject ({@link hardRejectReason}) — redirection, substitution,
  *     subshells, escapes, line breaks. This is what makes step 3's quote mask EXACT: with those
  *     characters gone, `'`/`"` pairing is the entirety of quoting, so the mask's regions are exactly
  *     bash's quoted regions and the unquoted connectors are exactly bash's command boundaries. Callers
@@ -524,7 +524,19 @@ export declare function resolveOperandSpellings(base: string | undefined, operan
  *  here-document, a here-string or a literal in-root stdin file; a directory change (which then makes every relative
  *  stdin literal in the command unjudged). A substitution body (`$(…)`, backticks, `<(…)`) is judged on its own: green
  *  under the compound walk, or exempt under this whitelist; a here-document body is text, not commands. */
-export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): boolean;
+export declare function refusedCommandMayRead(command: string, allow: ReadonlySet<string>, boundary: BashReadonlyRootBoundary | undefined, 
+/** The {@link ShellScanDecline} members THIS SEAT reads as evidence (tables and argument: `fs-bash.ts`); one
+ *  the table omits ends the scan with "exempt". */
+declinesAreEvidence: ReadonlySet<ShellScanDecline>): RefusedCommandScan;
+/** What ONE scan of a refused command found — TWO facts, because a seat's table answers only the first. `mayRead`
+ *  is the whitelist's verdict ("may read a file the boundary never judged"), which a seat turns into a MANDATE.
+ *  `declined` is the scan's own report that it could not judge where a segment reads AT ALL
+ *  ({@link SHELL_SCAN_DECLINES}), recorded BEFORE the seat's table and so the SAME on every seat: a seat omitting
+ *  that decline has ruled only that an ANSWERER may retire the ask, never that nothing happened. */
+export interface RefusedCommandScan {
+    readonly mayRead: boolean;
+    readonly declined: 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
@@ -602,6 +614,10 @@ export interface OutOfRootReadGateVerdict {
      *  operand is placed against a base bash has already left, so no path can be named honestly. Read it
      *  as display/triage evidence; emptiness is not "not gated". */
     readonly paths: readonly string[];
+    /** Did the deployment's DENY judge speak about an operand this command names? The other half of the same
+     *  question, over the very same readers, in a second pass WITH the deny judge — which is what lets the
+     *  containment answer above stay deny-free and keep its `paths` contract. Absent ⇔ it said nothing. */
+    readonly denied?: true;
 }
 /** Test seam for the lockstep pin that the launcher table (the ONE launcher truth, in the program-position
  *  reader's module) stays a SUBSET of the rule lane's curated `BARE_INTERPRETER_NAMES`. Exported for that one
@@ -638,10 +654,10 @@ export declare const COMMAND_LAUNCHERS_FOR_TEST: ReadonlySet<string>;
  *    base across segments) and dropping it would place every later relative operand against a base bash
  *    has already left. A move the walk cannot model (`pushd`/`popd`) is not silently tolerated either —
  *    see the `paths`-less gated answer below.
- *  · The CONTAINMENT half only: {@link BashReadonlyRootBoundary.denyMatch} is deliberately NOT passed
- *    on. The deny judge outranks containment inside the walk and returns early, which would let a
- *    deny-listed operand HIDE the fact that it also sits outside the roots — the deny demotion is
- *    unchanged on the full face, and this one keeps answering its own question underneath it.
+ *  · BOTH halves from ONE extraction, in TWO passes: the CONTAINMENT pass alone is deny-free, because
+ *    {@link BashReadonlyRootBoundary.denyMatch} outranks containment inside the walk and returns early,
+ *    which would let a deny-listed operand HIDE the fact that it also sits outside the roots. A SECOND
+ *    pass over the SAME readers does carry that judge, and is what answers `denied` (see below).
  *  · `face: "open"` is honoured: under the open read face containment is structurally satisfied, an
  *    out-of-roots operand is not a finding, and this gate is silent — a full-read deployment sees no
  *    gate here, by the same one mechanism the face already defines.