@sema-agent/core 7.40.1 → 7.41.0

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

@@ -501,9 +501,9 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * gate all read it off the call's face instead of a name table. ABSENT ⇒ the tool is handled as a
      * write whose target cannot be confirmed (fail-closed under every path-confining face) — exactly how
      * a tool outside the retired name tables was handled. `param` outranks `aliases` (NotebookEdit's
-     * `notebook_path` beats a decoy `file_path`). `skillScopeEligible` is a SEPARATE grant: only a tool
-     * that sets it enters the active-skill `allowPaths` face (Write/Edit do; NotebookEdit deliberately
-     * does not; a caller tool that merely takes a built-in's NAME inherits nothing).
+     * `notebook_path` beats a decoy `file_path`). `skillScopeEligible` is a SEPARATE grant whose one reader (the
+     * skill-scope write fence) is retired (Write/Edit set it; NotebookEdit deliberately does not; a caller
+     * tool that merely takes a built-in's NAME inherits nothing).
      */
     pathTarget?: ToolPathTarget;
     /**
@@ -1071,16 +1071,14 @@ export interface ToolExecuteContext {
      */
     getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
     /**
-     * 🔴 design/77 §3 / §7 — read-only SNAPSHOT of the parent task's ACTIVE skill-manifest frames (the
-     * Gate-3 deny-narrowing scope, see {@link SkillManifest}), filled by the Runner. A delegation tool
-     * (`createSubagentTool`) reads it AT SPAWN TIME and propagates it into the child task so the child
-     * inherits the parent skill's tool/path restrictions (a child of a manifested skill is at most as
-     * capable as the manifest). Returns an opaque, frozen array of frames; an empty array = no manifest is
-     * active (the common case). The model/worker can neither read nor set it (it is not a tool argument).
-     * Undefined when the tool runs outside a Runner task. The returned frame objects are intentionally
-     * opaque to callers other than the Runner internals that re-seed them.
+     * A read-only CAPTURE of this (parent) task's skill grant rows for the run — the tools its active skills list in
+     * `allowed-tools` / `disallowed-tools` ({@link import("./skill-grant.js").SkillGrantRecord}: skill, list, entry),
+     * filled by the Runner. A delegation tool (`createSubagentTool`) reads it AT SPAWN TIME and threads it into the child,
+     * which holds the rows until it ends. A copy: the parent's later activations never reach it. An empty array = no active
+     * skill lists (the common case). The model can neither read nor set it (it is not a tool argument). Undefined when the
+     * tool runs outside a Runner task.
      */
-    activeSkillScope?: () => readonly unknown[];
+    activeSkillGrants?: () => readonly import("./skill-grant.js").SkillGrantRecord[];
     /**
      * Parent effective-policy inheritance (tighten-only) — the Runner-filled chain accessor a delegation tool
      * (`createSubagentTool` / the `run_workflow` spawn legs) calls AT SPAWN TIME and threads verbatim into the
@@ -1089,7 +1087,7 @@ export interface ToolExecuteContext {
      * (`spec.toolPolicy ?? deps.toolPolicy` — the exact slot this task's own gate enforces) with the frozen
      * task onAsk (opaque half), and its effective shellGate. The child's prepare folds these as
      * ADDITIONAL constraint layers — inheritance can only narrow a child, never widen it. Runner-filled,
-     * read-only, NEVER a model/tool argument (same posture as {@link activeSkillScope}). Undefined when the
+     * read-only, NEVER a model/tool argument (same posture as {@link activeSkillGrants}). Undefined when the
      * tool runs outside a Runner task.
      */
     inheritedGateForChildren?: () => import("./runner/contracts.js").InheritedGate;

package/dist/core/tools.d.ts

@@ -54,7 +54,7 @@ export declare function rebindDefineToolCtx(product: AgentTool, enrich: ToolCtxE
  * tool read them as `undefined` on every call and its ctx-first arms were structurally dead. This
  * closes the gap at MOUNT time instead: the mount — which does hold the Runner's trusted context —
  * supplies a builder, and the adapter runs it PER CALL, so call-time snapshots (the run's current
- * model, the live skill scope) stay current rather than freezing at factory time.
+ * model, the live skill grants) stay current rather than freezing at factory time.
  *
  * Shape is deliberately the SAME `(ctx) => ctx` one the Runner's `spec.tools` wrapper already applies,
  * so a mount passes THAT builder itself instead of re-listing the axes — one source for the trusted

package/dist/core/trace.d.ts

@@ -441,6 +441,21 @@ export type TraceEvent = {
     toolCallId: string;
     command: string;
     ts: number;
+} | {
+    /**
+     * An active skill's `allowed-tools` row cleared the call, so no person and no classifier was asked: the allow
+     * layer's third attribution channel beside `permission.persisted_rule_allowed` and `permission.read_only_allowed`.
+     * `skill` names the skill whose list spoke and `entries` the rows the call stands on, as the skill spells them
+     * (deployment text; a consumer rendering it applies its own display sanitizer).
+     */
+    kind: "permission.skill_allowed";
+    version: 1;
+    taskId: string;
+    toolName: string;
+    toolCallId: string;
+    skill: string;
+    entries: string[];
+    ts: number;
 } | {
     /**
      * design/179 — the person's persisted rule store could not be read (at prepare, or for one call), so

package/dist/core/types.d.ts

@@ -17,7 +17,7 @@ export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoct
 export type { PermissionMode } from "./ask-origin.js";
 export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
-export type { AgentDefinition, SkillManifest, SkillSpec } from "./agent-definition.js";
+export type { AgentDefinition, SkillSpec } from "./agent-definition.js";
 export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse, OnElicit } from "./mcp-server-spec.js";
 export type { TaskLimits } from "./task-limits.js";
 export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult, HumanReviewGateRow } from "./task-result.js";

package/dist/engine/harness/agent-harness.d.ts

@@ -1,7 +1,8 @@
 import type { ActorAssertion, AssistantMessage, ImageContent, Model, UserMessage } from "../llm/index.js";
 import { type ToolTurnRepair } from "../llm/index.js";
+import { type ExecutedToolCallOutcome } from "../loop/agent-loop.js";
 import type { HaltRemainingDirective } from "../loop/types.js";
-import type { AgentMessage, AgentTool, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
+import type { AgentMessage, AgentTool, AgentToolCall, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
 import { type EngineSegment } from "../../core/untrusted-text.js";
 import type { CommittedFrameCarrier } from "../../core/frame-settlement.js";
 import type { AbortResult, AgentHarnessEvent, AgentHarnessEventResultMap, AgentHarnessOptions, AgentHarnessOwnEvent, AgentHarnessResources, AgentHarnessStreamOptions, ExecutionEnv, PromptTemplate, Skill } from "./types.js";
@@ -522,6 +523,16 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
         images?: ImageContent[];
     } & UserMessageProvenance): Promise<void>;
     appendMessage(message: AgentMessage): Promise<void>;
+    /** The loop's `afterToolCall`: one `tool_result` hook emit per executed call (every registered handler, one fold). */
+    private afterToolCallHook;
+    /**
+     * Finalize a call this harness's caller executed OUTSIDE a turn (a resumed, already-approved call) exactly as the
+     * loop finalizes its own: the same {@link finalizeToolOutcome} over the same `tool_result` emit, so the call meets the
+     * same handlers, the same patch application and the same throwing-hook posture as a live one.
+     */
+    finalizeToolCall(toolCall: AgentToolCall, args: unknown, executed: ExecutedToolCallOutcome): Promise<ExecutedToolCallOutcome & {
+        toolCall: AgentToolCall;
+    }>;
     getModel(): Model;
     /** The ref that chose the CURRENT model — {@link getModel}'s companion (a word re-resolves, an object pins). */
     getModelRef(): import("../../core/model-seat.js").ModelRef;

package/dist/engine/harness/agent-harness.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream, ensureToolTurnInvariants, snapshotActorAssertion, stripEngineMetadata } from "../llm/index.js";
-import { runAgentLoop } from "../loop/agent-loop.js";
+import { finalizeToolOutcome, runAgentLoop } from "../loop/agent-loop.js";
 import { resolveAgentCoreStreamFn } from "../loop/runtime-deps.js";
 import { normalizeEngineSegments } from "../../core/untrusted-text.js";
 import { AUTH_CARRIER_NAMES } from "../../brain/request-params.js";
@@ -674,18 +674,7 @@ export class AgentHarness {
                 });
                 return result;
             },
