@sema-agent/core 5.46.0 → 5.47.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 5.47.0 — 2026-08-20
+
+### Added
+- design/336 slices 2+3 — the F-020 deep fix completes:
+  - **Slice 2 (settlement + hold)**: a delegation's memory-pollution verdict is a durable
+    SETTLEMENT ACCOUNT (three strict side-ledgers; write-ahead launch rows; crash-idempotent
+    retry; fork/bg lane parity), and instruction-form files under exposure ride a three-state
+    HOLD (held → released/disposed, loud timeout `config.memory_hold_timeout`;
+    `MemoryEngineOptions.holdSettleTimeoutMs`). `HarvestReport.containment` (#331) and the
+    `memory.hold_*` notice family land with it. The origin representation family is
+    serialization-closed (carrier tokenization + round-trip property laws).
+  - **Slice 3 (read side + human faces)**: `memory_search` returns two exposure bands (clean
+    first; `MemoryEntryHeader.exposure`; `MemorySearchHit` becomes a discriminated union
+    CleanHit | ExposedHit — see BREAKING); exposed entries render as opaque handles (zero
+    model-authored text on the passive face); `memory_get` delivery carries a fact-form banner
+    and marks the session derived (`onTaintedDelivery` — mechanical closure of source-scope
+    laundering); the memory-dir Read lane head-parses committed origin. Human faces (host API
+    only, deliberately no model tool): `listExternalOriginEntries` + `clearEntryOrigin` (audited
+    un-mark: write-ahead custody → committed tombstone → same-id re-record;
+    `listOriginClearances`; `memory.origin_clear_*` family). A live behavioral probe pins that a
+    marked entry in context is still used normally (deepseek-v4-flash, zero refusal).
+  - `memoryProvenance: "off"` keeps every read face byte-identical to 5.46 (pinned directly).
+- `NOTICE_AUDIENCE` + `noticeAudienceOf` — the presentation-tier registry (who a notice code is
+  for): "user" for the session-memory posture disclosures, everything else defaults "operator".
+  `EngineNotice.sessionId` typed top-level key, lifted from `detail.sessionId` at the delivery
+  throat (mint sites untouched). `ambiguousOriginRepresentation` exported (the origin ambiguity
+  predicate a third-party backend refuses multi-carrier representations with).
+- The session-reconcile never-started texts condition their re-issue cue on the blocking
+  approval/gate being resolved first (#352 — the side-effect statement stayed true; the action
+  cue no longer amplifies a blocked-approval loop).
+
+### Changed
+- **BREAKING (types)**: `MemorySearchHit` is now a discriminated union (CleanHit | ExposedHit)
+  instead of a single interface. Backend contract: the conformance suite gains two cases
+  (exposure carriage + two-band truncation boundary) — a backend implementing the pre-336 shape
+  fails them (upgrade-order duty: adopt the new clauses before taking 5.47 in a mixed fleet).
+  `memory_get` tool contract revision 3→4, `memory_search` 2→3 (execute-visible text changes).
+- The kill-tree descendant-reap suite's liveness probe reads a ZOMBIE as dead (a landed SIGKILL
+  whose parent died first waits for init to reap it; under load that outlasted any fixed poll
+  window — the 5.30.0/5.46.0 publish-gate flake, root-caused and fixed).
+
 ## 5.46.0 — 2026-08-19
 
 ### Added

package/dist/agents/subagent.js

@@ -3,6 +3,8 @@ import { isAbsolute } from "node:path";
 import { withDelegationProvenance } from "../core/tool-policy.js";
 import { isHighSurrogate, isLowSurrogate } from "../core/surrogate-safe-slice.js";
 import { newDelegationProvenanceAggregate, reduceDelegationAttestation } from "../core/memory-engine/delegation-provenance.js";
