@sema-agent/core 7.14.0 → 7.16.0

package/dist/tools/fs/index.d.ts

@@ -17,34 +17,34 @@ export * from "./read-face.js";
 import { type CwdRef, type ReadImageDownsamplerOption } from "./fs-shared.js";
 /** Options for {@link createHandsToolkit}. */
 export interface HandsToolkitOptions {
-    /** design/119 (CC --add-dir parity): extra allowed containment roots (canonical). Widens file-tool
-     *  containment only; the primary root keeps the cwd/base role. The full `bash` (effect:write) is NOT
-     *  constrained by these — it is deliberately unsandboxed and only uses them for its post-`cd`
-     *  disclosure note. RB-413: `bash_readonly` IS constrained by them (that face refuses a read outside
-     *  the roots), so widening here widens what the read-only band may read. */
+    /** CC --add-dir parity: extra allowed containment roots (canonical). Widens file-tool containment
+     *  only; the primary root keeps the cwd/base role. The full `bash` (effect:write) is NOT constrained
+     *  by these — it is deliberately unsandboxed and only uses them for its post-`cd` disclosure note.
+     *  `bash_readonly` IS constrained by them (that face refuses a read outside the roots), so widening
+     *  here widens what the read-only band may read. */
     additionalRoots?: readonly string[];
-    /** Ruled 2026-08-05 (read-boundary whitelist): extra allowed containment roots for the READ faces
-     *  only — read_file/grep/glob/repo_map and (RB-413) `bash_readonly` admit them; edit_file/
-     *  write_file/notebook_edit and the full `bash`'s disclosure roots deliberately do NOT (widening
-     *  reads must never silently widen writes). Caveat, same tradeoff RB-413 already states for
-     *  `additionalRoots`: `bash_readonly`'s COMMAND allowlist is a deployment declaration — a
+    /** The read-boundary whitelist: extra allowed containment roots for the READ faces only —
+     *  read_file/grep/glob/repo_map and `bash_readonly` admit them; edit_file/write_file/notebook_edit
+     *  and the full `bash`'s disclosure roots deliberately do NOT (widening reads must never silently
+     *  widen writes). Caveat, the same tradeoff `additionalRoots` states:
+     *  `bash_readonly`'s COMMAND allowlist is a deployment declaration — a
      *  deployment that puts a mutating command into `bashReadonlyAllow` has declared it read-safe,
      *  and that declaration applies inside every root, these included. Keep the allowlist genuinely
      *  non-mutating if these roots must stay read-only through the shell face too. */
     additionalReadRoots?: readonly string[];
     /** Mount a shell tool. Pass false for an env without a real shell (e.g. `StubExecutionEnv`) so a bash
-     *  tool that can only error never reaches the model (design/44 §9 S1). Default false. */
+     *  tool that can only error never reaches the model. Default false. */
     includeShell?: boolean;
-    /** Verifier read-only boundary (design/44 §6): mount ONLY effect:read hand tools — read_file/grep/glob
+    /** Verifier read-only boundary: mount ONLY effect:read hand tools — read_file/grep/glob
      *  (+ `bash_readonly` when `includeShell`). Drops edit_file/write_file and the full `bash`. Default false. */
     readOnly?: boolean;
     /** Override the `bash_readonly` command allowlist (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
     bashReadonlyAllow?: readonly string[];
-    /** Commit-message attribution trailer for the `bash` git protocol (design/64 §8.1D). Default NONE
-     *  ([c209] BREAKING: attribution is a deployment identity asset — the branded scenario sets it);
-     *  pass `"Name <email>"` to advertise one, `false` (≡ unset) for no trailer section. */
+    /** Commit-message attribution trailer for the `bash` git protocol. Default NONE — attribution is a
+     *  deployment identity asset, so the branded deployment sets it; pass `"Name <email>"` to advertise
+     *  one, `false` (≡ unset) for no trailer section. */
     commitCoAuthor?: string | false;
-    /** design/99 §E13 — the caller's own {@link CwdRef} to track this task's logical cwd, instead of one
+    /** The caller's own {@link CwdRef} to track this task's logical cwd, instead of one
      *  created internally. The Runner passes its own so it can OBSERVE `cd` moves (`cwdRef.current` changes)
      *  and emit a `workspace_changed` event. Ignored in `readOnly` mode (no `cd`). Default: a fresh ref at root. */
     cwdRef?: CwdRef;
@@ -53,56 +53,55 @@ export interface HandsToolkitOptions {
     /** Runner-owned owner/scope fallback used when a tool execute context is unavailable in tests. */
     taskOwner?: string;
     taskScope?: string;
-    /** design/129 — see createBashTool's taskOpts.sessionId: session-resident background commands. */
+    /** See createBashTool's taskOpts.sessionId: session-resident background commands. */
     sessionId?: string;
     /** Mount TaskOutput/TaskStop directly from this band. Runner sets false and mounts the unified dispatcher once. */
     mountBackgroundTaskTools?: boolean;
-    /** design/116 §7 G2b: completion-notification sink for finished background commands (threaded to
-     *  createBashTool's onTaskNotification; the Runner wires the run-local injection lane here). */
+    /** Completion-notification sink for finished background commands (threaded to createBashTool's
+     *  onTaskNotification; the Runner wires the run-local injection lane here). */
     taskNotification?: (n: import("../../core/task-notification.js").TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
-    /** design/116 detach: the run-local per-tool-call detach hub (mid-flight ctrl+b → adopt as background). */
+    /** The run-local per-tool-call detach hub (mid-flight ctrl+b → adopt as background). */
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
-    /** RB-370 ② (cli): the Bash `timeout` parameter's DEFAULT budget, in ms — applied when the
-     *  model omits `timeout`. Resolution (options over env over constant — the standing sema discipline:
-     *  deployments configure the tool, not the process): this field ?? env `BASH_DEFAULT_TIMEOUT_MS` ??
-     *  120000; invalid (non-finite / <= 0) values are discarded at every leg. See
+    /** The Bash `timeout` parameter's DEFAULT budget, in ms — applied when the model omits `timeout`.
+     *  Resolution (options over env over constant — the standing sema discipline: deployments configure
+     *  the tool, not the process): this field ?? env `BASH_DEFAULT_TIMEOUT_MS` ?? 120000; invalid
+     *  (non-finite / <= 0) values are discarded at every leg. See
      *  {@link import("./fs-shared.js").resolveBashTimeoutCaps} — the SAME resolver renders the tool
-     *  description, so the advertised numbers always match the enforced ones. Additive: absent ⇒
-     *  byte-compat 120s. Applies to both shell legs (`bash` and `bash_readonly`). */
+     *  description, so the advertised numbers always match the enforced ones. Absent ⇒ 120s. Applies to
+     *  both shell legs (`bash` and `bash_readonly`). */
     bashDefaultTimeoutMs?: number;
-    /** RB-370 ② (cli): the Bash `timeout` parameter's engine CEILING, in ms — requests above it
-     *  are clamped (with the RB-370 requested/capped disclosure naming THIS value). Resolution: (this
-     *  field ?? env `BASH_MAX_TIMEOUT_MS` ?? 600000), then floored at the resolved default — CC's own
-     *  only-widen semantic: a ceiling below the default is a narrowing intent = invalid, ignored in
-     *  favor of the default. Additive: absent ⇒ byte-compat 600s. */
+    /** The Bash `timeout` parameter's engine CEILING, in ms — requests above it are clamped (the
+     *  requested/capped disclosure names THIS value). Resolution: (this field ?? env
+     *  `BASH_MAX_TIMEOUT_MS` ?? 600000), then floored at the resolved default — CC's own only-widen
+     *  semantic: a ceiling below the default is a narrowing intent = invalid, ignored in favor of the
+     *  default. Absent ⇒ 600s. */
     bashMaxTimeoutMs?: number;
     /** Structured sink for the timeout-cap discard announcements both shell legs emit at mount (see
      *  {@link import("../../core/types.js").EngineNotice} / `RunnerDeps.onNotice`). Wired, it REPLACES
      *  their `console.warn` line (a forwarding host must not show every fact twice); absent, the
-     *  console line prints verbatim (byte-compat loudness). Threaded per toolkit build — never a
+     *  console line prints verbatim (last-resort loudness). Threaded per toolkit build — never a
      *  global. */
     onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
-    /** RB-220 — see createBashTool's taskOpts.oneShot / createTaskOutputTool's TaskToolOptions.oneShot for
-     *  the full contract: this run has no later turn for an async background notification to land in.
+    /** See createBashTool's taskOpts.oneShot / createTaskOutputTool's TaskToolOptions.oneShot for the
+     *  full contract: this run has no later turn for an async background notification to land in.
      *  Threaded to both the Bash background-launch receipt and (when this band mounts TaskOutput itself,
-     *  `mountBackgroundTaskTools: true`) the TaskOutput poll receipt. Absent ⇒ byte-compat (unbranched,
-     *  pre-RB-220 wording). */
+     *  `mountBackgroundTaskTools: true`) the TaskOutput poll receipt. Absent ⇒ the unbranched wording. */
     oneShot?: boolean;
-    /** RB-198 F1 (CC 220 `Zry`/`WZi.#m` parity): see createBashTool's taskOpts field of the same name for the
-     *  full contract. Threaded from {@link HandsBandOptions.autoBackgroundOnTimeout} (a deployment-level
-     *  opt-in) — NOT from `detachHub`/`taskRegistry` merely being present, which are wired unconditionally by
-     *  the Runner for every task and so cannot double as an opt-in signal. Default undefined ⇒ `false`
-     *  downstream (byte-compat: an omitted field changes nothing for any existing caller). */
+    /** CC `Zry`/`WZi.#m` parity: see createBashTool's taskOpts field of the same name for the full
+     *  contract. Threaded from {@link HandsBandOptions.autoBackgroundOnTimeout} (a deployment-level
+     *  opt-in) — NOT from `detachHub`/`taskRegistry` merely being present, which are wired unconditionally
+     *  by the Runner for every task and so cannot double as an opt-in signal. Default undefined ⇒ `false`
+     *  downstream. */
     autoBackgroundOnTimeout?: boolean;
-    /** 批③: Read-image downsampler seam ({@link ReadImageDownsamplerOption}). Default undefined = auto-detect
+    /** Read-image downsampler seam ({@link ReadImageDownsamplerOption}). Default undefined = auto-detect
      *  the optional sharp dependency once per process; `false` disables it (deterministic no-sharp behavior). */
     readImageDownsampler?: ReadImageDownsamplerOption;
-    /** PDF degradation chain v2: the SERVING model's PDF capability profile (prepare-task derives it via
+    /** PDF degradation chain: the SERVING model's PDF capability profile (prepare-task derives it via
      *  {@link import("./fs-pdf.js").pdfModelCapabilitiesOf}). A model without native document input gets pdftotext text extraction →
      *  rendered page images (vision) → an honest placeholder, instead of a brain-level placeholder. Default
-     *  undefined = fully capable (byte-compat: native document block). */
+     *  undefined = fully capable (native document block). */
     pdfModelCapabilities?: PdfModelCapabilities;
     /** Append the per-read content-safety reminder after a successful text read
      *  ({@link import("./fs-shared.js").readCyberReminderText}). Default TRUE — a BYOM deployment cannot
@@ -112,10 +111,10 @@ export interface HandsToolkitOptions {
      *  exemption gate the upstream 88 source had around the same mechanism (see readCyberReminderText's note
      *  for the full attribution). Absent ⇒ appended. */
     readCyberReminder?: boolean;
-    /** design/138 S2-C — write-time content gate for Write/Edit/NotebookEdit (see {@link BeforeWriteHook}).
-     *  The Runner wires the MemoryEngine's memory-domain scan here; absent ⇒ byte-identical behavior. */
+    /** Write-time content gate for Write/Edit/NotebookEdit (see {@link BeforeWriteHook}). The Runner
+     *  wires the MemoryEngine's memory-domain scan here; absent ⇒ byte-identical behavior. */
     beforeWrite?: BeforeWriteHook;
-    /** design/381 — first-touch file-history hook for Write/Edit/NotebookEdit (see
+    /** First-touch file-history hook for Write/Edit/NotebookEdit (see
      *  {@link TrackFileEditHook}): called after the content gates pass, immediately before the final
      *  env write, so the file's pre-edit state is durably recorded before it changes. The Runner
      *  wires it to `FileHistoryStore.trackEdit`; absent ⇒ byte-identical behavior (no history). */
@@ -126,54 +125,51 @@ export interface HandsToolkitOptions {
      *  Purely additive: it cannot refuse a write, and a fault in it is contained in both shapes (a
      *  synchronous throw and a rejected promise), neither of them awaited. */
     onFileEdited?: FileEditedHook;
-    /** #181-F6 — see createBashTool's taskOpts field of the same name: whether the Monitor tool is on
-     *  this run's roster (the Runner mounts Monitor, this band never does). `false` drops the gh
-     *  rate-limit hint's Monitor clause; absent ⇒ historic full wording (byte-compat). */
+    /** See createBashTool's taskOpts field of the same name: whether the Monitor tool is on this run's
+     *  roster (the Runner mounts Monitor, this band never does). `false` drops the gh rate-limit hint's
+     *  Monitor clause; absent ⇒ the full wording. */
     monitorToolActive?: boolean;
-    /** design/199 件B — ADDITIONS to the built-in sensitive-path READ deny set
+    /** ADDITIONS to the built-in sensitive-path READ deny set
      *  ({@link import("./read-deny.js").READ_FACE_DEFAULT_DENY_ENTRIES}), judged by the structured read
      *  faces (Read/Grep/Glob/RepoMap and their traversals) in BOTH containment modes. Add-only:
      *  additions union with the active built-ins, `[]` ≡ absent (union identity), and additions can
      *  never remove a built-in — the one removal channel is the deployment's built-in configuration
-     *  ({@link readDenyBuiltinTiers} / {@link readDenyBuiltinExclude}, #245 revision of D-4). Bad entry
-     *  shapes throw at wiring time (#123). The write faces are untouched (their guard is
-     *  createSensitivePathPolicy). */
+     *  ({@link readDenyBuiltinTiers} / {@link readDenyBuiltinExclude}). Bad entry shapes throw at wiring
+     *  time. The write faces are untouched (their guard is createSensitivePathPolicy). */
     readDenyPatterns?: readonly ReadDenyEntry[];
-    /** #245 — the deployment's built-in-table TIER selection ({@link import("./read-deny.js").ReadDenyBuiltinConfig}
+    /** The deployment's built-in-table TIER selection ({@link import("./read-deny.js").ReadDenyBuiltinConfig}
      *  `tiers` key): EXACTLY the listed tiers of {@link import("./read-deny.js").READ_FACE_BUILTIN_DENY_TABLE}
      *  are active (`[]` = none — explicit and legal); absent = the default selection
      *  ({@link import("./read-deny.js").READ_DENY_DEFAULT_TIERS} — every tier except `shell-history`).
      *  Composes with {@link readDenyBuiltinExclude} (tier selection first, then row removal) and never
-     *  touches the additions seats. Unknown tier names throw at wiring time (#123). Deployment seat
-     *  ONLY — deliberately not a TaskSpec key, so no task can widen below its deployment. */
+     *  touches the additions seats. Unknown tier names throw at wiring time. Deployment seat ONLY —
+     *  deliberately not a TaskSpec key, so no task can widen below its deployment. */
     readDenyBuiltinTiers?: readonly string[];
-    /** #245 — per-row removal from the built-in table by STABLE NAME (= the row's canonical pattern
-     *  text, e.g. `".ssh"`, `".config/gcloud"`), applied after {@link readDenyBuiltinTiers} selection.
-     *  Naming a row of an inactive tier is a satisfied intent (no-op); a name matching NO table row
-     *  throws at wiring time (#123 — never silently ignored). Deployment seat ONLY, same clamp
-     *  argument as the tiers key. */
+    /** Per-row removal from the built-in table by STABLE NAME (= the row's canonical pattern text, e.g.
+     *  `".ssh"`, `".config/gcloud"`), applied after {@link readDenyBuiltinTiers} selection. Naming a row
+     *  of an inactive tier is a satisfied intent (no-op); a name matching NO table row throws at wiring
+     *  time (never silently ignored). Deployment seat ONLY, same clamp argument as the tiers key. */
     readDenyBuiltinExclude?: readonly string[];
-    /** design/199 件A — the READ-face containment state for the structured read faces
+    /** The READ-face containment state for the structured read faces
      *  ({@link import("./read-face.js").ReadFace}; resolved through the SAME
      *  {@link import("./read-face.js").resolveReadFace} order prepare-task uses). Absent ⇒ the
-     *  resolution order's default = "roots" (D-1b: the engine never opens implicitly). "open" skips
-     *  ONLY the roots containment judgment — the deny set, the UNC out-of-set refusal and the
-     *  special-file type gates run in both faces (§2.0). Beside `readOnly: true` the mount wins:
-     *  this seat is deps-shaped (a deployment default, not a per-call assertion), so its "open"
-     *  CLAMPS to "roots" and the clamp is ANNOUNCED (`config.read_face_deployment_clamped`, through
-     *  `onNotice` / `console.warn`) — the loud refusal belongs to the TASK seat (`TaskSpec.readFace`),
-     *  which is the one genuine per-call contradiction (#237; stale "refused loudly" wording here
-     *  predated the 96ef89d seat distinction). Never affects the write faces. */
+     *  resolution order's default = "roots" (the engine never opens implicitly). "open" skips ONLY the
+     *  roots containment judgment — the deny set, the UNC out-of-set refusal and the special-file type
+     *  gates run in both faces. Beside `readOnly: true` the mount wins: this seat is deps-shaped (a
+     *  deployment default, not a per-call assertion), so its "open" CLAMPS to "roots" and the clamp is
+     *  ANNOUNCED (`config.read_face_deployment_clamped`, through `onNotice` / `console.warn`) — the loud
+     *  refusal belongs to the TASK seat (`TaskSpec.readFace`), the one genuine per-call contradiction.
+     *  Never affects the write faces. */
     readFace?: "open" | "roots";
-    /** design/319 (A ticket) — the session's reminder provenance mark: the band's engine-minted
+    /** The session's reminder provenance mark: the band's engine-minted
      *  `<system-reminder>` open tags (the Read cyber/dedup/offset/empty reminders and the gh
      *  rate-limit hint) carry it as `mark="…"`, matching the system-prompt declaration the Runner
      *  renders for the same session. Threaded by prepare-task; a library-direct mount that omits it
-     *  keeps the historic bare tags (byte-compat — with no declaration in its prompt, a bare tag is
-     *  the honest form). The tag is rendered by the mint home (core/reminder-mint.ts) — the content
-     *  BODY next to it is byte-untouched. */
+     *  keeps bare tags — with no declaration in its prompt, a bare tag is the honest form. The tag is
+     *  rendered by the mint home (core/reminder-mint.ts) — the content BODY next to it is
+     *  byte-untouched. */
     reminderMark?: string;
-    /** design/319 (B ticket) — the per-run trailer/defuse trigger counters (observation seat, G9②):
+    /** The per-run trailer/defuse trigger counters (observation seat):
      *  the Read text/notebook/PDF-text disclosure trailers bump `read.*` / `notebook.*` / `pdf.*`
      *  keys here. The form suffixes are enumerated once, on the consumer-facing contract
      *  (`TaskResult.stats.mechanisms.reminderDisclosures` in core/types.ts) — this map is the same
@@ -184,10 +180,10 @@ export interface HandsToolkitOptions {
     reminderDisclosureCounts?: import("../../core/reminder-disclosure.js").ReminderDisclosureCounts;
 }
 /**
- * Build the per-task hand tool band over an injected env + fresh per-task read state (design/44 §11 A).
+ * Build the per-task hand tool band over an injected env + fresh per-task read state.
  * `rootCanonical` is the already-canonicalized containment root (prepare-task resolves it once). Normal
  * mode mounts read/edit/write/grep/glob (+`bash` when `includeShell`); `readOnly` mode mounts only the
  * effect:read tools read/grep/glob (+`bash_readonly` when `includeShell`) — the verifier boundary. Subset
- * selection beyond that is the caller's job via the existing design/38 tool-filter.
+ * selection beyond that is the caller's job via the tool-filter.
  */
 export declare function createHandsToolkit(env: ExecutionEnv, readFileState: ReadFileState, rootCanonical: string, opts?: HandsToolkitOptions): AgentTool[];

package/dist/tools/fs/notebook.d.ts

@@ -1,17 +1,16 @@
 import type { ImageContent } from "../../internal/llm.js";
 /**
- * RB-227 — the Read tool's Jupyter-notebook projection: `.ipynb` is rendered as cells
- * with outputs (CC 2.1.220 parity: `Ctd`/`wtd`/`Zx_`/`Qx_`/`eI_`/`tI_`/`Atd`, pretty220.js
- * :371265-:371426), never as raw JSON text. The raw-JSON rendering let a notebook's base64 outputs
- * overflow the Read token cap, auto-paginate into an `isPartialView` entry, and thereby lock
- * NotebookEdit out via the requireRead gate (RB-200 F2) — with the marker's own offset/limit hint
- * pointing at a range that itself exceeds the cap (the base64 lives on one mega-line).
+ * The Read tool's Jupyter-notebook projection: `.ipynb` is rendered as cells with outputs (CC 2.1.220
+ * parity), never as raw JSON text. Raw-JSON rendering lets a notebook's base64 outputs overflow the
+ * Read token cap, auto-paginate into an `isPartialView` entry, and thereby lock NotebookEdit out via
+ * the requireRead gate — with the marker's own offset/limit hint pointing at a range that itself
+ * exceeds the cap (the base64 lives on one mega-line). That is the failure mode this lane removes.
  *
  * Pure module (no I/O, no env): index.ts owns reading/decoding/state; this owns parse + render.
  */
-/** CC 220 `o3r` (:60226): extname === ".ipynb". */
+/** CC `o3r` parity: extname === ".ipynb". */
 export declare function isNotebookPath(p: string): boolean;
-/** CC 220 `Jx_ = 1e4` (:371426): PER-CELL cap on the summed output payload (text chars + image
+/** CC `Jx_` = 1e4: PER-CELL cap on the summed output payload (text chars + image
  *  base64 chars). A cell over it has its ENTIRE outputs array replaced by one pointer line —
  *  per cell, never a running global budget (CC's `Xx_` accumulator restarts for every cell). */
 export declare const NOTEBOOK_CELL_OUTPUT_POINTER_CHARS = 10000;
@@ -20,12 +19,12 @@ export declare const NOTEBOOK_CELL_OUTPUT_POINTER_CHARS = 10000;
  *  text exceeds 10K is always pointered, so this clip is unreachable insurance kept at the same
  *  10K yardstick (simplification of CC's two-stage clip, recorded deliberately). */
 export declare const NOTEBOOK_OUTPUT_TEXT_CLIP = 10000;
-/** RB-227 E4 — cumulative image budget across the WHOLE notebook: the 10K per-cell pointer bounds
- *  one cell, but N cells × ~9KB images is unbounded. CC gets an implicit bound because image data
- *  counts toward its 256KB projected-JSON cap (`ePi = 262144`, :61029) and then HARD-ERRORS; sema
- *  reuses that same figure but as a DEGRADATION budget — images past it are dropped with an honest
- *  marker instead of making the notebook unreadable/uneditable (which is the RB-227 failure mode
- *  this whole lane exists to remove). Divergence-logged. */
+/** Cumulative image budget across the WHOLE notebook: the 10K per-cell pointer bounds one cell, but
+ *  N cells × ~9KB images is unbounded. CC gets an implicit bound because image data counts toward its
+ *  256KB projected-JSON cap (`ePi` = 262144) and then HARD-ERRORS; sema reuses that same figure but as
+ *  a DEGRADATION budget — images past it are dropped with an honest marker instead of making the
+ *  notebook unreadable/uneditable, which is the failure mode this lane exists to remove.
+ *  Divergence-logged. */
 export declare const NOTEBOOK_IMAGE_BASE64_BUDGET = 262144;
 export interface NotebookOutputImage {
     /** Whitespace-stripped base64 (magic-validated — never an unverified blob, see `imageFromData`). */
@@ -40,9 +39,9 @@ export interface NotebookOutput {
 export interface NotebookCell {
     /** `cell.id`, or the synthesized `cell-${index}` for nbformat<4.5 — index = the UNFILTERED array
      *  position, because NotebookEdit's `/^cell-(\d+)$/` positional fallback resolves exactly that.
-     *  Deliberate delta (review r2 finding 2): sema synthesizes for any NON-STRING id (`typeof id ===
-     *  "string"` guard in `parseNotebookCells`) where CC's `wtd` uses `e.id ?? cell-${t}` (:371314)
-     *  and would render e.g. a numeric id literally — but NotebookEdit's id match is string-only, so
+     *  Deliberate delta: sema synthesizes for any NON-STRING id (`typeof id === "string"` guard in
+     *  `parseNotebookCells`) where CC's `wtd` uses `e.id ?? cell-${t}` and would render e.g. a numeric
+     *  id literally — but NotebookEdit's id match is string-only, so
      *  CC's literal form would be un-addressable while sema's positional alias resolves; nbformat
      *  ids are spec-string, so this branch only fires on out-of-spec input. */
     cell_id: string;
@@ -62,7 +61,7 @@ export type ParsedNotebook = {
     reason: "json" | "shape";
 };
 /**
- * CC `Ctd` + `wtd` (:371373 / :371313): parse the notebook JSON into the projected cell list.
+ * CC `Ctd` + `wtd`: parse the notebook JSON into the projected cell list.
  * Failure is a typed reason, not a throw — the Read lane falls back to raw text on it (sema
  * divergence from CC's hard error: a corrupt notebook stays readable so the model can see what is
  * wrong; NotebookEdit still refuses it with its own JSON-validation errors, so nothing is loosened).
@@ -81,13 +80,13 @@ export interface NotebookRender {
     imageChars: number;
 }
 /**
- * CC `eI_`/`tI_`/`Atd` (:371339/:371349/:371399): render projected cells to content blocks.
- * Tag shape is CC-verbatim, including the deliberately malformed closing tag `</cell id="X">`;
- * `<cell_type>` only when not code, `<language>` only for code cells whose language !== "python".
- * Output text rides with a leading "\n" (tI_) and adjacent text blocks merge with "\n" (Atd), so an
- * all-text notebook collapses to a single text block. Images ride as real image blocks in sema's
- * `{type:"image", data, mimeType}` shape, bounded by the cumulative `imageBase64Budget` (E4): past
- * it the image is DROPPED with an honest text marker — a degradation, never an error.
+ * CC `eI_`/`tI_`/`Atd`: render projected cells to content blocks. Tag shape is CC-verbatim, including
+ * the deliberately malformed closing tag `</cell id="X">`; `<cell_type>` only when not code,
+ * `<language>` only for code cells whose language !== "python". Output text rides with a leading "\n"
+ * and adjacent text blocks merge with "\n", so an all-text notebook collapses to a single text block.
+ * Images ride as real image blocks in sema's `{type:"image", data, mimeType}` shape, bounded by the
+ * cumulative `imageBase64Budget`: past it the image is DROPPED with an honest text marker — a
+ * degradation, never an error.
  */
 export declare function renderNotebookCells(cells: readonly NotebookCell[], imageBase64Budget: number): NotebookRender;
 /** Wire-card projection of a cell: base64 replaced by a length marker so the `details` card never

package/dist/tools/fs/pdf.d.ts

@@ -1,7 +1,7 @@
 /**
- * PDF read pipeline (+ 审计 — CC FileReadTool parity).
+ * PDF read pipeline (CC FileReadTool parity).
  *
- * CC ground truth (original-source-code, 取证 2026-07-07):
+ * CC ground truth (original source code):
  * - Whole-PDF path (`FileReadTool.ts:987-1016` + `utils/pdf.ts:88-103`): the file bytes are base64'd and
  *   sent as a native `{type:"document",source:{type:"base64",media_type:"application/pdf",data}}` content
  *   block — the model reads the text layer directly (no local text extraction).
@@ -40,7 +40,7 @@ export declare function parsePdfPageRange(pages: string): PdfPageRange | undefin
  * nothing matches (page tree inside compressed object streams — modern writers), NEVER a guess.
  */
 export declare function countPdfPagesFromBytes(bytes: Uint8Array): number | undefined;
-/** Max chars of a failed poppler call's stderr/stdout kept in the reported error (A-005.15). */
+/** Max chars of a failed poppler call's stderr/stdout kept in the reported error. */
 export declare const PDF_EXEC_ERROR_PREVIEW_CHARS = 400;
 /** Bound a poppler exec failure's captured stream to {@link PDF_EXEC_ERROR_PREVIEW_CHARS}, marking the cut
  *  (a bare slice reads identical to a short capture that just happened to end there — the model has no way

package/dist/tools/fs/read-deny.d.ts

@@ -60,9 +60,9 @@ export interface ReadDenyMatcher {
     readonly rgProbeGlobs: readonly ReadDenyRgGlob[];
 }
 /**
- * The closed set of built-in tiers (#245). A tier is the deployment's selection unit
+ * The closed set of built-in tiers. A tier is the deployment's selection unit
  * ({@link ReadDenyBuiltinConfig.tiers}); every {@link READ_FACE_BUILTIN_DENY_TABLE} row belongs to
- * exactly one. Unknown tier names refuse loudly (#123) — this array is the validation source and the
+ * exactly one. Unknown tier names refuse loudly — this array is the validation source and the
  * admin-face vocabulary, never re-spelled downstream.
  */
 export declare const READ_DENY_BUILTIN_TIERS: readonly ["credentials", "shell-history", "browser", "wallet", "agent-config"];
@@ -78,12 +78,12 @@ export interface ReadDenyBuiltinRow {
     readonly tier: ReadDenyBuiltinTier;
 }
 /**
- * READ_FACE_BUILTIN_DENY_TABLE — the FULL built-in table with tier metadata (#245: the material
- * basis of the deployment admin face — what an org administrator "sees" before selecting tiers /
- * excluding rows). Activation is a separate fact: the default face is the table under
+ * READ_FACE_BUILTIN_DENY_TABLE — the FULL built-in table with tier metadata: the material basis of
+ * the deployment admin face, what an org administrator "sees" before selecting tiers / excluding
+ * rows. Activation is a separate fact: the default face is the table under
  * {@link READ_DENY_DEFAULT_TIERS} (shell-history rows exist here but are OFF by default).
  * The dotenv family is deliberately NOT here — workspace `.env` files are working material for the
- * tasks this engine runs (the design's `outside_workspace` tier was also ruled OUT).
+ * tasks this engine runs; an `outside_workspace` tier is likewise deliberately absent.
  *
  * Each row states its tradeoff. Rows are matched as segment runs anywhere in the path, so a repo
  * fixture spelled `fixtures/.ssh/id_rsa` is refused too — deliberate: the refusal names the pattern,
@@ -99,20 +99,20 @@ export interface ReadDenyBuiltinRow {
  *
  * agent-config tier — the agent's OWN configuration files whose `env` / server blocks carry API keys
  * in cleartext (the shell's `settings.json` env block, a project `.mcp.json` server env, the engine
- * host's data-root `.env`). A structured read of one of these used to land the key verbatim in the
- * tool result and therefore in the session record. Rows name FILES, not the config DIRECTORIES:
+ * host's data-root `.env`). Unguarded, a structured read of one of these lands the key verbatim in
+ * the tool result and therefore in the session record. Rows name FILES, not the config DIRECTORIES:
  * `.sema`/`.claude` also hold agents, skills, hooks and (under the shell's layout,
  * `~/.sema/engine-data`) the engine data root with the memory library — material the model reads
  * and edits as ordinary work, and a directory-wide row would need a data-root passthrough (one more
  * rule) to keep it readable. The write face guards the directories (`sensitive-path-policy.ts`): a
  * write there is self-authorization; a read of a non-credential file there is debugging. Token
- * STORES of the same tooling (`.credentials.json`, `.codex/auth.json`, …) are credentials rows, not
+ * STORES of the same tooling (`.credentials.json`, an agent CLI's `auth.json`, …) are credentials rows, not
  * agent-config rows: a deployment that switches this tier off to debug its agent configuration must
  * not also expose the OAuth stores beside it.
  */
 export declare const READ_FACE_BUILTIN_DENY_TABLE: readonly ReadDenyBuiltinRow[];
 /**
- * The DEFAULT tier selection (#245 ruling ②): every tier EXCEPT `shell-history` — history files are
+ * The DEFAULT tier selection: every tier EXCEPT `shell-history` — history files are
  * unrestricted unless a deployment opts the tier in. Derived, not re-listed: a tier added to the
  * closed set is default-ON unless this expression is deliberately revisited (`agent-config` joined
  * default-ON this way: an unconfigured deployment refuses the agent's own key-bearing settings files;
@@ -120,30 +120,30 @@ export declare const READ_FACE_BUILTIN_DENY_TABLE: readonly ReadDenyBuiltinRow[]
  */
 export declare const READ_DENY_DEFAULT_TIERS: readonly ReadDenyBuiltinTier[];
 /**
- * The deployment's built-in-table configuration (#245 — deployment seat ONLY: RunnerDeps /
+ * The deployment's built-in-table configuration — deployment seat ONLY (RunnerDeps /
  * HandsToolkitOptions; deliberately NOT a TaskSpec key and NOT in the governed workflow whitelist,
  * so no task or governed script can widen below its deployment).
  *  - `tiers` — EXACTLY-these tier selection: listed tiers are active, unlisted ones are not
  *    (`[]` = no built-in tiers at all — an explicit, legal posture; absent = {@link READ_DENY_DEFAULT_TIERS}).
  *  - `exclude` — per-row removal by canonical pattern name, applied AFTER tier selection.
- * Unknown tier names / unknown row names refuse loudly (#123) — never silently ignored.
+ * Unknown tier names / unknown row names refuse loudly — never silently ignored.
  */
 export interface ReadDenyBuiltinConfig {
     tiers?: readonly string[];
     exclude?: readonly string[];
 }
 /**
- * Resolve the ACTIVE built-in rows under a deployment configuration (validated, loud — #123's three
- * bad-value states all throw: garbage shapes, unknown tier names, unknown row names). The one
+ * Resolve the ACTIVE built-in rows under a deployment configuration (validated, loud — all three
+ * bad-value states throw: garbage shapes, unknown tier names, unknown row names). The one
  * resolution used by {@link compileReadDeny}; exported so an admin face can preview the effective
  * table under a candidate configuration with the engine's own rules.
  */
 export declare function resolveReadDenyBuiltins(config?: ReadDenyBuiltinConfig): readonly ReadDenyBuiltinRow[];
 /**
  * READ_FACE_DEFAULT_DENY_ENTRIES — the DEFAULT-ACTIVE built-in set: {@link READ_FACE_BUILTIN_DENY_TABLE}
- * under {@link READ_DENY_DEFAULT_TIERS} (#245: shell-history rows are in the table, not in this face).
- * Kept as the historical name for consumers rendering "what does an unconfigured deployment refuse";
- * the tier-annotated table is the admin-face export.
+ * under {@link READ_DENY_DEFAULT_TIERS} (shell-history rows are in the table, not in this face). This
+ * is the export for consumers rendering "what does an unconfigured deployment refuse"; the
+ * tier-annotated table is the admin-face export.
  */
 export declare const READ_FACE_DEFAULT_DENY_ENTRIES: readonly ReadDenyEntry[];
 /** A compiled segment-run pattern (shared engine — the write guard delegates here too). */
@@ -159,8 +159,8 @@ export interface CompiledSegmentPattern {
  *  · "ascii"   — ASCII-case-insensitive (deny-set contract);
  *  · "unicode" — RegExp `i` flag (the write guard's historical host-keyed behavior — kept for it
  *    byte-identically; NOT used by the deny set).
- * Returns null when the pattern reduces to zero segments — the CALLER owns its loud path (#123: the
- * two consumers refuse with their own surface-specific texts).
+ * Returns null when the pattern reduces to zero segments — the CALLER owns its loud path (the two
+ * consumers refuse with their own surface-specific texts).
  */
 export declare function compileSegmentPattern(raw: string, fold: "none" | "ascii" | "unicode"): CompiledSegmentPattern | null;
 /**
@@ -185,10 +185,10 @@ export declare function persistedReadDenyEntryProblem(e: unknown): string | null
  * Compile the read-face deny judge: ACTIVE built-in rows ∪ additions. Additions are add-only at every
  * task layer (`[]` additions ≡ absent, deliberately a no-op rather than a refusal: an array API
  * cannot observe a "replace" intent, and union-with-empty is the identity, not a silent fallback);
- * the built-in half is selected by the DEPLOYMENT's `builtin` config (#245 — absent = the default
- * tier selection, see {@link resolveReadDenyBuiltins}). A deployment that turned a tier off can still
+ * the built-in half is selected by the DEPLOYMENT's `builtin` config (absent = the default tier
+ * selection, see {@link resolveReadDenyBuiltins}). A deployment that turned a tier off can still
  * re-add single patterns through the additions seats — they then ride as ordinary additions.
  * Bad entry shapes / zero-segment patterns / unknown tier or row names throw loudly, naming the
- * layer or knob (#123).
+ * layer or knob.
  */
 export declare function compileReadDeny(additions?: readonly ReadDenyEntry[], layer?: string, builtin?: ReadDenyBuiltinConfig): ReadDenyMatcher;

package/dist/tools/fs/read-face.d.ts

@@ -1,13 +1,12 @@
-/** The read-face containment state. `"roots"` = the historical containment judgment, unchanged.
+/** The read-face containment state. `"roots"` = the containment judgment runs.
  *  `"open"` = the containment step is skipped (canonicalization, deny set, UNC out-of-set refusal
  *  and the type gates all still run). */
 export type ReadFace = "open" | "roots";
-/** Loud value gate (#123): a `readFace` seat carries exactly "open" | "roots" — anything else
- *  (case variants, truthy garbage) refuses at wiring time, never folds to a default. Exported
+/** Loud value gate: a `readFace` seat carries exactly "open" | "roots" — anything else (case
+ *  variants, truthy garbage) refuses at wiring time, never folds to a default. Exported
  *  module-internally (not on the package surface) so prepare's unconditional config-guard leg can
- *  screen the seats on runs that never mount hands early and unconditionally (since #242 the
- *  resolver itself ALSO runs on every hands-less leg; this screen still fires first, so a garbage
- *  value refuses before any leg-shape branching). */
+ *  screen the seats on runs that never mount hands. The resolver itself also runs on every hands-less
+ *  leg; this screen still fires first, so a garbage value refuses before any leg-shape branching. */
 export declare function assertReadFaceValue(v: unknown, seat: string): ReadFace | undefined;
 /** Inputs to {@link resolveReadFace} — all structural/declaration facts, never permission modes
  *  (a deliberate axis separation: this shape carries facts, not verdicts). */
@@ -20,17 +19,16 @@ export interface ReadFaceInputs {
      *  LOAD-BEARING wall (bash_readonly is genuinely confined by it) — never openable. */
     readOnlyMount: boolean;
     /** Org governance declared (`RunnerDeps.permissionRuleStore.partitions.org === true`): default roots; the task layer
-     *  may not open (D-2 — tighten-only under governance; the deps layer, being the deployment's own
+     *  may not open (tighten-only under governance; the deps layer, being the deployment's own
      *  declaration, still may). */
     orgGoverned: boolean;
-    /** D-6: is the FULL shell (`core.bash@1`) structurally reachable on this mount? Computed BEFORE
-     *  tool-band assembly from spec-time facts (env kind / handsReadOnly / Bash exclusion — recon §3:
-     *  every exclusion source is spec-time-frozen, so this is always computable). When false, the
-     *  roots fence is the ONLY read boundary and the default stays roots even under a deps-layer
-     *  "open"… no — see the resolution order: an EXPLICIT open still wins (row 4 is a default, not a
-     *  clamp); what it changes is that NOTHING implicit opens a bash-less mount. */
+    /** Is the FULL shell (`core.bash@1`) structurally reachable on this mount? Computed BEFORE
+     *  tool-band assembly from spec-time facts (env kind / handsReadOnly / Bash exclusion — every
+     *  exclusion source is spec-time-frozen, so this is always computable). When false, the roots fence
+     *  is the ONLY read boundary, so no IMPLICIT default may open the face; an EXPLICIT "open" on
+     *  either seat still wins (row 4 of the order is a default, not a clamp). */
     fullShellReachable: boolean;
-    /** #237 — observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
+    /** Observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
      *  (readOnly mount + deps "open" + NO task seat). Fired exactly when the deps declaration was the
      *  deciding seat and the mount overrode it — not when a task-level "roots" pinned the same value
      *  anyway (the mount changed nothing there, and announcing it would claim a false cause), and
@@ -39,24 +37,23 @@ export interface ReadFaceInputs {
     onDeploymentClamp?: () => void;
 }
 /**
- * The ONE resolution order (§2.2), first hit wins. prepare-task AND createHandsToolkit both call
- * this — a library-direct mount gets identical validation and identical defaults.
+ * The ONE resolution order, first hit wins. prepare-task AND createHandsToolkit both call this — a
+ * library-direct mount gets identical validation and identical defaults.
  *
  *  1. read-only (verifier) mount → ROOTS; an explicit "open" on the TASK seat is a genuine
- *     per-call CONTRADICTION and refuses loudly (#123 — never silently pick a side). An "open"
- *     on the DEPLOYMENT seat alone is a deployment-wide default, not a per-task assertion — it
- *     silently CLAMPS to roots (stricter-wins), same seat distinction row 2 already draws for
- *     org governance below.
- *  2. org-governed: TaskSpec "open" refuses (task layer only tightens, D-2); deps "open" wins;
+ *     per-call CONTRADICTION and refuses loudly (never silently pick a side). An "open" on the
+ *     DEPLOYMENT seat alone is a deployment-wide default, not a per-task assertion — it silently
+ *     CLAMPS to roots (stricter-wins), the same seat distinction row 2 draws for org governance.
+ *  2. org-governed: TaskSpec "open" refuses (task layer only tightens); deps "open" wins;
  *     otherwise ROOTS.
  *  3. explicit seat: spec ?? deps.
- *  4. bash-less mount (D-6): ROOTS (the fence is the only read boundary there — "the fence guards
+ *  4. bash-less mount: ROOTS (the fence is the only read boundary there — "the fence guards
  *     nothing bash reaches anyway" does not hold, so no implicit default may open it).
- *  5. default: ROOTS (D-1b — the engine never opens implicitly).
+ *  5. default: ROOTS — the engine never opens implicitly.
  */
 export declare function resolveReadFace(i: ReadFaceInputs): ReadFace;
 /**
- * #237 — the ONE text of the deployment-clamp announcement (`config.read_face_deployment_clamped`).
+ * The ONE text of the deployment-clamp announcement (`config.read_face_deployment_clamped`).
  * Both stations deliver THIS object through their own `deliverEngineNotice` call (prepare-task with
  * the `RunnerDeps.onNotice` seat, once per notice sink — the sink, not the deps object, because the
  * Runner rebuilds its deps; `createHandsToolkit` with its band-local `HandsToolkitOptions.onNotice`

package/dist/tools/fs/repo-map.d.ts

@@ -3,14 +3,14 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
 import type { ReadFace } from "./read-face.js";
 /** Extract top-level symbol names (deduped, in first-seen order) from source text. A lightweight
- *  comment/docstring state machine (council #4) skips column-0 declaration-like lines that are really
- *  inside a `/* … *​/` block comment or a Python `"""`/`'''` docstring — otherwise e.g. a module
- *  docstring containing `def foo():` at column 0 produces a phantom symbol. Not a full parser (v1
- *  heuristic): it tracks whole-line block/docstring regions, the common false-positive source.
+ *  comment/docstring state machine skips column-0 declaration-like lines that are really inside a
+ *  `/* … *​/` block comment or a Python `"""`/`'''` docstring — otherwise e.g. a module docstring
+ *  containing `def foo():` at column 0 produces a phantom symbol. Not a full parser: it tracks
+ *  whole-line block/docstring regions, the common false-positive source.
  *
- *  ⚠️ **Exported ONLY as a v1 heuristic, NOT a containment proof** (design/79 §3): it is column-0 /
- *  source-only and skips indented lines, so it CANNOT enumerate everything an artifact can call. The
- *  auto-promote tripwire (src/core/auto-promote.ts) consumes it in ESCALATE-ONLY mode — a clean scan
- *  contributes nothing; it can only ever raise an escalation, never clear one. */
+ *  ⚠️ **A heuristic, NOT a containment proof**: it is column-0 / source-only and skips indented lines,
+ *  so it CANNOT enumerate everything an artifact can call. The auto-promote tripwire
+ *  (src/core/auto-promote.ts) consumes it in ESCALATE-ONLY mode — a clean scan contributes nothing;
+ *  it can only ever raise an escalation, never clear one. */
 export declare function extractSymbols(text: string): string[];
 export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;