-            afterToolCall: async ({ toolCall, args, result, isError }) => {
-                const patch = await this.emitHook({
-                    type: "tool_result",
-                    toolCallId: toolCall.id,
-                    toolName: toolCall.name,
-                    input: args,
-                    content: result.content,
-                    details: result.details,
-                    isError,
-                });
-                return patch;
-            },
+            afterToolCall: ({ toolCall, args, result, isError }) => this.afterToolCallHook(toolCall, args, result, isError),
             prepareNextTurn: async () => {
                 await this.flushPendingSessionWrites();
                 await this.emitHook({ type: "turn_boundary", model: this.model });
@@ -1217,6 +1206,21 @@ export class AgentHarness {
             throw normalizeHarnessError(error, "session");
         }
     }
+    async afterToolCallHook(toolCall, args, result, isError) {
+        const patch = await this.emitHook({
+            type: "tool_result",
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            input: args,
+            content: result.content,
+            details: result.details,
+            isError,
+        });
+        return patch;
+    }
+    finalizeToolCall(toolCall, args, executed) {
+        return finalizeToolOutcome(toolCall, executed, (result, isError) => this.afterToolCallHook(toolCall, args, result, isError));
+    }
     getModel() {
         return this.model;
     }

package/dist/engine/loop/agent-loop.d.ts

@@ -23,7 +23,7 @@
  */
 import type { AssistantMessage, ToolResultMessage } from "../llm/index.js";
 import { type AgentCoreStreamRuntimeDeps } from "./runtime-deps.js";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, HaltRemainingDirective, StreamFn } from "./types.js";
+import type { AfterToolCallResult, AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentToolResult, HaltRemainingDirective, StreamFn } from "./types.js";
 /** Callback used by synchronous loop runners to publish agent lifecycle events. */
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 /** Named reasons the loop goes around again. Assertable in tests via the trace sink. */
@@ -154,6 +154,11 @@ type ExecutedToolCallBatch = {
     messages: ToolResultMessage[];
     terminate: boolean;
 };