+import { registerDelegationLaunch, replayExternalSettlementEffects, settleDelegation } from "../core/memory-engine/delegation-settlement.js";
+import { enqueueMemoryAnnouncement } from "../core/memory-engine/layout.js";
 import { resolveModel, resolveModelDisplayLabel } from "../core/roles.js";
 import { OUTPUT_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { TOOL_SEARCH_NAME } from "../core/runner/tool-disclosure.js";
@@ -1935,6 +1937,59 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const shortDesc = `fork: ${(typeof a.description === "string" && a.description.trim() ? a.description.trim() : prompt).slice(0, 180)}`;
                     const bgOwner = sessionScopedBg ? ctx.sessionId : ctx.taskId ?? bg.owner;
                     const bgScope = treeScope;
+                    const forkSettlementSeat = ctx.delegationSettlement?.();
+                    const forkSettleId = forkSettlementSeat !== undefined ? `bg-${uuidv7()}` : undefined;
+                    if (forkSettlementSeat !== undefined && forkSettleId !== undefined) {
+                        try {
+                            registerDelegationLaunch(forkSettlementSeat.controlDir, { settleId: forkSettleId, sessionId: forkSettlementSeat.sessionId, now: Date.now, ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}) });
+                        }
+                        catch (e) {
+                            dropHostAbortListener();
+                            const wt = await finishWorktree();
+                            return {
+                                isError: true,
+                                content: `Sub-agent not started in background: the delegation settlement account could not record the launch (${(e instanceof Error ? e.message : String(e)).slice(0, 300)}) — fail-closed; repair the memory control plane or retry.${wt ? `\n${wt}` : ""}`,
+                                details: { error: "settlement_write_ahead_failed" },
+                            };
+                        }
+                    }
+                    const settleForkRow = (status) => {
+                        if (forkSettlementSeat === undefined || forkSettleId === undefined)
+                            return;
+                        const att = status !== undefined ? childAttestation(status) : undefined;
+                        const verdict = att === "external" ? "external" : att === "clean" ? "clean" : "unattestable";
+                        let settled = false;
+                        let lastErr;
+                        for (let attempt = 0; attempt < 3 && !settled; attempt++) {
+                            try {
+                                settleDelegation(forkSettlementSeat.controlDir, { settleId: forkSettleId, status: verdict, now: Date.now });
+                                settled = true;
+                            }
+                            catch (e) {
+                                lastErr = e;
+                            }
+                        }
+                        if (settled && verdict === "external") {
+                            try {
+                                replayExternalSettlementEffects(forkSettlementSeat.controlDir, { carry: true, now: Date.now });
+                            }
+                            catch {
+                            }
+                        }
+                        if (!settled) {
+                            const detail = lastErr instanceof Error ? lastErr.message : String(lastErr);
+                            try {
+                                enqueueMemoryAnnouncement(forkSettlementSeat.controlDir, {
+                                    kind: "gate",
+                                    at: Date.now(),
+                                    items: [`delegation settlement: the terminal observation for a background fork of session ${JSON.stringify(forkSettlementSeat.sessionId)} could NOT be recorded (verdict ${verdict}) — the row stays pending and expires as UNPROVEN at the settlement window (fail-closed floor): ${detail.slice(0, 200)}`],
+                                });
+                            }
+                            catch {
+                                console.warn(`[sema] delegation settlement terminal write failed (fork, verdict ${verdict}, session ${forkSettlementSeat.sessionId}): ${detail}`);
+                            }
+                        }
+                    };
                     let taskId;
                     try {
                         taskId = bg.registry.registerBackgroundAgent({
@@ -1962,6 +2017,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         catch {
                         }
                         const wt = await finishWorktree();
+                        if (forkSettlementSeat !== undefined && forkSettleId !== undefined) {
+                            try {
+                                settleDelegation(forkSettlementSeat.controlDir, { settleId: forkSettleId, status: "void", now: Date.now, note: "registration failed before invoke (not dispatched)" });
+                            }
+                            catch {
+                            }
+                        }
                         return { isError: true, content: `Sub-agent not started in background: ${e instanceof Error ? e.message : String(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
                     }
                     childInternals.peerSelfRef?.addAxis("h", taskId);
@@ -2106,6 +2168,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     void opts.runner
                         .runTask(bgForkSpec, bgForkInternals)
                         .then(async (child) => {
+                        settleForkRow(child.status);
                         dropHostAbortListener();
                         await finishWorktree();
                         try {
@@ -2202,6 +2265,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                     })
                         .catch((e) => {
+                        settleForkRow("failed");
                         dropHostAbortListener();
                         void finishWorktree();
                         const killed = abort.signal.aborted;
@@ -2268,7 +2332,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                     : `Note: it is stopped automatically (killed) if still running when this task ends — do not promise the user results beyond this task.`,
                             ],
                         }),
-                        details: { type: "agent", subagent_type: FORK_SUBAGENT_TYPE, status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt },
+                        details: { type: "agent", subagent_type: FORK_SUBAGENT_TYPE, status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt, ...(forkSettleId !== undefined ? { settle_id: forkSettleId } : {}) },
                     };
                 }
                 const bgIgnoredNote = a.run_in_background === true
@@ -2368,6 +2432,60 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const shortDesc = reviveRow?.description ?? String(a.description ?? "sub-agent").slice(0, 200);
                 const bgOwner = reviveRow !== undefined ? reviveRow.owner : sessionScopedBg ? ctx.sessionId : ctx.taskId ?? bg.owner;
                 const bgScope = treeScope;
+                const settlementSeat = ctx.delegationSettlement?.();
+                const bgSettleId = settlementSeat !== undefined ? `bg-${uuidv7()}` : undefined;
+                if (settlementSeat !== undefined && bgSettleId !== undefined) {
+                    try {
+                        registerDelegationLaunch(settlementSeat.controlDir, { settleId: bgSettleId, sessionId: settlementSeat.sessionId, now: Date.now, ...(ctx.toolCallId !== undefined ? { toolUseId: ctx.toolCallId } : {}) });
+                    }
+                    catch (e) {
+                        dropHostAbortListener();
+                        await cancelObserver();
+                        const wt = await finishWorktree();
+                        return {
+                            isError: true,
+                            content: `Sub-agent not started in background: the delegation settlement account could not record the launch (${(e instanceof Error ? e.message : String(e)).slice(0, 300)}) — fail-closed; repair the memory control plane or retry.${wt ? `\n${wt}` : ""}`,
+                            details: { error: "settlement_write_ahead_failed" },
+                        };
+                    }
+                }
+                const settleDelegationRow = (status) => {
+                    if (settlementSeat === undefined || bgSettleId === undefined)
+                        return;
+                    const att = status !== undefined ? childAttestation(status) : undefined;
+                    const verdict = att === "external" ? "external" : att === "clean" ? "clean" : "unattestable";
+                    let settled = false;
+                    let lastErr;
+                    for (let attempt = 0; attempt < 3 && !settled; attempt++) {
+                        try {
+                            settleDelegation(settlementSeat.controlDir, { settleId: bgSettleId, status: verdict, now: Date.now });
+                            settled = true;
+                        }
+                        catch (e) {
+                            lastErr = e;
+                        }
+                    }
+                    if (settled && verdict === "external") {
+                        try {
+                            replayExternalSettlementEffects(settlementSeat.controlDir, { carry: true, now: Date.now });
+                        }
+                        catch {
+                        }
+                    }
+                    if (!settled) {
+                        const detail = lastErr instanceof Error ? lastErr.message : String(lastErr);
+                        try {
+                            enqueueMemoryAnnouncement(settlementSeat.controlDir, {
+                                kind: "gate",
+                                at: Date.now(),
+                                items: [`delegation settlement: the terminal observation for a background delegation of session ${JSON.stringify(settlementSeat.sessionId)} could NOT be recorded (verdict ${verdict}) — the row stays pending and expires as UNPROVEN at the settlement window (fail-closed floor): ${detail.slice(0, 200)}`],
+                            });
+                        }
+                        catch {
+                            console.warn(`[sema] delegation settlement terminal write failed (verdict ${verdict}, session ${settlementSeat.sessionId}): ${detail} — the pending row expires as unproven at the settlement window`);
+                        }
+                    }
+                };
                 let taskId;
                 try {
                     taskId = bg.registry.registerBackgroundAgent(reviveRow !== undefined
@@ -2427,6 +2545,13 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     dropHostAbortListener();
                     await cancelObserver();
                     const wt = await finishWorktree();
+                    if (settlementSeat !== undefined && bgSettleId !== undefined) {
+                        try {
+                            settleDelegation(settlementSeat.controlDir, { settleId: bgSettleId, status: "void", now: Date.now, note: "registration failed before invoke (not dispatched)" });
+                        }
+                        catch {
+                        }
+                    }
                     return { isError: true, content: `Sub-agent not started in background: ${e instanceof Error ? e.message : String(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
                 }
                 childInternals.peerSelfRef?.addAxis("h", taskId);
@@ -2744,6 +2869,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : opts.runner.runTask(bgSpec, bgInternals);
                 void bgChildPromise
                     .then(async (child) => {
+                    settleDelegationRow(child.status);
                     closeObserverWindow(child.status);
                     dropHostAbortListener();
                     await finishWorktree();
@@ -2938,6 +3064,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                 })
                     .catch(async (e) => {
+                    settleDelegationRow("failed");
                     closeObserverWindow("failed");
                     dropHostAbortListener();
                     void finishWorktree();
@@ -3043,7 +3170,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 : `Note: it is stopped automatically (killed) if still running when this task ends — do not promise the user results beyond this task.`,
                         ],
                     }),
-                    details: { type: "agent", status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt },
+                    details: { type: "agent", status: "async_launched", isAsync: true, task_id: taskId, description: shortDesc, prompt, ...(bgSettleId !== undefined ? { settle_id: bgSettleId } : {}) },
                 };
             }
             let child;

package/dist/core/governance-codes.d.ts

@@ -67,3 +67,16 @@ export type RuleSyncDropReason = keyof typeof RULE_SYNC_DROP_CODES;
 /** The subset that may appear on a LOCAL quarantined row (design/182 §8.1 `quarantine` instruction /
  *  fence arm / local screening). `own_actor_forged` is inbound-only by construction. */
 export type RuleQuarantineReason = Exclude<RuleSyncDropReason, "own_actor_forged">;
+/**
+ * The presentation-tier registry (the server's wire whitelist retires into this
+ * table once shipped): WHO a notice code is for. `"user"` = a session-scoped disclosure the end
+ * user of that session should see (safe to project onto the session's event stream); `"operator"`
+ * = a deployment/config/ops fact for whoever runs the process. Presentation tier is a property of
+ * the CODE (closed set, one code one tier) — never of an individual emission, which is why this is
+ * a registry and not an EngineNotice field. Codes absent from the table read as `"operator"`
+ * (the conservative default: never push an unclassified code at an end user).
+ * Orthogonal to {@link NON_GOVERNANCE_MEMORY_CODES} (a retry-semantics table, not presentation).
+ */
+export declare const NOTICE_AUDIENCE: Readonly<Record<string, "user" | "operator">>;
+/** The audience for `code` — table lookup with the conservative `"operator"` default. */
+export declare function noticeAudienceOf(code: string): "user" | "operator";

package/dist/core/governance-codes.js

@@ -29,6 +29,28 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.erasure_index_residue",
     "memory.export_incomplete",
     "memory.import_rejected",
+    "memory.hold_opened",
+    "memory.hold_released",
+    "memory.hold_disposed",
+    "memory.settlement_resolve_unattributed",
+    "memory.settlement_resolve_invalid",
+    "memory.settlement_resolve_unknown",
+    "memory.session_account_resolve_unattributed",
+    "memory.session_account_resolve_unknown",
+    "memory.hold_resolve_unattributed",
+    "memory.hold_resolve_invalid",
+    "memory.hold_resolve_unknown",
+    "memory.hold_resolve_invalid_state",
+    "memory.settlement_record_failed",
+    "memory.session_account_failed",
+    "memory.origin_clear_unattributed",
+    "memory.origin_clear_invalid",
+    "memory.origin_clear_unknown",
+    "memory.origin_clear_not_marked",
+    "memory.origin_clear_challenged",
+    "memory.origin_clear_pending",
+    "memory.origin_clear_conflict",
+    "memory.origin_clear_failed",
 ]);
 export function governanceRetryClass(code) {
     if (Object.prototype.hasOwnProperty.call(GOVERNANCE_CODES, code)) {
@@ -46,3 +68,14 @@ export const RULE_SYNC_DROP_CODES = {
     below_gc_frontier: "local-quarantined",
     server_rejected: "local-quarantined",
 };
+export const NOTICE_AUDIENCE = {
+    "memory.session_polluted": "user",
+    "memory.harvest_quarantined": "user",
+    "memory.delegation_static_mark_waived": "user",
+    "memory.hold_opened": "user",
+    "memory.hold_released": "user",
+    "memory.hold_disposed": "user",
+};
+export function noticeAudienceOf(code) {
+    return NOTICE_AUDIENCE[code] ?? "operator";
+}

package/dist/core/memory-engine/delegation-settlement.d.ts

@@ -0,0 +1,318 @@
+import type { MemoryOriginCause } from "./types.js";
+export declare const DELEGATION_SETTLEMENT_FILE = "delegation-settlement.json";
+/** A row's FIRST-WRITE status. Rows are immutable after their first write — every later transition
+ *  is an append-only event ({@link SettlementEvent}); the effective status is the fold. */
+export type SettlementRowStatus = "pending" | "unattestable";
+/** The effective (folded) status vocabulary. */
+export type SettlementStatus = "pending" | "clean" | "external" | "expired" | "void" | "unattestable";
+/** One delegation's launch fact (write-ahead: this row lands BEFORE the delegation registers or
+ *  invokes — a launch that cannot be accounted must not run). */
+export interface DelegationSettlementRow {
+    /** Background lane: minted at the write-ahead point (the launch site holds it thereafter).
+     *  Sync lane: the injective `(sessionId, toolCallId)` encoding ({@link syncSettleId}). */
+    settleId: string;
+    sessionId: string;
+    launchedAt: number;
+    lane: "background" | "sync";
+    status: SettlementRowStatus;
+    /** The delegation TOOL CALL that launched this row (background lane) — the receipt-exemption
+     *  anchor: a sync delivery claiming to be a background launch receipt is honored only when a
+     *  write-ahead row for ITS OWN toolUseId exists (a status string alone must not buy the
+     *  exemption — adversarial round 2's forged-receipt vehicle). */
+    toolUseId?: string;
+}
+/** One append-only transition/annotation event. Idempotent per eventId. */
+export interface SettlementEvent {
+    settleId: string;
+    eventId: string;
+    at: number;
+    kind: "settle" | "admin-resolve" | "annotation";
+    /** For `settle`: the observed terminal (`"unattestable"` = the delegation terminated but its
+     *  conduct is permanently unprovable — a recorder-less or incomplete chain). For `admin-resolve`:
+     *  the host's ruling ("clean"|"external"). */
+    status?: "clean" | "external" | "expired" | "void" | "unattestable";
+    /** Audit attribution for `admin-resolve` (who asked — required there, refused absent). */
+    requestId?: string;
+    note?: string;
+}
+/** The injective sync-lane settleId: `encodeURIComponent` on both members keeps the separator
+ *  unambiguous (neither side can smuggle a `:`), so `(sessionId, toolCallId)` is one-to-one. */
+export declare function syncSettleId(sessionId: string, toolCallId: string): string;
+/**
+ * §3.3 write-ahead — land the pending row for a BACKGROUND delegation, before registration and
+ * before invoke (行→注册→invoke). Idempotent per settleId (a revive cycle re-registers under a
+ * fresh settleId; a crash-retry of the same launch replays the same row). Throws on an unwritable
+ * or corrupt ledger — the launch site fails the launch loudly (a delegation that cannot be
+ * accounted must not run: the whole point is that no child exists outside the account).
+ */
+export declare function registerDelegationLaunch(controlDir: string, input: {
+    settleId: string;
+    sessionId: string;
+    now: () => number;
+    toolUseId?: string;
+}): void;
+/**
+ * §3.5 (r5-3) — the SYNC lane's unattestable row: a synchronous delegation delivered with a
+ * missing/unknown attestation under the "attested-only" evidence standard. The row is a durable
+ * TERMINAL at first write (there is nothing left to settle — the window is already closed
+ * unprovable), and it must commit BEFORE the result enters the transcript: the caller treats a
+ * throw here as "deliver an error instead" (fail-closed — unattested content must not ride into
+ * the transcript of a session whose account could not record the fact).
+ */
+export declare function recordSyncUnattestable(controlDir: string, input: {
+    sessionId: string;
+    toolCallId: string;
+    now: () => number;
+}): void;
+/**
+ * §3.3 settle — append one observed terminal (idempotent per eventId; the default eventId keys on
+ * (settleId, status) so an at-least-once observer replays into one event). Transition legality is
+ * the FOLD's question, not the append's: an event that the fold rules out (e.g. `clean` arriving
+ * after `expired`) still lands — as an event row the fold reads as an annotation-grade fact — so
+ * the account never loses an observation (事件不丢), it just doesn't let it rewrite history.
+ */
+export declare function settleDelegation(controlDir: string, input: {
+    settleId: string;
+    status: "clean" | "external" | "expired" | "void" | "unattestable";
+    now: () => number;
+    eventId?: string;
+    note?: string;
+}): void;
+/**
+ * §3.3 host valve — `resolveSettlement(settleId, "clean"|"external", requestId)`. Advisory, same
+ * trust plane as the host API family; `requestId` is the audit anchor and is REQUIRED (a
+ * settlement resolution without attribution is refused loudly, #123 posture). Effective-state
+ * semantics live in the fold: an admin `clean` flips the EFFECTIVE state (releases post-expiry)
+ * but never the history bit, and a LATER observed `external` overrides it (观测证据>admin 裁决).
+ */
+export declare function resolveSettlementRecord(controlDir: string, input: {
+    settleId: string;
+    to: "clean" | "external";
+    requestId: string;
+    now: () => number;
+}): void;
+/** One settlement's folded (effective) view. */
+export interface EffectiveSettlement {
+    row: DelegationSettlementRow;
+    /** The effective status after the fold (终局序: clean/external 互斥首达胜; external 可覆写
+     *  expired; admin clean 翻 effective 不翻史; admin 之后的 observed external 再覆写). */
+    effective: SettlementStatus;
+    /** Monotonic history bit: an `external` was EVER observed (never cleared, admin included not —
+     *  admin resolves are rulings, not observations). */
+    everExternal: boolean;
+    /** The terminal event whose identity keys the external-effects replay (undefined while pending). */
+    terminalEventId?: string;
+}
+/** Lock-less folded read of the whole ledger (journal-aware, fail-closed on corruption). */
+export declare function effectiveSettlements(controlDir: string): EffectiveSettlement[];
+/** One session's folded rows (the harvest classifier's input). */
+export declare function sessionSettlements(controlDir: string, sessionId: string): EffectiveSettlement[];
+/**
+ * §3.1 — the session exposure classifier over the settlement account (the durable pollution marker
+ * is the OTHER input; the caller ORs them). `exposed` ⇔ any {external, unattestable, expired}
+ * effective row; `pending` ⇔ not exposed ∧ any pending row. The mint cause follows the strongest
+ * evidence: an external row is an observed fact; unattestable/expired are evidence windows that
+ * closed unprovable (the static-standard cause).
+ */
+export declare function classifySessionSettlements(rows: readonly EffectiveSettlement[]): {
+    state: "clean" | "pending" | "exposed";
+    cause?: MemoryOriginCause;
+    reason?: string;
+};
+/**
+ * §3.3-4 — expire overdue pending rows (reconciliation's first leg). Every expiry is an event
+ * (idempotent by (settleId, "expired") key); returns the settleIds newly expired this pass.
+ */
+export declare function expireOverdueSettlements(controlDir: string, input: {
+    timeoutMs: number;
+    now: () => number;
+}): string[];
+/**
+ * §3.3-2 — replay the EXTERNAL rows' side effects (账先落、副作用可重放): ensure the durable
+ * pollution marker is in place (wx, first-write-wins) and the retroaction challenge sweep has
+ * covered the session's unmarked committed contributions (eventId keyed to the terminal event —
+ * a replay lands the SAME generation, a later terminal re-arms). Also enqueues the next-session
+ * announcement once per terminal event. Idempotent throughout; the watermark only skips work.
+ * `carry` scopes the sweep domain exactly like the engine's own sweeps (marked rows carry their
+ * account under "carry"; the "off" width challenges everything).
+ */
+export declare function replayExternalSettlementEffects(controlDir: string, input: {
+    carry: boolean;
+    now: () => number;
+}): Array<{
+    settleId: string;
+    sessionId: string;
+}>;
+export declare const SESSION_ACCOUNTS_FILE = "session-accounts.json";
+export interface SessionAccountRow {
+    sessionId: string;
+    openedAt: number;
+    /** The STICKY unattributed set (rel paths), frozen at materialize (§3.6 归属判据): pre-existing,
+     *  uncommitted files seen while a FOREIGN dangling open row stood. Membership never shrinks on
+     *  later writes (the r3-5 sticky law); it clears only when the row is re-opened with a fresh
+     *  classification (the residue was adjudicated by an intervening harvest). */
+    unattributed: string[];
+    closedAt?: number;
+    /** r7-3 — the host valve closed this row WITHOUT adjudication: it stops dangling but keeps
+     *  triggering the residue arm until the next FULL-domain harvest closes an account normally
+     *  (an unadjudicated close must not launder the residue window it covered). */
+    unadjudicated?: true;
+}
+/** The dangling-trigger read: open rows (and unadjudicated closes) belonging to OTHER sessions.
+ *  These are what arm the unattributed residue classification at a session's materialize. */
+export declare function foreignDanglingSessionAccounts(controlDir: string, selfSessionId: string): SessionAccountRow[];
+/** Open (or re-open, on a same-session resume) the session's account row, persisting the sticky
+ *  unattributed classification frozen at THIS materialize. */
+export declare function openSessionAccount(controlDir: string, input: {
+    sessionId: string;
+    now: () => number;
+    unattributed: readonly string[];
+}): void;
+/** The current session's sticky unattributed set (the harvest's residue-arm input). */
+export declare function sessionUnattributedSet(controlDir: string, sessionId: string): Set<string>;
+/** Close the session's account row — called ONLY after a FULL-domain harvest (zero deferred
+ *  files): a partial harvest's close would launder the deferred residue window (§3.6 序则②).
+ *  A normal full close also clears every standing `unadjudicated` flag (r7-3: the valve's
+ *  conservative window ends when a full harvest has adjudicated the plane). */
+export declare function closeSessionAccount(controlDir: string, input: {
+    sessionId: string;
+    now: () => number;
+}): void;
+/** The host valve for a dangling row (advisory; §3.6 — dangling rows never auto-expire). The
+ *  close is `closed-unadjudicated` (r7-3): it stops the row dangling but the residue arm keeps
+ *  firing until a full-domain harvest closes normally. `requestId` required (audit, #123). */
+export declare function resolveSessionAccountRecord(controlDir: string, input: {
+    sessionId: string;
+    requestId: string;
+    now: () => number;
+}): void;
+export declare const HOLDS_FILE = "holds.json";
+export declare const HOLD_DIR = "hold";
+export type HoldStatus = "capturing" | "held" | "released" | "disposed";
+export type HoldTerminal = "dirty" | "expired" | "conflict" | "discarded" | "capture_lost";
+export interface HoldRow {
+    holdId: string;
+    /** The WRITER session (lineage attribution on release records this id — the true author). */
+    sessionId: string;
+    /** The committed entry this hold's file addressed, when it addressed one (update form). */
+    entryId?: string;
+    op: "add" | "update";
+    /** CAS anchor at capture time (update form): release refuses to blind-write over a later edit. */
+    baseRev?: string;
+    /** Path relative to the memory dir (the plane seat the file was removed from). */
+    relPath: string;
+    /** The entry slug (path relative to the scope dir, sans `.md`) — the release leg's projection
+     *  identity and its filename-scan input. */
+    slug: string;
+    /** The write scope the capture belonged to — the release commits into it. */
+    scope: string;
+    /** The custody file name under `hold/`. */
+    captureName: string;
+    /** sha256 over the captured bytes (minted from the ONE read buffer — the same buffer writes the
+     *  custody file and, verified, is what release commits: no verify-reread window). */
+    contentDigest: string;
+    capturedAt: number;
+    /** The settlement rows whose outcome this hold waits on (the session's pending set at capture). */
+    settleIds: string[];
+    status: HoldStatus;
+    disposition?: {
+        terminal: HoldTerminal;
+        quarantineName?: string;
+    };
+    /** Host valve verdict awaiting the next harvest ("release" commits with cause "static"). */
+    resolved?: "release" | "discard";
+}
+export declare function readHolds(controlDir: string): HoldRow[];
+/** ATOMIC no-replace restore of a staged file onto a plane path (adversarial round 2: an
+ *  existsSync-then-rename pair is a TOCTOU — POSIX rename REPLACES a destination created between
+ *  the check and the call, clobbering a third writer's newer bytes). `link` refuses EEXIST
+ *  atomically: on success the staging name is dropped (one inode, two names → one); on EEXIST the
+ *  staging file is KEPT (custody — never overwrite the plane's newer legal bytes). */
+export declare function noReplaceRestore(stagingPath: string, destPath: string): "restored" | "kept" | "stranded";
+/**
+ * §4.2 — open one hold over an instruction-form file: the two-stage journal.
+ *   ① append row `status:"capturing"` (deterministic captureName + contentDigest minted from the
+ *     one read buffer) — the account exists before any byte moves;
+ *   ② write the custody file FROM THE SAME BUFFER, read it back, verify the digest;
+ *   ③ remove the plane file RENAME-FIRST (atomic move into `hold/<staging>`), then hash what
+ *     actually moved: equal ⇒ the staging duplicate is dropped (custody already holds verified
+ *     bytes); unequal ⇒ a third writer replaced the file between read and rename — NO-CLOBBER
+ *     rollback (the newer bytes go back ONLY if the plane path is still absent; a re-created path
+ *     keeps both copies, staging stays in custody and the caller hears "conflict" — never an
+ *     overwrite of newer legal bytes);
+ *   ④ flip the row to `"held"`.
+ * Every failure path returns a structured outcome (never throws past the row append): the caller
+ * fail-closes the file through the ordinary quarantine containment instead — an instruction file
+ * must never stay on the plane because its hold failed. EXDEV on the rename is one such refusal
+ * (cross-filesystem staging gives up rename atomicity — refused, not degraded to copy+delete).
+ */
+export declare function openInstructionHold(controlDir: string, input: {
+    sessionId: string;
+    relPath: string;
+    absPath: string;
+    content: string;
+    entryId?: string;
+    op: "add" | "update";
+    baseRev?: string;
+    slug: string;
+    scope: string;
+    settleIds: readonly string[];
+    now: () => number;
+}): {
+    ok: true;
+    holdId: string;
+    thirdWriterStranded?: string;
+} | {
+    ok: false;
+    holdId?: string;
+    reason: string;
+};
+/**
+ * §4.2 reconciliation — converge half-way holds (a crash between the journal stages):
+ *  - `capturing` + custody file present & digest-equal ⇒ flip held (the crash was after ②);
+ *  - `capturing` + custody absent + plane file present & digest-equal ⇒ complete the capture and
+ *    continue the two-stage walk; digest-UNEQUAL ⇒ the bytes were replaced — `capture_lost`
+ *    (the file stays on the plane and walks the ordinary/§3.6 arms; never "capture whatever is
+ *    there now" — that would hold a third writer's bytes under the first writer's account);
+ *  - `capturing` + custody absent + plane file gone ⇒ `capture_lost` (nothing to hold).
+ *  - `held` + plane file REAPPEARED at the relPath ⇒ left alone (a fresh write is a fresh file —
+ *    the next harvest judges it on its own; the hold's custody bytes stay the hold's).
+ */
+export declare function reconcileHolds(controlDir: string, input: {
+    memoryDir: string;
+    now: () => number;
+}): void;
+/** Dispose one held row: custody bytes move to the quarantine directory (host-auditable), the row
+ *  records its terminal + quarantineName (from-row-to-bytes addressing survives every terminal). */
+export declare function disposeHold(controlDir: string, input: {
+    holdId: string;
+    terminal: HoldTerminal;
+    now: () => number;
+}): {
+    ok: boolean;
+    quarantineName?: string;
+};
+/** Flip one row to released (the caller — the harvest release leg — has already committed the
+ *  custody bytes through the full gate set; the custody file is dropped after the flip). */
+export declare function markHoldReleased(controlDir: string, input: {
+    holdId: string;
+    now: () => number;
+}): void;
+/** The host valve — `resolveHold(holdId, "release"|"discard", requestId)`: records the verdict on
+ *  the row; the NEXT harvest reconciliation executes it ("release" re-walks the full gates and
+ *  commits WITH cause "static" — a timeout release is not proof of cleanliness; "discard"
+ *  disposes to quarantine). requestId required (audit, #123). */
+export declare function resolveHoldRecord(controlDir: string, input: {
+    holdId: string;
+    action: "release" | "discard";
+    requestId: string;
+    now: () => number;
+}): void;
+/** Read one hold's custody bytes (release leg + expired-release valve). Returns undefined when
+ *  the custody file is gone or fails its digest — the caller records capture_lost, never commits
+ *  unverified bytes. For an expired-released row the bytes may already sit in quarantine
+ *  (disposition.quarantineName) — both seats are tried, digest-verified either way. */
+export declare function readHoldCustody(controlDir: string, row: HoldRow): string | undefined;
+/** True ⇔ the session's pollution marker or any non-clean settlement row blocks a clean release
+ *  (§4.2-1: any non-clean row in the session's account keeps the hold held/disposed). */
+export declare function sessionBlocksCleanRelease(controlDir: string, sessionId: string): boolean;