@sema-agent/core 5.20.0 → 5.21.0

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

@@ -1,34 +1,134 @@
 import { type WorkflowJournalEntry, type WorkflowJournalStore, type ResumeClaimArgs } from "../../core/workflow-journal-store.js";
+/**
+ * SVC-2 — the shared size bound for a journaled workflow-agent result, so ALL backends DEGRADE IDENTICALLY on
+ * an oversize TaskResult (no dialect divergence). Inlined from service's `workflow-journal-limits` on
+ * onboarding — the 5 MiB figure aligns with TiDB's ~6 MiB per-row txn-entry-size-limit (a row
+ * over it is REJECTED with "entry too large"); a LOAD-BEARING `append` that hit that would THROW and kill the
+ * whole workflow. PostgreSQL TEXT has no such low limit, so without a shared guard the same large result would
+ * journal fine on PG but fail the workflow on TiDB. All backends instead skip-journal a result whose serialized
+ * size exceeds {@link MAX_JOURNAL_RESULT_BYTES} (a no-op, never an insert/throw): the agent's ordinal is simply
+ * not cached, so a resume re-runs that one agent live. Resume is an optimization — a too-big-to-cache result is
+ * a graceful degrade, not a failure. Measured in BYTES (UTF-8) — a multibyte result can be larger than its
+ * `.length` in chars.
+ */
 export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
+/**
+ * RB-242 — how long a resume claim survives WITHOUT an engine release. This is the backstop for an engine that
+ * died holding one (crash / kill -9 / box reboot): it never reaches its `finally`, so nothing but expiry can
+ * ever free the row, and a source run whose resume is wedged forever is a worse failure than the fork this
+ * guards. One hour is the balance: comfortably longer than the gap between a resume's admission and its first
+ * journal write (the window in which a fork actually duplicates work), and short enough that a crashed box does
+ * not lock a run out for a working day. A LIVE engine's own release is the normal path and is prompt — this
+ * value is only ever reached by a run that is no longer running.
+ */
 export declare const RESUME_CLAIM_TTL_MS: number;
+/**
+ * RB-356② — a release REFRAINS from unlinking its own claim once the claim is this close to (or past) its
+ * expiry. Rationale: a peer may legitimately take a claim over the instant it expires, and `release` is a
+ * read-then-unlink pair with no compare-and-delete syscall between them — so the one situation where the
+ * unlink could destroy a SUCCESSOR's claim is precisely the one where the record we just read is already
+ * takeable. Refusing to unlink there is free: an expired claim blocks nobody (the next acquirer takes it over)
+ * and the sweep below reaps it. The margin only has to cover the scheduling gap between this method's read and
+ * its unlink; seconds is orders of magnitude more than that, and losing the last five seconds of a one-hour
+ * lease costs nothing.
+ */
 export declare const RESUME_CLAIM_RELEASE_GRACE_MS = 5000;
+/**
+ * RB-356③ — how often (per store instance) an acquisition also SWEEPS the claims directory. The header's
+ * "the TTL reaps any orphan" was an aspiration, not a mechanism: nothing ever reaped anything. An expired
+ * claim was only removed if a LATER resume off the SAME `(sourceRunId, scope)` came along to take it over —
+ * and the normal shape is exactly one resume per source run, so a crash (or any release that could not
+ * complete) leaked one small file per source run for the lifetime of the data root. The sweep makes the
+ * comment true. Throttled because it is a `readdir` on the claims directory: it is opportunistic hygiene, not
+ * a correctness path (takeover, not the sweep, is what unblocks a contended claim promptly).
+ */
 export declare const RESUME_CLAIM_SWEEP_INTERVAL_MS = 60000;