+/** An executed call's raw outcome, before (and, from {@link finalizeToolOutcome}, after) the post-execution half. */
+export type ExecutedToolCallOutcome = {
+    result: AgentToolResult<unknown>;
+    isError: boolean;
+};
 /**
  * How many tool names an unknown-tool miss spells out. A miss is a NAME problem: seeing a couple of dozen
  * real names is what lets a model spot the one it meant, while a full listing grows with the deployment
@@ -174,4 +179,14 @@ export declare const TOOL_VALIDATION_REFUSED_CODE = "tool.validation_refused";
  *  reported on the fault seat): a validator is a precondition read, not a network call, so a single
  *  bound serves every tool; a deployment validator that needs longer is a validator doing too much. */
 export declare const TOOL_INPUT_VALIDATION_TIMEOUT_MS = 10000;
+/**
+ * The post-execution half EVERY executed tool call passes through — the loop's own calls here, and a call
+ * the harness executed outside a turn (a resumed approved call, `AgentHarness.finalizeToolCall`) through the
+ * same function, so the two cannot drift into two dialects of one finalization: the `afterToolCall` patch
+ * (content / details / terminate / isError), the D4 posture on a throwing hook, and the delivery mark.
+ * `after` absent ⇒ the executed outcome stands as is (same object).
+ */
+export declare function finalizeToolOutcome<C>(toolCall: C, executed: ExecutedToolCallOutcome, after: ((result: AgentToolResult<unknown>, isError: boolean) => Promise<AfterToolCallResult | undefined>) | undefined): Promise<ExecutedToolCallOutcome & {
+    toolCall: C;
+}>;
 export {};

package/dist/engine/loop/agent-loop.js

@@ -1489,20 +1489,18 @@ async function executePreparedWithDisclosure(currentContext, assistantMessage, p
     }
     return finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, signal);
 }
