@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/session.d.ts

@@ -2,12 +2,13 @@ export { StoredSession } from "../internal/harness.js";
 export type { Session } from "../internal/harness.js";
 export { InMemorySessionRepo, InMemorySessionStorage, uuidv7, validateEntriesForImport, StreamingImportValidator, } from "../internal/harness.js";
 export { BaseSessionStorage, leafIdAfterEntry, } from "../internal/harness.js";
-export type { SessionStorage, SessionRepo, SessionMetadata, SessionTreeEntry, } from "../internal/harness.js";
+export type { SessionStorage, SessionRepo, SessionRow, SessionMetadata, SessionTreeEntry, } from "../internal/harness.js";
 export { SessionError } from "../internal/harness.js";
 export type { SessionWriteOptions } from "../internal/harness.js";
 import type { Session } from "../internal/harness.js";
-import type { SessionTreeEntry } from "../internal/harness.js";
+import type { SessionHead, SessionTreeEntry } from "../internal/harness.js";
 export type { SessionPlacementRecord } from "../internal/harness.js";
+export type { SessionHead } from "../internal/harness.js";
 /** True when `err` is a session optimistic-lock conflict (a concurrent writer won the branch leaf). Both
  *  halves read what a HOST `SessionStorage` threw, so both are guarded — unreadable is not a conflict,
  *  never a raise inside the classify-and-rethrow guard. The class test is KEPT: widening the verdict to
@@ -54,7 +55,7 @@ export interface AcquiredSession {
 }
 /**
  * A lightweight, read-only projection of one session for a `/resume` list (shell K-5 — re-attach without an
- * N+1 walk). Returned in bulk by {@link SessionStore.list}, newest-first by `lastActiveAt` by convention.
+ * N+1 walk). Returned in pages by {@link SessionStore.list}, newest-first by `(lastActiveAt, sessionId)`.
  * `lastTaskId` is the engine's term for what the service/wire surfaces as the session's **`lastRunId`** — the
  * most recent task run on this session, so a shell re-attaches in ONE hop.
  *
@@ -71,7 +72,10 @@ export interface SessionStoreSummary {
     /** When the session was created ({@link SessionMetadata.createdAt}, ISO string); absent when the backend's
      *  cache view doesn't carry it. */
     createdAt?: string;
-    /** Epoch ms the session was last acquired / touched / ran — the newest-first sort key for "recent sessions". */
+    /** Epoch ms of the session's newest activity the store RECORDS — its writes and its {@link SessionStore.touch}es (the Runner touches
+     *  a session as each run ends) — the newest-first sort key for "recent sessions". Recorded, never what one process saw: a restart,
+     *  another replica or a dropped cache reads the same time, and only a later activity moves it. An acquire that writes nothing is not
+     *  activity. */
     lastActiveAt: number;
     /** The most recent task run on this session (core's `taskId`; the service projects it as `lastRunId`).
      *  Absent until a task has run on the session (recorded via {@link SessionStore.noteTaskRun}). */
@@ -105,6 +109,54 @@ export interface SessionStoreSummary {
      *  predate the fork. The durable source of truth is the repo's persisted metadata. */
     forkedFrom?: string;
 }
+/** The page bounds of {@link SessionStore.list}: a query without `limit` reads `default` rows; an explicit `limit` is an integer in
+ *  1..`max`. */
+export declare const SESSION_LIST_LIMITS: Readonly<{
+    readonly default: 50;
+    readonly max: 1000;
+}>;
+/**
+ * What {@link SessionStore.list} is asked for. No query, or `{}`, is the unfiltered list — every owner's rows, unowned ones included —
+ * read from its first page, at most {@link SESSION_LIST_LIMITS}`.default` rows; a caller that wants every row pages with `after`.
+ * A store may define extension filters of its own (members beside these, e.g. a text search); a filter applies before the page is
+ * cut, so `after` and `limit` page the filtered list. A store refuses a member it does not read — an unread filter would list rows the
+ * caller asked to exclude.
+ */
+export interface SessionListQuery {
+    /** Only the rows this owner owns (exact match; a principal name, so a blank string is refused, never an owner of its own). Absent = no owner filter. */
+    owner?: string;
+    /** With `owner`: the unowned rows (owner `null`) too. A member of the owner filter only — given without `owner` it is refused, so a
+     *  query that lost its owner never widens into every owner's list. */
+    includeUnowned?: boolean;
+    /** The keyset cursor — the `lastActiveAt` and `sessionId` of the last row of the previous page: only rows after it in the list's
+     *  order are read (a smaller `lastActiveAt`, or the same one with a smaller `sessionId`). */
+    after?: {
+        lastActiveAt: number;
+        sessionId: string;
+    };
+    /** At most this many rows, an integer in 1..{@link SESSION_LIST_LIMITS}`.max`; absent = the default. Ask for one more than a page
+     *  shows to learn whether another page exists. */
+    limit?: number;
+}
+/** {@link readSessionListQuery}'s answer: the query's members as read, the defaults filled in. */
+export interface SessionListQueryReading {
+    readonly owner?: string;
+    readonly includeUnowned: boolean;
+    readonly after?: {
+        readonly lastActiveAt: number;
+        readonly sessionId: string;
+    };
+    readonly limit: number;
+    /** The values of the extension members the reading store declared and the query carries. */
+    readonly extensions: Readonly<Record<string, unknown>>;
+}
+/**
+ * The one reading of a {@link SessionListQuery}, for every store that implements {@link SessionStore.list}: `raw` read by the
+ * engine's receipt law (a plain object, each member read once), each member judged, the default limit filled in. `extensions` names
+ * the extension members the calling store reads (none for a store without extension filters); any other member is refused. A bad
+ * value is refused, never mapped to a default: `config.invalid_argument`.
+ */
+export declare function readSessionListQuery(raw: unknown, extensions?: readonly string[]): SessionListQueryReading;
 /**
  * The session lifecycle/caching layer the {@link Runner} depends on.
  *
@@ -113,8 +165,12 @@ export interface SessionStoreSummary {
  * a session from the persisted event log so any stateless runner instance can resume it.
  *
  * Implementations must be safe under concurrent `acquire` of the same id (return one session).
+ *
+ * `S` / `Q` are the store's list projection and query: a backend whose list carries more per row (or filters by more) extends
+ * {@link SessionStoreSummary} / {@link SessionListQuery} and implements `SessionStore<Its summary, Its query>` — still assignable
+ * wherever a `SessionStore` is taken.
  */
