@sema-agent/core 5.22.0 → 5.24.0

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;
@@ -232,5 +240,13 @@ export declare function withToolResultOffload(tool: AgentTool, store: ToolResult
  *  ⇒ byte-identical historic preview. An accessor (not a snapshot) because the wrap happens at
  *  prepare time, before the deferred classification exists and before any activation can. */
 reachableTools?: () => ReadonlySet<string> | undefined): AgentTool;
+/** The machine-recognizable start of an offloaded-detail replacement notice. Exported for consumers
+ *  that treat a `details` string as SEMANTIC INPUT (not display) — e.g. the session-continuation
+ *  read-state replay — so they can tell "this member was offloaded, the bytes here are a preview"
+ *  and degrade honestly instead of consuming preview bytes as the real value. */
+export declare const OFFLOADED_DETAIL_NOTICE_PREFIX = "\u2026[offloaded \u2014 ";
+/** True when `s` carries an offloaded-detail replacement notice (the newline-anchored prefix form the
+ *  walk emits). A semantic consumer treats such a string as NOT the member's real bytes. */
+export declare function isOffloadedDetailReplacement(s: string): boolean;
 /** The injected `read_tool_result` tool: pages through an offloaded result. `effect:"read"` (verifier/reconcile-safe). */
 export declare function createReadToolResultTool(store: ToolResultStore): AgentTool;

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