+/**
+ * RB-356③ — the sweep only reaps a claim that has been expired for at least this long. A just-expired claim
+ * is the exclusive business of whoever is taking it over right now; the sweep has no deadline to meet, so it
+ * stays well clear of that handover rather than adding a second unlinker to it.
+ */
 export declare const RESUME_CLAIM_REAP_GRACE_MS: number;
 export declare class FileWorkflowJournalStore implements WorkflowJournalStore {
     private readonly fsyncEnabled;
     private readonly dir;
+    /** RB-242: resume claims live in their own subdirectory so a claim file can never be mistaken for a run
+     *  ledger by anything that enumerates `workflow-journal/` (GC, the torn-tail replay, an operator's `ls`). */
     private readonly claimsDir;
     private readonly shared;
     private readonly sharedKey;
     private closed;
+    /** RB-356③: last {@link sweepExpiredClaims} timestamp — throttles the reap to one `readdir` per interval.
+     *  Per INSTANCE, not per directory: the sweep is idempotent hygiene, so a second instance doing its own
+     *  first sweep is harmless (unlike the fd/scope caches above, which are authority over the directory). */
     private lastClaimSweepAt;
+    /** RB-61: one AppendLog per run (torn-tail truncation at open) — replaces the raw fd map. */
     private get logs();
+    /** Per-run committed scope, cached at first touch — the append-path scope guard must NOT re-read the whole
+     *  ledger per append (a journaled result can be MBs; a many-agent workflow would go O(n²) on disk). One replay
+     *  discovers it; every later append compares against the cache. */
     private get scopes();
     constructor(root: string, fsyncEnabled?: boolean);
     private pathFor;
+    /** [1409]③ 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). */
     private replay;
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
+    /**
+     * RB-242 — the claim file for `(sourceRunId, scope)`. Keyed by BOTH ([1981]): a cross-scope caller already
+     * resolves to an empty journal (it cannot fork anything), so letting it share one claim key would only hand
+     * any tenant a denial-of-resume lever over another's runs. The scope is folded in as a digest rather than
+     * a sanitized literal so two distinct scopes can never collapse onto one filename by sanitization.
+     * Throws (via `sanitizePathComponent`) on a traversal-shaped runId — callers degrade, see below.
+     */
     private claimPathFor;
+    /**
+     * Read a claim file, KEEPING the exact bytes it was parsed from. A missing / truncated / malformed record
+     * reads as NO claim (takeable).
+     *
+     * RB-356② — the raw bytes are the record's identity token. POSIX has no compare-and-delete, so the only way
+     * this store can check "the file I decided about is still the file on disk" immediately before removing one
+     * is to re-read and compare (see {@link unlinkIfUnchanged}). Since RB-354 a claim is published whole, so
+     * "unparsable" no longer includes "a peer is mid-acquire" — it means external truncation/corruption, which
+     * genuinely is not a live claim.
+     */
     private readClaimRaw;
+    /**
+     * RB-356② — remove a claim ONLY if the bytes on disk are still the ones the decision to remove it was made
+     * on. This narrows the decide→delete window to two adjacent syscalls with no user-space work between them,
+     * and everything a peer can publish into that window is published atomically (RB-354), so the re-read sees
+     * either the bytes we judged (safe to unlink) or a peer's complete new claim (we back off and re-contend).
+     * `expectedRaw === undefined` = the file did not parse: there is no live claim to destroy.
+     */
     private unlinkIfUnchanged;
+    /**
+     * RB-356③ — reap claims nobody can be holding any more (see {@link RESUME_CLAIM_SWEEP_INTERVAL_MS}).
+     * Best-effort throughout: a sweep failure must never turn an admission into an error. Also drops the
+     * `.tmp` scratch a crash could strand mid-publish, on the same TTL horizon.
+     */
     private sweepExpiredClaims;
+    /**
+     * RB-242 ([1981]) — admission for a resume off `sourceRunId`. The LOCAL (TOC) twin of server's SQL
+     * `idem_key UNIQUE` + TTL: publishing the claim file is one atomic namespace operation that fails EEXIST
+     * against anyone who got there first, so two processes racing on the same box (the shape the in-process
+     * `startWorkflow` guards cannot see — a shell restart resuming a run a still-live process is already
+     * resuming) produce exactly one winner.
+     */
     resumeClaim(input: ResumeClaimArgs): Promise<{
         granted: boolean;
         holder?: string;
     }>;
+    /** RB-242 ([1981]) — release ONLY a claim this `newRunId` still holds. A claim that is already gone (TTL-reaped
+     *  and possibly taken over) is a no-op: unlinking a successor's claim would re-open the very fork this prevents. */
     releaseResumeClaim(input: ResumeClaimArgs): Promise<void>;
+    /** GC (service extra, mirrors the SQL twins): drop the run's ledger once the run is terminal + retained. */
     deleteByRun(runId: string): Promise<number>;
+    /** Release ledger fds (graceful shutdown; parity with the other file stores' dispose).
+     *  Refcounted: the fds are shared with any other instance on the same directory, so the LAST holder
+     *  closes them. Idempotent — a second dispose() on the same instance must not decrement twice and pull
+     *  the ledger out from under a live peer. */
     dispose(): void;
 }

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

@@ -1,17 +1,24 @@
 import { type WorkflowRunListByScopeOptions, type WorkflowRunStore, type WorkflowRunSummary } from "../../core/workflow-run-store.js";
 import type { WorkflowRun } from "../../orchestration/workflow.js";
 export interface FileWorkflowRunStoreOptions {
+    /** When false, a ledger append is NOT fsync'd (the observability store is non-engine-critical). Default true. */
     fsync?: boolean;
+    /** Compact the ledger into a snapshot once it exceeds this many events (then truncate). Default 1000. */
     compactEvery?: number;
 }
 export declare class FileWorkflowRunStore implements WorkflowRunStore {
     private readonly fsyncEnabled;
     private readonly compactEvery;
+    /** RB-59: authoritative state is SHARED per canonical directory (see the note above the class). */
     private readonly ledger;
+    /** RB-145: this instance's own close latch — the refcount belongs to the DIRECTORY, not to callers. */
     private closed;
     private get runs();
     constructor(root: string, opts?: FileWorkflowRunStoreOptions);
+    /** Serialize an op behind any in-flight op on the same id (the in-process per-id async mutex). */
     private withLock;
+    /** Commit one ledger event (append + fsync) THEN flip the in-memory map (crash-safe ordering), then
+     *  the best-effort housekeeping compaction (RB-150/RB-167) — all three steps in the base. */
     private commit;
     put(id: string, run: WorkflowRun): Promise<void>;
     get(id: string): Promise<WorkflowRun | null>;
@@ -23,7 +30,11 @@ export declare class FileWorkflowRunStore implements WorkflowRunStore {
         maxAgeMs?: number;
         keep?: number;
     }): Promise<number>;