-export interface SessionStore {
+export interface SessionStore<S extends SessionStoreSummary = SessionStoreSummary, Q extends SessionListQuery = SessionListQuery> {
     /**
      * design/173 §2.3 — durability declaration (see
      * {@link import("./checkpoint-store.js").StoreDurability}): whether sessions this store accepts
@@ -141,7 +197,7 @@ export interface SessionStore {
      * Declaring this commits the store to the placement obligations:
      *  1. a placed session enjoys the declared durability (`acquire(id, {requireExisting:true})`
      *     reaches it after a restart when `"durable"`);
-     *  2. placed sessions do NOT appear on host enumeration faces (`list()` and every deployment
+     *  2. placed sessions do NOT appear on host enumeration faces (`list` and every deployment
      *     listing path — restart-stable);
      *  3. acquire semantics for sessions WITHOUT a placement are byte-unchanged;
      *  4. `release(placedId)` is a REAL deletion (durable history included) — the joint reap's
@@ -170,7 +226,8 @@ export interface SessionStore {
         requireExisting?: boolean;
         placement?: SessionPlacement;
     }): Promise<AcquiredSession>;
-    /** Mark a session recently active (resets idle TTL where applicable). May be async for durable stores. */
+    /** Mark a session recently active: resets the idle TTL where applicable, and is activity the {@link list} order records. May be
+     *  async for durable stores. */
     touch(sessionId: string): void | Promise<void>;
     /** Drop a session from the live set (e.g. a throwaway task). Durable history may be retained by the backend. */
     release(sessionId: string): Promise<void>;
@@ -214,12 +271,16 @@ export interface SessionStore {
      */
     noteTaskRun?(sessionId: string, taskId: string, runId?: string): void | Promise<void>;
     /**
-     * Enumerate known sessions as lightweight {@link SessionStoreSummary} projections (newest-first by
-     * `lastActiveAt`) so a shell's `/resume` lists sessions + their last run in ONE call. **Optional**: the
-     * in-memory `TtlSessionStore` lists its live cache; a durable backend lists persisted sessions. A store
-     * that cannot enumerate omits this (the shell then has no session-list affordance — honest degrade).
+     * One page of the store's sessions as lightweight {@link SessionStoreSummary} projections, so a shell's `/resume` lists sessions +
+     * their last run in ONE call: every session ROW the store holds — what a restart still finds, not only what this process has
+     * cached — that the query admits, newest-first by `(lastActiveAt, sessionId)` (both descending; equal times order by id), at most
+     * `limit` rows after the `after` cursor (see {@link SessionListQuery}; read it with {@link readSessionListQuery}, whose refusals are
+     * this face's). Placed sessions are never listed (placement obligation 2). Reading the list is not activity, and a row's time only
+     * moves forward, so paging with `after` never reads a row twice — a row written or touched between two pages moves ahead of the
+     * cursor, where later pages do not read it (a fresh first page shows it). **Optional**: a store that cannot enumerate omits this (the
+     * shell then has no session-list affordance — honest degrade).
      */
-    list?(): Promise<SessionStoreSummary[]>;
+    list?(query?: Q): Promise<S[]>;
     /**
      * Subagent transcript persistence — enumerate the PLACED partition (the input to the joint reap's
      * partition leg: sessions whose owning agent row is gone are the orphan shape it collects).
@@ -243,59 +304,42 @@ export interface SessionStore {
      * an in-memory repo forks IN-PROCESS yet loses the copy on restart, while a durable repo (file/pg) makes the
      * fork survive restart/replica. **Capability presence ≠ durability** — a cross-replica consumer (design/114
      * warm-resume) MUST wire a durable repo; core cannot verify durability, only fail-loud on a missing source at
-     * fork time (returns `null`). `owner` (if given) scopes the new session for multi-tenant stores, and a store that
-     * also implements {@link register} MUST make the fork's ownership row agree with it — a fork COPIES the source's
-     * history, so the copy must never be weaker than the original: with no `owner` argument the fork inherits the
-     * SOURCE's row (a source with no row mints none, keeping the authorizer's claim branch intact). An EXPLICIT
-     * `owner: null` follows the same inheritance, deliberately: "anonymous" on a copy of an OWNED source would
-     * make that history claimable by anyone — a downgrade this face exists to prevent — so `null` only takes
-     * effect when the source itself is unowned/anonymous. MUST copy the COMMITTED leaf (an in-flight
-     * uncommitted turn of an active source is not included — a fork is a snapshot at the fork point).
+     * fork time (returns `null`). The fork is a new row whose owner cell is recorded in the write that creates it — a fork
+     * COPIES the source's history, so the copy is never weaker than the original: with no `owner` argument, or an
+     * EXPLICIT `null`, the fork records the SOURCE row's owner ("anonymous" on a copy of an OWNED source would admit
+     * every principal to that history — a downgrade this face exists to prevent); an owner string (a principal name — a blank
+     * string is refused, with no row left behind) records that owner.
+     * MUST copy the COMMITTED leaf (an in-flight uncommitted turn of an active source is not included — a fork is a
+     * snapshot at the fork point).
      */
     fork?(sourceId: string, owner?: string | null): Promise<string | null>;
     /**
-     * Session-ownership capability face (multi-tenant admission — the deployment's authorizer probes for
-     * BOTH methods and runs its owner gate only when they exist; a store without them forces the
-     * deployment into its fail-closed arm, refusing caller-supplied session ids under multi-tenancy).
+     * The row's {@link SessionHead} for `sessionId` — owner, occupant and active leaf — in ONE read of the row, never assembled from
+     * separate reads (a delete and re-create of the id between two reads would pair one generation's owner with the next one's
+     * occupant). `undefined` = no row for this id. A rejection is a read fault, not an answer.
      *
-     * `ownerOf` is THREE-state and the states must never collapse:
-     *  - `undefined` — the session has NO ownership row (unknown id): the authorizer claims it for the
-     *    calling principal (or 404s under require-existing).
-     *  - `null` — the session EXISTS and is anonymous (unowned): admitted (single-tenant/dev sharing).
-     *  - `string` — owned: a different principal is refused.
-     *  Collapsing `undefined` into `null` breaks the gate in both directions at once (an unknown id
-     *  reads as an admissible anonymous session; an anonymous session reads as claimable).
+     * The BY-ID read, for a reader that did not acquire the session (hosts, a deployment's authorizer). A store that has it hands out,
+     * from `acquire`, only a session of the occupant it names — a cached view of an occupant the row no longer holds (the row deleted,
+     * or deleted and created again, through another writer — on the File lane a writer in another process too) is not served — so its `incarnation` and the acquired session's metadata agree (the kit pins both); a run's own memory seat reads the session it ACQUIRED instead, never this lookup. The owner is a cell of the row: `null` = anonymous (admitted to every principal) — a row created
+     * with no owner (`acquire` names none), or a row written before the cell existed; a principal name = owned (a cell holding a blank string
+     * names nobody and is a read fault, never an owner). A placed row carries the owner its placing write recorded: the bundled stores'
+     * placing write names none (`acquire`'s options and {@link SessionPlacement} carry no principal), so their placed rows read `null`; a
+     * store's own placing write may record a principal (e.g. a delegation tree's owner), and a reader takes the row's owner as it reads. **Optional**: absent ⇒ no by-id read,
+     * and a deployment's authorizer, which needs this and {@link register} together, takes its fail-closed arm.
      */
-    ownerOf?(sessionId: string): Promise<string | null | undefined>;
+    headOf?(sessionId: string): Promise<SessionHead | undefined>;
     /**
-     * Idempotent ownership upsert, FIRST-WRITE-WINS and atomic: the first registered owner is kept,
-     * later calls neither overwrite nor throw. Deliberately makes NO authorization decision — the
-     * caller re-reads {@link ownerOf} after registering and judges there (which is exactly why the
-     * first-write-wins read-back must be atomic: a concurrent loser has to SEE the winner's owner on
-     * re-read, or it silently attaches to the winner's session). In-memory synchronous writes satisfy
-     * this trivially; durable implementations need a real uniqueness guarantee, not read-then-write.
-     * The ownership row must never expire BEFORE its session (a live session reading as `undefined`
-     * would be re-claimable by anyone); same-lifetime or longer both satisfy the contract — so a store that
-     * deletes the row when it deletes the history must gate that on the history delete having SUCCEEDED.
-     * An implementation must never store a value that {@link ownerOf} reads back as `undefined` (a row that
-     * EXISTS yet reads as "no row" is permanently claimable and never ownable): a FIRST write whose `owner` is
-     * neither a string nor `null` is refused loudly instead — the no-overwrite-no-throw rule above governs
-     * LATER calls, which stay silent no-ops whatever they carry.
+     * The owner write of the ownership pair ({@link headOf} + this). On an id with NO row it creates the row — an ordinary row, no
+     * placement — recording `owner` in the creating write, first-write-wins and atomic: of two concurrent first registers, both
+     * callers' re-reads see the same winner (durable implementations need a real uniqueness guarantee, not read-then-write). On an id
+     * whose row EXISTS it does nothing, whatever it carries — an owned row, an anonymous row, a row `acquire` created (which
+     * records `null`), or a placed row (the owner its placing write recorded) stays as it is: a row's owner is recorded by the write that
+     * creates it and `register` never changes it; there is no claiming of an existing row. A FIRST write whose `owner` is neither a principal
+     * name (a string with a visible character, no control or separator character, and no format character but a joiner) nor `null` is refused loudly and leaves no row; a later call stays a silent no-op
+     * whatever it carries. Deliberately makes NO
+     * authorization decision — the caller re-reads {@link headOf} and judges there. The owner lives and dies with its row.
      */
     register?(sessionId: string, owner: string | null): Promise<void>;
-    /**
-     * WHICH occupant holds `sessionId` now: the session row's {@link SessionMetadata.incarnation} cell,
-     * minted by the repo when the row came into existence and stable for the row's whole life (restarts,
-     * cache eviction, replicas). `undefined` = UNKNOWN — no row for this id, or a row written before the
-     * cell existed; a reader treats unknown as "cannot tell occupants apart", never as a different one.
-     * A rejection is a read fault, not an answer.
-     *
-     * The BY-ID read, for a reader that did not acquire the session (hosts; this read and the metadata of
-     * a session `acquire` hands back must agree — the incarnation kit pins both). A run's own memory seat
-     * reads the session it ACQUIRED instead, never a second lookup: the cached view `acquire` returns and
-     * a by-id read can answer two different rows. **Optional**: absent ⇒ no by-id read.
-     */
-    incarnationOf?(sessionId: string): Promise<string | undefined>;
     /** Number of live/cached sessions (best-effort). */
     readonly size: number;
     /** Release resources (timers, connections). Best-effort; must not throw. */

package/dist/core/session.js

@@ -4,9 +4,62 @@ export { BaseSessionStorage, leafIdAfterEntry, } from "../internal/harness.js";
 export { SessionError } from "../internal/harness.js";
 import { SessionError } from "../internal/harness.js";
 import { readMember, thrownIs } from "./thrown-value.js";
+import { receiptRefusal, receiveOwnProperties } from "./own-property-receipt.js";
+import { principalNameFault, principalNameOf } from "./principal-name.js";
 export function isSessionConflict(err) {
     return thrownIs(err, SessionError) && readMember(err, "code") === "conflict";
 }
+export const SESSION_LIST_LIMITS = Object.freeze({ default: 50, max: 1000 });
+const LIST_QUERY_MEMBERS = ["owner", "includeUnowned", "after", "limit"];
+export function readSessionListQuery(raw, extensions = []) {
+    if (raw === undefined)
+        return { includeUnowned: false, limit: SESSION_LIST_LIMITS.default, extensions: {} };
+    if (typeof raw !== "object" || raw === null)
+        throw receiptRefusal(`SessionStore.list: the query must be an object, got ${raw === null ? "null" : typeof raw}`);
+    const got = receiveOwnProperties(raw, { subject: "SessionListQuery", unit: "member", moment: "at SessionStore.list" });
+    const extended = {};
+    for (const name of Object.keys(got)) {
+        if (LIST_QUERY_MEMBERS.includes(name))
+            continue;
+        if (!extensions.includes(name))
+            throw receiptRefusal(`SessionStore.list: this store does not filter by "${name}" — refused rather than listing the rows that filter would exclude`);
+        extended[name] = got[name];
+    }
+    const { owner: ownerGiven, includeUnowned, after, limit } = got;
+    const owner = ownerGiven === undefined ? undefined : principalNameOf(ownerGiven);
+    if (ownerGiven !== undefined && owner === undefined) {
+        throw receiptRefusal(`SessionListQuery.owner must be a principal name (a string with a visible character, no control or separator character, and no format character but a joiner) when present, got ${principalNameFault(ownerGiven)}`);
+    }
+    if (includeUnowned !== undefined && typeof includeUnowned !== "boolean")
+        throw receiptRefusal(`SessionListQuery.includeUnowned must be a boolean when present, got ${typeof includeUnowned}`);
+    if (includeUnowned !== undefined && owner === undefined)
+        throw receiptRefusal("SessionListQuery.includeUnowned is a member of the owner filter and was given without owner — refused rather than read as every owner's list");
+    if (limit !== undefined && !(typeof limit === "number" && Number.isSafeInteger(limit) && limit >= 1 && limit <= SESSION_LIST_LIMITS.max)) {
+        throw receiptRefusal(`SessionListQuery.limit must be an integer in 1..${SESSION_LIST_LIMITS.max} when present`);
+    }
+    return {
+        ...(owner !== undefined ? { owner } : {}),
+        includeUnowned: includeUnowned === true,
+        ...(after !== undefined ? { after: readListCursor(after) } : {}),
+        limit: limit ?? SESSION_LIST_LIMITS.default,
+        extensions: extended,
+    };
+}
+function readListCursor(raw) {
+    if (typeof raw !== "object" || raw === null)
+        throw receiptRefusal(`SessionListQuery.after must be an object when present, got ${raw === null ? "null" : typeof raw}`);
+    const got = receiveOwnProperties(raw, { subject: "SessionListQuery.after", unit: "member", moment: "at SessionStore.list" });
+    for (const name of Object.keys(got)) {
+        if (name !== "lastActiveAt" && name !== "sessionId")
+            throw receiptRefusal(`SessionListQuery.after carries "${name}" — a cursor is a lastActiveAt and a sessionId`);
+    }
+    const { lastActiveAt, sessionId } = got;
+    if (typeof lastActiveAt !== "number" || !Number.isFinite(lastActiveAt))
+        throw receiptRefusal("SessionListQuery.after.lastActiveAt must be a finite number");
+    if (typeof sessionId !== "string")
+        throw receiptRefusal(`SessionListQuery.after.sessionId must be a string, got ${typeof sessionId}`);
+    return { lastActiveAt, sessionId };
+}
 export function hasSessionFork(store) {
     return typeof store.fork === "function";
 }

package/dist/core/shared-memory/tools.js

@@ -2,7 +2,7 @@ import { Type } from "typebox";
 import { errorResult } from "../tools.js";
 import { CONNECTING_MESSAGE, GENERIC_FAILURE_MESSAGE, NO_STORES_MESSAGE, SHARED_STORE_FRAME, UNAVAILABLE_MESSAGE, datePrefixOf, echoUntrusted, foldReaderError, listPrefixArgument, normalizeEntries, normalizeMemoryPath, normalizeReadValue, normalizeSnapshot, pageDocuments, relativePathRefusal, sanitizeSharedContent, validateDocumentPath, validatePathPrefix, } from "./normalize.js";
 import { SHARED_MEMORY_LIST_PAGE_SIZE, SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_READ_TOOL_NAME, } from "./types.js";
-import { toolFace } from "../tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "../tool-catalog-entries.js";
 const LIST_HINT = "List shared memory stores and their documents — check here before telling the user you do not have something.";
 const LIST_DESCRIPTION = [
     LIST_HINT,
@@ -127,6 +127,7 @@ export function createSharedMemoryTools(opts) {
     const listTool = {
         name: SHARED_MEMORY_LIST_TOOL_NAME,
         ...toolFace("memory-list"),
+        ruleFace: mountRuleFace("memory-list"),
         description: LIST_DESCRIPTION,
         defer: true,
         parameters: Type.Object({
@@ -258,6 +259,7 @@ export function createSharedMemoryTools(opts) {
     const readTool = {
         name: SHARED_MEMORY_READ_TOOL_NAME,
         ...toolFace("memory-read"),
+        ruleFace: mountRuleFace("memory-read"),
         description: READ_DESCRIPTION,
         defer: true,
         parameters: Type.Object({

package/dist/core/shared-memory/types.d.ts

@@ -2,7 +2,7 @@
  * design/177 — the SHARED memory-store seam (connected team/deployment memory libraries the model may
  * BROWSE and READ through two tools) and its model-facing constants.
  *
- * Upstream anchor: CC 2.1.223's `memory_list` / `memory_read` pair, whose defining property was READ/WRITE
+ * Upstream anchor: the reference's `memory_list` / `memory_read` pair, whose defining property was READ/WRITE
  * ASYMMETRY (no model-side write channel); CC no longer has that shape — 2.1.296 also mounts `yd` (cli296.js:242348) "memory_write" — and sema keeps the 223 one (KL-878): write governance is an
  * environment concern, and the tool face's entire participation in it is truthfully reporting each
  * store's `writable` bit. sema keeps that structure and pushes the whole credential/consent half onto

package/dist/core/shell-read-silence.d.ts

@@ -1,7 +1,7 @@
 import type { ShellReadVerdict } from "../tools/fs/shell-read-check.js";
 import { type ShellReadDisposition } from "../tools/fs/shell-read-judge.js";
 import type { GatePass } from "./runner/gate-exit.js";
-import type { AskGuard } from "./tool-policy.js";
+import type { PermissionResult } from "./tool-policy.js";
 /** One station answer, received and read: what a reader acts on (`kind`) and the answer it acts on (`verdict` — the engine's own
  *  copy, received once). `unbelieved`: the station's answer was not received or contradicted its own finding, and `verdict` is the
  *  engine's refusal of it (its sentence names the station's words only where they are words of the closed sets — nothing a station
@@ -35,17 +35,16 @@ export interface StationAnswerCall {
  * ({@link silencedBy}).
  */
 export declare function readStationAnswer(answer: ShellReadVerdict, call: StationAnswerCall): StationAnswerReading;
-/** Whose silence a station's answer carries, each its own class on the question it keeps or mints: unread rows are a rule that could
- *  not be read (the rule lane's class); the finding `unanswered` is, unless rows are unread, the environment's silence — shell text the
- *  engine cannot read (a guard) — and the marks only pick whose. Either is a question only a person answers; `probe` follows the finding. */
-export declare function silencedBy(verdict: ShellReadVerdict, d: {
-    readonly guards?: readonly AskGuard[];
-    readonly ruleUnreadable?: unknown;
-}): {
-    ruleUnreadable?: "persisted_rows";
-    guards?: readonly AskGuard[];
-    requiresRealApproval?: true;
-};
+/** The ask `d` with the silence a station's answer carries, each its own class on the question it keeps or mints: unread rows are a
+ *  rule that could not be read (the rule lane's class); the finding `unanswered` is, unless rows are unread, the environment's silence —
+ *  shell text the engine cannot read (a guard, attested on the ask's record for `call` beside the guards it already carries) — and the
+ *  marks only pick whose. Either is a question only a person answers; `probe` follows the finding. No silence ⇒ `d` itself. */
+export declare function silencedBy<D extends Extract<PermissionResult, {
+    action: "ask";
+}>>(d: D, verdict: ShellReadVerdict, call: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+}): D;
 /** The station's SILENCE ({@link readStationAnswer}), applied once, before any disposition arm: a station — a host-mounted one
  *  included — may spell `vouch`, `mandated` or `ordinary` beside it, and no word vouches for what nobody judged. A deny stands; an
  *  ask keeps its words and gains the silence's class; an allow becomes the silence's question (`ask.message`), one only a person

package/dist/core/shell-read-silence.js

@@ -3,6 +3,7 @@ import { dispositionsOfRow, SHELL_READ_FINDINGS } from "../tools/fs/shell-read-j
 import { receiveContract } from "./decision-receipt.js";
 import { egressThrownText } from "./untrusted-egress.js";
 import { receive } from "./mods/kernel/receive.js";
+import { attest, attestationOf } from "./engine-attestation.js";
 const DISPOSITIONS = ["refuse", "mandated", "ordinary", "vouch"];
 const MEMBER_KINDS = {
     disposition: "word",
@@ -71,21 +72,24 @@ export function readStationAnswer(answer, call) {
     call.report?.(new Error(`shell read station answered out of its contract for tool "${call.toolName}"${call.toolCallId !== undefined ? ` (toolCallId ${call.toolCallId})` : ""} — ${sentence}`));
     return { kind: "refuse", verdict: { disposition: "refuse", finding: "none", sentence }, unbelieved: true };
 }
-export function silencedBy(verdict, d) {
+export function silencedBy(d, verdict, call) {
     const environment = verdict.environmentSilent === true || (verdict.finding === "unanswered" && verdict.rowsUnread !== true);
+    if (!environment && verdict.rowsUnread !== true)
+        return d;
     const rows = verdict.rowsUnread === true && d.ruleUnreadable === undefined ? { ruleUnreadable: "persisted_rows" } : {};
-    const guards = environment && d.guards?.includes("unverifiable_shell_text") !== true ? { guards: [...(d.guards ?? []), "unverifiable_shell_text"] } : {};
-    return environment || verdict.rowsUnread === true ? { ...rows, ...guards, requiresRealApproval: true } : {};
+    const out = { ...d, ...rows, requiresRealApproval: true };
+    const held = attestationOf(d, call)?.guards ?? [];
+    return environment && !held.includes("unverifiable_shell_text") ? attest(out, call, { guards: [...held, "unverifiable_shell_text"] }) : out;
 }
 export function applyUnansweredSilence(pass, verdict, ask) {
     if (verdict.details !== undefined)
         pass.shellReadDetails = verdict.details;
     if (pass.decision.action === "ask") {
-        pass.decision = { ...pass.decision, ...silencedBy(verdict, pass.decision) };
+        pass.decision = silencedBy(pass.decision, verdict, pass.req);
         return;
     }
     if (pass.decision.action !== "allow")
         return;
-    pass.decision = { action: "ask", message: ask.message, decisionReason: "safety", ...silencedBy(verdict, {}), ...(ask.account !== undefined ? { probeReason: ask.account } : {}) };
+    pass.decision = silencedBy({ action: "ask", message: ask.message, decisionReason: "safety", ...(ask.account !== undefined ? { probeReason: ask.account } : {}) }, verdict, pass.req);
     pass.tightenedBy = ask.tightenedBy;
 }

package/dist/core/shell-run-candidates.js

@@ -276,7 +276,7 @@ function unwrap(words) {
     if (row.viaShell === true)
         return `\`${name}\` evaluates its operands as shell input this reader does not read`;
     if (row.executes !== undefined) {
-        const hit = words.slice(1).find((w) => w.expands !== false || row.executes.includes(w.text));
+        const hit = words.slice(1).find((w) => w.expands !== false || row.executes.some((x) => w.text === x || (x.length === 2 && /^-[^-]/.test(w.text) && w.text.includes(x[1]))));
         return hit === undefined ? words : hit.expands !== false ? `an expansion where \`${name}\` reads its arguments` : `\`${name} ${hit.text}\` runs a command this reader does not read`;
     }
     const valueFlags = new Set(row.valueFlags);
@@ -394,6 +394,8 @@ function unwrap(words) {
         if (r !== true)
             return r;
         i++;
+        if (durationTaken && positionalTaken)
+            break;
     }
     if (i >= words.length)
         return words;

package/dist/core/shell-wrapper-projection.js

@@ -30,7 +30,7 @@ const runsCommand = (spec) => spec.effect === "executes" || spec.value?.kind ===
 function projectRow(row) {
     const sorted = (xs) => [...new Set(xs)].sort();
     const all = spellings(row);
-    const viaShell = row.reentry?.kind === "shell" || row.launcher?.shellText !== undefined || row.body === "first-operand" || row.body === "assignment-values" || (row.operands?.rest?.kind === "program-text" && row.operands.rest.language === "arithmetic");
+    const viaShell = (row.reentry?.kind === "shell" && row.reentry.text !== "history") || row.launcher?.shellText !== undefined || row.body === "first-operand" || row.body === "assignment-values" || (row.operands?.rest?.kind === "program-text" && row.operands.rest.language === "arithmetic");
     if (row.launcher === undefined) {
         if (viaShell)
             return { valueFlags: [], flags: [], commandString: [], viaShell: true };

package/dist/core/shell-wrapper-table.d.ts

@@ -181,6 +181,12 @@ export declare const SHELL_WRAPPER_TABLE: {
         readonly commandString: readonly [];
         readonly viaShell: true;
     };
+    readonly fc: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-e", "-s"];
+    };
     readonly source: {
         readonly valueFlags: readonly [];
         readonly flags: readonly [];
@@ -289,14 +295,14 @@ export declare const SHELL_WRAPPER_TABLE: {
         readonly viaShell: true;
     };
     readonly chroot: {
-        readonly valueFlags: readonly [];
-        readonly flags: readonly [];
+        readonly valueFlags: readonly ["--groups", "--userspec", "-G", "-g", "-u"];
+        readonly flags: readonly ["--help", "--skip-chdir", "--version"];
         readonly commandString: readonly [];
         readonly positional: RegExp;
     };
     readonly setpriv: {
-        readonly valueFlags: readonly [];
-        readonly flags: readonly [];
+        readonly valueFlags: readonly ["--ambient-caps", "--apparmor-profile", "--bounding-set", "--egid", "--euid", "--groups", "--inh-caps", "--pdeathsig", "--regid", "--reuid", "--rgid", "--ruid", "--securebits", "--selinux-label"];
+        readonly flags: readonly ["--clear-groups", "--dump", "--help", "--init-groups", "--keep-groups", "--nnp", "--no-new-privs", "--reset-env", "--version", "-V", "-d", "-h"];
         readonly commandString: readonly [];
     };
     readonly numactl: {
@@ -305,8 +311,9 @@ export declare const SHELL_WRAPPER_TABLE: {
         readonly commandString: readonly [];
     };
     readonly prlimit: {
-        readonly valueFlags: readonly [];
-        readonly flags: readonly [];
+        readonly valueFlags: readonly ["--output", "--pid", "-o", "-p"];
+        readonly flags: readonly ["--as", "--core", "--cpu", "--data", "--fsize", "--help", "--locks", "--memlock", "--msgqueue", "--nice", "--nofile", "--noheadings", "--nproc", "--raw", "--rss", "--rtprio", "--rttime", "--sigpending", "--stack", "--verbose", "--version", "-V", "-h"];
+        readonly attached: readonly ["-c", "-d", "-e", "-f", "-i", "-l", "-m", "-n", "-q", "-r", "-s", "-t", "-u", "-v", "-x", "-y"];
         readonly commandString: readonly [];
     };
     readonly "systemd-run": {
@@ -316,7 +323,7 @@ export declare const SHELL_WRAPPER_TABLE: {
     };
     readonly valgrind: {
         readonly valueFlags: readonly [];
-        readonly flags: readonly [];
+        readonly flags: readonly ["--alignment", "--allow-mismatched-debuginfo", "--avg-transtab-entry-size", "--cachegrind-out-file", "--callgrind-out-file", "--child-silent-after-fork", "--default-suppressions", "--demangle", "--dhat-out-file", "--dsymutil", "--error-exitcode", "--error-limit", "--error-markers", "--errors-for-leak-kinds", "--exit-on-first-error", "--expensive-definedness-checks", "--fair-sched", "--free-fill", "--freelist-big-blocks", "--freelist-vol", "--fullpath-after", "--gen-suppressions", "--help", "--help-debug", "--help-dyn-options", "--ignore-range-below-sp", "--ignore-ranges", "--input-fd", "--keep-debuginfo", "--keep-stacktraces", "--kernel-variant", "--leak-check", "--leak-check-heuristics", "--leak-resolution", "--log-fd", "--log-file", "--main-stacksize", "--malloc-fill", "--massif-out-file", "--max-stackframe", "--max-threads", "--merge-recursive-frames", "--num-callers", "--num-transtab-sectors", "--partial-loads-ok", "--quiet", "--read-inline-info", "--read-var-info", "--redzone-size", "--resync-filter", "--run-cxx-freeres", "--run-libc-freeres", "--show-below-main", "--show-emwarns", "--show-error-list", "--show-leak-kinds", "--show-mismatched-frees", "--show-possibly-lost", "--show-reachable", "--sigill-diagnostics", "--sim-hints", "--smc-check", "--soname-synonyms", "--suppressions", "--time-stamp", "--tool", "--trace-children", "--trace-children-skip", "--trace-children-skip-by-arg", "--track-fds", "--track-origins", "--undef-value-errors", "--unw-stack-scan-frames", "--unw-stack-scan-thresh", "--valgrind-stacksize", "--verbose", "--version", "--vgdb", "--vgdb-error", "--vgdb-poll", "--vgdb-shadow-registers", "--vgdb-stop-at", "--workaround-gcc296-bugs", "--xml", "--xml-fd", "--xml-file", "--xml-user-comment", "--xtree-leak", "--xtree-leak-file", "--xtree-memory", "--xtree-memory-file", "-h", "-q", "-s", "-v"];
         readonly commandString: readonly [];
     };
     readonly firejail: {

package/dist/core/shell-wrapper-table.js

@@ -27,6 +27,7 @@ export const SHELL_WRAPPER_TABLE = {
     unshare: { valueFlags: ["--boottime", "--map-group", "--map-user", "--monotonic", "--propagation", "--root", "--setgid", "--setgroups", "--setuid", "--wd", "-G", "-R", "-S", "-w"], flags: ["--cgroup", "--fork", "--help", "--ipc", "--keep-caps", "--kill-child", "--map-current-user", "--map-root-user", "--mount", "--mount-proc", "--net", "--pid", "--time", "--user", "--uts", "--version", "-C", "-T", "-U", "-c", "-f", "-i", "-m", "-n", "-p", "-r", "-u"], commandString: [] },
     nsenter: { valueFlags: ["--setgid", "--setuid", "--target", "-G", "-S", "-t"], flags: ["--all", "--cgroup", "--help", "--ipc", "--mount", "--net", "--no-fork", "--pid", "--preserve-credentials", "--root", "--time", "--user", "--uts", "--version", "--wd", "-C", "-F", "-T", "-U", "-Z", "-a", "-i", "-m", "-n", "-p", "-u"], attached: ["-r", "-w"], commandString: [] },
     eval: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    fc: { valueFlags: [], flags: [], commandString: [], executes: ["-e", "-s"] },
     source: { valueFlags: [], flags: [], commandString: [], viaShell: true },
     ".": { valueFlags: [], flags: [], commandString: [], viaShell: true },
     trap: { valueFlags: [], flags: [], commandString: [], viaShell: true },
@@ -45,12 +46,12 @@ export const SHELL_WRAPPER_TABLE = {
     busybox: { valueFlags: [], flags: [], commandString: [] },
     su: { valueFlags: ["--group", "--shell", "--supp-group", "--whitelist-environment", "-G", "-g", "-s", "-w"], flags: ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"], commandString: ["--command", "--session-command", "-c"], viaShell: true },
     runuser: { valueFlags: ["--group", "--shell", "--supp-group", "--user", "--whitelist-environment", "-G", "-g", "-s", "-u", "-w"], flags: ["--fast", "--help", "--login", "--no-pty", "--preserve-environment", "--pty", "--version", "-P", "-T", "-V", "-f", "-h", "-l", "-m", "-p"], commandString: ["--command", "--session-command", "-c"], viaShell: true },
-    chroot: { valueFlags: [], flags: [], commandString: [], positional: /^/ },
-    setpriv: { valueFlags: [], flags: [], commandString: [] },
+    chroot: { valueFlags: ["--groups", "--userspec", "-G", "-g", "-u"], flags: ["--help", "--skip-chdir", "--version"], commandString: [], positional: /^/ },
+    setpriv: { valueFlags: ["--ambient-caps", "--apparmor-profile", "--bounding-set", "--egid", "--euid", "--groups", "--inh-caps", "--pdeathsig", "--regid", "--reuid", "--rgid", "--ruid", "--securebits", "--selinux-label"], flags: ["--clear-groups", "--dump", "--help", "--init-groups", "--keep-groups", "--nnp", "--no-new-privs", "--reset-env", "--version", "-V", "-d", "-h"], commandString: [] },
     numactl: { valueFlags: [], flags: [], commandString: [] },
-    prlimit: { valueFlags: [], flags: [], commandString: [] },
+    prlimit: { valueFlags: ["--output", "--pid", "-o", "-p"], flags: ["--as", "--core", "--cpu", "--data", "--fsize", "--help", "--locks", "--memlock", "--msgqueue", "--nice", "--nofile", "--noheadings", "--nproc", "--raw", "--rss", "--rtprio", "--rttime", "--sigpending", "--stack", "--verbose", "--version", "-V", "-h"], attached: ["-c", "-d", "-e", "-f", "-i", "-l", "-m", "-n", "-q", "-r", "-s", "-t", "-u", "-v", "-x", "-y"], commandString: [] },
     "systemd-run": { valueFlags: [], flags: [], commandString: [] },
-    valgrind: { valueFlags: [], flags: [], commandString: [] },
+    valgrind: { valueFlags: [], flags: ["--alignment", "--allow-mismatched-debuginfo", "--avg-transtab-entry-size", "--cachegrind-out-file", "--callgrind-out-file", "--child-silent-after-fork", "--default-suppressions", "--demangle", "--dhat-out-file", "--dsymutil", "--error-exitcode", "--error-limit", "--error-markers", "--errors-for-leak-kinds", "--exit-on-first-error", "--expensive-definedness-checks", "--fair-sched", "--free-fill", "--freelist-big-blocks", "--freelist-vol", "--fullpath-after", "--gen-suppressions", "--help", "--help-debug", "--help-dyn-options", "--ignore-range-below-sp", "--ignore-ranges", "--input-fd", "--keep-debuginfo", "--keep-stacktraces", "--kernel-variant", "--leak-check", "--leak-check-heuristics", "--leak-resolution", "--log-fd", "--log-file", "--main-stacksize", "--malloc-fill", "--massif-out-file", "--max-stackframe", "--max-threads", "--merge-recursive-frames", "--num-callers", "--num-transtab-sectors", "--partial-loads-ok", "--quiet", "--read-inline-info", "--read-var-info", "--redzone-size", "--resync-filter", "--run-cxx-freeres", "--run-libc-freeres", "--show-below-main", "--show-emwarns", "--show-error-list", "--show-leak-kinds", "--show-mismatched-frees", "--show-possibly-lost", "--show-reachable", "--sigill-diagnostics", "--sim-hints", "--smc-check", "--soname-synonyms", "--suppressions", "--time-stamp", "--tool", "--trace-children", "--trace-children-skip", "--trace-children-skip-by-arg", "--track-fds", "--track-origins", "--undef-value-errors", "--unw-stack-scan-frames", "--unw-stack-scan-thresh", "--valgrind-stacksize", "--verbose", "--version", "--vgdb", "--vgdb-error", "--vgdb-poll", "--vgdb-shadow-registers", "--vgdb-stop-at", "--workaround-gcc296-bugs", "--xml", "--xml-fd", "--xml-file", "--xml-user-comment", "--xtree-leak", "--xtree-leak-file", "--xtree-memory", "--xtree-memory-file", "-h", "-q", "-s", "-v"], commandString: [] },
     firejail: { valueFlags: [], flags: [], commandString: [] },
     bwrap: { valueFlags: [], flags: [], commandString: [] },
     ash: { valueFlags: [], flags: [], commandString: [], viaShell: true },

package/dist/core/side-query.d.ts

@@ -1,6 +1,7 @@
 import type { AssistantMessage, StopReason, Tool, ToolResultMessage, Usage, UserMessage } from "../internal/llm.js";
 import type { Brain, Model, ModelRef, ModelRole, ModelRoles, TaskSpec, ThinkingLevel } from "./types.js";
 import { type DegradationInfo } from "../brain/degrading.js";
+import { type BrainErrorCode } from "../brain/errors.js";
 /** A tool DEFINITION exposed to the model in a side query (never executed by the engine). */
 export interface SideQueryToolDef {
     name: string;
@@ -117,6 +118,15 @@ export interface SideQueryResult {
      *  RETURNS the honest failure instead of throwing: utility callers uniformly need "no answer +
      *  why", and a throw would lose usage/model attribution for the failed attempt. */
     errorMessage?: string;
+    /** The brain code of a failed query (`stopReason:"error"`), lifted from {@link errorMessage}'s `[code]` prefix by the one
+     *  shared parser; absent when the message names none (an engine-minted shell, a custom brain). */
+    errorCode?: BrainErrorCode;
+    /** The STRUCTURAL failure kind the reply carried (`AssistantMessage.errorKind`), forwarded as is: `input_too_long` (the
+     *  provider refused the request as over its window), `length_empty`, `degenerate`. Absent when the reply carried none. */
+    errorKind?: AssistantMessage["errorKind"];
+    /** `true` when the failure was a provider refusal its minter RULED OUT as input-too-long (`AssistantMessage.inputTooLongRuledOut`),
+     *  forwarded as is. Absent otherwise. */
+    inputTooLongRuledOut?: true;
 }
 /** Dependencies the Runner passes through (a strict subset of RunnerDeps — no session/tool machinery). */
 export interface SideQueryDeps {