@@ -121,6 +121,8 @@ export function firstPartyOffloadPolicy(toolName) {
     switch (toolName) {
         case "Read":
             return { offload: false };
+        case "Write":
+            return { offload: false };
         case "Bash":
             return { offloadThresholdChars: 30_000 };
         case "Grep":
@@ -154,7 +156,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>`);
 }
@@ -163,21 +166,93 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId, re
         return tool;
     const wrappedExecute = async (toolCallId, params, signal, onUpdate) => {
         const res = await tool.execute(toolCallId, params, signal, onUpdate);
+        const offloadedDetails = res.details === undefined ? undefined : await offloadOversizedDetailStrings(res.details, store, thresholdChars, sessionId, toolCallId);
+        const withDetails = (r) => offloadedDetails === undefined || offloadedDetails.value === res.details ? r : { ...r, details: offloadedDetails.value };
         if (totalTextChars(res.content) <= thresholdChars)
-            return res;
+            return withDetails(res);
         const full = res.content
             .filter((b) => b.type === "text")
             .map((b) => b.text)
             .join("\n");
         if (full.length <= PREVIEW_HEAD_CHARS + PREVIEW_TAIL_CHARS)
-            return res;
+            return withDetails(res);
         const ref = buildToolResultRef(sessionId, toolCallId);
         await store.put(ref, full);
         const images = res.content.filter((b) => b.type !== "text");
-        return { ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] };
+        return withDetails({ ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] });
     };
     return { ...tool, execute: wrappedExecute };
 }
+const OFFLOADED_DETAIL_HEAD_CHARS = 2_000;
+const OFFLOADED_DETAIL_NOTICE_ALLOWANCE_CHARS = 400;
+export const OFFLOADED_DETAIL_NOTICE_PREFIX = "…[offloaded — ";
+export function isOffloadedDetailReplacement(s) {
+    return s.includes(`\n${OFFLOADED_DETAIL_NOTICE_PREFIX}`);
+}
+async function offloadOversizedDetailStrings(details, store, thresholdChars, sessionId, toolCallId) {
+    const puts = [];
+    const onStack = new Set();
+    const isPlainObject = (v) => {
+        if (typeof v !== "object" || v === null)
+            return false;
+        const p = Object.getPrototypeOf(v);
+        return p === Object.prototype || p === null;
+    };
+    const replace = (full, path) => {
+        const detailRef = buildToolResultRef(sessionId, toolCallId + " " + path);
+        puts.push(Promise.resolve(store.put(detailRef, full)));
+        return (`${full.slice(0, OFFLOADED_DETAIL_HEAD_CHARS)}\n` +
+            `${OFFLOADED_DETAIL_NOTICE_PREFIX}${full.length} chars total; ref "${detailRef}"; the remainder is retained in this run's tool-result store and reads back through the deployment's tool-results face]`);
+    };
+    const memo = new Map();
+    const walk = (v, segs) => {
+        if (typeof v === "string")
+            return v.length > thresholdChars && v.length > OFFLOADED_DETAIL_HEAD_CHARS + OFFLOADED_DETAIL_NOTICE_ALLOWANCE_CHARS ? replace(v, JSON.stringify(segs)) : v;
+        if (Array.isArray(v)) {
+            if (onStack.has(v))
+                return v;
+            const done = memo.get(v);
+            if (done !== undefined)
+                return done;
+            onStack.add(v);
+            let changed = false;
+            const next = v.map((item, i) => {
+                const w = walk(item, [...segs, i]);
+                if (w !== item)
+                    changed = true;
+                return w;
+            });
+            onStack.delete(v);
+            const result = changed ? next : v;
+            memo.set(v, result);
+            return result;
+        }
+        if (isPlainObject(v)) {
+            if (onStack.has(v))
+                return v;
+            const done = memo.get(v);
+            if (done !== undefined)
+                return done;
+            onStack.add(v);
+            let changed = false;
+            const next = {};
+            for (const [k, item] of Object.entries(v)) {
+                const w = walk(item, [...segs, k]);
+                if (w !== item)
+                    changed = true;
+                Object.defineProperty(next, k, { value: w, enumerable: true, writable: true, configurable: true });
+            }
+            onStack.delete(v);
+            const result = changed ? next : v;
+            memo.set(v, result);
+            return result;
+        }
+        return v;
+    };
+    const value = walk(details, []);
+    await Promise.all(puts);
+    return { value };
+}
 export function createReadToolResultTool(store) {
     return defineTool({
         name: OFFLOAD_TOOL_NAME,

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

@@ -4188,11 +4188,13 @@ export interface RunnerDeps {
      * they confirmed once is not asked about again.
      *
      * This is the one seam in this file that LOOSENS, and it is shaped so it can only do so within limits
-     * the engine holds. The provider hands out a READ face anchored to one verified principal; the write
-     * face is core-private, so a deployment has no API path to put a rule in — that goes through the
-     * approval-record protocol, which requires a confirmed human decision. Rules are consumed post-fold, in
-     * the gate's ask branch, and never resolve an ask carrying `requiresRealApproval` or one a PreToolUse
-     * hook raised.
+     * the engine holds. The provider hands out a READ face anchored to one verified principal. The write
+     * face is an exported BACKEND CONTRACT (ruled 2026-08-10: an out-of-repo store twin builds against the
+     * same definitions instead of mirroring them), but the ENGINE reaches it only on the consent lanes —
+     * redemption of a confirmed human decision, the tighten-delete, and the sync join — a wiring invariant
+     * pinned by a registered-caller scan (test/permission-rule-writer-callers); no exported convenience
+     * mints a rule around consent. Rules are consumed post-fold, in the gate's ask branch, and never
+     * resolve an ask carrying `requiresRealApproval` or one a PreToolUse hook raised.
      *
      * Omitted ⇒ the lane does not exist: no rules are read, no field is added to any ask, and the decision
      * path is byte-identical to a build without it. An unauthenticated task (no `principal`) resolves to
@@ -4200,6 +4202,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

@@ -88,7 +88,7 @@ export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW,
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, type ToolResultStore, type ToolResultSlice, } from "./core/tool-result-store.js";
-export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
+export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";
@@ -136,23 +136,31 @@ export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRul
 /**
  * design/179 — persisted ALLOW rules: the standing form of approvals a person already gave.
  *
- * Note what is NOT here. `PermissionRuleWriter` is core-private and never exported, so a deployment has
- * no API path that puts a rule in the store; every rule that enters through the engine comes out of the
- * consent protocol below (a durable approval record, an authenticated confirmation, a principal-bound
- * redemption). Removal is exported without that ceremony, because narrowing on a user's behalf is allowed
- * and widening is not.
+ * The consent boundary, restated precisely (ruled 2026-08-10): the ENGINE's only write
+ * path into a rule store is the consent protocol below (a durable approval record, an authenticated
+ * confirmation, a principal-bound redemption). That fact is a property of the engine's wiring, not of
+ * what this file exports — a deployment always owned its own storage bytes. The BACKEND CONTRACT
+ * (writer types, the writer handle key, and the fold pure functions) is therefore exported further
+ * down, so an out-of-repo store implementation (the server's SQL twin) is built against the same
+ * definitions as the file backend instead of mirroring them — mirrored types are how comment/contract
+ * drift starts. What stays deliberately absent is any convenience that mints rules AROUND consent:
+ * exporting the contract gives a store implementer the same powers it already had over its own bytes,
+ * and nothing more. Removal is exported without ceremony, because narrowing on a user's behalf is
+ * allowed and widening is not.
  */
 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 { 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, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, type PermissionRuleWriter, type WritablePermissionRuleStore, type RuleWriteDelta, type RuleAddDelta, type RuleDeleteDelta, type RuleSyncJoinDelta, type RawRuleSyncState, type RedemptionAuthorization, } 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 +186,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

@@ -112,16 +112,18 @@ export { buildAutoModePrompt, renderAutoModeWindow, renderAutoModeAction, AUTO_M
 export { AUTO_MODE_BASE_PROMPT, AUTO_MODE_PERMISSIONS_EXTERNAL } from "./core/auto-mode-prompt-assets.js";
 export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRule, wildcardMatch, } from "./core/permission-rules.js";
 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 { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, } 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;