@sema-agent/core 5.22.0 → 5.23.0

package/dist/core/tool-policy.d.ts

@@ -69,8 +69,16 @@ export interface ToolCallRequest {
 /** Where a decision came from, for audit (design/37). `"sandbox"` (F-012 L2) marks an allow the
  *  sandbox-admission leg resolved: the deployment declared an isolated execution env, every surviving
  *  ask on the call was engine-classified sandbox-local, and the call crosses no declared boundary —
- *  disclosed durably as `permission.sandbox_admitted`. */
-export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier" | "persisted_rule" | "sandbox";
+ *  disclosed durably as `permission.sandbox_admitted`.
+ *
+ *  design/182 §7 adds the two ORG-layer words, both TIGHTENING-only:
+ *   - `"org_rule"` — an organization policy rule spoke (a deny, or an ask that no configuration can
+ *     dismiss). Distinct from `"rule"` (a deployment `ToolPolicy` rule) because the AUTHORITY differs:
+ *     an org rule comes from the org's server-published snapshot, not from this deployment's policy.
+ *   - `"org_unavailable"` — an org-governed deployment could not adjudicate against a snapshot, so the
+ *     whole decision boundary failed closed (see `ORG_UNAVAILABLE_DECISION_REASON`, the single
+ *     spelling this word is minted from). */
+export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier" | "persisted_rule" | "sandbox" | "org_rule" | "org_unavailable";
 /**
  * WHO (or what) ENDED an approval — the machine-readable twin of a settlement's human-readable text,
  * so a consumer tells "a person decided this" from "nobody answered" without prose-matching a sentence.
@@ -78,10 +86,20 @@ export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier"
  * what ended the WAIT.
  *
  *  - `"human"` — a person, or the approver acting for one, returned a final verdict (allow or deny).
- *  - `"timeout"` — the configured approval window elapsed with no answer.
+ *  - `"timeout"` — an approval window elapsed with no answer.
  *  - `"aborted"` — every other NON-HUMAN end: the task aborted, the approver threw or reported nobody
  *    reachable, the decision arrived out of contract, a store or transport gave way, retries ran out.
  *
+ * **Which windows `"timeout"` speaks for** (#114①, 2026-08-09 — the promise this note used to make was
+ * wider than the code): the engine stamps it at the waits IT owns — `createApprovalPolicy`'s
+ * `approvalTimeoutMs` window, and the durable park's TTL. The SYNCHRONOUS `onAsk` leg is not one of
+ * them: there the deployment owns the window (the engine starts no timer for a callback it does not
+ * schedule), so an unanswered card and a refused one arrive as the same `false` and the engine records
+ * `"human"` rather than inventing a cause it did not observe. A host that DOES time its own card out
+ * can say so — {@link AskOutcome}'s object arm carries an optional `settledBy` for exactly this — but a
+ * host that does not is indistinguishable, by construction. Read an absent `"timeout"` as "no window
+ * the engine owns elapsed", never as "nobody's window elapsed".
+ *
  * The three words are exhaustive and mutually exclusive over the ways an approval can end, and the
  * minimum discrimination a consumer needs — someone refused vs nobody answered — is `"human"` vs the
  * other two.
@@ -694,17 +712,32 @@ export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal)
  *    untyped bridge is a fail-closed deny naming the defect (the historical truthy leniency was a
  *    fail-open on the security face with no live producer).
  *  - `"unavailable"` — the G1 per-ask routing verdict (see {@link OnAsk}).
- *  - `{ allow, updatedInput? }` — verdict PLUS an operator EDIT of the presented args
+ *  - `{ allow, updatedInput?, settledBy? }` — verdict PLUS an operator EDIT of the presented args
  *    (whole-replacement form, e.g. ctrl+g "edit script in $EDITOR"): the human approved a MODIFIED
  *    action, and executing the un-edited args would betray that consent. `allow` folds STRICTLY
  *    (`allow === true`) — an object arm is a deliberate caller, so no truthy leniency — and
  *    `updatedInput` is honored only on allow (a deny edit never executes anything). The edit is
  *    applied as the resolved decision's own rewrite: the gate re-validates it against the tool
  *    schema exactly like a hook/policy rewrite.
+ *
+ * #114② (2026-08-09) — `settledBy` on the object arm is the SYNCHRONOUS leg's only channel for saying
+ * what ended the wait. This leg's window belongs to the HOST (`onAsk` is a callback the deployment
+ * owns; the engine starts no timer for it), so a host that timed its own approval card out could
+ * previously only report a plain `false`, which the engine correctly recorded as `"human"` — a person
+ * refusing. The two words the host may self-report:
+ *  - `"human"` — a person answered (identical to omitting the field);
+ *  - `"timeout"` — the host's own approval window elapsed with no answer. Legal ONLY with
+ *    `allow: false`: a window that elapsed cannot be the thing that approved an action, so
+ *    `{allow: true, settledBy: "timeout"}` is a contradiction and is refused fail-closed (the same
+ *    narrowing the `PermissionResult` allow arm already spells in its type).
+ * `"aborted"` is deliberately NOT accepted here — that word names the engine's OWN fail-closed ends
+ * (abort, throw, unavailable, out-of-contract value), each already stamped at its own arm, and a
+ * self-reported one would let a host relabel its refusal as an engine failure.
  */
 export type AskOutcome = boolean | "unavailable" | {
     allow: boolean;
     updatedInput?: unknown;
+    settledBy?: Extract<ApprovalSettledBy, "human" | "timeout">;
 };
 /**
  * ruled 2026-08-04 — forward an approver into a delegated child, stamping every ask it raises with the

package/dist/core/tool-policy.js

@@ -844,12 +844,40 @@ export async function resolveAsk(req, onAsk, signal) {
         };
     }
     if (typeof ok === "object" && ok !== null) {
-        if (ok.allow !== true) {
-            return { action: "deny", message: `approval denied for "${req.toolName}": ${req.message}`, decisionReason: "mode", settledBy: "human" };
+        const supplied = ok.settledBy;
+        const allowed = ok.allow;
+        const suppliedEdit = ok.updatedInput;
+        if (supplied !== undefined && supplied !== "human" && supplied !== "timeout") {
+            return {
+                action: "deny",
+                message: `the approver for "${req.toolName}" reported settledBy "${typeof supplied === "string" ? containThrownText(supplied) : supplied === null ? "null" : typeof supplied}", which is outside what a synchronous ` +
+                    `approver may self-report — it is exactly "human" or "timeout" (or omitted); denied fail-closed`,
+                decisionReason: "mode",
+                settledBy: "aborted",
+            };
+        }
+        if (supplied === "timeout" && allowed === true) {
+            return {
+                action: "deny",
+                message: `the approver for "${req.toolName}" returned an allow settled by "timeout" — an elapsed approval window cannot be ` +
+                    `what approved a call; denied fail-closed (report timeout with allow:false, or allow with settledBy "human"/omitted)`,
+                decisionReason: "mode",
+                settledBy: "timeout",
+            };
+        }
+        if (allowed !== true) {
+            return {
+                action: "deny",
+                message: supplied === "timeout"
+                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}`
+                    : `approval denied for "${req.toolName}": ${req.message}`,
+                decisionReason: "mode",
+                settledBy: supplied === "timeout" ? "timeout" : "human",
+            };
         }
-        if (ok.updatedInput === undefined)
+        if (suppliedEdit === undefined)
             return { action: "allow", decisionReason: "mode", presentedInput: presented.value, settledBy: "human" };
-        const edit = tryCloneArgs(ok.updatedInput);
+        const edit = tryCloneArgs(suppliedEdit);
         if (!edit.ok) {
             return {
                 action: "deny",

package/dist/core/tool-result-store.d.ts

@@ -213,7 +213,15 @@ export declare function firstPartyOffloadPolicy(toolName: string): {
 };
 /** Head+tail preview of an offloaded result, pointing at {@link OFFLOAD_TOOL_NAME} via `ref`. Exported so
  *  the per-message aggregate budget (design/64 §17.2) produces the SAME preview format (deterministic →
- *  byte-identical across queries → prompt-cache safe). */
+ *  byte-identical across queries → prompt-cache safe).
+ *
+ *  #115 (2026-08-09) — the truncation line states WHERE the rest is, not what anyone can do with it.
+ *  "read more" alone reads as a promise that the full output is retrievable, and the model relays that
+ *  promise to the person it is talking to; what is actually guaranteed is narrower and exactly two
+ *  things: the text is retained in this run's tool-result store, and THIS chain can page it back. A
+ *  host-side read face (an HTTP route that hands the user the whole output) is a separate deployment
+ *  feature that may or may not exist — so the line names it as a deployment fact instead of implying
+ *  it, and the model can answer "can I get the full log?" without guessing. */
 export declare function buildPreview(full: string, ref: string, sizes?: {
     head: number;
     tail: number;

package/dist/core/tool-result-store.js

@@ -154,7 +154,8 @@ export function buildPreview(full, ref, sizes, reachableTools) {
     const tail = full.slice(tailStart);
     return (`${PERSISTED_OUTPUT_PREFIX}"${ref}" chars="${total}">\n` +
         `${head}\n` +
-        `…[truncated — ${total} chars total. ${offloadPagebackHint(ref, "preview", reachableTools)}]\n` +
+        `…[truncated — ${total} chars total, retained in this run's tool-result store; a user-facing read face is a deployment fact. ` +
+        `${offloadPagebackHint(ref, "preview", reachableTools)}]\n` +
         `${tail}\n` +
         `</persisted-output>`);
 }

package/dist/core/trace.d.ts

@@ -382,6 +382,53 @@ export type TraceEvent = {
     taskId: string;
     message: string;
     ts: number;
+} | {
+    /**
+     * design/182 §4.6 — a cloud-sync round moved a (rule, scope) from REMOVED back to LIVE: another
+     * replica's add outlived the local tombstone (add-wins is the locked merge semantic, so the
+     * transition itself is not news — its VISIBILITY is). The person who deleted the rule has to be
+     * able to learn that it came back, and to delete it again. Metadata only: the canonical rule
+     * text and the scope KIND — a project scope's root path stays out of the trace.
+     */
+    kind: "permission.rule_sync_resurrected";
+    version: 1;
+    /** The bucket this round synced. A local-owner bucket cannot sync, so this is always a principal. */
+    principal: string;
+    rule: string;
+    scopeKind: "global" | "project";
+    ts: number;
+} | {
+    /**
+     * design/182 §4.3/§5.2 — a cloud-sync round REFUSED an inbound row, or quarantined a local one.
+     * The reason is a closed code from the governance-codes family (never free text): the machine
+     * reads the table. One event per dropped row — a silently refused row is indistinguishable from
+     * a row that never existed, which is the failure this event exists to prevent.
+     */
+    kind: "permission.rule_sync_dropped";
+    version: 1;
+    principal: string;
+    rule: string;
+    scopeKind: "global" | "project";
+    /** Closed reason code ({@link import("./governance-codes.js").RuleSyncDropReason}). */
+    reason: string;
+    ts: number;
+} | {
+    /**
+     * design/182 §7.4 — an org-governed deployment could NOT adjudicate against an org snapshot
+     * (never installed, provider failed past the staleness bound, or the persisted state was
+     * refused). The gate answered by failing the WHOLE decision boundary closed: every terminal
+     * allow became a real-approval ask. This is the operator-facing half of that tighten — the
+     * deployment is paying the "ask about everything" price and has to be able to see why.
+     */
+    kind: "permission.org_snapshot_unavailable";
+    version: 1;
+    taskId: string;
+    toolName: string;
+    toolCallId: string;
+    /** The overlay's own disclosure lines (deployment-authored/engine-authored, never model text),
+     *  joined — provider failure, refused snapshot, rollback refusal, missing durable persistence. */
+    message: string;
+    ts: number;
 } | {
     /**
      * F-012 L2 — a pending ask was AUTO-ADMITTED by the sandbox-admission leg: the deployment's

package/dist/core/types.d.ts

@@ -4200,6 +4200,44 @@ export interface RunnerDeps {
      * disclosure — a loosening face fails toward asking.
      */
     permissionRuleStore?: import("./permission-rule-store.js").PermissionRuleStoreProvider;
+    /**
+     * design/182 §4.5 (F-011) — declare that this deployment keeps its permission rules in the
+     * IDENTITY-LESS local bucket: a task with no `principal` resolves rules through the provider's
+     * `forLocalOwner()` face instead of resolving to zero rules.
+     *
+     * A DECLARATION, never an inference (same rule as {@link permissionRuleOrg}): the local bucket is
+     * "this machine's owner", a fact only the deployment knows. Omitted/`false` ⇒ v1 exactly — an
+     * unauthenticated task reads no rules. Declared `true` while the wired provider has no local-owner
+     * face (or while no provider is wired at all) is a configuration contradiction and is refused loudly
+     * at prepare, rather than silently degrading to "the rules this person approved stopped applying".
+     *
+     * A local-owner bucket cannot cloud-sync (syncing is an authenticated act); it is adopted into a
+     * principal bucket by `adoptFilePermissionRuleStore`, after which the local-owner face resolves the
+     * adopted principal's bucket forever.
+     */
+    localOwnerRules?: boolean;
+    /**
+     * design/182 §7 — the ORG rule overlay for an org-GOVERNED deployment. Constructed with
+     * `createOrgRuleOverlay` (that constructor is the boot gate: a governed declaration with no snapshot
+     * provider refuses to boot), so a value here IS the declaration — nothing is inferred from wiring.
+     *
+     * Present ⇒ every tool call is adjudicated against the org's published deny/ask snapshot BEFORE the
+     * ask-resolution chain (org deny > org ask > personal allow rule > bare ask), and while the overlay
+     * cannot adjudicate (never installed / past the staleness bound / a refused rollback) the WHOLE
+     * decision boundary fails closed: every terminal allow becomes a real-approval ask and both
+     * ask→allow seams are disarmed. Omitted ⇒ the org layer does not exist and the decision path is
+     * byte-identical to a build without it.
+     */
+    permissionRuleOrg?: import("./permission-rule-org.js").OrgRuleOverlay;
+    /**
+     * design/182 §9 — DECLARE that this deployment drives cloud sync (`syncPermissionRules`) for the
+     * wired rule store. Purely a disclosure input: it is reported as `permissionRules.syncWired` on the
+     * wiring manifest and changes no decision. It exists because the sync loop is HOST-driven (core
+     * bundles no fetch and owns no timer), so there is nothing for the engine to infer — and "are this
+     * machine's standing approvals shared with other devices and a server?" is exactly the trust-domain
+     * fact an operator must be able to read off the manifest instead of guessing.
+     */
+    permissionRuleSyncWired?: boolean;
     /**
      * design/99 §K — resolve the **per-principal runtime ENTITLEMENTS** the engine
      * ENFORCES server-side, keyed by `spec.principal`. A deployment (the SERVICE) implements it over center's

package/dist/core/wiring-manifest.d.ts

@@ -136,6 +136,17 @@ export interface WiringManifest {
      *  "this build has no such feature", and a present-and-false one says "it exists and is off here". */
     permissionRules: {
         storeWired: boolean;
+        /** design/182 §9 — this deployment DECLARED that it drives cloud sync for the wired rule store
+         *  (`RunnerDeps.permissionRuleSyncWired`). Connecting a bucket to a sync endpoint merges every
+         *  device, the transport and the server into ONE consent trust domain, which is a fact an operator
+         *  reads off the manifest rather than infers. `false` on a deployment that does not sync — same
+         *  present-and-false shape as `storeWired`, for the same reason. */
+        syncWired: boolean;
+        /** design/182 §7 — this deployment DECLARED org governance (`RunnerDeps.permissionRuleOrg`, whose
+         *  constructor refuses to boot a governed declaration with no snapshot provider). `true` also means
+         *  the fail-closed availability contract is armed: while no org snapshot can be adjudicated
+         *  against, every terminal allow tightens to a real-approval ask. */
+        orgGoverned: boolean;
     };
     /**
      * Governance surfaces (presence facts only). `audience: "operator"` is the MACHINE-READABLE
@@ -192,6 +203,10 @@ export interface WiringFacts {
     backgroundAgentStoreWired: boolean;
     /** design/179 — a persisted allow-rule store provider is wired. */
     permissionRuleStoreWired: boolean;
+    /** design/182 §9 — the deployment declared that it drives cloud sync for that store. */
+    permissionRuleSyncWired: boolean;
+    /** design/182 §7 — the deployment declared org governance (an org rule overlay is wired). */
+    permissionRuleOrgGoverned: boolean;
     hostChildEventSinkWired: boolean;
     lockedConfigWired: boolean;
     complianceWired: boolean;
@@ -200,7 +215,7 @@ export interface WiringFacts {
 }
 /** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
  *  single-source shapes, no parallel hand-copied interface). */
-export type StaticWiringDeps = Pick<RunnerDeps, "onAsk" | "onQuestion" | "interactionPosture" | "onElicit" | "checkpointStore" | "sessionStore" | "backgroundAgentStore" | "onBackgroundChildEvent" | "lockedConfig" | "compliancePostureResolver" | "memoryScopeAdmission" | "retentionPolicy" | "permissionRuleStore">;
+export type StaticWiringDeps = Pick<RunnerDeps, "onAsk" | "onQuestion" | "interactionPosture" | "onElicit" | "checkpointStore" | "sessionStore" | "backgroundAgentStore" | "onBackgroundChildEvent" | "lockedConfig" | "compliancePostureResolver" | "memoryScopeAdmission" | "retentionPolicy" | "permissionRuleStore" | "permissionRuleSyncWired" | "permissionRuleOrg">;
 /** Named view of the spec seats the static half reads (a `Pick` of the real {@link TaskSpec}). */
 export type StaticWiringSpec = Pick<TaskSpec, "onAsk" | "onQuestion" | "checkpointStore" | "durableApproval" | "mcp" | "interactiveTools" | "interactionPosture">;
 /**

package/dist/core/wiring-manifest.js

@@ -86,7 +86,11 @@ export function deriveWiringManifest(facts) {
         parkLane,
         session: { store: manifestDurabilityOf(facts.sessionDurability) },
         fleet: { backgroundAgentStore: facts.backgroundAgentStoreWired, hostChildEventSink: facts.hostChildEventSinkWired },
-        permissionRules: { storeWired: facts.permissionRuleStoreWired },
+        permissionRules: {
+            storeWired: facts.permissionRuleStoreWired,
+            syncWired: facts.permissionRuleSyncWired,
+            orgGoverned: facts.permissionRuleOrgGoverned,
+        },
         governance: {
             audience: "operator",
             lockedConfig: facts.lockedConfigWired,
@@ -179,6 +183,8 @@ export function describeStaticWiring(deps, spec = {}) {
         sessionDurability: resolveDeclaredDurability(deps.sessionStore, "sessionStore"),
         backgroundAgentStoreWired: deps.backgroundAgentStore !== undefined,
         permissionRuleStoreWired: deps.permissionRuleStore !== undefined,
+        permissionRuleSyncWired: deps.permissionRuleSyncWired === true,
+        permissionRuleOrgGoverned: deps.permissionRuleOrg !== undefined,
         hostChildEventSinkWired: deps.onBackgroundChildEvent !== undefined,
         lockedConfigWired: deps.lockedConfig !== undefined,
         complianceWired: deps.compliancePostureResolver !== undefined,

package/dist/index.d.ts

@@ -145,14 +145,16 @@ export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRul
 export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, type PersistedAllowRule, type RuleTombstone, type RuleScope, type RuleDot, type RuleAdd, type RuleAddOrigin, type RuleSuggestion, type RuleReject, type RuleRejectCode, type ParsedAllowRule, type PersistedRuleTool, type PersistedRuleMatch, } from "./core/permission-rule-model.js";
 export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, type PermissionRuleStore, type PermissionRuleStoreProvider, type StoredAllowRules, type RemoveResult, type PutResult, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, type RuleSyncState, type RuleSyncFrontier, type RuleSyncDrop, type RuleSyncLandingReport, type RuleOwner, type QuarantinedRuleAdd, } from "./core/permission-rule-store.js";
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, type PermissionRuleSyncTransport, type PermissionRuleSyncResult, type RuleSyncRequestBody, type RuleSyncResponseBody, } from "./core/permission-rule-sync.js";
-export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, type OrgPermissionRule, type OrgRuleSnapshot, type OrgRuleSnapshotProvider, type OrgRuleStatePersistence, type PersistedOrgRuleState, type OrgRuleOverlay, type OrgOverlayResolution, type OrgOverlayStatus, type EffectivePermissionRule, } from "./core/permission-rule-org.js";
+export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, type OrgPermissionRule, type OrgRuleSnapshot, type OrgRuleSnapshotProvider, type OrgRuleStatePersistence, type PersistedOrgRuleState, type OrgRuleOverlay, type OrgOverlayResolution, type OrgOverlayStatus, type EffectivePermissionRule, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES, type RuleSyncDropReason, type RuleQuarantineReason } from "./core/governance-codes.js";
 export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
 export { adoptFilePermissionRuleStore, type AdoptFileRuleStoreResult } from "./stores/file/permission-rule-adopt.js";
+export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./stores/file/adoption/marker.js";
+export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./stores/file/adoption/adopt.js";
 export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, type Hooks, type HookToolContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, type PermissionDeniedSource, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, type NormalizedMemorySpec, type MemorySpecInput, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, type Embedder, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, type UtilityGate, type MemoryStore, type MemoryVectorMode, type ScoredMemory, type MemoryNoteHeader, type MemoryNoteRecord, type MemoryNoteType, type StructuredNoteInput, } from "./core/memory.js";
-export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
+export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, type SharedMemoryStoreProvider, type SharedMemoryStoreReader, type SharedMemoryPagedList, type SharedMemoryStoreInfo, type SharedMemoryDocumentEntry, type SharedMemorySnapshot, type SharedMemoryRequestContext, type MemoryListDetails, type MemoryReadDetails, } from "./core/shared-memory/types.js";
 export { sharedMemoryStoreContract, type SharedMemoryFixture, type SharedMemoryStoreContractHooks, } from "./core/shared-memory/contract.js";
 export { termSet, jaccardDistance, cosineDistance } from "./core/memory-vector.js";
@@ -178,7 +180,7 @@ export { teacherMode, TEACHER_PROFILE, type TeacherModePair, type TeacherProfile
 export { loadOrchestrationEnv, DEFAULT_REASONING_INTENSITY, type OrchestrationMode, type OrchestrationEnv, } from "./scenarios/env.js";
 export { runWorkflow, startWorkflow, workflowAgentCallKey, WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowAgentBlockedError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE, type WorkflowFanOutSlotError, type WorkflowFanOutOptions, WORKFLOW_SUBAGENT_PROMPT, WORKFLOW_SUBAGENT_PROMPT_SCHEMA, WORKFLOW_SUBAGENT_APPEND, WORKFLOW_SUBAGENT_APPEND_SCHEMA, type WorkflowHandle, MAX_WORKFLOW_ITEMS, type WorkflowRun, type WorkflowRunStatus, type WorkflowItemStatus, type WorkflowPhase, type WorkflowGroup, type WorkflowAgentRun, type WorkflowAgentHandle, type WorkflowRunStats, type WorkflowEvent, type WorkflowBudget, type WorkflowAgentOptions, type WorkflowRunContext, type WorkflowInternals, type RunWorkflowOptions, type RunWorkflowResult, type WorkflowTimers, } from "./orchestration/workflow.js";
 export { listWorkflowRuns, getWorkflowRun, subscribeWorkflow, deriveAgentDisplayStatus, type AgentDisplayStatus } from "./orchestration/workflow-observe.js";
-export { runGoal, DECLARE_DONE_TOOL_NAME, type GoalSpec, type GoalResult, type GoalStatus, type GoalVerdict, type GoalTurnState, type GoalVerificationKind, } from "./orchestration/goal.js";
+export { runGoal, DECLARE_DONE_TOOL_NAME, type GoalSpec, type GoalResult, type GoalStatus, type GoalBudgetCause, type GoalVerdict, type GoalTurnState, type GoalVerificationKind, } from "./orchestration/goal.js";
 export { emitTaskOutcome, type TaskOutcome } from "./core/task-outcome.js";
 export { runOracle, captureBaseline, resolveFrozenPaths, snapshotFrozenPaths, restoreFrozenPaths, specError, type SpecContract, type OracleGateSpec, type OracleGreenSpec, type OracleVerdict, type OracleGateResult, type OracleRunReport, type OracleBaseline, } from "./core/spec-contract.js";
 export { runSpec, type RunSpecOptions, type RunSpecResult, type RunSpecOracleReport } from "./orchestration/run-spec.js";

package/dist/index.js

@@ -114,14 +114,16 @@ export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRul
 export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, } from "./core/permission-rule-model.js";
 export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, } from "./core/permission-rule-store.js";
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, } from "./core/permission-rule-sync.js";
-export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, } from "./core/permission-rule-org.js";
+export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES } from "./core/governance-codes.js";
 export { prepareCardApproval, confirmRuleApproval, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
 export { adoptFilePermissionRuleStore } from "./stores/file/permission-rule-adopt.js";
+export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./stores/file/adoption/marker.js";
+export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./stores/file/adoption/adopt.js";
 export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, } from "./core/memory.js";
-export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, readV2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, migrateScope, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, syncMemoryScope, } from "./core/memory-engine/index.js";
+export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, readV2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, migrateScope, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, syncMemoryScope, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, } from "./core/shared-memory/types.js";
 export { sharedMemoryStoreContract, } from "./core/shared-memory/contract.js";
 export { termSet, jaccardDistance, cosineDistance } from "./core/memory-vector.js";

package/dist/orchestration/goal.d.ts

@@ -66,6 +66,13 @@ export interface GoalSpec {
     taskSignature?: string;
 }
 export type GoalStatus = "achieved" | "max_iterations" | "budget" | "blocked" | "suspended" | "needs_review" | "failed" | "aborted";
+/**
+ * #111 — which ceiling ended a `status:"budget"` run. The status set stays CLOSED (a consumer
+ * switching on it keeps compiling); this is the terminating FACTOR beside it, because the two
+ * ceilings ask the caller for opposite corrections: `"tokens"` = the allowance is spent (narrow the
+ * objective / raise `budgetTokens`), `"walltime"` = `totalTimeoutMs` elapsed (give it more time).
+ */
+export type GoalBudgetCause = "tokens" | "walltime";
 export interface GoalResult {
     readonly status: GoalStatus;
     /** Last iteration's result; absent on a preflight-terminate (a stop BEFORE iteration 1 ran). */
@@ -83,6 +90,9 @@ export interface GoalResult {
     readonly checkpointToken?: CheckpointToken;
     /** Set on `failed` (incl. `goal.donecheck_error`). */
     readonly errorCode?: string;
+    /** #111 — present IFF `status === "budget"` (the KEY is absent otherwise, so presence alone reads
+     *  as "stopped on a ceiling"). See {@link GoalBudgetCause}. */
+    readonly budgetCause?: GoalBudgetCause;
 }
 /** Reserved name of the goal-completion signal tool (injected by `runGoal` when there is no outputSchema). */
 export declare const DECLARE_DONE_TOOL_NAME = "DeclareDone";

package/dist/orchestration/goal.js

@@ -89,7 +89,7 @@ export async function runGoal(runner, spec) {
     const goalSignal = spec.signal
         ? AbortSignal.any([spec.signal, deadlineCtl.signal])
         : deadlineCtl.signal;
-    const classifyStop = () => spec.signal?.aborted ? "aborted" : deadlineCtl.signal.aborted ? "budget" : null;
+    const classifyStop = () => spec.signal?.aborted ? { status: "aborted" } : deadlineCtl.signal.aborted ? { status: "budget", budgetCause: "walltime" } : null;
     const mk = (status, iterations, over) => {
         const r = {
             status,
@@ -101,6 +101,7 @@ export async function runGoal(runner, spec) {
             cumulativeTokens,
             checkpointToken: over?.checkpointToken,
             errorCode: over?.errorCode,
+            ...(status === "budget" && over?.budgetCause !== undefined ? { budgetCause: over.budgetCause } : {}),
         };
         if (verificationKind === "mechanical" && status !== "suspended" && status !== "needs_review") {
             runner.emitTaskOutcome?.({
@@ -129,9 +130,9 @@ export async function runGoal(runner, spec) {
         for (let iteration = 1; iteration <= spec.maxIterations; iteration++) {
             const preStop = classifyStop();
             if (preStop)
-                return mk(preStop, iteration - 1);
+                return mk(preStop.status, iteration - 1, { budgetCause: preStop.budgetCause });
             if (spec.budgetTokens !== undefined && cumulativeTokens >= spec.budgetTokens)
-                return mk("budget", iteration - 1);
+                return mk("budget", iteration - 1, { budgetCause: "tokens" });
             const objective = iteration === 1 ? spec.objective : continuationPrompt(spec.objective, lastFeedback, hasOutputSchema);
             const doneRef = {};
             const tools = hasOutputSchema
@@ -147,7 +148,7 @@ export async function runGoal(runner, spec) {
             }
             const midStop = classifyStop();
             if (midStop)
-                return mk(midStop, iteration, { result });
+                return mk(midStop.status, iteration, { result, budgetCause: midStop.budgetCause });
             if (result.status === "blocked")
                 return mk("blocked", iteration, { result });
             if (result.status === "failed") {
@@ -169,7 +170,7 @@ export async function runGoal(runner, spec) {
             catch {
                 const s = classifyStop();
                 if (s)
-                    return mk(s, iteration, { result });
+                    return mk(s.status, iteration, { result, budgetCause: s.budgetCause });
                 return mk("failed", iteration, { result, errorCode: "goal.donecheck_error" });
             }
             lastVerdict = verdict;

package/dist/stores/file/adoption/adopt.d.ts

@@ -0,0 +1,146 @@
+/**
+ * design/183 (F-011) — `adoptLocalDataRoot`: the ROOT-level adoption state machine for the file
+ * backend. It generalizes the design/182 rule-bucket arc (exclusive lock + durable intent marker +
+ * monotone phase CAS + permanent terminal record + quarantine-not-delete) to the WHOLE data root:
+ *
+ *   ① take the data-root locks (the engine's own boot lock + a dedicated ADOPTION-LOCK) — a live
+ *     writer refuses the adoption loudly instead of interleaving with it
+ *   ② land the durable root intent marker `adoption.json`                        → phase 2
+ *   ③ identity-axis rebind legs (the ONLY stores whose data carries identity):
+ *       - permission rules: the design/182 machine, NESTED as-is — never re-implemented. Its own
+ *         sub-arc (including its first sync round) runs here; legs are independent, the root phase
+ *         only orders "all legs of a stage complete before the stage advances"
+ *       - session-policy rows: per-row ATOMIC REWRITE (the filename is a one-way hash of the
+ *         composite key, so a rename cannot rebind; the `__principal` metadata must change too)
+ *                                                                                → phase 3
+ *   ④ resolution switch: publishing phase 4 is itself the switch (the marker is the truth host
+ *     configuration follows, never the reverse), and the affected-deployment CONFIG ACCOUNT is
+ *     landed — configs the machine cannot reach are honest `migrated: false` entries that stay
+ *     outstanding until a consumer WITNESSES them                                → phase 4
+ *   ⑤ carriage legs (data to the cloud): pluggable, idempotent, re-run whole on resume; rows the
+ *     far side refuses land in the per-store QUARANTINE area — preserved and disclosed, never
+ *     deleted, and never blocking the arc (a quarantined row is a COMPLETED disposition)
+ *                                                                                → phase 5
+ *   ⑥ the marker is atomically rewritten into its PERMANENT terminal record carrying the immutable
+ *     report. Never deleted; a re-run short-circuits to it.
+ *
+ * FREEZE (design/183 §8 load-bearing premise): from the moment ② lands, the whole root is read-only
+ * for everyone but this machine — live writers are excluded by the locks, and across crashes every
+ * file store constructor refuses the in-flight marker (invariant I6, `assertAdoptionBootGate`).
+ * Idempotent resume ("re-run completes the unfinished legs") is only sound because no per-store row
+ * moves underneath it; the freeze is the premise of idempotence, not an implementation detail.
+ *
+ * What this half deliberately does NOT do: bulk data carriage for the zero-identity stores (session,
+ * checkpoint, memory, …) — ownership of those rows rides with the carriage legs (server bulk-import
+ * endpoints / existing sync faces), which plug into ⑤ through {@link AdoptionCarriageLeg}. Core's
+ * file half ships the freeze face, the acceptance face and the rebind legs.
+ */
+import type { PermissionRuleSyncTransport } from "../../../core/permission-rule-sync.js";
+import { type AdoptionReceipt, type AdoptionSource, type AffectedDeploymentConfig } from "./marker.js";
+/** The per-leg context handed to a carriage leg: rows the far side REFUSES go here — preserved and
+ *  disclosed, never deleted (design/183 §7.2). Quarantining never fails the leg. */
+export interface AdoptionCarriageLegContext {
+    quarantine: (name: string, bytes: string) => void;
+}
+/**
+ * One pluggable carriage leg for stage ⑤ (design/183 §5). MUST be idempotent: a resume re-runs every
+ * carriage leg in full (a sync round is a join; an import is row-keyed) — only legs WITHOUT a
+ * self-attesting completion predicate record completion bits, and carriage legs all have one (the
+ * far side's row set). `run` resolves with the carried row count; a throw stalls the arc at the
+ * ④→⑤ boundary and the marker keeps the root frozen until a re-run completes the leg.
+ */
+export interface AdoptionCarriageLeg {
+    /** Store family name as it should appear in the report legs (e.g. "session", "memory"). */
+    store: string;
+    run: (ctx: AdoptionCarriageLegContext) => Promise<{
+        rows?: number;
+    } | void>;
+}
+export interface AdoptLocalDataRootOptions {
+    /** The data root (the directory `FileStorageBackend` and the independent file stores build over). */
+    root: string;
+    from: AdoptionSource;
+    toPrincipal: string;
+    /** The claim REFERENCE for the new identity's credentials (minted by the server; design/183 §4.3).
+     *  A reference, never the credential bytes — the marker file is a plain-text sidecar. */
+    credentials: {
+        issuedBy: "server";
+        ref: string;
+    };
+    /** The permission-rule bucket leg (design/182, nested unchanged). Absent ⇒ the deployment has no
+     *  file rule bucket and the leg is skipped. */
+    rules?: {
+        dir: string;
+        transport: PermissionRuleSyncTransport;
+    };
+    /** Stage-⑤ carriage legs (server bulk-import / existing sync faces). All must complete for the arc
+     *  to reach its terminal record. */
+    carriage?: AdoptionCarriageLeg[];
+    /** Extra affected-deployment configs beyond the built-in minimum face (design/183 §6: the table may
+     *  GROW, never shrink — an entry with the same (deployment, key) overrides the built-in values). */
+    additionalConfigs?: AffectedDeploymentConfig[];
+    now?: () => number;
+    onError?: (message: string) => void;
+}
+export type AdoptLocalDataRootResult = AdoptionReceipt
+/** A leg failed. The marker holds the last COMPLETED phase and keeps the root frozen (I6); call
+ *  again to resume from there. No bytes were lost — that is the state machine's whole contract. */
+ | {
+    status: "stalled";
+    phase: 2 | 3 | 4 | 5;
+    error: string;
+};
+/** A consumer's typed read-back receipt: proof it OBSERVED the required value at runtime, bound to
+ *  this adoption. Only this clears an account entry — an operator ack is recorded, never clearing. */
+export interface AdoptionConfigWitnessReceipt {
+    adoptionId: string;
+    deployment: string;
+    key: string;
+    observedValue: string;
+    atMs: number;
+}
+/** Record an operator acknowledgement on one account entry. Recorded, NEVER clearing: the account's
+ *  discriminating power comes from consumer witness, not from a hand-written boolean (design/183 §3.3). */
+export declare function ackAdoptionConfig(root: string, deployment: string, key: string, now?: () => number): void;
+/**
+ * Clear one config-account entry with a consumer's bound runtime read-back receipt. The receipt must
+ * name THIS adoption and carry the entry's exact required value — anything else is refused (typed):
+ * a mis-bound witness would clear the account while the deployment is still locked out.
+ */
+export declare function witnessAdoptionConfig(root: string, receipt: AdoptionConfigWitnessReceipt): void;
+/** Enumerate the quarantine area (introspection face — a quarantined row is DISCLOSED, not buried). */
+export declare function listAdoptionQuarantine(root: string): Array<{
+    store: string;
+    name: string;
+    path: string;
+}>;
+/** One root's adoption posture, readable WITHOUT the adoption parameters (the standing
+ *  introspection face design/183 §3.3 requires: while the config account is uncleared, the
+ *  outstanding list stays loudly readable — a standing answer, not a one-shot log line). */
+export type AdoptionStatus = {
+    state: "none";
+} | {
+    state: "in-flight";
+    from: AdoptionSource;
+    toPrincipal: string;
+    phase: 2 | 3 | 4 | 5;
+} | {
+    state: "adopted";
+    receipt: AdoptionReceipt;
+};
+/** Read the root's adoption posture: never throws on absence, throws (typed) on a corrupt marker. */
+export declare function readAdoptionStatus(root: string): AdoptionStatus;
+/**
+ * Run (or resume) the root-level adoption state machine over the data root (design/183 §3).
+ *
+ * Contract notes for the calling deployment:
+ *  - stop the engine first: this machine takes the SAME boot lock (`root/LOCK`) as
+ *    `FileStorageBackend`, so a live instance refuses the adoption loudly rather than interleaving —
+ *    plus the dedicated `ADOPTION-LOCK` against a concurrent adoption of independently-constructed
+ *    stores. Across crashes the in-flight marker + the I6 boot gate carry the same exclusion;
+ *  - idempotent: a re-run with the same (from → toPrincipal) answers the recorded receipt without
+ *    re-running any leg; a re-run toward a DIFFERENT principal is refused (typed);
+ *  - quarantined rows never block the arc, and post-terminal repair rides each store's NORMAL
+ *    channel (sync round / import generation — design/183 §7.2), never a re-opened adoption.
+ */
+export declare function adoptLocalDataRoot(opts: AdoptLocalDataRootOptions): Promise<AdoptLocalDataRootResult>;