@sema-agent/core 5.31.0 → 5.33.0

package/dist/core/hooks.js

@@ -1,6 +1,7 @@
 import { decisionText, refuseOutOfContractDecision } from "./tool-policy.js";
 import { brandPolicyAskClass } from "./ask-class.js";
 import { inlineUntrusted } from "./untrusted-text.js";
+import { PROBE_REASON_MAX, normalizeProbeCause } from "./checkpoint-store.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { createSafeNotifier } from "./safe-notify.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
@@ -256,12 +257,20 @@ export async function runToolGate(input) {
     }
     if (decision.action === "allow" && (input.irreversibility === "always" || input.irreversibility === "maybe")) {
         let tighten = true;
+        let probeReason;
+        let probeCause;
         if (input.irreversibility === "maybe" && input.reversibilityProbe) {
             let reversible = false;
             const probeArgs = policyRewrite !== undefined ? policyRewrite : currentInput;
             try {
                 const verdict = await withProbeTimeout(Promise.resolve(input.reversibilityProbe(probeArgs)), input.approvalTimeoutMs, input.abortSignal);
                 reversible = verdict?.reversible === true;
+                if (!reversible) {
+                    const raw = verdict?.reason;
+                    if (typeof raw === "string" && raw.trim().length > 0)
+                        probeReason = inlineUntrusted(raw, PROBE_REASON_MAX);
+                    probeCause = normalizeProbeCause(verdict?.cause);
+                }
             }
             catch {
                 reversible = false;
@@ -273,6 +282,8 @@ export async function runToolGate(input) {
                 action: "ask",
                 message: `tool "${toolName}" performs an irreversible action — explicit approval required`,
                 decisionReason: "safety",
+                ...(probeReason !== undefined ? { probeReason } : {}),
+                ...(probeCause !== undefined ? { probeCause } : {}),
             };
             denySource = input.shellGated === true ? "shellGate" : "safety";
         }
@@ -436,7 +447,7 @@ export async function runToolGate(input) {
             ? { origin: orgAskOrigin !== undefined ? `org_${orgAskOrigin}` : "policy" }
             : undefined;
         if (suspendAsk && decision.action === "ask") {
-            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined);
+            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined, decision.action === "ask" ? decision.probeReason : undefined, decision.action === "ask" ? decision.probeCause : undefined);
             if (suspended) {
                 if ("parkFailed" in suspended)
                     parkFailed = suspended.parkFailed;
@@ -455,7 +466,7 @@ export async function runToolGate(input) {
                     req.args = outcome.presentedInput;
                 }
                 if (suspendAsk && outcome.parkDeclined && parkFailed === undefined) {
-                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined);
+                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined, decision.action === "ask" ? decision.probeReason : undefined, decision.action === "ask" ? decision.probeCause : undefined);
                     if (suspended) {
                         if ("parkFailed" in suspended)
                             parkFailed = suspended.parkFailed;
@@ -483,7 +494,7 @@ export async function runToolGate(input) {
             const resolved = await resolveAsk(decision, req);
             decision = resolved;
             if (resolved.action === "deny" && resolved.approverUnavailable === true && suspendAsk && parkFailed === undefined) {
-                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.decisionReason : undefined);
+                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.decisionReason : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeReason : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeCause : undefined);
                 if (suspended) {
                     if ("parkFailed" in suspended)
                         parkFailed = suspended.parkFailed;

package/dist/core/memory-engine/file-backend.d.ts

@@ -61,11 +61,15 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     /** Injected clock (opus 1.258 LOW: match the engine's `this.now` determinism discipline). */
     private readonly now;
     /**
-     * The COMMITTED-rev ledger (`revs.json`, id → rev). Zero-copy makes it load-bearing for CAS: the
-     * entry files are the SAME files the session edits, so "read the current rev from the file" would
-     * make every legitimate update self-conflict (the file already holds the new content). The ledger
-     * records the rev as of the last COMMIT (applyPatches) — a CAS compares against IT, so an in-session
-     * edit passes (baseRev == ledger) while a concurrently-committed change conflicts (ledger advanced).
+     * The COMMITTED-rev ledger (`revs.json`, id → row; design/186 schema v2). Zero-copy makes it
+     * load-bearing for CAS: the entry files are the SAME files the session edits, so "read the current
+     * rev from the file" would make every legitimate update self-conflict (the file already holds the
+     * new content). Each row records the rev as of the last COMMIT (applyPatches) — a CAS compares
+     * against IT, so an in-session edit passes (baseRev == ledger) while a concurrently-committed
+     * change conflicts (ledger advanced) — PLUS the projection BINDING (owning scope + slug): bytes
+     * are model-plane material anyone can copy or relocate, so the account — model-invisible, outside
+     * every file-tool root — is what holds ownership. "rev matches" alone is no longer a serve
+     * credential; "rev matches AND the coordinates match the binding" is.
      * Read-side (`listHeaders`/`getByIds`/`search`) SYNCS the ledger to disk THROUGH the inbound gate
      * (B2 — out-of-session edits, e.g. a git pull into an in-repo memory dir, are secret/cap-scanned;
      * rejects are quarantined + shadow-restored, never adopted); the applyPatches lookup does NOT sync
@@ -73,6 +77,33 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * (fail-closed), never a silent empty-ledger downgrade.
      */
     private ledger;
+    /** Top-level unknown keys of the loaded v2 envelope — write-preserved (§1.1). */
+    private envelopeExtras;
+    /**
+     * §3.1 (r3-④) — the migration retry judge: the PERSISTED schema form, set at every real disk read
+     * of the ledger and flipped only by the locked migration. Deliberately NOT derived from the
+     * in-memory ledger shape: the v1 compat arm upgrades rows in memory (§3.2), so the memory shape
+     * reads "already v2" after the first stand-down and the retry would die. `"v1"` arms the
+     * per-entry opportunistic retry (construction / reads / checkControlPlane / every locked
+     * mutation); undefined = the disk form has not been observed yet.
+     */
+    private persistedSchemaVersion;
+    /** §3.1 — the v1-compat window is loud ONCE per instance (per-row unbound noise stays suppressed;
+     *  the OVERALL state does not). */
+    private announcedV1Compat;
+    /** §3.4 — O(1) retry judge for the READ entries' unbound-convergence attempts: recomputed at
+     *  every disk load and every persist (both already iterate the rows), never by scanning per read.
+     *  Slightly stale-TRUE is harmless (one try-lock + one early-return reload); stale-FALSE cannot
+     *  happen (every seat that changes the rows passes through a maintaining seat). While a blocker
+     *  is genuinely stuck (a standing duplicate), each read pays one census — the same bounded cost
+     *  the v1 read retry accepts for an incomplete store, in a state the sweeps warn about loudly. */
+    private unboundRowsKnown;
+    /** Adopting-face notice dedup (copy / undecidable-probe / ambiguous / census-incomplete): one
+     *  still-pending state announces once per instance; changed bytes mint a new key and re-announce
+     *  (same posture as the restricted finding keys, which are per-MOUNT — this face has no mount). */
+    private adoptionNoticeKeys;
+    /** Test seam (§7.4 r4-④ arm): force a post-commit-point transfer-append failure. */
+    private transfersAppendFault?;
     /** B2 — inbound-gate findings accumulated by read-side syncs; the engine drains them into
      *  `HarvestReport.inboundFindings` at harvest. */
     private inboundFindings;
@@ -94,8 +125,77 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private shadowPath;
     private loadLedger;
     /** B3: atomic + fail-closed — a ledger that cannot be persisted throws (the commit is incomplete
-     *  and the caller must know), never a silent swallow. */
+     *  and the caller must know), never a silent swallow. Always writes the v2 envelope; writing over
+     *  an unmigrated v1 disk is refused loudly (mutations migrate FIRST — §3.1's "变异必先迁" is an
+     *  invariant here, not a convention: a v2 write minus the census would strand every row unbound). */
     private saveLedger;
+    /** v1-journal restore ONLY (§1.2 dual-read): the snapshot predates the upgrade and is persisted in
+     *  ITS OWN form — the migration (which runs after recovery, under the lock) owns the v1→v2 swap
+     *  together with its backup + evidence protocol. */
+    private persistLedgerV1;
+    /** Fail-open announcement convenience (S2-B queue posture — an unwritable queue never fails the
+     *  operation that had something to say; the fail-CLOSED evidence lane is `transfers.jsonl`). */
+    private enqueueExternalItems;
+    /** One-shot dedup for adopting-face notices (see {@link adoptionNoticeKeys}). */
+    private announceAdoptionNotice;
+    /** Resolve a binding's absolute projection path WITHOUT registering anything (probes must stay
+     *  side-effect-free; `scopeDir` would register an unknown scope name from a hand-edited row). */
+    private bindingAbsPath;
+    private bindingRelPath;
+    /**
+     * §3.3/§2.2 — the strict projection census: EVERY id-bearing file under EVERY registered scope,
+     * with `{complete}` honesty. Absence is ENOENT-only AT EVERY LEVEL — deliberately NOT
+     * `scanEntryFiles`, whose root arm folds an unreadable scope root into "empty scope" (`onSkip`
+     * fires for non-root only): copied here, one transient root EACCES would turn "only B was
+     * visible" into "only B exists" and mint a permanent wrong binding (bound rows are never
+     * re-derived). Symlinks / depth overflow / non-.md are exclusions by the entry-scan contract,
+     * not census gaps.
+     */
+    private censusProjectionsLocked;
+    /** §3.6 — capture the pre-migration v1 bytes exactly once (`wx`: the first scene is never
+     *  overwritten by a retry). */
+    private writeV1BackupOnce;
+    /** §3.1 — non-blocking txn-mutex acquisition for the opportunistic migration entries (the
+     *  constructor cannot await). LIVE contention stands down — wait semantics belong to the async
+     *  writers; every entry retries later. A STALE lock (past its deadline, owner token present) gets
+     *  ONE synchronous single-winner steal, same judge and same token discipline as the async
+     *  waiter's steal: without it, a crashed holder's leftover lock would stand down every sync entry
+     *  forever, and a READ-ONLY deployment — which never runs an async writer to do the stealing —
+     *  would sit in v1-compat indefinitely (the very suspension §3.1 bounds to seconds). Steal-safety
+     *  is unchanged: the caller runs journal recovery INSIDE the acquired lock before touching state. */
+    private tryAcquireTxnLockSync;
+    /** §3.1 — one opportunistic migration attempt (read entries / construction / checkControlPlane):
+     *  try-lock, recover, migrate, release. A busy lock is a clean stand-down (the mutation entries
+     *  bootstrap the migration under their own lock regardless). */
+    private tryOpportunisticMigrate;
+    /**
+     * §3.3-§3.5 — the migration body. MUST hold the txn mutex. Reloads the DISK truth (the retry
+     * judge is {@link persistedSchemaVersion}, set by that reload — never the in-memory shape), then:
+     * v1 ⇒ full census-derived rebind + one-shot backup + journaled swap + one migration-summary
+     * evidence event; v2-with-unbound ⇒ re-derive the unbound rows only (bound rows are FINAL — only
+     * explicit transactions rewrite a binding), each new bind carrying a `migration-bind` evidence
+     * event. An INCOMPLETE census abandons the pass with ZERO writes ("only what was visible" is not
+     * "all that exists"; a wrong binding is worse than no binding) and retries at the next entry.
+     * P=0 rows stay unbound (「缺失≠删除」— dropping the row would endorse an unattributed delete);
+     * P≥2 rows stay unbound (the migration never adjudicates which projection is real — an existing
+     * dup audit keeps ringing until a harvest or a human resolves it). Idempotent: v2 + zero unbound
+     * is a no-op version check.
+     */
+    private migrateLockedIfNeeded;
+    /** Read the evidence log's event ids, healing a TORN TAIL (a crash mid-append): the fragment is
+     *  quarantined for evidence, the sound prefix stands (lines are self-contained — damage never
+     *  spreads backward). Any NON-tail corruption is fail-closed (B3 family). */
+    private readTransferEvs;
+    /** §1.1 commit-point honesty: any failure BEFORE the journal write must refuse the whole
+     *  transaction cleanly — so the append target's writability (and the log's soundness) is probed
+     *  here, never discovered after the point of no return. */
+    private precheckTransfersAppendable;
+    /** Append evidence events, idempotent by `ev` (the recovery leg re-runs this for a journal whose
+     *  append crashed). The ONLY failure class here is I/O — never capacity: a size threshold would
+     *  freeze legitimate moves behind a full log, so growth is disclosed, not refused. A failure
+     *  AFTER the commit point is COMMITTED-PENDING (the caller keeps the journal and throws — calling
+     *  it "refused" would invite a retry of a transaction the next recovery completes anyway). */
+    private appendTransfers;
     /**
      * @param opts.unlocked RB-447 (2026-07-31, hardening review) — set by the two callers that run
      * WITHOUT the txn mutex (the constructor and {@link checkControlPlane}). `applyPatches` serializes
@@ -120,7 +220,9 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     /** RB-447 — is another writer mid-transaction right now? True while the txn lock dir exists and is
      *  not past its stale line (a stale lock is a crashed holder: its artifacts ARE ours to recover).
      *  Only consulted by the two UNLOCKED callers — inside `applyPatches` the lock is ours by
-     *  construction. Cheap: one `stat` on the lock dir, no lock acquisition, never blocks. */
+     *  construction. Cheap: one `stat` on the lock dir, no lock acquisition, never blocks.
+     *  §3.1 ⓪ (r5-①): "no lock" is ENOENT-only — a stat FAILURE folded into "nobody is committing"
+     *  let a transient EIO run the unlocked recovery (and its staged sweep) over a live transaction. */
     private txnInFlight;
     /** Remove orphaned `.stage-*` files (a crash BEFORE the journal rename = clean rollback: nothing
      *  was committed, the staged tmps are litter). Dotfiles are invisible to entry scans regardless. */
@@ -152,11 +254,46 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  Ledger-write discipline: the sync=true adoption path WRITES `revs.json`, and that write is
      *  wholesale (atomic replace) — unserialized against applyPatches' transaction it is a
      *  lost update (the later writer drops every row the earlier one added). sync=true is therefore
-     *  reachable ONLY through {@link readScopeAdopting}: `probeOnly` runs the scan with NO adoption
-     *  side effects and returns undefined at the FIRST divergent entry (adoption required — the
-     *  caller re-runs the scan under the txn mutex against a freshly reloaded ledger); a completed
-     *  probe pass returns the entries (nothing to adopt, no lock ever taken). */
+     *  reachable ONLY through {@link readScopeAdopting}: `probeOnly` runs the scan with NO ledger
+     *  side effects and returns undefined at the FIRST entry that needs an ACCOUNT transaction (an
+     *  edit adoption, or a move candidate — the caller re-runs the scan under the txn mutex against
+     *  a freshly reloaded ledger); a completed probe pass returns the entries. A COPY or an
+     *  undecidable binding probe needs no transaction (withheld + announced, account untouched), so
+     *  the probe classifies those inline and keeps going — a store with a lingering copy never
+     *  contends for the writer lock on every read. */
     private readScope;
+    /**
+     * design-A RB-5 ([A3]) — the read-side whitewash gate, shared by the bound-here divergence lane
+     * and the move+edit lane so the two can never drift: an out-of-session disk change (git pull /
+     * hand edit) of a repo-ingested entry that strips `provenance`, or strips a present `trust`
+     * marker, is the same whitewash applyPatches' I-2 clause refuses — adoption must not be the
+     * laundering back door. Baseline = the COMMITTED state (control-plane shadow; the disk file is
+     * the very thing under suspicion). A shadow-less legacy entry has no independent baseline, so the
+     * gate cannot fire for it — but every adoption/commit backfills the shadow, closing that window
+     * on first contact. `containment` keeps the reason honest per lane (the move lane quarantines
+     * WITHOUT restoring at the never-bound path).
+     */
+    private whitewashInboundFinding;
+    /**
+     * §2.2/§2.3 — one MOVE candidate under the txn mutex: a committed entry's bytes at non-bound
+     * coordinates whose bound projection is CONFIRMED absent (ENOENT, probed under this same lock).
+     * Adoption needs all three conditions — candidate present + bound path ENOENT + store-wide
+     * uniqueness through a census that proves its own completeness: with B and C both planted,
+     * single-condition ENOENT would let READ ORDER pick the owner; with a half census, "only B was
+     * visible" is not "only B exists" (r4-③/r5-②). Gate-clean adoption is an EXPLICIT transaction:
+     * row rebind + `prev` trace in one atomic ledger write, an `adopted-move` evidence event in the
+     * same journaled commit, and a loud announcement — external move/rename is the writeScope-null
+     * plane's PRIMARY legitimate input channel (git pull), so it is upgraded to a traced transaction,
+     * never refused wholesale. Candid boundary (D-1, ruled): a byte-identical delete-then-plant is
+     * THIS SAME disk observation — the adoption is a TRACED acceptance, not a rejection; what v2
+     * removes is the delete's invisibility (missing now rings), the relocation's tracelessness
+     * (transfers row + prev), and the silence. Out-of-band writers do not take this lock, so a
+     * TOCTOU window between the ENOENT re-verification and the commit remains for an adversary that
+     * can recreate the original mid-window — that actor is the delete-then-plant actor (same candid
+     * boundary), not a new capability; the tri-state probe closes FAULT misjudgment, and claims no
+     * more. Returns the entry to serve, or undefined (refused/deferred this pass).
+     */
+    private adoptMoveCandidateLocked;
     /**
      * The adopting read: {@link readScope} sync=true with its ledger write serialized behind the
      * SAME cross-process txn mutex applyPatches holds (acquisition/steal/timeout semantics shared,
@@ -208,12 +345,15 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * WRITES ARE REFUSED, loudly — a view handed to a write path is a defect, not a fallback.
      */
     retrievalView(): MemoryBackend;
-    /** Dedup keys for divergence findings the restricted view already recorded on THIS instance: one
-     *  materialize reads a scope several times (listHeaders, then getByIds per scope), and a
-     *  checkpoint-cadence harvest re-audits the same still-pending state — without the key, one
-     *  untouched divergence would mint a finding per read. Per-process on purpose (no durable state to
-     *  lifecycle: a cross-process resume re-discloses once, which is the desired "still pending"
-     *  notice); a divergence whose bytes CHANGE mints a new key and is reported again. */
+    /** Dedup keys for divergence findings the restricted view already recorded: one materialize reads
+     *  a scope several times (listHeaders, then getByIds per scope), and a checkpoint-cadence harvest
+     *  re-audits the same still-pending state — without the key, one untouched divergence would mint
+     *  a finding per read. Per AUDITED MOUNT (design/186 §6): the keys live and die with the mount,
+     *  same lifecycle as the id-less scope/baseline pair — one mount discloses a still-pending
+     *  divergence once, and the NEXT audited mount (a later restricted session in this process, or a
+     *  cross-process resume) re-discloses once, which is the desired "still pending" notice; the
+     *  in-process and cross-process postures agree. A divergence whose bytes CHANGE mints a new key
+     *  and is reported again within the mount. */
     private restrictedFindingKeys;
     private recordRestrictedFinding;
     /** Id-less audit state for an adoption-restricted session's WRITE scope. Armed only by the
@@ -262,7 +402,11 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private readScopeCommitted;
     /** Does `id` have a projection file anywhere in the store OTHER than `excludeAbsPath`? Returns
      *  that projection's rel path, or undefined. Early-exits on the first hit; only consulted on the
-     *  rare divergent-with-shadow path (the scope-binding guard above), never on clean reads. */
+     *  rare divergent-with-shadow path (the scope-binding guard above) for UNBOUND rows — bound rows
+     *  answer the same question in O(1) from the account binding (design/186 §2.4). RETIREMENT
+     *  CONDITION: unbound rows are a migration transitional; when they are gone this scan form has no
+     *  caller left and retires WITH them (delete the function, not just the call — a dead scan arm is
+     *  the residue class the retirement registry exists for). */
     private idProjectionElsewhere;
     /**
      * The ADOPTION-RESTRICTED projection of this backend (see {@link readScopeCommitted}) — what a
@@ -287,9 +431,13 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * over the session's scopes — bytes landed AFTER materialize (a mid-session shell write) are
      * detected here, at the very boundary where an unrestricted harvest would have admitted them —
      * then check the committed account for entries MISSING from disk entirely (an unattributed delete
-     * is divergence too). Ledger rows carry no scope, so presence is judged across every registered
-     * scope, the same resolution `getByIds` uses; a rename or cross-scope move therefore never reads
-     * as missing. Non-destructive throughout: nothing is restored, forgotten, or adopted here.
+     * is divergence too). BOUND rows (design/186 §2.2) are judged AT THEIR COMMITTED PROJECTION: a
+     * single-copy move / delete-then-plant empties the bound address and rings here even though the
+     * id is still "somewhere" (the v1 any-scope presence test read exactly that as fine — the
+     * registered residual this schema retires); byte-carriers of the id at other addresses are named
+     * in the same finding. UNBOUND rows (migration transitional) keep the v1 store-wide presence
+     * test — no false alarms while their address is underivable. Non-destructive throughout: nothing
+     * is restored, forgotten, or adopted here.
      *
      * `opts.idlessWriteScope` is the CALLER's per-call session verdict (same posture as the mount:
      * the backend never guesses): when the audited session HAS a write scope, id-less files under it
@@ -345,7 +493,9 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private assertTxnLockOwnership;
     private applyPatchesLocked;
     /** Plan one patch: decide CAS/conflicts against CURRENT state, emit journal ops (no entry-file
-     *  writes here — staging/execution happen in {@link applyPatches}). */
+     *  writes here — staging/execution happen in {@link applyPatches}). Every row write is BOUND
+     *  (§1.1) at the coordinates the batch ACTUALLY lands — a slug collision's `-n` suffix binds the
+     *  suffixed slug, the same one `applied[].slug` reports (v1's ledger had no landing awareness). */
     private planOne;
     private locateById;
     getConsolidationCursor(scope: string): Promise<string | undefined>;