-async function finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, signal) {
+function finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, signal) {
+    return finalizeToolOutcome(prepared.toolCall, executed, config.afterToolCall === undefined
+        ? undefined
+        : (result, isError) => config.afterToolCall({ assistantMessage, toolCall: prepared.toolCall, args: prepared.args, result, isError, context: currentContext }, signal));
+}
+export async function finalizeToolOutcome(toolCall, executed, after) {
     let result = executed.result;
     let isError = executed.isError;
     const deliveryMark = readDeliveryFailureMark(executed.result.details);
-    if (config.afterToolCall) {
+    if (after) {
         try {
-            const afterResult = await config.afterToolCall({
-                assistantMessage,
-                toolCall: prepared.toolCall,
-                args: prepared.args,
-                result,
-                isError,
-                context: currentContext,
-            }, signal);
+            const afterResult = await after(result, isError);
             if (afterResult) {
                 result = {
                     content: afterResult.content ?? result.content,
@@ -1522,11 +1520,7 @@ async function finalizeExecutedToolCall(currentContext, assistantMessage, prepar
                 result = { ...result, details };
         }
     }
-    return {
-        toolCall: prepared.toolCall,
-        result,
-        isError,
-    };
+    return { toolCall, result, isError };
 }
 function safeAbortDetails(fn) {
     try {

package/dist/engine/loop/types.d.ts

@@ -772,6 +772,8 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      * repeat-safety effect below its fail-closed `write` default (only the caller's `toolAxes` does). Absent on non-MCP tools.
      */
     mcpReadOnlyHint?: true;
+    /** The server's own `_meta["anthropic/requiresUserInteraction"] === true` declaration: a call to this tool must be put to a person (read per call off the live mount array; MCP tools only). */
+    mcpRequiresUserInteraction?: true;
     /**
      * The tool's permission seat — see `ToolSpec.permissionSeat` (src/core/tool-spec.ts). `"passthrough"` = the tool states no
      * permission of its own; set by the MCP and A2A materializers on a remote peer's tool and carried by `defineTool` from a

package/dist/index.d.ts

@@ -72,7 +72,7 @@ export { WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS } from "./orchestration/workflow-siz
 export { ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./core/untrusted-text.js";
 export { materializeA2aTools, A2aRpcError, type MaterializedA2a, type A2aPeerStatus, type A2aRefreshResult, type A2aToolAxis } from "./core/a2a.js";
 export { PROTOCOL_TABLE, MCP_NAMESPACE, A2A_NAMESPACE, protocolOf, type ProtocolNamespace, type ProtocolId } from "./core/protocol-table.js";
-export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, stripRev, type SessionPolicyStore, type SessionPermissionRules, type StoredSessionRules, type SessionRulesRecord, type PutRulesOptions, } from "./core/session-policy-store.js";
+export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, stripRev, assertSessionRuleNamesCurrent, type SessionPolicyStoreOptions, type SessionRuleNameRefusal, type SessionPolicyStore, type SessionPermissionRules, type StoredSessionRules, type SessionRulesRecord, type PutRulesOptions, } from "./core/session-policy-store.js";
 export { SAFETY_MERGE_CONFORMANCE_CORPUS, type SafetyMergeVector } from "./core/safety-merge-corpus.js";
 export { SAFETY_AXIS_VOCABULARY } from "./core/safety-axis-vocab.js";
 export { createSessionRulePolicy } from "./core/runner/session-rule-policy.js";
@@ -120,7 +120,7 @@ export { InMemoryCheckpointStore, CheckpointError, mintCheckpointId, mintCheckpo
 export { EXECUTION_OUTCOME_RECORD_WORDS, EXECUTION_RECORD_LEAVES_ROW_UNRECORDED, type ExecutionOutcomeRecordWord, type ExecutionRecordRowFacts, type ExecutionVerdict, ExecutionOutcomeConflictError, checkpointExecutionRecorded, executionRecordDisposition, sameExecutionRecord, executionVerdict, } from "./core/checkpoint-execution-record.js";
 export { PAUSE_REGISTRY, type GateKind, type PendingKind, type ResumeGate, isGateKind, resumeGateMatches, type CheckpointPause, type CheckpointFields, pauseOf, checkpointFrom } from "./core/pause-registry.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 { FileUsageWindowStore, type FileUsageWindowStoreOptions } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";
 export { InMemoryFileHistoryStore, boundaryPublishVerdict } from "./core/file-history-store.js";
 export { captureFileBackupViaEnv, applyFileRestoreViaEnv } from "./core/file-history-store.js";
@@ -141,12 +141,13 @@ export { brainToRuntime } from "./core/runtime.js";
 export { createSensitivePathPolicy, RECOMMENDED_SENSITIVE_PATTERNS } from "./core/sensitive-path-policy.js";
 export { createFsWriteGatePolicy, WRITE_EXEMPT_DIR_COVERS_ROOT_CODE, type FsWriteGatePolicyOptions } from "./core/fs-write-gate-policy.js";
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
+export { judgeRuleToolName, RULE_TOOL_NAME_VERDICTS, type RuleToolNameVerdict } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, RESUPPLIED_FRAME_PREAMBLE, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, type TaskNotificationPayload, type TaskNotificationStatus, type ExternalNotificationInput, type SystemInjection, type SystemInjectionPriority, type NotificationInjectionOutcome, // the injector's outcome words (`parked_durably` = the session's durable box took the frame)
 NOTIFICATION_INJECTION_OUTCOMES, // …and their value half + guard, so a host wiring its own uplink validates a reported outcome without duplicating the vocabulary
 isNotificationInjectionOutcome, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, type SemaProvenance, HANDBACK_STATES, type HandbackState, COMPACTION_KINDS, type CompactionKind, handbackStateOf, terminalFrameFacets, } from "./core/task-notification.js";
 export { TOOL_FAMILIES, TOOL_MOUNT_TAGS, TOOL_APPROVAL_CARDS, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, TOOL_PATH_ABSENCES, TOOL_WIRE_NAME_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_CARD_ID_MAX_CHARS, TOOL_KEY_MAX_CHARS, TOOL_KEYS_MAX, RENDER_HINT_MAX_CHARS, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_LIST, type ToolFamily, type ToolMountTag, type ToolApprovalCard, type ToolPathAccess, type ToolPathBase, type ToolPathAbsence, type ToolPathTarget, type ToolCallPathTarget, type ToolRosterPathTarget, pathTargetSlotOnly, type ToolRuleFace, type ToolRenderHints, type ToolFaceDeclaration, type ToolCatalogEntry, } from "./core/tool-face.js";
-export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, BARE_REQUEST_CODE, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, type ToolCallLike, pathConfinableWriteToolNames, skillScopeWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
+export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, BARE_REQUEST_CODE, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, type ToolCallLike, pathConfinableWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
 export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, type RosterSource, type ToolIdentity, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, rosterToolName, ruleNamesOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, type RosterBoundMembers, type RosterBoundCode, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
 export { type ToolCallFace } from "./core/tool-policy.js";
 export { effectivePathTargetOf, pathTargetBaseOf, type ToolPathBases, type PathTargetReading } from "./core/effective-path-target.js";
@@ -196,6 +197,8 @@ export { type ReadRootGrantScreen } from "./core/read-root-grant-screen.js";
 export { type AskOrigin, ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate, screenAskClassMembers } from "./core/ask-origin.js";
 export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, RELEASABLE_ASK_CLASSES, MODE_RELEASE_REASONS, type ModeReleaseReason, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";
 export { modePolicyOf, type ModePolicy, PERMISSION_MODE_FOLD_REASONS, type PermissionModeFoldReason, type PermissionModeReceipt, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
+export type { PermissionSeatInputs, PermissionSeatReading } from "./core/mode-policy.js";
+export type { SkillGateSeats, SkillGrantHit, SkillGrantLane, SkillGrantRecord } from "./core/skill-grant.js";
 export { readDenyClassifierRules, renderClassifierDenyRules, type DerivedDenyRule } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource, type AutoModeDenySource } from "./core/runtime-caps.js";
 export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_PARTIES, type SettlementParty, isSettlementParty, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, type ModeRelease, type ModeRefusal, screenGateOutcome } from "./core/gate-outcome.js";
@@ -308,6 +311,8 @@ export { BACKGROUND_AGENT_CONTRACT_SCOPE, backgroundAgentStoreContract, backgrou
 export { PEER_DIRECTORY_CONTRACT_SCOPE, peerDirectoryContract, type PeerDirectoryContractHooks } from "./core/store-contracts/peer-directory-contract.js";
 export { type BackgroundAgentStore, type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentUsage, canAccessAgentRecord, STALE_RUNNING_REAP_ATTRIBUTION, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, queryBackgroundAgents, type BackgroundAgentQuery, } from "./core/background-agent-store.js";
 export { serveDurableAgentRowLane, buildAgentPollDetails, type AgentPollDetailsInput, } from "./core/task-registry-agent.js";
+export { readAgentState, agentStateSourceOfRecord, agentStateSummary, type AgentState, type AgentApproval, type AgentApprovalState, type AgentStateRow, type AgentStateSource, } from "./core/agent-state.js";
+export type { TranscriptStep } from "./agents/subagent-steps.js";
 export type { UnifiedTaskResult } from "./core/task-registry-shared.js";
 export { TASK_OUTPUT_REPLAY_KINDS, type TaskOutputReplay } from "./core/task-registry-shared.js";
 export { REMOVAL_LIVENESS_WORDS, type RemovalLiveness, RULE_WRITE_COMMITTED_WORDS, type RuleWriteCommitted } from "./core/permission-rule-store.js";
@@ -365,7 +370,7 @@ export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } f
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, ShellGateDoctrine, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ReadRootGrantCandidate, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, TrackFileEditHook, TrackEditRequest, TrackEditResult, FileEditedHook, FileEditedNotice, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, TerminalCause, PausedCause, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, ShellGateDoctrine, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolInputVerdict, ToolInputValidationContext, ReversibilityVerdict, ReadRootGrantCandidate, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";

package/dist/index.js

@@ -58,7 +58,7 @@ export { WORKFLOW_SIZE_GUIDELINE_AGENT_CAPS } from "./orchestration/workflow-siz
 export { ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./core/untrusted-text.js";
 export { materializeA2aTools, A2aRpcError } from "./core/a2a.js";
 export { PROTOCOL_TABLE, MCP_NAMESPACE, A2A_NAMESPACE, protocolOf } from "./core/protocol-table.js";
-export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, stripRev, } from "./core/session-policy-store.js";
+export { InMemorySessionPolicyStore, SessionPolicyError, loosenReasons, normalizeRules, stripRev, assertSessionRuleNamesCurrent, } from "./core/session-policy-store.js";
 export { SAFETY_MERGE_CONFORMANCE_CORPUS } from "./core/safety-merge-corpus.js";
 export { SAFETY_AXIS_VOCABULARY } from "./core/safety-axis-vocab.js";
 export { createSessionRulePolicy } from "./core/runner/session-rule-policy.js";
@@ -115,10 +115,11 @@ export { brainToRuntime } from "./core/runtime.js";
 export { createSensitivePathPolicy, RECOMMENDED_SENSITIVE_PATTERNS } from "./core/sensitive-path-policy.js";
 export { createFsWriteGatePolicy, WRITE_EXEMPT_DIR_COVERS_ROOT_CODE } from "./core/fs-write-gate-policy.js";
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
+export { judgeRuleToolName, RULE_TOOL_NAME_VERDICTS } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, RESUPPLIED_FRAME_PREAMBLE, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, NOTIFICATION_INJECTION_OUTCOMES, isNotificationInjectionOutcome, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, HANDBACK_STATES, COMPACTION_KINDS, handbackStateOf, terminalFrameFacets, } from "./core/task-notification.js";
 export { TOOL_FAMILIES, TOOL_MOUNT_TAGS, TOOL_APPROVAL_CARDS, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, TOOL_PATH_ABSENCES, TOOL_WIRE_NAME_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_CARD_ID_MAX_CHARS, TOOL_KEY_MAX_CHARS, TOOL_KEYS_MAX, RENDER_HINT_MAX_CHARS, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_LIST, pathTargetSlotOnly, } from "./core/tool-face.js";
-export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, BARE_REQUEST_CODE, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, pathConfinableWriteToolNames, skillScopeWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
+export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, BARE_REQUEST_CODE, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, pathConfinableWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
 export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, rosterToolName, ruleNamesOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
 export {} from "./core/tool-policy.js";
 export { effectivePathTargetOf, pathTargetBaseOf } from "./core/effective-path-target.js";
@@ -255,6 +256,7 @@ export { BACKGROUND_AGENT_CONTRACT_SCOPE, backgroundAgentStoreContract, backgrou
 export { PEER_DIRECTORY_CONTRACT_SCOPE, peerDirectoryContract } from "./core/store-contracts/peer-directory-contract.js";
 export { canAccessAgentRecord, STALE_RUNNING_REAP_ATTRIBUTION, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, queryBackgroundAgents, } from "./core/background-agent-store.js";
 export { serveDurableAgentRowLane, buildAgentPollDetails, } from "./core/task-registry-agent.js";
+export { readAgentState, agentStateSourceOfRecord, agentStateSummary, } from "./core/agent-state.js";
 export { TASK_OUTPUT_REPLAY_KINDS } from "./core/task-registry-shared.js";
 export { REMOVAL_LIVENESS_WORDS, RULE_WRITE_COMMITTED_WORDS } from "./core/permission-rule-store.js";
 export { normalizeReadRootCandidate, READ_ROOT_CANDIDATE_DIR_MAX } from "./core/read-root-candidate.js";

package/dist/stores/file/adoption/adopt.js

@@ -3,7 +3,8 @@ import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { adoptFilePermissionRuleStore } from "../permission-rule-adopt.js";
 import { BootLock, atomicWriteFile, ensureDir, sanitizeScope } from "../fs-atomic.js";
-import { SESSION_POLICY_MARK_SUFFIX, judgeSessionPolicyRowObject, readSessionPolicyMark } from "../session-policy-store.js";
+import { SESSION_POLICY_MARK_SUFFIX, attributeSessionPolicyRow, judgeSessionPolicyRowObject, readSessionPolicyMark } from "../session-policy-store.js";
+import { SessionPolicyError } from "../../../core/session-policy-store.js";
 import { thrownText } from "../../../core/thrown-value.js";
 import { AdoptionError, NOT_MIGRATED_BY_DESIGN, readRootAdoptionFile, writeRootAdoptionFile, } from "./marker.js";
 const CONFIG_ACCOUNT_FILE = "adoption-configs.json";
@@ -193,12 +194,8 @@ function rewriteSessionPolicyRows(root, fromPrincipal, toPrincipal) {
     const tmpDir = join(dir, "tmp");
     let rows = 0;
     for (const file of files) {
-        if (!file.endsWith(".json"))
+        if (!file.endsWith(".json") || file.endsWith(SESSION_POLICY_MARK_SUFFIX))
             continue;
-        if (file.endsWith(SESSION_POLICY_MARK_SUFFIX)) {
-            carrySessionPolicyMark(dir, tmpDir, file, fromPrincipal, toPrincipal);
-            continue;
-        }
         const source = join(dir, file);
         let raw;
         try {
@@ -210,15 +207,14 @@ function rewriteSessionPolicyRows(root, fromPrincipal, toPrincipal) {
             throw err;
         }
         const judged = judgeSessionPolicyRowObject(raw);
-        if ("corrupt" in judged)
+        const row = "row" in judged ? judged.row : undefined;
+        const { owner } = attributeSessionPolicyRow(dir, file, row);
+        if (owner === undefined)
             continue;
-        const row = judged.row;
-        if (row.__principal !== fromPrincipal)
+        if (owner.principal !== fromPrincipal)
             continue;
-        if (typeof row.__sid !== "string")
-            continue;
-        const stem = sanitizeScope(JSON.stringify([row.__sid, toPrincipal]));
-        const rewritten = JSON.stringify({ ...row, __principal: toPrincipal });
+        const stem = sanitizeScope(JSON.stringify([owner.sessionId, toPrincipal]));
+        const rewritten = row !== undefined ? JSON.stringify({ ...row, __principal: toPrincipal }) : raw;
         const target = join(dir, `${stem}.json`);
         if (existsSync(target)) {
             if (readFileSync(target, "utf8") === rewritten) {
@@ -226,18 +222,22 @@ function rewriteSessionPolicyRows(root, fromPrincipal, toPrincipal) {
                 rows += 1;
                 continue;
             }
-            throw new AdoptionError("adoption_row_collision", `a session-policy row for session "${row.__sid}" already exists under "${toPrincipal}" with different content — ` +
+            throw new AdoptionError("adoption_row_collision", `a session-policy row for session "${owner.sessionId}" already exists under "${toPrincipal}" with different content — ` +
                 `merging two existing rows is a sync join, not a rewrite; the adoption marker is left in place for inspection`);
         }
         atomicWriteFile(tmpDir, target, rewritten);
         removeIfPresent(source);
         rows += 1;
     }
+    for (const file of files) {
+        if (file.endsWith(SESSION_POLICY_MARK_SUFFIX))
+            carrySessionPolicyMark(dir, tmpDir, file, fromPrincipal, toPrincipal);
+    }
     return rows;
 }
 function carrySessionPolicyMark(dir, tmpDir, file, fromPrincipal, toPrincipal) {
     const source = join(dir, file);
-    const mark = readSessionPolicyMark(source);
+    const mark = readMarkOrRefuse(source);
     if (mark === null)
         return;
     if (mark.__principal !== fromPrincipal)
@@ -245,12 +245,19 @@ function carrySessionPolicyMark(dir, tmpDir, file, fromPrincipal, toPrincipal) {
     if (typeof mark.__sid !== "string")
         return;
     const target = join(dir, `${sanitizeScope(JSON.stringify([mark.__sid, toPrincipal]))}${SESSION_POLICY_MARK_SUFFIX}`);
-    const there = readSessionPolicyMark(target);
+    const there = readMarkOrRefuse(target);
     const merged = there === null ? mark.__hwm : Math.max(mark.__hwm, there.__hwm);
     const mergedGen = Math.max(mark.__gen ?? 0, there?.__gen ?? 0);
     atomicWriteFile(tmpDir, target, JSON.stringify({ ...mark, __principal: toPrincipal, __hwm: merged, __gen: mergedGen }));
     removeIfPresent(source);
 }
+function readMarkOrRefuse(path) {
+    const read = readSessionPolicyMark(path);
+    if ("corrupt" in read) {
+        throw new SessionPolicyError("corrupt", `session rules high-water mark ${read.corrupt.reason}: ${path} — refusing rather than restart this key's rev from zero. Deleting that file is the repair, and it gives up the number it was holding.`);
+    }
+    return read.mark;
+}
 function removeIfPresent(path) {
     try {
         unlinkSync(path);

package/dist/stores/file/index.d.ts

@@ -4,6 +4,7 @@ import type { ToolResultStore } from "../../core/tool-result-store.js";
 import { type EvictPolicy } from "../../core/session-store.js";
 import type { SessionStore } from "../../core/session.js";
 import { type FileCheckpointStoreOptions } from "./checkpoint-store.js";
+import { type FileSessionPolicyStoreOptions } from "./session-policy-store.js";
 import { type FileFileHistoryStoreOptions } from "./file-history-store.js";
 import type { CorruptReadInfo } from "./corrupt-read-sink.js";
 import type { FileHistoryStore } from "../../core/file-history-store.js";
@@ -21,7 +22,7 @@ export { FileToolResultStore } from "./tool-result-store.js";
 export { FileSessionPolicyStore, type FileSessionPolicyStoreOptions, type SessionPolicyCorruptReadInfo } from "./session-policy-store.js";
 export { FileFileHistoryStore, type FileFileHistoryStoreOptions } from "./file-history-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
-export { FileUsageWindowStore } from "./usage-window-store.js";
+export { FileUsageWindowStore, type FileUsageWindowStoreOptions } from "./usage-window-store.js";
 export { FileStrategyStore, type FileStrategyStoreOptions } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { FileStoreLockError, type FileStoreLockErrorCode } from "./fs-atomic.js";
@@ -74,6 +75,10 @@ export interface FileStorageBackendOptions {
      * FileStorageBackendOptions.onCorruptRead} above, because one failure grammar takes one sink.
      */
     fileHistory?: Omit<FileFileHistoryStoreOptions, "onCorruptRead">;
+    /** The session-rules store's options — today the names this deployment mounts its own tools under
+     *  (`mountedToolNames`, the roster its write and loosening checks judge rule names against). The corrupt-read sink is
+     *  wired from {@link FileStorageBackendOptions.onCorruptRead}, as for {@link fileHistory}. */
+    sessionPolicy?: Omit<FileSessionPolicyStoreOptions, "onCorruptRead">;
     /** design/81 Slice 5 — an optional {@link import("../../core/memory.js").Embedder}. Injected ⇒ the memory
      *  store does portable (in-process) vector recall over a rebuildable sidecar index (`vectorMode:"portable"`);
      *  absent ⇒ the lexical floor, byte-identical to before. Config-driven (the deployment injects it); OFF by
@@ -93,7 +98,8 @@ export interface FileStorageBackendOptions {
      * Reach TODAY: {@link FileStorageBackend.sessionPolicyStore} (an absent file ⇒ no rules; a present but
      * unreadable / unparseable / malformed file ⇒ refused, the disclosure delivered alongside the refusal)
      * and {@link FileStorageBackend.sessionStore}'s repo (a session listing that silently omits what it
-     * could not read). The aggregated roster and mailbox stores receive the same sink. A store that
+     * could not read). The aggregated roster, mailbox and usage-window stores receive the same sink (the
+     * usage-window ledger refuses a damaged record and discloses its location here). A store that
      * grows the seat later is wired here in the same constructor.
      *
      * The payload is the UNION shape ({@link FileStorageCorruptReadInfo}): `path` + `reason` always,

package/dist/stores/file/index.js

@@ -72,11 +72,11 @@ export class FileStorageBackend {
             built.push(() => this.fileMemory.close());
             this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
             this.toolResultStore = new FileToolResultStore(this.root, corruptRead);
-            this.sessionPolicyStore = new FileSessionPolicyStore(this.root, corruptRead);
+            this.sessionPolicyStore = new FileSessionPolicyStore(this.root, { ...opts.sessionPolicy, ...corruptRead });
             this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root, true, corruptRead);
             built.push(() => this.fileWorkflowJournal.dispose());
             this.workflowJournalStore = this.fileWorkflowJournal;
-            this.usageWindowStore = new FileUsageWindowStore(this.root);
+            this.usageWindowStore = new FileUsageWindowStore(this.root, corruptRead);
             this.fileAgentRows = new FileBackgroundAgentStore(this.root, corruptRead ?? {});
             built.push(() => this.fileAgentRows.close());
             this.backgroundAgentStore = this.fileAgentRows;

package/dist/stores/file/mailbox-store.js

@@ -145,7 +145,7 @@ export async function acquireMailboxBoxLock(lockPath, waitMs) {
                     return;
                 }
                 if (now === undefined || now === "unreadable" || now.nonce !== mine.nonce) {
-                    const e = new Error(`FileMailboxStore: the box lock ${lockPath} changed hands while this process held it (a stale reclaim overlapped) — the operation just performed may have raced another process; do not trust it`);
+                    const e = new Error(`FileMailboxStore: the box lock changed hands while this process held it (a stale reclaim overlapped) — the operation just performed may have raced another process; do not trust it. The lock file's location is on this error's \`lockPath\`, not in this message.`);
                     e.code = MAILBOX_BOX_LOCK_COMPROMISED_CODE;
                     e.lockPath = lockPath;
                     throw e;
@@ -195,7 +195,7 @@ export async function acquireMailboxBoxLock(lockPath, waitMs) {
             sweepLockResidue(join(lockPath, ".."), lockPath.slice(join(lockPath, "..").length + 1));
         }
         if (Date.now() >= deadline) {
-            const e = new Error(`FileMailboxStore: the box lock ${lockPath} was not obtainable within ${waitMs}ms (${holderNote}) — refusing to touch the box without it`);
+            const e = new Error(`FileMailboxStore: the box lock was not obtainable within ${waitMs}ms (${holderNote}) — refusing to touch the box without it. The lock file's location is on this error's \`lockPath\`, not in this message.`);
             e.code = MAILBOX_BOX_LOCK_TIMEOUT_CODE;
             e.lockPath = lockPath;
             if (owner !== "unreadable" && owner !== "unobservable")

package/dist/stores/file/permission-rule-adopt.js

@@ -4,6 +4,7 @@ import { writerOf } from "../../core/permission-rule-store.js";
 import { createPermissionRuleStoreProvider } from "../../core/permission-rule-provider.js";
 import { syncPermissionRules } from "../../core/permission-rule-sync.js";
 import { thrownText } from "../../core/thrown-value.js";
+import { FileStoreLockError } from "./fs-atomic.js";
 import { FileDurableRulePartitionProvider, LOCAL_OWNER_FILE, principalRuleFileName, readRuleAdoptionFile, writeRuleAdoptionFile, } from "./permission-rule-store.js";
 export async function adoptFilePermissionRuleStore(opts) {
     if (typeof opts.toPrincipal !== "string" || opts.toPrincipal === "") {
@@ -30,7 +31,15 @@ export async function adoptFilePermissionRuleStore(opts) {
     }
     const provider = new FileDurableRulePartitionProvider(opts.dir, opts.onError);
     try {
-        const lockProbe = writerOf(provider.forPrincipal(opts.toPrincipal));
+        let lockProbe;
+        try {
+            lockProbe = writerOf(provider.forPrincipal(opts.toPrincipal));
+        }
+        catch (err) {
+            if (!(err instanceof FileStoreLockError))
+                throw err;
+            throw new FileStoreLockError(err.code, `the permission-rule writer lock ${err.lockPath} refuses the adoption (${err.code}${err.ownerPid !== undefined ? `, held by pid ${err.ownerPid}` : ""}) — stop the live writer, then run the adoption again`, err.lockPath, err.ownerPid);
+        }
         if (lockProbe === undefined)
             throw new Error("the target store refused a write face");
         let phase = existing !== undefined && "marker" in existing ? existing.marker.phase : 2;

package/dist/stores/file/permission-rule-store.d.ts

@@ -108,9 +108,8 @@ export type RuleAdoptionFile = {
         atMs: number;
     };
 };
-/** Read the adoption marker, `undefined` when none. A corrupt marker THROWS: after phase 4 the marker
- *  IS the owner-resolution truth, and guessing on a corrupt truth would either resurrect the retired
- *  bucket (write fork) or invent an adoption that never happened. */
+/** The ADOPTION voice of {@link judgeRuleAdoptionFile}: the adoption helper's reader is the operator who repairs the
+ *  marker, so it names the directory. A corrupt marker THROWS. */
 export declare function readRuleAdoptionFile(dir: string): RuleAdoptionFile | undefined;
 /** Atomically publish the adoption marker (same write-temp → fsync → rename discipline as the store). */
 export declare function writeRuleAdoptionFile(dir: string, content: RuleAdoptionFile): void;
@@ -123,7 +122,8 @@ declare class FileDurableRulePartition implements WritableDurableRulePartition {
     readonly durability: StoreDurability;
     readonly fidelity: StoreFidelity;
     constructor(dir: string, file: string, acquireWriteLock: () => void, onError?: ((message: string) => void) | undefined);
-    /** Read and validate. Any refusal answers with an empty set AND says so — never a silent empty store. */
+    /** Read and validate. Any refusal answers with an empty set AND says so — never a silent empty store. The answer's
+     *  sentence names no location ({@link refusalText}); the disclosure that accompanies it does. */
     private read;
     private disclose;
     /**
@@ -204,6 +204,8 @@ export declare class FileDurableRulePartitionProvider implements DurableRulePart
     });
     /** The org partition's durable home in this directory (design/182 §7.4 contract; `org.json`). Shares
      *  this provider's writer lock — an install is a write. */
+    /** {@link judgeRuleAdoptionFile} at request time (owner resolution runs on every read), in {@link refusalText}'s voice. */
+    private adoptionMarker;
     orgStatePersistence(): OrgRuleStatePersistence;
     private fileOrgPersistence;
     /** Take the writer lock, once, on first use of a write face. Reading never calls this. */