+    /** Force a compaction now (test/inspection): rewrite the snapshot from the authoritative map and
+     *  truncate the live ledger (RB-167's closeForSwap recipe lives in the base). */
     compactNow(): void;
+    /** Test/inspection helper: number of stored runs. */
     get size(): number;
+    /** Release the append handle (best-effort). The boot LOCK is released by the backend factory. */
     close(): void;
 }

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

@@ -1,30 +1,312 @@
+/**
+ * Bare command names `bash_readonly` permits out of the box, ALSO the default reversible set for the
+ * design/80 D-2 {@link import("./fs-bash.js").bashReversibilityProbe} classifier. **Coarse first filter, NOT a security
+ * boundary**: {@link coarseReadonlyCheck} matches only the command NAME, so a listed command with a
+ * writing flag (e.g. `find -delete`, `sort -o`, `tee`) would still write. Such commands are therefore
+ * kept OFF this default — the list is curated to commands with NO write/mutation mode under ANY args, so
+ * the `effect:"read"` declaration (relied on by wake/resume reconcile + the verifier read-only boundary)
+ * AND the classifier's "reversible" promise both stay truthful. The deployment's tool-policy gate is the
+ * authoritative control (design/44 §5, council blocker #1); anything that can mutate state or run arbitrary
+ * code belongs on the full `bash` (effect:write, gated), not here. A deployment may widen this list,
+ * accepting that responsibility.
+ *
+ * design/80 D-2 final-council MAJOR: `date` (`-s`/`--set` → CLOCK_SETTIME), `hostname` (`<name>` → kernel
+ * hostname), and `file` (`-C -m` → compiles/writes a magic file) were REMOVED — each is read-only by NAME
+ * but state-MUTATING with args, which an argv[0]-only filter cannot tell apart. Leaving them in defeated
+ * both the `effect:read` truthfulness here and the classifier's irreversibility promise (a `date -s` would
+ * auto-allow an irreversible clock jump under `shellGate:"classify"`).
+ */
+/** The verdict every unresolvable / out-of-root / unbounded finding ends on. The findings differ in what
+ *  they found; the consequence is one consequence, and a copy that drifts reads as a second rule. */
 export declare const NOT_AUTO_ALLOWED = "\u2014 not auto-allowed";
 export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
+/**
+ * G2 — options for {@link parseLeadingCommandName}. Omitting them keeps the parser byte-identical to
+ * what every existing caller (the `bash_readonly` declaration face, the coarse command-name policy, the
+ * permission-rule floor, the skill tool specifier) has always received.
+ */
 export interface LeadingCommandNameOptions {
+    /**
+     * Read a shell operator that sits inside a QUOTED region as ordinary argument TEXT rather than as an
+     * operator, so `grep -E "a|b" f.log` parses as the single simple command it is.
+     *
+     * OPT-IN, and used by ONE caller: the compound classify face ({@link classifyCompoundReadonlyDetailed}),
+     * which has already rejected the whole command for backslashes / `$` / backticks / subshells / line
+     * breaks and so is inside {@link quoteMask}'s exactness envelope. The declaration and rule faces do
+     * NOT set it — their contract is "a single simple command with no operator characters at all", which
+     * is a spelling rule about what a person can read at a glance, not a claim about bash's grammar.
+     *
+     * Fail-closed on unbalanced quoting: with a region left open, the mask is not trusted and every
+     * operator character counts, exactly as without this option.
+     */
     quotedOperatorsAreText?: boolean;
 }
+/**
+ * The SINGLE fail-closed simple-command parser shared by `bash_readonly` ({@link coarseReadonlyCheck}), the
+ * `bash` reversibility classifier ({@link import("./fs-bash.js").bashReversibilityProbe}), and the coarse command-name policy
+ * ({@link import("../../core/tool-policy.js").createCoarseCommandNamePolicy}). It extracts the leading
+ * `argv[0]` command NAME of a SINGLE simple command, rejecting anything that could chain past or escape an
+ * argv[0]-name filter: shell operators (pipes / redirects / `;` / `&&` / `$(…)` / subshells / backticks /
+ * newlines / backslash), a path-prefixed command (`/usr/bin/foo`), or a leading env-assignment (`FOO=bar cmd`).
+ *
+ * Returns `{ name }` for a parseable single bare command, or `{ reject }` with a human reason otherwise. It
+ * does NOT inspect ARGUMENTS for write flags or consult any allowlist — that is the caller's job (the
+ * allowlist for `bash_readonly`, the allow/deny lists for the coarse policy). Keeping ONE parser is the whole
+ * point: a second argv[0] parser would drift from this one and silently open a bypass.
+ */
 export declare function parseLeadingCommandName(command: string, options?: LeadingCommandNameOptions): {
     name: string;
 } | {
     reject: string;
 };
