@sema-agent/core 7.4.0 → 7.5.1

package/dist/core/runner/prepare-listings.js

@@ -0,0 +1,76 @@
+import { formatLocalDate } from "../../prompts/default.js";
+import { SKILL_TOOL_NAME } from "./synthetic-tools.js";
+import { renderAgentListingDelta } from "./turn-attachments.js";
+export function prepareListings(input) {
+    const { spec, tools, onceLedger, sessionId, toolFaceSnapshot, activeTools, resume, skillsListing, listingRideRef, renderWithDate, envFacts, tzValid, userTz } = input;
+    if (spec.agents !== undefined && spec.agents.length > 0) {
+        const known = new Set(tools.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+        for (const def of spec.agents) {
+            const unknownAllow = (def.allowTools ?? []).filter((n) => n !== "*" && !known.has(n));
+            if (unknownAllow.length > 0) {
+                try {
+                    onceLedger.onError(new Error(`TaskSpec.agents: agent "${def.name}" allows tool(s) ${unknownAllow.join(", ")} not present in this task's assembled roster — likely a typo (the entry would be item-filtered at spawn; the agent stays usable). Advisory only: the delegation pool can differ from this roster, so a tool mounted only on the delegation tool or produced by per-spawn extraTools makes this spurious.`), { phase: "config", sessionId });
+                }
+                catch {
+                }
+            }
+            for (const n of def.denyTools ?? []) {
+                if (n === "*")
+                    continue;
+                if (!known.has(n)) {
+                    const e = new Error(`TaskSpec.agents: agent "${def.name}" declares tool "${n}" in its denied tools, but no such tool exists in this deployment — fix the agent's tools list or mount the tool.`);
+                    e.code = "config.agent.unknown_tool";
+                    throw e;
+                }
+            }
+        }
+    }
+    const rosterBearingSpec = (spec.tools ?? []).find((t) => t.agentListing !== undefined && t.agentListing.length > 0);
+    const rosterFaceDeferred = rosterBearingSpec !== undefined &&
+        !(toolFaceSnapshot.exclude?.includes(rosterBearingSpec.name) ?? false) &&
+        (toolFaceSnapshot.defer?.includes(rosterBearingSpec.name) ?? false) &&
+        !activeTools.has(rosterBearingSpec.name);
+    const agentListingSpec = rosterBearingSpec !== undefined &&
+        !rosterFaceDeferred &&
+        !(toolFaceSnapshot.exclude?.includes(rosterBearingSpec.name) ?? false)
+        ? rosterBearingSpec
+        : undefined;
+    const agentListing = agentListingSpec
+        ? {
+            entries: agentListingSpec.agentListing,
+            toolName: agentListingSpec.name,
+            seedAnnounced: resume !== undefined || spec.sessionId !== undefined,
+            ...(agentListingSpec.agentModels !== undefined ? { models: agentListingSpec.agentModels } : {}),
+        }
+        :
+            !rosterFaceDeferred && ((resume?.seed.announcedListings?.agents?.length ?? 0) > 0 || spec.sessionId !== undefined)
+                ?
+                    {
+                        entries: [],
+                        toolName: (spec.tools ?? []).find((t) => t.agentListing !== undefined)?.name ?? "Agent",
+                        seedAnnounced: true,
+                    }
+                : undefined;
+    if (spec.attachments?.agentListing === false && agentListing !== undefined && agentListing.entries.length > 0) {
+        onceLedger.onError(new Error(`attachments.agentListing is explicitly false but the "${agentListing.toolName}" delegation tool mounts a ${agentListing.entries.length}-type roster — the model will never see the agent-type listing its tool description points to.`), { phase: "config", sessionId });
+    }
+    if (spec.attachments?.skillsListing === false && skillsListing !== undefined && skillsListing.entries.length > 0) {
+        onceLedger.onError(new Error(`attachments.skillsListing is explicitly false but ${skillsListing.entries.length} skill(s) are mounted — the model will never see the skills listing the ${SKILL_TOOL_NAME} tool description points to.`), { phase: "config", sessionId });
+    }
+    const announcedListingsRef = onceLedger.arms();
+    if (rosterFaceDeferred && rosterBearingSpec !== undefined) {
+        const rideEntries = rosterBearingSpec.agentListing;
+        const rideModels = rosterBearingSpec.agentModels;
+        listingRideRef.current = (newly) => {
+            if (!newly.includes(rosterBearingSpec.name))
+                return undefined;
+            if ((announcedListingsRef.agents?.length ?? 0) > 0)
+                return undefined;
+            return renderAgentListingDelta({ announcedAgentTypes: undefined }, rideEntries, rosterBearingSpec.name, rideModels);
+        };
+    }
+    const dateChange = renderWithDate
+        ? { legDate: envFacts.date, today: () => formatLocalDate(new Date(), tzValid ? userTz : undefined) }
+        : undefined;
+    return { agentListing, announcedListingsRef, dateChange };
+}

package/dist/core/runner/prepare-lsp.d.ts

@@ -0,0 +1,55 @@
+/**
+ * design/390 §1.2 M8 — prepareTask's LSP phase, verbatim from the driver: the manager fold (spec > deps), the
+ * LSP tool mount over the per-task env with its git-ignore filter, the diagnostics lane behind its four
+ * preconditions (a manager whose sessions feed a registry, write-capable hands, not opted out), the run-scoped
+ * registry key, and the edit nudge (raw path → the SAME resolution the tool leg uses → registry reset +
+ * session didChange). No manager ⇒ nothing mounts and both lane seats are undefined. The interface is the
+ * dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the
+ * fork-governance note before it and the memory trio's occupancy read after it (design/390 §1.5 S1: a stretch
+ * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
+ * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ */
+import type { AgentTool, ExecutionEnv } from "../../internal/harness.js";
+import type { LspDiagnosticsRegistry } from "../lsp-diagnostics.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Prepared } from "./contracts.js";
+export interface PrepareLspInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `lspManager` (the per-task manager, outranks the deployment's),
+     *  `lspDiagnostics` (the lane's opt-out), `handsReadOnly` (a read-only run has no lane). Never mutated. */
+    spec: Pick<TaskSpec, "lspManager" | "lspDiagnostics" | "handsReadOnly">;
+    /** borrowed-readonly — the deployment's manager seat (read only when the spec carries none). */
+    deps: Pick<RunnerDeps, "lspManager">;
+    /** borrowed-readonly — the run's resolved env: the tool's in-env server and git-ignore filter, and the
+     *  session lookup the nudge performs. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the SETTLED task root: the tool's git-ignore root, and the nudge's resolution base when
+     *  no cwd is tracked. */
+    taskRootFinal: string;
+    /** borrowed-readonly — whether a real fs env is present (the lane's hands precondition). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the acquired session id: the run's key into the deployment-shared registry. */
+    sessionId: string;
+    /** borrowed-readonly — the tracked-cwd cell the hands band writes; the nudge READS `current` per call as its
+     *  resolution base (identity is the contract — the band's `cd` handling writes this exact cell). */
+    handsCwdRef: Prepared["cwdRef"];
+    /** borrowed-mutable — the run's shared roster (identity is the contract). Writer here: ONE push (the LSP tool)
+     *  when a manager exists. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the env-hand membership set the read-posture observer projects; writer here: `add("LSP")`
+     *  on the mount. */
+    envHandToolNames: Set<string>;
+}
+export interface PrepareLspResult {
+    /** borrowed-readonly — the manager's diagnostics registry when the lane is live, else undefined (the
+     *  registry is a DEPLOYMENT object shared by every task; this run reads and resets it under its own key). */
+    lspDiagnostics: LspDiagnosticsRegistry | undefined;
+    /** owned — the edit nudge (raw path in), or undefined when the lane is not live. */
+    nudgeLspOnEdit: ((rawPath: string) => void) | undefined;
+    /** borrowed-readonly — the run's registry key (= the session id): a session hosts one run at a time and the
+     *  run loop releases the key at the terminal. */
+    lspRunIdent: string;
+}
+/** The M8 phase body — prepareTask's LSP stretch, verbatim (see the module header). */
+export declare function prepareLsp(input: PrepareLspInput): PrepareLspResult;

package/dist/core/runner/prepare-lsp.js

@@ -0,0 +1,27 @@
+import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
+import { pathToUri } from "../lsp-protocol.js";
+export function prepareLsp(input) {
+    const { spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, tools, envHandToolNames } = input;
+    const lspManager = spec.lspManager ?? deps.lspManager;
+    if (lspManager) {
+        const lspRoot = taskRootFinal;
+        tools.push(createLspTool(lspManager, { isPathIgnored: gitCheckIgnoreFilter(executionEnv, lspRoot), env: executionEnv }));
+        envHandToolNames.add("LSP");
+    }
+    const lspDiagnostics = spec.lspDiagnostics !== false && lspManager?.diagnostics !== undefined && handsEnabled && spec.handsReadOnly !== true
+        ? lspManager.diagnostics
+        : undefined;
+    const lspRunIdent = sessionId;
+    const nudgeLspOnEdit = lspDiagnostics
+        ? (rawPath) => {
+            const baseDir = handsCwdRef?.current ?? taskRootFinal;
+            const filePath = resolveLspPath(rawPath, baseDir);
+            lspDiagnostics.fileEdited(lspRunIdent, pathToUri(filePath));
+            void lspManager
+                .sessionFor(filePath, undefined, executionEnv)
+                .then((session) => session?.notifyFileChanged?.(filePath))
+                .catch(() => undefined);
+        }
+        : undefined;
+    return { lspDiagnostics, nudgeLspOnEdit, lspRunIdent };
+}

package/dist/core/runner/prepare-memory.d.ts

@@ -1,6 +1,6 @@
 import type { BeforeWriteHook, EffectiveMemoryScopes, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
 import { type CaptureEntitlementInput, type MemoryCapturePosture } from "./memory-capture-optout.js";
-import type { Prepared } from "./prepare-task.js";
+import type { Prepared } from "./contracts.js";
 export interface PrepareMemoryInput {
     spec: TaskSpec;
     deps: RunnerDeps;

package/dist/core/runner/prepare-offload-wrappers.d.ts

@@ -0,0 +1,62 @@
+/**
+ * design/390 §1.2 M0 (the offload half of the prelude) — prepareTask's nested-usage accumulator, the
+ * large-tool-result offload store resolution and the THREE offload wrappers every later mount site
+ * applies (caller tools, first-party hand tools, remote MCP/A2A peers), verbatim from the driver.
+ *
+ * SYNCHRONOUS by construction: the segment held no await in the driver, and a phase that yields where
+ * the driver did not would open a microtask window between two steps that used to be adjacent (the
+ * design/238 T1 posture). Nothing here touches the store — the wrappers close over it and only the
+ * wrapped tools' `execute` reach it, at run time.
+ *
+ * What stays in the driver: the trust-axis choice of `offloadScope` (`spec.principal ?? "default"`)
+ * and its disclosure, and the reserved-name door that FOLLOWS these wrappers (it awaits a bounded
+ * session forget, so it belongs with the driver's other refusal legs).
+ */
+import { type ToolResultStore } from "../tool-result-store.js";
+import type { AgentTool } from "../../internal/harness.js";
+import type { NestedUsage, NestedUsageAccum, RunnerDeps, TaskSpec } from "../types.js";
+import type { PrepareResume } from "./contracts.js";
+export interface PrepareOffloadWrappersInput {
+    /** borrowed-readonly — the REBOUND spec (the config-doors result); read for the per-task coarse
+     *  offload knob only. */
+    spec: Pick<TaskSpec, "toolResultThresholdChars">;
+    /** borrowed-readonly — the deployment's coarse offload knob and its injected store (used AS-IS when
+     *  present; a Runner-shared instance is viewed per task, see the body). */
+    deps: Pick<RunnerDeps, "toolResultThresholdChars" | "toolResultStore">;
+    /** borrowed-readonly — the resume leg, read for the checkpoint seed's nested-usage snapshot so
+     *  delegated cost spent before a suspend is not lost; `undefined` on a fresh run. */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+    /** borrowed-readonly — the run's TRUST identity (`spec.principal ?? "default"`, minted by the
+     *  driver): the namespace a Runner-shared store is scoped under. Never the registry domain. */
+    offloadScope: string;
+    /** borrowed-readonly — the acquired session id, the offload wrapper's ref-minting coordinate. */
+    sessionId: string;
+}
+export interface PrepareOffloadWrappersResult {
+    /** borrowed-mutable — the run's nested sub-run usage accumulator (`Prepared.nestedStats`).
+     *  Mutation owners after this call: `reportUsage` below (the only writer — every delegation tool
+     *  reports through it via the tool ctx); the driver reads it into `Prepared`. */
+    nestedStats: NestedUsageAccum;
+    /** borrowed-readonly — the one writer of `nestedStats`; the driver threads it onto the tool ctx. */
+    reportUsage: (u: NestedUsage) => void;
+    /** borrowed-readonly — the store the wrappers close over, or `undefined` when offload is disabled
+     *  (threshold 0 / non-finite). The driver reads it for the reserved-name door, the ReadToolResult
+     *  mount, the durable-suspend gate and the compaction lane. Not a resource: nothing to release. */
+    offloadStore: ToolResultStore | undefined;
+    /** borrowed-mutable — the LIVE "currently callable tools" accessor cell the offload preview's
+     *  pageback hint reads. Mutation owners after this call: the deferred-disclosure branch of the
+     *  driver sets `.current` once the deferred/active sets exist; nothing else writes it. */
+    offloadReachableToolsRef: {
+        current?: () => ReadonlySet<string>;
+    };
+    /** borrowed-readonly — wrap a CALLER tool (per-tool `offload` / `offloadThresholdChars` honored). */
+    maybeOffload: (tool: AgentTool, perTool?: {
+        offload?: boolean;
+        offloadThresholdChars?: number;
+    }) => AgentTool;
+    /** borrowed-readonly — wrap a FIRST-PARTY mount (the per-tool persistence table; Read/Write exempt). */
+    firstPartyOffload: (tool: AgentTool) => AgentTool;
+    /** borrowed-readonly — wrap a REMOTE-PEER mount (MCP `_meta` size declaration, else 50K). */
+    remoteToolOffload: (tool: AgentTool) => AgentTool;
+}
+export declare function prepareOffloadWrappers(input: PrepareOffloadWrappersInput): PrepareOffloadWrappersResult;

package/dist/core/runner/prepare-offload-wrappers.js

@@ -0,0 +1,45 @@
+import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, withToolResultOffload, } from "../tool-result-store.js";
+export function prepareOffloadWrappers(input) {
+    const { spec, deps, resume, offloadScope, sessionId } = input;
+    const nestedStats = { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0, anyUnpriced: false };
+    if (resume) {
+        nestedStats.tokens = resume.seed.nestedStats.tokens;
+        nestedStats.turns = resume.seed.nestedStats.turns;
+        nestedStats.tasks = resume.seed.nestedStats.tasks;
+        nestedStats.costMicroUsd = resume.seed.nestedStats.costMicroUsd;
+        nestedStats.anyUnpriced = resume.seed.nestedStats.anyUnpriced ?? true;
+    }
+    const reportUsage = (u) => {
+        nestedStats.tokens += u.tokens;
+        nestedStats.turns += u.turns;
+        nestedStats.tasks += u.tasks;
+        nestedStats.costMicroUsd += u.costMicroUsd ?? 0;
+        if (u.costMicroUsd === undefined)
+            nestedStats.anyUnpriced = true;
+    };
+    const explicitGlobalThreshold = spec.toolResultThresholdChars ?? deps.toolResultThresholdChars;
+    const offloadThreshold = explicitGlobalThreshold ?? DEFAULT_TOOL_RESULT_THRESHOLD_CHARS;
+    const offloadEnabled = Number.isFinite(offloadThreshold) && offloadThreshold > 0;
+    const rawOffloadStore = offloadEnabled ? (deps.toolResultStore ?? new InMemoryToolResultStore()) : undefined;
+    const offloadStore = rawOffloadStore instanceof RunnerSharedToolResultStore
+        ? new ScopedToolResultStore(rawOffloadStore, offloadScope)
+        : rawOffloadStore;
+    const offloadReachableToolsRef = {};
+    const maybeOffload = (tool, perTool) => {
+        if (!offloadStore || perTool?.offload === false)
+            return tool;
+        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId, () => offloadReachableToolsRef.current?.());
+    };
+    const firstPartyOffload = (tool) => {
+        const policy = firstPartyOffloadPolicy(tool.name);
+        if (policy.offload === false)
+            return maybeOffload(tool, policy);
+        return maybeOffload(tool, explicitGlobalThreshold === undefined ? policy : undefined);
+    };
+    const remoteToolOffload = (tool) => {
+        if (explicitGlobalThreshold !== undefined)
+            return maybeOffload(tool);
+        return maybeOffload(tool, { offloadThresholdChars: tool.mcpMaxResultSizeChars ?? 50_000 });
+    };
+    return { nestedStats, reportUsage, offloadStore, offloadReachableToolsRef, maybeOffload, firstPartyOffload, remoteToolOffload };
+}

package/dist/core/runner/prepare-permission-rules.d.ts

@@ -0,0 +1,132 @@
+/**
+ * design/389 — prepare's permission-rule phase: the TWO gate lanes the unified store feeds.
+ *
+ * `prepareTask` used to assemble the personal lane inline (a store read + a hand-spliced session
+ * overlay + two admission arms) and the org lane from a second seam. Both now read the ONE store query —
+ * `PermissionRuleStore.effective({ sessionId })` — and this module is where that read is taken and how it
+ * is shared between the two lanes of one adjudicated call.
+ *
+ * ## One read per adjudicated call
+ *
+ * The gate consults the org lane (`orgRules.adjudicate`) on every decision and the personal lane
+ * (`persistedRules.admits`) only on a surviving ask, in that order. The org lane's read is therefore
+ * HANDED to the personal lane by `toolCallId` (taken once, then forgotten), so a governed deployment pays
+ * one store query — one org-source fetch — per call, exactly as it did with two seams. An entry the
+ * personal lane never claims (an allow, a deny) is evicted first-in-first-out past a small bound; an
+ * evicted or never-handed entry simply costs the personal lane its own read. The handoff is a cost
+ * device, not a semantic one: both lanes judge one snapshot, which is the honest shape for one decision.
+ *
+ * ## Where the lanes do NOT go
+ *
+ * Neither is a `ToolPolicy`, and neither joins `policyLayers`: inside the fold an allow is the lowest
+ * position (a permanent no-op) and a layer's mere presence flips `hasEffectAwareGate`, which would
+ * silence the ungated-write warning for deployments that wired no policy at all.
+ */
+import type { AskRuleEvidence, ToolCallRequest } from "../tool-policy.js";
+import type { OrgGateVerdict, PersistedRuleAnswer, PersistedRuleHit } from "../hooks.js";
+import type { PersistedAllowRule } from "../permission-rule-model.js";
+import { type OrgRuleResolution } from "../permission-rule-org.js";
+import type { PermissionRuleStoreProvider } from "../permission-rule-provider.js";
+/** The one SHELL tool the persisted-rule lane speaks for. */
+export declare const PERSISTED_RULE_TOOL = "Bash";
+/** design/382 §2.5 — the READ tool the directory-rule family speaks for (its one other admission
+ *  point, the cd-segment notch, lives inside the model's own conjunction/coverage arms). */
+export declare const DIRECTORY_RULE_TOOL = "Read";
+/**
+ * design/252 G-2 — the evidence an INHERITED-lane ask carries.
+ *
+ * The three inherited mint sites present an ANCESTOR policy's own decision, resolved at the ancestor's
+ * approver, from inside the policy fold — upstream of the gate's org layer and its rule lane, neither of
+ * which has spoken for this call at that point. So the record is stamped rather than omitted (every ask
+ * the engine mints carries one, and a consumer never has to tell a missing field from a field that means
+ * something), and each half names the accurate absence for THIS deployment: a partition that is not
+ * configured at all reads `"not_wired"`, and one that exists but has not adjudicated this ask reads
+ * `"not_adjudicated"`. Reporting the second for a deployment that has neither would assert a governance
+ * layer that does not exist.
+ *
+ * FROZEN: one record is handed to every inherited ask on this leg, and `resolveAsk` shallow-spreads the
+ * request — so an `onAsk` consumer holding `req.ruleEvidence` would otherwise be able to edit what the
+ * next ask on this leg reports.
+ */
+export declare function inheritedAskRuleEvidence(provider: PermissionRuleStoreProvider | undefined): AskRuleEvidence;
+/**
+ * design/252 G-2 — the snapshot REVISION an org answer was read off, screened before it becomes
+ * evidence.
+ *
+ * #123 loud-bad-value: the org partition's own install and serving gates screen a snapshot's revision,
+ * so a healthy in-tree partition cannot reach here with junk; a FOREIGN store (the interface is public)
+ * can. A non-finite value is refused rather than carried — an evidence field is worthless if `NaN` can
+ * wear the same shape as revision 41 — and the defect is announced through `onDefect` instead of quietly
+ * becoming "this deployment reported no revision".
+ *
+ * The ADJUDICATION is untouched either way: the caller's verdict is the whole decision, and a
+ * defective ATTRIBUTION must never change what a governance layer decided.
+ */
+export declare function orgRevisionEvidenceOf(resolution: OrgRuleResolution, onDefect: (message: string) => void): {
+    revision?: number;
+};
+/**
+ * design/252 G-2 / design/375 — project the admitting COVERAGE SET onto the gate's rule-lane answer:
+ * each member's canonical text plus its own add DOTS. A single rule admitting the whole command is a
+ * one-element set; a compound admitted by the per-segment conjunction is the set of covering rules in
+ * segment order (the model's own reporting-order contract).
+ *
+ * `adds` on a listed rule are the LIVE adds — the store's read already dropped tombstoned dots — so
+ * this is the set that actually admitted the call, which is the identity a later audit reconciles a
+ * shadowed ask against. The sanitized display text deliberately is not one. Copied rather than
+ * aliased: the evidence must not change under a store that reuses its row objects.
+ */
+export declare function persistedRuleHitOf(admitting: readonly PersistedAllowRule[] | undefined): PersistedRuleHit | undefined;
+/**
+ * design/382 §2.5-1 — the persisted-rule lane's READ arm: the call's target path in the SAME lexical
+ * identity the rule family is defined over — absolute as spelled, relative resolved against the LIVE
+ * tracked working directory (the very base the Read tool itself resolves against; task root when no
+ * tracker moved), then normalized lexically, zero IO. One admission predicate
+ * ({@link directoryRuleAdmits}), the one eligibility predicate for scope/liveness, first table-order hit
+ * reported. Everything this lane does NOT do is structural: it clears ASKS only — the read fences
+ * (workspace containment, the sensitive-read deny face) judge inside the tool exactly as they would with
+ * no rule anywhere, and an unresolvable path is simply no admission (fail toward asking).
+ */
+export declare function directoryRuleLaneAnswer(table: readonly PersistedAllowRule[], args: unknown, ctx: {
+    root: string | undefined;
+    sessionId: string | undefined;
+    liveCwd: string | undefined;
+}): PersistedRuleHit | undefined;
+/** The two lanes prepare hands the gate. Each is `undefined` when its partition is not configured, so
+ *  a deployment without one keeps a decision path byte-identical to a build without the feature. */
+export interface PermissionRuleLanes {
+    personal: {
+        admits: (req: ToolCallRequest) => Promise<PersistedRuleAnswer>;
+    } | undefined;
+    org: {
+        adjudicate: (req: ToolCallRequest) => Promise<OrgGateVerdict>;
+    } | undefined;
+}
+/**
+ * Build the gate's two permission-rule lanes over the unified store, resolved once per task.
+ *
+ * design/182 §4.5 (F-011) — the LOCAL-OWNER declaration is judged here, at prepare. It is a declaration,
+ * so one that cannot be honored is refused LOUDLY rather than degrading into "this deployment's standing
+ * approvals silently stopped applying" (the §7.4 org bit's rule, applied to the availability direction:
+ * the failure is deterministic and belongs at wiring time).
+ */
+export declare function createPermissionRuleLanes(cfg: {
+    provider: PermissionRuleStoreProvider | undefined;
+    localOwnerDeclared: boolean;
+    principal: string | undefined;
+    sessionId: string;
+    /** The isolation-aware task root — the same value the file fence, the prompt cwd and the session rules
+     *  use, so a project-scoped rule agrees with every other place that says "this project". */
+    root: string;
+    /** The LIVE tracked working directory (adversarial-review P1): the base a relative cd resolves against
+     *  after an earlier observable `cd`; read per call. */
+    liveCwd: () => string | undefined;
+    /** True iff the reserved question-tool NAME resolves to the ENGINE's own content-ask tool on this leg. */
+    questionToolMounted: boolean;
+    questionToolName: string;
+    onRevisionDefect: (message: string) => void;
+    /** Sink for the store's disclosure lines (a session partition that could not be read, rows it served
+     *  that were dropped) and for a durable read failure — each read's lines are delivered once, whichever
+     *  lane took the read. */
+    onDisclosure: (message: string) => void;
+}): PermissionRuleLanes;

package/dist/core/runner/prepare-permission-rules.js

@@ -0,0 +1,140 @@
+import { directoryRuleAdmits, eligiblePersisted, findAdmittingRule, lexicalNormalAbsolutePathOf, segmentCoverageOf } from "../permission-rule-model.js";
+import { orgRuleVerdictFor } from "../permission-rule-org.js";
+export const PERSISTED_RULE_TOOL = "Bash";
+export const DIRECTORY_RULE_TOOL = "Read";
+const HANDOFF_BOUND = 256;
+export function inheritedAskRuleEvidence(provider) {
+    const org = provider?.partitions.org === true ? "not_adjudicated" : "not_wired";
+    const personal = provider?.partitions.durable === true ? "not_adjudicated" : "not_wired";
+    return Object.freeze({ orgRevisionAbsent: org, orgRuleAbsent: org, personalRuleDotsAbsent: personal });
+}
+export function orgRevisionEvidenceOf(resolution, onDefect) {
+    const reported = resolution.revision;
+    if (reported === undefined)
+        return {};
+    if (typeof reported === "number" && Number.isFinite(reported))
+        return { revision: reported };
+    onDefect(`the org rule partition reported revision ${JSON.stringify(reported)} — a snapshot revision is a finite number; ` +
+        `the adjudication stands, but the ask carries no revision evidence for this call`);
+    return {};
+}
+export function persistedRuleHitOf(admitting) {
+    return admitting === undefined
+        ? undefined
+        : { rules: admitting.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
+}
+export function directoryRuleLaneAnswer(table, args, ctx) {
+    const filePath = args?.file_path;
+    if (typeof filePath !== "string" || filePath === "")
+        return undefined;
+    const spelled = filePath.startsWith("/") ? filePath : `${(ctx.liveCwd ?? ctx.root ?? "").replace(/\/+$/, "")}/${filePath}`;
+    const target = lexicalNormalAbsolutePathOf(spelled);
+    if (target === undefined)
+        return undefined;
+    const hit = table.find((r) => eligiblePersisted(r, { tool: DIRECTORY_RULE_TOOL, cwd: ctx.root, sessionId: ctx.sessionId }) && directoryRuleAdmits(r, target));
+    return hit !== undefined ? persistedRuleHitOf([hit]) : undefined;
+}
+export function createPermissionRuleLanes(cfg) {
+    const provider = cfg.provider;
+    if (cfg.localOwnerDeclared) {
+        if (provider === undefined || !provider.partitions.durable) {
+            throw new Error("RunnerDeps.localOwnerRules is declared but no durable permission-rule partition is wired — there is no bucket for the local owner to hold rules in; refusing rather than running as if the declaration were absent");
+        }
+        if (provider.forLocalOwner === undefined) {
+            throw new Error("RunnerDeps.localOwnerRules is declared but the wired permission-rule provider implements no forLocalOwner() face — a provider without a local-owner bucket cannot honor the declaration; refusing rather than silently resolving zero rules");
+        }
+    }
+    if (provider === undefined)
+        return { personal: undefined, org: undefined };
+    const anonymous = cfg.principal === undefined || cfg.principal === "";
+    const store = anonymous && cfg.localOwnerDeclared
+        ?
+            provider.forLocalOwner()
+        : provider.forPrincipal(anonymous ? undefined : cfg.principal);
+    const handed = new Map();
+    const read = () => store.effective({ sessionId: cfg.sessionId }).then((view) => {
+        for (const line of view.disclosures)
+            cfg.onDisclosure(line);
+        return view;
+    });
+    const hand = (toolCallId) => {
+        const p = read();
+        handed.delete(toolCallId);
+        handed.set(toolCallId, p);
+        if (handed.size > HANDOFF_BOUND) {
+            const oldest = handed.keys().next().value;
+            if (oldest !== undefined)
+                handed.delete(oldest);
+        }
+        p.catch(() => undefined);
+        return p;
+    };
+    const claim = (toolCallId) => {
+        const p = handed.get(toolCallId);
+        if (p === undefined)
+            return read();
+        handed.delete(toolCallId);
+        return p;
+    };
+    const org = provider.partitions.org
+        ? {
+            adjudicate: async (req) => {
+                if (req.toolName === cfg.questionToolName && cfg.questionToolMounted)
+                    return { status: "available" };
+                let resolution;
+                try {
+                    resolution = (await hand(req.toolCallId)).org;
+                }
+                catch (err) {
+                    return { status: "unavailable", disclosures: [`the permission-rule store threw while resolving the org partition: ${err instanceof Error ? err.message : String(err)}`] };
+                }
+                if (resolution.status === "unavailable" || resolution.status === "ungoverned") {
+                    return { status: "unavailable", disclosures: resolution.status === "ungoverned" ? ["the store reports no org partition while the provider declares one — unreadable governance, never an empty one"] : resolution.disclosures };
+                }
+                const revisionCell = orgRevisionEvidenceOf(resolution, cfg.onRevisionDefect);
+                const command = req.args?.command;
+                if (req.toolName !== PERSISTED_RULE_TOOL || typeof command !== "string")
+                    return { status: "available", ...revisionCell };
+                const verdict = orgRuleVerdictFor(resolution.rules, { tool: req.toolName, command });
+                return verdict === undefined ? { status: "available", ...revisionCell } : { status: "available", verdict, ...revisionCell };
+            },
+        }
+        : undefined;
+    const personal = provider.partitions.durable
+        ? {
+            admits: async (req) => {
+                if (anonymous && !cfg.localOwnerDeclared)
+                    return undefined;
+                if (req.toolName !== PERSISTED_RULE_TOOL && req.toolName !== DIRECTORY_RULE_TOOL)
+                    return undefined;
+                let view;
+                try {
+                    view = await claim(req.toolCallId);
+                }
+                catch (err) {
+                    cfg.onDisclosure(err instanceof Error ? err.message : String(err));
+                    return { unreadable: true };
+                }
+                if (view.unreadable !== undefined) {
+                    cfg.onDisclosure(view.unreadable);
+                    return { unreadable: true };
+                }
+                const table = view.rules;
+                const liveCwd = cfg.liveCwd();
+                if (req.toolName === DIRECTORY_RULE_TOOL) {
+                    return directoryRuleLaneAnswer(table, req.args, { root: cfg.root, sessionId: cfg.sessionId, liveCwd });
+                }
+                const command = req.args?.command;
+                if (typeof command !== "string")
+                    return undefined;
+                const execCwd = liveCwd !== undefined ? { execCwd: liveCwd } : {};
+                const admitting = findAdmittingRule(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
+                if (admitting !== undefined)
+                    return persistedRuleHitOf(admitting);
+                const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
+                return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
+            },
+        }
+        : undefined;
+    return { personal, org };
+}