@sema-agent/core 7.54.1 → 7.56.0

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

@@ -1,7 +1,7 @@
-import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, openSync, readdirSync, rmSync, utimesSync } from "node:fs";
 import { join } from "node:path";
-import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, forkRowCells, getEntriesToFork, incarnationCell, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
-import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
+import { BaseSessionStorage, StoredSession, SessionError, assertForkTarget, compareOccupants, forkRowCells, frozenRow, getEntriesToFork, importRowCells, incarnationCell, leafIdAfterEntry, ownerCell, readIncarnationCell, readOwnerCell, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
+import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, firstJsonlRecord, lastJsonlRecord, readJsonlRecords, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { thrownText } from "../../core/thrown-value.js";
@@ -9,9 +9,14 @@ const SUFFIX = ".jsonl";
 const SESSION_LINE_JUDGE = {
     accepts: (r) => {
         const line = r;
-        return line.kind === "meta" || (line.kind === "entry" && line.entry !== null && typeof line.entry === "object");
+        if (line.kind === "meta")
+            return true;
+        if (line.kind !== "entry" || line.entry === null || typeof line.entry !== "object" || Array.isArray(line.entry))
+            return false;
+        const entry = line.entry;
+        return typeof entry.id === "string" && (entry.type !== "leaf" || entry.targetId === null || typeof entry.targetId === "string");
     },
-    what: "a session line is neither a meta header nor an entry record",
+    what: "a session line is neither a meta header nor an entry record with a string id (and, for a leaf, a string or null target)",
 };
 const sharedSessionStorages = new Map();
 const sessionStorageFinalizer = new FinalizationRegistry(({ canonical, log }) => {
@@ -31,10 +36,12 @@ class FileSessionStorage extends BaseSessionStorage {
     log;
     canonicalPath;
     holders = new Set();
+    occupant;
     constructor(log, meta, entries, canonicalPath) {
         super(meta, entries);
         this.log = log;
         this.canonicalPath = canonicalPath;
+        this.occupant = { incarnation: meta.incarnation };
     }
     addHolder(holder) {
         this.holders.add(holder);
@@ -46,6 +53,9 @@ class FileSessionStorage extends BaseSessionStorage {
     closeLog() {
         this.log.close();
     }
+    isViewOf(row) {
+        return this.log.isFileAtPath() && compareOccupants(this.occupant, row) !== "different";
+    }
     persistSync(entry) {
         this.log.append({ kind: "entry", entry }, true);
     }
@@ -91,45 +101,70 @@ export class FileSessionRepo {
                 tally = info;
             this.onCorruptRead?.({ ...info, sessionId: id });
         }, SESSION_LINE_JUDGE);
-        let meta;
+        const meta = this.headerOf(id, path, lines[0], () => ` (${tally?.dropped ?? 0} of ${tally?.total ?? lines.length} records skipped as corrupt)`);
         const entries = [];
-        for (const line of lines) {
-            if (line.kind === "meta")
-                meta = line;
-            else
+        for (const line of lines)
+            if (line.kind === "entry")
                 entries.push(line.entry);
+        return { meta, entries };
+    }
+    headerOf(id, path, first, skipped = () => "") {
+        if (first === undefined || first.kind !== "meta")
+            throw new SessionError("corrupt_session", `Session ${id} is unreadable: its log has no meta header${skipped()}`);
+        const said = (key) => (detail) => this.disclose(path, `session header ${key}: ${detail}`, id);
+        const incarnation = readIncarnationCell(first.incarnation, said("incarnation"));
+        const forkedFromIncarnation = readIncarnationCell(first.forkedFromIncarnation, said("forkedFromIncarnation"));
+        return {
+            id,
+            createdAt: first.createdAt,
+            ...(first.forkedFrom !== undefined ? { forkedFrom: first.forkedFrom } : {}),
+            ...(first.placement !== undefined ? { placement: first.placement } : {}),
+            ...(incarnation !== undefined ? { incarnation } : {}),
+            ...(forkedFromIncarnation !== undefined ? { forkedFromIncarnation } : {}),
+            owner: readOwnerCell(first.owner, id),
+        };
+    }
+    async headOf(sessionId) {
+        return this.atRow(sessionId, (fd, size, meta) => {
+            const last = lastJsonlRecord(fd, size, (r) => r.kind === "entry", SESSION_LINE_JUDGE);
+            return { owner: meta.owner ?? null, incarnation: meta.incarnation, leafId: last === undefined ? null : leafIdAfterEntry(last.entry) };
+        });
+    }
+    rowOf(sessionId) {
+        return this.atRow(sessionId, (_fd, _size, meta, mtimeMs) => ({ ...meta, lastActiveAt: Math.trunc(mtimeMs) }));
+    }
+    atRow(sessionId, read) {
+        const path = this.pathFor(sessionId);
+        let fd;
+        try {
+            fd = openSync(path, "r");
         }
-        if (meta === undefined) {
-            throw new SessionError("corrupt_session", `Session ${id} is unreadable: its log has no meta header (${tally?.dropped ?? 0} of ${tally?.total ?? lines.length} records skipped as corrupt)`);
+        catch (err) {
+            if (err.code === "ENOENT")
+                return undefined;
+            throw err;
         }
-        const { createdAt, forkedFrom, placement, incarnation, forkedFromIncarnation } = meta;
-        for (const [key, token] of [["incarnation", incarnation], ["forkedFromIncarnation", forkedFromIncarnation]]) {
-            if (token !== undefined && typeof token !== "string")
-                this.disclose(path, `session header carries a non-string ${key} (${typeof token}) — read as an UNKNOWN occupant`, id);
+        try {
+            const { size, mtimeMs } = fstatSync(fd);
+            return read(fd, size, this.headerOf(sessionId, path, firstJsonlRecord(fd, size, SESSION_LINE_JUDGE)), mtimeMs);
+        }
+        finally {
+            closeSync(fd);
         }
-        return {
-            meta: {
-                id,
-                createdAt,
-                ...(forkedFrom !== undefined ? { forkedFrom } : {}),
-                ...(placement !== undefined ? { placement } : {}),
-                ...(typeof incarnation === "string" ? { incarnation } : {}),
-                ...(typeof forkedFromIncarnation === "string" ? { forkedFromIncarnation } : {}),
-            },
-            entries,
-        };
     }
     storage(meta, entries) {
         const { id } = meta;
         const canonical = canonicalStoreKey(this.pathFor(id));
         const live = sharedSessionStorages.get(canonical)?.deref();
-        if (live !== undefined) {
+        if (live !== undefined && live.isViewOf(meta)) {
             live.addHolder(this);
             this.joined.set(canonical, new WeakRef(live));
             return live;
         }
+        if (live !== undefined)
+            evictSharedSessionStorage(canonical);
         const log = new AppendLog(this.pathFor(id));
-        const created = new FileSessionStorage(log, meta, entries, canonical);
+        const created = new FileSessionStorage(log, frozenRow({ ...meta, ...(meta.placement !== undefined ? { placement: { ...meta.placement } } : {}) }), entries, canonical);
         sharedSessionStorages.set(canonical, new WeakRef(created));
         created.addHolder(this);
         this.joined.set(canonical, new WeakRef(created));
@@ -153,10 +188,17 @@ export class FileSessionRepo {
         const createdAt = new Date().toISOString();
         const path = this.pathFor(id);
         if (!existsSync(path)) {
-            evictSharedSessionStorage(canonicalStoreKey(path));
+            const owner = ownerCell(options.owner);
             const placement = options.placement !== undefined ? { ...options.placement, placedAt: options.placement.placedAt ?? Date.now() } : undefined;
-            const meta = { id, createdAt, ...(placement !== undefined ? { placement } : {}), ...incarnationCell(undefined) };
-            atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ kind: "meta", ...meta })}\n`);
+            const meta = { id, createdAt, ...(placement !== undefined ? { placement } : {}), ...incarnationCell(undefined), ...owner };
+            try {
+                writeThenLink(path, `${JSON.stringify({ kind: "meta", ...meta })}\n`);
+            }
+            catch (err) {
+                if (err.code === "EEXIST")
+                    throw new SessionError("conflict", `session ${id} was created by another writer between this create's existence check and its write — refusing to replace or attach to that row`);
+                throw err;
+            }
             return new StoredSession(this.storage(meta, []));
         }
         const { meta, entries } = this.read(id);
@@ -166,80 +208,65 @@ export class FileSessionRepo {
         const { meta, entries } = this.read(metadata.id);
         return new StoredSession(this.storage(meta, entries));
     }
-    async list() {
-        let names;
+    async touch(sessionId) {
+        const now = new Date();
         try {
-            names = readdirSync(this.dir);
+            utimesSync(this.pathFor(sessionId), now, now);
         }
         catch (err) {
-            if (err.code !== "ENOENT") {
-                this.disclose(this.dir, `session directory unreadable (${err.code ?? "unknown"}) — listed as empty`);
-            }
-            return [];
-        }
-        const out = [];
-        for (const name of names) {
-            if (!name.endsWith(SUFFIX))
-                continue;
-            const id = name.slice(0, -SUFFIX.length);
-            try {
-                const { createdAt, forkedFrom, placement } = this.read(id).meta;
-                if (placement !== undefined)
-                    continue;
-                out.push({ id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) });
-            }
-            catch (err) {
-                if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the listing`, id);
-                }
-            }
+            if (err.code === "ENOENT")
+                return;
+            throw new SessionError("storage", `session ${sessionId}'s activity could not be recorded: ${thrownText(err)}`, err instanceof Error ? err : undefined);
         }
-        return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
     }
-    async listPlaced(kind, opts) {
+    async list() {
+        return this.rows("the listing")
+            .filter((row) => row.placement === undefined)
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    rows(listing) {
         let names;
         try {
             names = readdirSync(this.dir);
         }
         catch (err) {
             if (err.code !== "ENOENT") {
-                this.disclose(this.dir, `session directory unreadable (${err.code ?? "unknown"}) — placed listing degraded to empty`);
+                this.disclose(this.dir, `session directory unreadable (${err.code ?? "unknown"}) — ${listing} degraded to empty`);
             }
             return [];
         }
-        const now = Date.now();
         const out = [];
         for (const name of names) {
             if (!name.endsWith(SUFFIX))
                 continue;
             const id = name.slice(0, -SUFFIX.length);
-            let placement;
+            let row;
             try {
-                placement = this.read(id).meta.placement;
+                row = this.rowOf(id);
             }
             catch (err) {
-                if (!(err instanceof SessionError && err.code === "not_found")) {
-                    this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from the placed listing`, id);
-                }
+                this.disclose(this.pathFor(id), `session log unreadable (${thrownText(err)}) — skipped from ${listing}`, id);
                 continue;
             }
+            if (row !== undefined)
+                out.push(row);
+        }
+        return out;
+    }
+    async listPlaced(kind, opts) {
+        const now = Date.now();
+        const out = [];
+        for (const row of this.rows("the placed listing")) {
+            const placement = row.placement;
             if (placement === undefined || placement.kind !== kind)
                 continue;
             if (opts?.scope !== undefined && placement.scope !== opts.scope)
                 continue;
-            if (opts?.olderThanMs !== undefined) {
-                let ageAnchor = placement.placedAt;
-                try {
-                    ageAnchor = statSync(this.pathFor(id)).mtimeMs;
-                }
-                catch {
-                }
-                if (now - ageAnchor <= opts.olderThanMs)
-                    continue;
-            }
+            if (opts?.olderThanMs !== undefined && now - row.lastActiveAt <= opts.olderThanMs)
+                continue;
             out.push(placement.scope !== undefined && placement.handle !== undefined
-                ? { sessionId: id, placedAt: placement.placedAt, scope: placement.scope, handle: placement.handle }
-                : { sessionId: id, placedAt: placement.placedAt, tupleIncomplete: true });
+                ? { sessionId: row.id, placedAt: placement.placedAt, scope: placement.scope, handle: placement.handle }
+                : { sessionId: row.id, placedAt: placement.placedAt, tupleIncomplete: true });
         }
         return out;
     }
@@ -248,15 +275,19 @@ export class FileSessionRepo {
             return this.read(id).meta;
         }
         catch (err) {
-            return err instanceof SessionError && err.code === "not_found" ? undefined : {};
+            if (err instanceof SessionError && err.code === "not_found")
+                return undefined;
+            throw err;
         }
     }
     async placementOf(sessionId) {
         try {
             return this.read(sessionId).meta.placement;
         }
-        catch {
-            return undefined;
+        catch (err) {
+            if (err instanceof SessionError && err.code === "not_found")
+                return undefined;
+            throw err;
         }
     }
     async delete(metadata) {
@@ -275,7 +306,7 @@ export class FileSessionRepo {
         const id = options.id ?? uuidv7();
         const createdAt = new Date().toISOString();
         const path = this.pathFor(id);
-        const meta = { id, createdAt, ...forkRowCells(await source.getMetadata()) };
+        const meta = { id, createdAt, ...forkRowCells(await source.getMetadata(), options.owner) };
         const lines = [JSON.stringify({ kind: "meta", ...meta })];
         for (const entry of forked) {
             lines.push(JSON.stringify({ kind: "entry", entry }));
@@ -288,12 +319,10 @@ export class FileSessionRepo {
         return this.read(sessionId).entries;
     }
     async importEntries(sessionId, owner, entries, options) {
-        void owner;
         const validated = validateEntriesForImport(entries, options);
-        const prior = this.priorHeader(sessionId);
+        const meta = importRowCells(sessionId, owner, this.priorHeader(sessionId), new Date().toISOString());
         evictSharedSessionStorage(canonicalStoreKey(this.pathFor(sessionId)));
-        const createdAt = new Date().toISOString();
-        const lines = [JSON.stringify({ kind: "meta", id: sessionId, createdAt, ...incarnationCell(prior) })];
+        const lines = [JSON.stringify({ kind: "meta", ...meta })];
         for (const entry of validated) {
             lines.push(JSON.stringify({ kind: "entry", entry }));
         }

package/dist/stores/file/workflow-journal-store.d.ts

@@ -48,9 +48,9 @@ export declare const RESUME_CLAIM_SWEEP_INTERVAL_MS = 60000;
  */
 export declare const RESUME_CLAIM_REAP_GRACE_MS: number;
 export interface FileWorkflowJournalStoreOptions {
-    /** Disclosure seat for a ledger line this store DROPPED on replay (not JSON, not a record, or a record
-     *  with none of this ledger's members) — a resume that silently finds "nothing to replay" re-runs the
-     *  work with no signal. Never fires on a missing ledger; swallow-guarded. */
+    /** Disclosure seat for a ledger line that is not one of the run's records (not JSON, not an object, no `scope` /
+     *  `ordinal`, another scope) and — with the refusal, carrying the ledger's path — for whatever refused a `load`.
+     *  Never fires on a missing ledger or on a crash's unterminated tail; swallow-guarded. */
     onCorruptRead?: (info: CorruptReadInfo) => void;
 }
 export declare class FileWorkflowJournalStore implements WorkflowJournalStore {
@@ -79,9 +79,15 @@ export declare class FileWorkflowJournalStore implements WorkflowJournalStore {
     /** CC local form: the run's on-disk journal path for the notification diagnostics line.
      *  Traversal-shaped ids (LLM-controlled on some paths) degrade to undefined, never throw. */
     locator(runId: string): string | undefined;
-    /** Replay a run's ledger: last-writer-wins per ordinal; a torn/unparsable line is skipped (uncommitted). */
+    /** Replay a run's ledger: last-writer-wins per ordinal, with every line that is not one of the run's records
+     *  (`notRecords`) and the scope the first record fixes. Rows come back as written — which arm each one is, and
+     *  whether anything refuses, is {@link load}'s question, so the scope lookup `append` makes refuses on nothing. */
     private replay;
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
+    /** The run's entries, ascending by ordinal, each winning line read through {@link readWorkflowJournalEntry}. A
+     *  ledger line that is not one of the run's records, or a corrupt row, REFUSES the whole load: dropped, what it
+     *  held would look never journaled and a resume would run it again. Only the unterminated tail a crash leaves is
+     *  uncommitted. The location goes to `onCorruptRead`, not into the message; a superseded line is not read. */
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
     /**
      * RB-242 — the claim file for `(sourceRunId, scope)`. Keyed by BOTH: a cross-scope caller already

package/dist/stores/file/workflow-journal-store.js

@@ -1,18 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { callKeyOrdinal } from "../../core/workflow-journal-store.js";
+import { callKeyOrdinal, readWorkflowJournalEntry, WorkflowJournalIncompatibleError, } from "../../core/workflow-journal-store.js";
 import { AppendLog, readJsonlRecords } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { canonicalStoreKey, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { assertJournalEntryFits } from "../../core/workflow-journal-store.js";
 export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
-function entryOf(rec) {
-    if (rec.parked !== undefined)
-        return { callKey: rec.callKey, parked: rec.parked };
-    return { callKey: rec.callKey, result: rec.result };
-}
 export const RESUME_CLAIM_TTL_MS = 60 * 60 * 1000;
 export const RESUME_CLAIM_RELEASE_GRACE_MS = 5_000;
 export const RESUME_CLAIM_SWEEP_INTERVAL_MS = 60_000;
@@ -21,7 +16,7 @@ const sharedJournalDirs = new Map();
 const MAX_OPEN_JOURNAL_LOGS = 64;
 function isJournalLine(r) {
     const rec = r;
-    return typeof rec.callKey === "string" && typeof rec.scope === "string" && Number.isFinite(rec.ordinal);
+    return typeof rec.scope === "string" && Number.isFinite(rec.ordinal);
 }
 export class FileWorkflowJournalStore {
     fsyncEnabled;
@@ -86,11 +81,17 @@ export class FileWorkflowJournalStore {
                 scope ??= r.scope;
                 return r.scope === scope;
             },
-            what: "a journal line carries no callKey/scope pair, or a scope other than its run's first line",
+            what: "a journal line carries no scope/ordinal pair, or a scope other than its run's first line",
+        };
+        const notRecords = [];
+        const onCorrupt = (info) => {
+            if (info.kind === "record")
+                notRecords.push(info);
+            this.discloseCorrupt?.(info);
         };
-        for (const rec of readJsonlRecords(path, this.discloseCorrupt, judge))
-            byOrdinal.set(rec.ordinal, entryOf(rec));
-        return scope === undefined ? undefined : { scope, byOrdinal };
+        for (const rec of readJsonlRecords(path, onCorrupt, judge))
+            byOrdinal.set(rec.ordinal, rec);
+        return { scope, byOrdinal, notRecords };
     }
     async append(runId, scope, entry) {
         assertJournalEntryFits(entry);
@@ -126,9 +127,23 @@ export class FileWorkflowJournalStore {
     }
     async load(runId, scope) {
         const rec = this.replay(runId);
-        if (!rec || rec.scope !== scope)
+        if (!rec || (rec.scope !== undefined && rec.scope !== scope))
             return [];
-        return [...rec.byOrdinal.entries()].sort((a, b) => a[0] - b[0]).map(([, e]) => e);
+        const lost = rec.notRecords[0];
+        if (lost !== undefined) {
+            this.discloseCorrupt?.({ kind: "file", path: this.pathFor(runId), reason: `${lost.form}: ledger line ${lost.line} is not one of the run's records (the run's journal is refused)` });
+            throw WorkflowJournalIncompatibleError.ledgerLine(runId, lost.line, lost.form);
+        }
+        const out = [];
+        for (const [ordinal, line] of [...rec.byOrdinal.entries()].sort((a, b) => a[0] - b[0])) {
+            const read = readWorkflowJournalEntry(line);
+            if ("corrupt" in read) {
+                this.discloseCorrupt?.({ kind: "file", path: this.pathFor(runId), reason: `${read.corrupt}: journal entry #${ordinal} ${read.why} (the run's journal is refused)` });
+                throw new WorkflowJournalIncompatibleError(runId, ordinal, line);
+            }
+            out.push(read.entry);
+        }
+        return out;
     }
     claimPathFor(sourceRunId, scope) {
         const scopeTag = createHash("sha256").update(scope).digest("hex").slice(0, 16);

package/dist/tools/artifact/artifact-text.d.ts

@@ -1,6 +1,6 @@
 /**
  * The model-facing text of the Artifact tool. Every sentence is the upstream tool's wording, taken
- * byte-for-byte from the reference corpus (Claude Code 2.1.259, `cli259.js`; the line of each constant is
+ * byte-for-byte from the reference corpus (the line of each constant is
  * noted beside it) with one class of edit: a reference to a hosting product this library does not have
  * (`claude.ai`, its terminal/gallery/Slack surfaces, an `out_dir` save) is replaced by the smallest
  * neutral phrase. The replacement list is registered in the divergence register beside this package.

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

@@ -8,8 +8,8 @@ const ARTIFACT_ACTION_LEGS = {
     hosted: { publish: ["env", "outside_write"], list: ["outside_read"], read: ["outside_read"], list_files: ["outside_read"], read_file: ["outside_read"] },
     "local-stub": { publish: ["env"], list: [], read: [], list_files: [], read_file: [] },
 };
-import { ARTIFACT_TOOL_NAME, toolFace } from "../../core/tool-catalog-entries.js";
-import { resolveAsk } from "../../core/tool-policy.js";
+import { ARTIFACT_TOOL_NAME, mountRuleFace, toolFace } from "../../core/tool-catalog-entries.js";
+import { attest, resolveAsk } from "../../core/tool-policy.js";
 import { NOT_BINDABLE } from "../../core/skill-grant-binding.js";
 import { approvalCardOf } from "../../core/tool-roster.js";
 import { errorResult } from "../../core/tools.js";
@@ -328,7 +328,8 @@ export function createArtifactTool(opts) {
         if (sharedReadApproved.has(url))
             return Promise.resolve({ ok: true });
         if (permissionMode !== undefined) {
-            const verdict = arbitrateByMode(permissionMode(), classifyAsk({ action: "ask", requiresRealApproval: true, guards: ["artifact_shared_read"] }, { contentQuestion: false, markedUnresolvable: false, org: undefined, tightened: undefined, mandateMarks: {} }));
+            const call = { toolCallId: ctx.toolCallId, toolName: ARTIFACT_TOOL_NAME };
+            const verdict = arbitrateByMode(permissionMode(), classifyAsk(attest({ action: "ask", requiresRealApproval: true }, call, { guards: ["artifact_shared_read"] }), { call, contentQuestion: false, markedUnresolvable: false, org: undefined, tightened: undefined, mandateMarks: {} }));
             if (verdict.kind === "released") {
                 if (!releaseAnnounced && onNotice !== undefined) {
                     releaseAnnounced = true;
@@ -448,6 +449,7 @@ export function createArtifactTool(opts) {
     return {
         name: ARTIFACT_TOOL_NAME,
         ...toolFace("artifact"),
+        ruleFace: mountRuleFace("artifact"),
         contentOrigin: ARTIFACT_PLANE_CONTENT_ORIGIN[caps.plane],
         description: artifactDescription(caps.plane, caps.actions),
         parameters: buildSchema(caps),

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

@@ -39,14 +39,27 @@ export declare const LOOP_LIST_HEADS: ReadonlySet<string>;
  * over control words and earlier assignments re-traces). One fact, two readers that must agree.
  */
 export declare function isLeadingAssignmentWord(words: readonly LexedWord[], i: number): boolean;
-export declare const PROGRAM_POSITION_REFUSAL_KINDS: readonly ["option_at_program_position", "control_syntax_at_program_position"];
+export declare const PROGRAM_POSITION_REFUSAL_KINDS: readonly ["option_at_program_position", "control_syntax_at_program_position", "wildcard_program_word"];
 export type ProgramPositionRefusalKind = (typeof PROGRAM_POSITION_REFUSAL_KINDS)[number];
 /** Why the program could not be read — a closed set, each member minted into one sentence. `owner` is the word
  *  that took the offending token: the control word or the first launcher of the chain. */
-export type ProgramPositionRefusal = {
+export type ProgramPositionRefusal = 
+/** `endedBy`: the launcher whose bare `--` ended its options before this word — the word is then no option of anyone's
+ *  but a name spelled like one (`env -- -i ls` runs a program named `-i`), and the sentence says that, not "the option". */
+{
     readonly kind: "option_at_program_position";
     readonly owner: string;
     readonly option: string;
+    readonly endedBy?: string;
+}
+/** The program word carries an unquoted glob (`s[h]`, `s*h`, `./c?t`): the shell expands it against the filesystem,
+ *  so which program runs — a shell among them — is not readable from the text (`touch sh; s[h] -c '…'`). `word` is the
+ *  word as written, `at` its argv index (the words AFTER it are still handed over, so a deny operand still refuses).
+ *  Both faces ask, the same as any unreadable program position. */
+ | {
+    readonly kind: "wildcard_program_word";
+    readonly word: string;
+    readonly at: number;
 } | {
     readonly kind: "control_syntax_at_program_position";
     readonly owner: string;
@@ -130,3 +143,7 @@ export declare function programPositionRunsShell(pos: ProgramPosition, runsShell
 export declare function shellScanDeclineOf(pos: ProgramPosition, acceptsStreamTarget: (basename: string) => boolean): ShellScanDecline | undefined;
 /** ONE sentence per refusal kind, minted here and nowhere else. */
 export declare function programPositionRefusalSentence(refusal: ProgramPositionRefusal): string;
+/** The sentence a segment whose program the walk DECLINED carries, read off the segment's text — the program-position reader's own
+ *  refusal, the stream fact, or that no program could be named: the read station's account of the segment and the removal guard's
+ *  are this one sentence. */
+export declare function declinedProgramSentence(text: string): string;