+/** Coarse pre-execution check for `bash_readonly`: the command must be a single bare allowlisted command
+ *  with no shell operators. It validates the NAME only (+ blocks operators/path-prefix/env-assignment); it
+ *  does NOT inspect arguments for write flags — keeping the allowlist free of write-capable commands and
+ *  the policy gate are what make `effect:"read"` truthful. Returns a reason when rejected, else undefined.
+ *  design/154: this `effect:"read"` DECLARATION face deliberately stays strict-single-command; only the
+ *  classify face ({@link classifyCompoundReadonly} via {@link import("./fs-bash.js").bashReversibilityProbe}) segments compounds. */
 export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>, options?: LeadingCommandNameOptions): string | undefined;
+/**
+ * RB-412 — the READ-BOUNDARY face of the read-only classification (opt-in).
+ *
+ * The allowlist vets `argv[0]` only, so until this face existed every listed reader could name ANY
+ * path: `ls /etc` and `cat /etc/passwd` classified read-only, and a deployment whose manual-mode shell
+ * gate auto-allows the read-only verdict served the whole filesystem with no approval prompt. CC 2.1.220
+ * demotes exactly these shapes (its per-command path extractor + working-directory containment check,
+ * pretty220 @457568) and renders an approval option naming the directory (@905642).
+ *
+ * Supplying this object turns the check ON; omitting it leaves the classifier byte-identical to its
+ * pre-RB-412 behaviour, so a consumer pinned to an older calling convention is unaffected.
+ */
 export interface BashReadonlyRootBoundary {
+    /** Canonical containment roots — the primary root plus any additional allowed directories. An EMPTY
+     *  array means "no directory is allowed", so every path-shaped operand demotes (a bare `cat a.txt`
+     *  still does not: a name with no separator can only reach the working directory, which is the
+     *  caller's to govern). A caller that wants the check OFF omits the whole object instead. */
     roots: readonly string[];
+    /** Base for resolving relative operands. Defaults to `roots[0]`. Callers tracking an observable `cd`
+     *  should pass the LIVE working directory, or a `..` operand will be judged against the wrong base. */
     cwd?: string;
+    /** Expansion for a leading `~`. Without it a `~`-rooted operand is unresolvable and demotes (with no
+     *  out-of-root signal — the classifier does not know where it points, which is a different verdict
+     *  from knowing it points outside). */
     homeDir?: string;
 }
+/**
+ * RB-412 — the structured verdict of {@link classifyCompoundReadonlyDetailed}. `reason === undefined`
+ * is the read-only verdict; everything else is a demotion.
+ */
 export interface CompoundReadonlyVerdict {
+    /** Demotion reason (the same string {@link classifyCompoundReadonly} returns), or undefined. */
     reason?: string;
+    /** Set only when the SOLE obstacle to the read-only verdict was the root boundary: every segment is
+     *  an allowlisted reader, no blocking/device/backgrounding arm fired, and the offending arguments are
+     *  statically resolved paths outside the roots. A gate can therefore offer the narrow "allow reading
+     *  from <dir>" approval instead of a generic shell prompt. Absent for every other demotion — an
+     *  unresolvable path deliberately does NOT carry it (nothing concrete to grant). */
     outOfRootRead?: true;
+    /** The resolved out-of-root paths, de-duplicated, in first-seen order. Present iff `outOfRootRead`. */
     outOfRootPaths?: readonly string[];
+    /**
+     * RB-451 — the paths this scan resolved INSIDE the roots (de-duplicated, first-seen order), i.e. the
+     * candidates a caller holding a filesystem should re-check with symlinks resolved. Absent when there
+     * are none.
+     *
+     * Why the ALLOW side is reported at all: containment here is LEXICAL (see
+     * {@link resolveOperandLexically}), so "inside the roots" means the written spelling has an in-root
+     * prefix — a symlink inside a root that points out of it (`<root>/vendor` → `/etc`) passes. Closing
+     * that needs `realpath`, which this function deliberately cannot do (synchronous, pure, no
+     * ExecutionEnv). Carrying the candidates is the seam: the ENFORCING caller canonicalizes them and
+     * re-compares (`createBashReadonlyTool` does exactly this — a target that resolves out of root is
+     * refused there). Typically 0-2 entries per command.
+     *
+     * Present on BOTH arms, not only the allow arm: a command can name one out-of-root path AND one
+     * in-root candidate (`cat /etc/passwd inroot.txt`), and a caller that EXEMPTS the out-of-root path
+     * (the engine's own overflow spool, or a non-canonical spelling that resolves back inside) then goes
+     * on to execute — with the other candidate still unverified. The field is what that caller checks
+     * before running, whichever way the lexical verdict came out.
+     *
+     * Includes bare-word operands (`cat linkfile.txt`), which are NOT lexical out-of-root candidates —
+     * the "a name with no separator can only reach the working directory" argument is true lexically and
+     * false under symlinks, so those are exactly the entries a filesystem-holding caller must resolve.
+     * They never affect {@link reason}: a bare word cannot demote and does not here either.
+     */
     checkedPaths?: readonly string[];
+    /**
+     * RB-474 — operands whose spelling carries an UNEXPANDED glob (`*`, `?`, `[…]`, unquoted). Lexical
+     * containment is not decidable for them: the shell expands the pattern AFTER this verdict is made, and
+     * inside a root an expansion can land on a symlink that points out of it (`cat *` where the directory
+     * holds a link to an out-of-root file — reproduced end-to-end, not a theoretical shape).
+     *
+     * They are NOT in {@link checkedPaths}: a filesystem-holding resolver answers the unexpanded spelling
+     * with its deepest EXISTING ancestor — the directory itself — and reports nothing escaping, which is
+     * precisely the false "resolved, inside" answer this field exists to prevent.
+     *
+     * CONSUMER CONTRACT. A gate that auto-allows on containment must treat a verdict carrying this field as
+     * UNDECIDED: ask, or expand the patterns itself against the filesystem and judge every match. The
+     * read-only judgement itself is unaffected — `ls *` genuinely writes nothing, and {@link reason} stays
+     * absent — because a hard refusal here would take a routine idiom away from every caller, including the
+     * ones that CAN resolve it. The engine's own `bash_readonly` leg is such a caller: it expands and
+     * resolves each match before executing, so it keeps running these commands unprompted.
+     *
+     * `cd` is the one exception, and it fails closed: a glob there cannot be expanded into the single
+     * directory the compound face must track as the new working directory, so it demotes (see {@link reason}).
+     */
     undecidedPaths?: readonly string[];
 }
+/**
+ * RB-412 — the single minting point for the out-of-root-read approval option text, so a gate rendering
+ * the prompt and any other consumer cannot drift apart. Shape follows CC 2.1.220 (@905642): the option
+ * shows the LAST segment of the grantable directory followed by a separator, not the full path.
+ *
+ * `directory` is the directory to be granted — a caller holding a filesystem (this classifier does not)
+ * resolves a file operand to its parent first; CC does the same with a stat-then-dirname step.
+ * The separator is always `/`: this classifier's path handling is POSIX-lexical throughout, where CC
+ * uses the host's native separator.
+ */
 export declare function formatOutOfRootReadApprovalOption(directory: string): string;
+/**
+ * RB-412 — {@link classifyCompoundReadonly} with the structured verdict. The name/operator/blocking arms
+ * run FIRST and unchanged, so an existing demotion keeps its exact reason and never acquires the
+ * out-of-root signal; the boundary scan below only ever converts a would-be READ-ONLY verdict into a
+ * demotion, which is why omitting `boundary` reproduces the pre-RB-412 behaviour exactly.
+ */
 export declare function classifyCompoundReadonlyDetailed(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+/**
+ * RB-413 — the read boundary ALONE, for the `bash_readonly` face.
+ *
+ * `bash_readonly` declares `effect:"read"` and is admitted by {@link coarseReadonlyCheck}, an argv[0]-NAME
+ * filter: path operands were invisible to it, so an allowlisted reader could name any file on the host
+ * (`cat /etc/passwd`) and — with no approval gate on the read effect — get it. The compound face above
+ * answers a different question for a different consumer (a gate that can ASK); this face answers only
+ * "does this command read outside the roots", leaving the availability arms (blocking stdin, `tail -f`,
+ * device reads) untouched so a caller wiring it gains the boundary and nothing else.
+ *
+ * PRECONDITION: `command` has already passed {@link coarseReadonlyCheck}, i.e. it is ONE simple command
+ * with no connectors, redirects, substitutions or escapes anywhere. That is what makes a whitespace split
+ * exact here. Feeding it an unvetted compound is not unsafe (the connector ends up glued to a token, which
+ * only ever produces MORE path candidates and a stricter verdict) but the reason text would name a
+ * nonsense command, so callers vet first.
+ *
+ * Returns the same {@link CompoundReadonlyVerdict} the compound face returns: `reason === undefined` means
+ * every path operand resolved inside the roots. A caller with no approval channel treats BOTH demotion
+ * kinds — resolved-and-outside (`outOfRootRead`, with `outOfRootPaths`) and could-not-resolve (reason
+ * only) — as a refusal; there is nowhere to degrade to.
+ *
+ * SCOPE OF THE GUARANTEE (RB-448, both directions): "inside the roots" is LEXICAL containment — see
+ * {@link resolveOperandLexically}. A symlink inside a root that points out of it reads as in-root here,
+ * so this face bounds where a command may NAME a file, not where the kernel will ultimately take it.
+ * RB-451 — a deployment that needs filesystem-true containment resolves the operands itself, and this
+ * verdict hands it the list to resolve ({@link CompoundReadonlyVerdict.checkedPaths}, on both arms).
+ * `createBashReadonlyTool` is that caller for the `bash_readonly` leg and does it on a local env.
+ */
 export declare function classifySimpleCommandReadBoundary(command: string, boundary: BashReadonlyRootBoundary): CompoundReadonlyVerdict;
+/**
+ * design/154 — compound read-only classification, reason-only face. Returns the demotion reason, or
+ * undefined when the command classifies read-only. RB-412 added the optional `boundary`: with it, an
+ * allowlisted reader whose path arguments leave the allowed directories is demoted too (use
+ * {@link classifyCompoundReadonlyDetailed} when the caller wants to know that WHY, e.g. to offer the
+ * narrow "allow reading from <dir>" approval); without it the verdict is exactly what it always was.
+ */
 export declare function classifyCompoundReadonly(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;
+/**
+ * Iteration cap for {@link classifyBoundedReadonlyPollLoop}. The bound must be a LITERAL in the
+ * command text (that is what makes "bounded" provable without executing anything); this cap keeps a
+ * literal-but-huge bound (`$(seq 1 999999)`) from turning "bounded" into "unbounded in practice".
+ * 120 beats × the sleep cap below ≈ 20h worst case — the walltime axis governs actual runtime; this
+ * arm's job is only that termination is structurally guaranteed.
+ */
 export declare const POLL_LOOP_MAX_BEATS = 120;
+/**
+ * Per-`sleep` cap (seconds) for {@link classifyBoundedReadonlyPollLoop}. A literal `sleep 99999999`
+ * is technically bounded but practically a hang — the same hazard class the RB-41 availability arms
+ * demote (a green verdict that blocks until the tool timeout is green in name only).
+ */
 export declare const POLL_LOOP_MAX_SLEEP_SECONDS = 600;
+/**
+ * The BOUNDED READ-ONLY POLL LOOP arm of the classify face. The compound classifier above rejects any
+ * control structure (`for` is not an allowlisted name), which makes `shellGate:"classify"` behave like
+ * `"always"` for a monitoring consumer whose whole idiom is `for i in $(seq 1 8); do tail -n 5 x.log;
+ * sleep 2; done`. This arm accepts EXACTLY that grammar and nothing else. Returns the rejection
+ * reason, or undefined when the command matches the grammar (⇒ safe to treat as reversible).
+ *
+ * It is ADDITIVE and consulted only after {@link classifyCompoundReadonly} rejected (see
+ * {@link import("./fs-bash.js").bashReversibilityProbe}): it can never change a verdict the plain face
+ * already gives, and every unparseable shape falls through to a rejection — the default path is
+ * untouched.
+ *
+ * SAFETY ARGUMENT — why this allowance does not increase irreversibility/egress risk. Each pillar
+ * maps to a test group in test/poll-loop-classifier.test.ts (G1-G6):
+ *  G1 BOUNDED TERMINATION. The loop head must be one of three LITERAL forms with a computable
+ *     iteration count ≤ {@link POLL_LOOP_MAX_BEATS} ({@link pollLoopBeatsOf}); `while`/`until` never
+ *     match the skeleton. Every body command terminates: non-`sleep` segments inherit the RB-41/84/
+ *     108/153 availability arms via {@link classifyCompoundReadonlyDetailed} (blocking stdin, `tail
+ *     -f`, unbounded devices all reject), and `sleep` must be a literal ≤
+ *     {@link POLL_LOOP_MAX_SLEEP_SECONDS}. Bounded beats × terminating body ⇒ the loop halts.
+ *  G2 NO WRITE OR EGRESS CHANNEL. Every non-`sleep` body segment must pass the SAME
+ *     {@link coarseReadonlyCheck} parser + allowlist as the plain face (one parser, no drift);
+ *     `sleep` touches neither filesystem nor network. No redirection (`>` `<`), no `$`/backtick
+ *     substitution, no subshell exists anywhere: the body bans them wholesale
+ *     ({@link POLL_BODY_HARD_REJECT}), and the head's single `$(seq <int> <int>)` exemption is an
+ *     exact-spelling match whose two arguments are literal digits.
+ *  G3 CONNECTOR CLOSURE. `;` is the only connector in the body; `|`/`&`/`&&`/`||` are banned there
+ *     outright, and a nested control structure surfaces as a `for`/`do`/`done` head token that fails
+ *     the allowlist. Nothing can chain past the vetted segment heads.
+ *  G4 READ BOUNDARY UNCHANGED. The reassembled body goes through the boundary scan of
+ *     {@link classifyCompoundReadonlyDetailed} with the caller's boundary — out-of-root operands
+ *     reject exactly as on the plain face (RB-412/413, not relaxed by one rule). STRICTER here: a
+ *     verdict carrying {@link CompoundReadonlyVerdict.undecidedPaths} (an unexpanded glob) rejects,
+ *     because the probe face is reason-only and a repeated read of a runtime-decided target must not
+ *     auto-allow.
+ *  G5 STRUCTURE SOUNDNESS (the parser sees what bash executes). Whitespace is normalized first: any
+ *     non-ASCII / control whitespace ({@link NON_ASCII_WHITESPACE}) rejects the whole command, so this
+ *     grammar's `[ \t]`/`\s` word split and bash's `$IFS` split cannot diverge (an NBSP-joined
+ *     `ls x` never reads as head `ls` here while bash runs one word). Quote pairing is then checked
+ *     whole-string ({@link pollLoopQuotesBalanced}); the var/iterable region admits no quote character
+ *     at all; so the `for … ; do … ; done` skeleton the anchored regex matches is exactly the one bash
+ *     parses — a `done` hidden in quotes either unbalances (reject) or leaves a body token that fails
+ *     the allowlist. Within the body, the quote-blind `;` split inherits the compound face's
+ *     soundness argument: with all expansion metacharacters banned, quotes only ever HIDE connectors,
+ *     so mis-splits are over-fine and the error direction is reject, never widen.
+ *  G6 ENVIRONMENT INTEGRITY. The loop variable must be a SINGLE LOWERCASE LETTER: the `for`
+ *     assignment mutates a shell variable, and a name like `PATH`/`IFS`/`LD_PRELOAD`/`BASH_ENV`
+ *     would change how the body's commands RESOLVE (`for PATH in dir; do cat x; done` would run
+ *     `dir/cat` — arbitrary code under an auto-allow). No known resolution-affecting variable is a
+ *     single lowercase letter, and the body cannot read the variable anyway (`$` is banned there),
+ *     so the counter is write-only and inert.
+ *
+ * ACCEPTED-COST NOTES (the residuals, recorded rather than silently tolerated — same posture as the
+ * RB-84 `head` note above):
+ *  · `$(seq …)` RESOLVES A COMMAND. This is the ONE command-substitution form the ruling exempts, and
+ *    it does run whatever `seq` resolves to on PATH (or a shell function/alias of that name). Two
+ *    facts bound the exposure. FIRST, the trust assumption is ISOMORPHIC to the allowlist itself:
+ *    `ls`/`cat`/`grep` are equally PATH-resolved, so a party that can shadow `seq` can already shadow
+ *    `cat` — this arm adds no trust assumption the plain face does not already make, and the file's
+ *    standing posture is that the tool-policy gate is the authoritative control and command-name
+ *    resolution to the real coreutils binaries is assumed (see {@link BASH_READONLY_DEFAULT_ALLOW}).
+ *    SECOND, the beat count is taken from the LITERAL digits, not from seq's output, so a shadowed
+ *    `seq` emitting more items only loosens the ITERATION bound (never the read-only / no-write /
+ *    no-egress envelope — every beat still runs allowlisted readers + literal `sleep`), and the
+ *    walltime axis cascades a hard kill regardless. A deployment wanting NO command-substitution at
+ *    all can prefer `{<lo>..<hi>}` or a literal list, which bash expands internally with no command
+ *    run. (Codex adversarial review flagged the substitution as [high] and recommended dropping it;
+ *    kept per the ruling that names `$(seq <int> <int>)` as the one exemption — recorded for a
+ *    tightening decision, since the brace form is a drop-in equivalent.)
+ *  · STDIN-BLOCKING BODY (an availability residual, not a safety one). CLOSED for the shape this note
+ *    used to record: a quoted multiword operand like `grep "x y"` read, to the then whitespace-blind
+ *    tokenizer, as two operands meeting grep's file floor, while bash passes ONE pattern and no file and
+ *    grep blocks on stdin. {@link splitWordsQuoteAware} now counts the operand bash actually passes, so
+ *    that command demotes on both this arm and the plain face. What REMAINS residual is the general
+ *    statement: this arm inherits whatever the shared availability arms can see, they are best-effort
+ *    (an operand that only turns out to be unreadable at run time is not in the text), and a hang is
+ *    bounded by the tool timeout — outside the irreversibility / egress envelope this arm governs. The
+ *    G1 termination guarantee is therefore stated for the NON-stdin-blocking body.
+ *
+ * NON-RESIDUAL (a divergence this arm CLOSES rather than accepts): the JS-`\s`-vs-bash-`$IFS` gap.
+ * Because the shared parser splits on JS `\s` (which includes NBSP/U+2000-block/U+3000/form-feed/
+ * vertical-tab) but bash's default `$IFS` does not, `ls x` reads as head `ls` here yet is ONE
+ * command word to bash. Rather than reason about the (harmless — nonexistent program, exit 127)
+ * consequence case by case, the whole command is rejected up front if it carries any such character
+ * ({@link NON_ASCII_WHITESPACE}), so the grammar's tokenization and bash's stay identical.
+ */
 export declare function classifyBoundedReadonlyPollLoop(command: string, allow: ReadonlySet<string>, boundary?: BashReadonlyRootBoundary): string | undefined;

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

@@ -1,20 +1,80 @@
+/**
+ * 编码 parity 批(docs/CC-TOOL-PARITY-SWEEP-2026-07.md P0)— file encoding + line-ending detection
+ * for the Read/Edit/Write band, ported from CC's `utils/fileRead.ts` mechanism and hardened where CC
+ * is lossy:
+ *
+ *  - BOM detection: `FF FE` → utf16le, `EF BB BF` → utf8-with-BOM, else plain utf8. (CC 88→2.1.187
+ *    dynamic-verified: detection is BOM-only; UTF-16BE / heuristic sniffing deliberately NOT done —
+ *    a wrong guess silently corrupts, and the BOM-less case stays a refusal at the Read layer.)
+ *  - The MODEL-FACING text is BOM-stripped and CRLF-normalized (what the model quotes in `old_string`
+ *    must match what Read showed it).
+ *    RB-285 (encoding LOW, 归因收窄 — CC 220 亲核): the blanket "(CC parity)" that used to sit on this
+ *    line was half wrong, because CC has TWO read lanes and they disagree with each other.
+ *      · CRLF-normalize — parity on both lanes (`Zr_` @276877 and `Mqe` @58197 both `replaceAll`).
+ *      · BOM-strip — parity on CC's READ lane only (`Zr_` @276877: `charCodeAt(0) === 65279 → slice(1)`).
+ *        CC's EDIT/WRITE lane (`Mqe`) does NOT strip: it hands the model text with the leading U+FEFF
+ *        still in it, and only the staleness/hash coordinate (`X9` = `CTe` + CRLF, @365630-365635)
+ *        strips. sema strips in ONE shared decoder for every lane, so the model-facing view and the
+ *        hash coordinate cannot drift apart — an improvement over CC's split, recorded as such rather
+ *        than claimed as parity.
+ *  - Write-back re-encodes with the ORIGINAL encoding, PRESERVES the BOM (CC drops it on Write — its
+ *    lossy face, dynamic-verified W1; we keep it, recorded as a deliberate improvement), and restores
+ *    the file's dominant line endings for Edit (Write keeps the model's endings as-is, CC decision).
+ */
+/** Detected byte-level encoding of a text file (BOM-driven; utf8 is the no-BOM default). */
 export interface DetectedFileEncoding {
     encoding: "utf8" | "utf16le";
     hadBom: boolean;
 }
 export type DetectedLineEndings = "CRLF" | "LF";
 export interface DecodedTextFile {
+    /** Model-facing text: BOM stripped, `\r\n` normalized to `\n`. The staleness-hash coordinate. */
     text: string;
     encoding: DetectedFileEncoding;
+    /** Dominant line ending of the ORIGINAL bytes (majority vote — CC `CKt` @58184 同算法).
+     *  Deliberately NOT per-line lossless: a mixed-endings file is unified to the dominant ending on
+     *  the first edit (codex 镜头1/2 LOW, accepted non-goal — CC behaves the same way).
+     *  RB-285 (encoding LOW): the COUNTING RULE is CC's; the SAMPLE is not. CC votes on the first 4096
+     *  characters only (`CKt(s.slice(0, 4096))` @58201) while {@link detectLineEndings} below votes on
+     *  the whole file — so a file whose first 4KB is LF and whose bulk is CRLF gets opposite verdicts.
+     *  sema's whole-file vote is kept on purpose: the verdict decides what an Edit WRITES BACK across
+     *  the entire file, so sampling a prefix is exactly the case where the cheap answer flips the
+     *  remaining 99% of the lines. Registered as a deliberate delta, not parity. */
     endings: DetectedLineEndings;
+    /** codex 双镜头 MED: a utf16le body with an ODD byte count is TRUNCATED/corrupt — decoding would
+     *  silently drop the dangling byte and a later write-back would destroy it permanently. Flagged so
+     *  the tool layer fails closed instead of "repairing" the file. */
     malformed?: true;
 }
+/** BOM-only encoding detection (CC `detectEncodingForResolvedPath` parity — no content heuristics). */
 export declare function detectFileEncoding(bytes: Uint8Array): DetectedFileEncoding;
+/** Decode file bytes into the model-facing normalized form + the metadata needed to write back losslessly. */
 export declare function decodeTextBytes(bytes: Uint8Array): DecodedTextFile;
+/**
+ * Re-encode text for writing back to a file that was decoded with {@link decodeTextBytes}.
+ *
+ * @param text normalized (`\n`) text when `endings` is CRLF/LF (Edit path — restore the file's
+ *   dominant endings); pass `endings:"preserve"` to write the text's OWN line endings untouched
+ *   (Write path — CC decision: the model sent explicit endings in `content` and meant them).
+ * @returns a plain string for the no-BOM utf8 + LF-or-preserve fast path (byte-compatible with the
+ *   pre-batch writer), else the exact bytes (BOM + encoded body).
+ */
 export declare function encodeTextForFile(text: string, encoding: DetectedFileEncoding, endings: DetectedLineEndings | "preserve"): string | Uint8Array;
+/** Normalize model-supplied match/replacement text the same way the file text was normalized
+ *  (CC FileEditTool parity: `old_string`/`new_string` are CRLF-normalized before matching).
+ *  Deliberately does NOT strip a leading U+FEFF: an `old_string` starting with one may be quoting
+ *  genuine file content — use {@link normalizeFileText} only where the string stands for a whole file. */
 export declare function normalizeEditText(s: string): string;
+/** RB-222 ([1937] W2) — split a leading U+FEFF off MODEL-SUPPLIED whole-file text (CC `CTe` parity,
+ *  220 @365630). The BOM is a file-level byte marker, not text: decodeTextBytes strips it on the way
+ *  in, so it can never live in the normalized coordinate. Only for strings that stand for a WHOLE
+ *  file (Write `content`, readFileState seeding) — a decoded file text's leading U+FEFF is genuine
+ *  content and must stay. */
 export declare function splitLeadingBom(text: string): {
     hadBom: boolean;
     text: string;
 };
+/** RB-222 ([1937] W2) — CC `X9` parity (220 @365635 = BOM-strip + CRLF-normalize): THE coordinate
+ *  every readFileState hash lives in (Read/Edit/Write staleness all hash `decodeTextBytes(...).text`).
+ *  A hash taken on raw model content with a leading U+FEFF can never agree with any later re-read. */
 export declare function normalizeFileText(s: string): string;