@agentproto/runtime 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { B as BuildHeartbeatAgent } from './heartbeat-COGpMrJS.js';
 export { H as HeartbeatAgent, a as HeartbeatRunner, R as RuntimeEvent, b as RuntimeEvents, p as parseDuration } from './heartbeat-COGpMrJS.js';
 import { AcpPermissionResolution, AcpMcpServer } from '@agentproto/acp';
 import { ChildProcess } from 'node:child_process';
-import { R as ResolvedAuthSpec, D as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './spawn-defaults-DAbADRd4.js';
-export { a as AuthEcho, b as AuthResolutionError, C as CredentialSource, c as DefaultsAdapterAuthConfig, d as DefaultsAdapterConfig, e as ResolvedSpawnAuthMaterial, f as ResolvedSpawnDefaults, S as SpawnDefaultsConfig, g as credentialFingerprint, n as normalizeSkillsOption, r as resolveAuthSpec, h as resolveSpawnDefaults } from './spawn-defaults-DAbADRd4.js';
+import { W as WorktreeIsolationMode, R as ResolvedAuthSpec, D as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './config-BRKy_SAF.js';
+export { a as AuthEcho, b as AuthResolutionError, C as CredentialSource, c as DefaultsAdapterAuthConfig, d as DefaultsAdapterConfig, e as ResolvedSpawnAuthMaterial, f as ResolvedSpawnDefaults, S as SpawnDefaultsConfig, g as credentialFingerprint, n as normalizeSkillsOption, r as resolveAuthSpec, h as resolveSpawnDefaults } from './config-BRKy_SAF.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { AdapterHandle, SetupField, AdapterResolver, AdapterLister, AdapterEntry } from '@agentproto/provider-kit';
 import { SandboxProvider } from '@agentproto/sandbox';
@@ -495,6 +495,23 @@ interface SessionDescriptor {
      *  the daemon's. Lets the UI show "crashed with the daemon" instead of a
      *  bare "killed" that reads as deliberate. */
     endedReason?: "daemon-restart";
+    /** Whether a turn was actually in flight the INSTANT `status` flipped to
+     *  "killed" — captured before anything else runs, because `busy` itself
+     *  cannot be trusted after the fact: `runAgentTurn`'s `finally` is what
+     *  clears `busy`, and that `finally` never fires for a generator that's
+     *  never resumed (a killed child mid-tool-call, or a dead daemon), so a
+     *  post-hoc read of `busy` on a killed session may just be showing you
+     *  whatever it froze at. This field exists because `status: "killed"`
+     *  alone can't tell a human's Stop mid-turn apart from a supervisor
+     *  reaping a child that had already finished — both leave `exitCode:
+     *  null`, and `turnsCompleted` alone is too weak (a session killed
+     *  mid-SECOND-turn also has `turnsCompleted: 1`). `killedMidTurn: true`
+     *  paired with any `turnsCompleted` means interrupted; `false`/absent
+     *  alongside `turnsCompleted > 0` means the work was done before the
+     *  kill — see activityFor in the vscode package for the read. Set by
+     *  `kill()`, `shutdownImpl`'s force-kill, and `loadHistorySnapshot`'s
+     *  wasAlive reclassification; absent for every other terminal path. */
+    killedMidTurn?: boolean;
     /** Last time anything was written to stdout/stderr. Lets the UI
      *  spot stuck sessions ("running for 2h, last output 12min ago"). */
     lastOutputAt?: string;
@@ -514,6 +531,10 @@ interface SessionDescriptor {
     /** Free-text label the spawner can attach (e.g. conversation id,
      *  operator name) so the UI can group/filter. */
     label?: string;
+    /** Derived from the session's FIRST prompt — what this conversation is
+     *  about, for a UI that would otherwise show the adapter's argv. Distinct
+     *  from `label`, which the spawner supplies and which always wins. */
+    title?: string;
     /** True when the session was spawned under a real PTY (node-pty)
      *  instead of `child_process.spawn`. PTY sessions carry raw ANSI
      *  bytes (alt-screen, key bindings, colors); attach goes through
@@ -529,6 +550,25 @@ interface SessionDescriptor {
     argv?: readonly string[];
     /** Working directory the session was spawned in. Cloned by restart. */
     cwd?: string;
+    /** Root of the git worktree the session was spawned in — the session→
+     *  worktree edge, resolved from `cwd` at spawn time
+     *  (`resolveWorktreeIdentity`). Distinct from `cwd`, which may be a
+     *  subdirectory of it. Absent when `cwd` isn't inside a linked worktree (a
+     *  plain checkout, a non-repo dir) and for every session persisted before
+     *  this field existed.
+     *
+     *  Recorded rather than computed at read time because it can't be
+     *  recovered later: a worktree removed after the session ran leaves nothing
+     *  on disk to re-resolve. */
+    worktreePath?: string;
+    /** Generation id of that worktree, read at spawn from the provision marker
+     *  (`agentproto-worktree.json` in the worktree's private gitdir, written by
+     *  `worktree.provision`). Absent whenever `worktreePath` is, and also for a
+     *  worktree created by a bare `git worktree add` — nothing writes a marker
+     *  there. The marker is what distinguishes generations, so a
+     *  `worktreePath` without an id identifies a PATH, which a later worktree
+     *  may reuse; the pair identifies one specific worktree. */
+    worktreeId?: string;
     /** Adapter slug for agent-cli sessions — restart uses this with
      *  `/sessions/agent` to spin up a fresh ACP runtime. Undefined for
      *  pty/command kinds. */
@@ -818,6 +858,22 @@ interface SessionsRegistry {
     enqueuePrompt(id: string, message: unknown, opts?: {
         interrupt?: boolean;
     }): Promise<void>;
+    /** Cancel the in-flight turn on a live agent-cli session and leave the
+     *  session itself alive and idle — the bare "interrupt, no next prompt"
+     *  primitive `sendPrompt`/`enqueuePrompt`'s `opts.interrupt` arm lacks
+     *  on its own, since that arm always exists to redirect onto a NEW
+     *  prompt. Reuses the same `interruptInFlightTurn` helper those two
+     *  share.
+     *
+     *  Idempotent by design: idle, unknown-alive (starting/running only —
+     *  same liveness `validateAgentTurn` checks), or already-terminal
+     *  (exited/killed/error) all resolve `{ wasBusy: false }` rather than
+     *  throwing — a no-op interrupt is not an error. Throws only when the
+     *  id is unknown, or when `cancel()` itself rejects ("does not support
+     *  interrupt", propagated from `interruptInFlightTurn`). */
+    interruptSession(id: string): Promise<{
+        wasBusy: boolean;
+    }>;
     /** Stamp `lastActivityAt` on a live agent-cli session's descriptor
      *  and schedule a debounced persist. Called from the `onActivity`
      *  callback threaded down through the driver → ACP client, which
@@ -1789,6 +1845,19 @@ interface PolicyRunState {
     nextPolicyId?: string;
     error?: string;
 }
+/**
+ * Does `policy` watch `sessionId`? True when the id is the representative
+ * `sessionId` or appears anywhere in the fan-in `sessionIds` group — the two
+ * ways `AttachPolicyInput` can name a session.
+ *
+ * This is the reverse of the policy→session link, and it is deliberately
+ * computed on demand over `list()` rather than persisted: a session→policy
+ * index in policies.json (or a `policies` field on the session record) would
+ * be a second source of truth to keep in sync across attach, fan-in nudges,
+ * `next` chaining, and snapshot reload. A filtered pass is O(policies) on a
+ * set the daemon already holds in memory.
+ */
+declare function policyWatchesSession(policy: PolicyRunState, sessionId: string): boolean;
 interface CompletionPolicySupervisor {
     /**
      * Attach a completion policy to an already-running session.
@@ -2153,6 +2222,127 @@ type SandboxProviderResolver = AdapterResolver<SandboxProviderHandle>;
 /** List every sandbox provider with its live status + capabilities. */
 type SandboxProviderLister = AdapterLister<SandboxAdapterInfo>;
 
+/**
+ * Policy layer for `agent_start.worktree` — the config-driven decision of
+ * WHETHER to isolate a spawn into its own git worktree, kept deliberately
+ * separate from HOW one is provisioned.
+ *
+ * This module holds no dependency on `@agentproto/worktree`. Same reasoning
+ * as `worktree-identity.ts`'s docblock, only stronger: provisioning runs the
+ * `worktree.provision` TOOL (git + the base tree's `agentproto.json` setup
+ * hooks), which would drag the driver/harness/provider graph into
+ * `@agentproto/runtime` for a capability the runtime only ever *triggers*.
+ * So the concrete provisioner is an INJECTED PORT ({@link WorktreeProvisioner})
+ * wired at the composition root by a host that already depends on the
+ * worktree package (the CLI). The runtime owns only the pure decision
+ * ({@link decideWorktreeIsolation}) and the config/env resolution
+ * ({@link loadWorktreeIsolation}) — both trivially unit-testable without git.
+ *
+ * Mirrors `agent_start.sandbox`'s `resolveSandboxProvider` injection shape,
+ * except sandbox can default its resolver inside the runtime (the runtime
+ * depends on `@agentproto/sandbox`); worktree cannot, so an unwired daemon
+ * simply has no provisioner and a spawn that would need one fails loud rather
+ * than silently spawning unisolated.
+ */
+
+/** Env override for the isolation policy. Highest-priority source, ahead of
+ *  the `worktrees.isolation` config field — see `loadWorktreeIsolation`. */
+declare const WORKTREE_ISOLATION_ENV = "AGENTPROTO_WORKTREES_ISOLATION";
+/** The default when nothing is configured. Back-compat-preserving: a caller
+ *  that passes no `worktree` field spawns exactly where it asked. */
+declare const DEFAULT_WORKTREE_ISOLATION: WorktreeIsolationMode;
+/**
+ * The `agent_start.worktree` field. `true` isolates with an auto-minted slug;
+ * an object additionally pins the slug and/or base ref; `false` (or omitted)
+ * is "no explicit request" — the policy mode decides.
+ */
+type WorktreeField = boolean | {
+    slug?: string;
+    base?: string;
+};
+/** The caller's explicit request, normalized — `undefined` when the field is
+ *  absent or `false`, otherwise the (possibly empty) slug/base overrides. */
+interface WorktreeRequest {
+    slug?: string;
+    base?: string;
+}
+/** What the runtime hands the provisioner. `cwd` is where the session would
+ *  otherwise spawn; the provisioner resolves the owning repo from it. */
+interface WorktreeProvisionRequest {
+    cwd: string;
+    /** Explicit slug from the caller; omitted ⇒ the provisioner mints a
+     *  collision-free one (see the host implementation). */
+    slug?: string;
+    /** Base ref the worktree branch is cut from; omitted ⇒ the provisioner's
+     *  default (`origin/main`). */
+    base?: string;
+    /** Free-text label (the session's `label`) the provisioner may fold into a
+     *  minted slug for human readability. Never load-bearing for correctness. */
+    labelHint?: string;
+}
+/** The provisioner's outcome. `isolated: false` is NOT a failure — it means
+ *  there was nothing to isolate (`cwd` sits in no git repo), and the caller
+ *  should spawn plain at the original cwd. A genuine failure throws. */
+type WorktreeProvisionOutcome = {
+    isolated: true;
+    cwd: string;
+    branch: string;
+} | {
+    isolated: false;
+    reason: "not-a-git-repo";
+};
+/**
+ * Injected port: provision a git worktree for `req.cwd` and return the
+ * worktree's own cwd for the spawn to land in. Wired at the composition root
+ * by the CLI (over `@agentproto/worktree`); absent on a bare runtime.
+ */
+type WorktreeProvisioner = (req: WorktreeProvisionRequest) => Promise<WorktreeProvisionOutcome>;
+/** The pure decision's three outcomes. */
+type WorktreeDecision = {
+    action: "spawn-in-place";
+} | {
+    action: "provision";
+    request: WorktreeRequest;
+} | {
+    action: "reject";
+    message: string;
+};
+/**
+ * Normalize the raw field into an explicit request, or `undefined` when the
+ * caller made no request (`false` / omitted). An object with no overrides
+ * still counts as a request (`{}`) — the caller opted in, just without pins.
+ */
+declare function normalizeWorktreeField(field: WorktreeField | undefined): WorktreeRequest | undefined;
+/**
+ * The resolution matrix — mode × explicit-request × depth — with no side
+ * effects. Every branch is exercised in `worktree-isolation.test.ts`.
+ *
+ * Depth-0 gate: a nested spawn (`depth > 0`, i.e. made through the scoped
+ * orchestrator sub-gateway) NEVER provisions — it inherits its parent's
+ * ground, per AIP-46 §Delegation. This bites before the mode is even
+ * consulted, so `always` too provisions only at the root and an explicit
+ * request from a nested spawn is a silent no-op (spawn-in-place), not a
+ * reject: the child is meant to share the parent's tree.
+ */
+declare function decideWorktreeIsolation(input: {
+    mode: WorktreeIsolationMode;
+    field: WorktreeField | undefined;
+    depth: number;
+}): WorktreeDecision;
+/** Parse a raw string into a valid mode, or `undefined` when it isn't one. */
+declare function parseWorktreeIsolationMode(raw: string | undefined): WorktreeIsolationMode | undefined;
+/**
+ * Resolve the effective isolation mode: env > config field > default. Mirrors
+ * `resolveWorktreesRoot`'s precedence (there's no flag layer — this is read
+ * daemon-side at spawn, not from an invocation). Never throws: an unreadable
+ * config falls through to the default.
+ */
+declare function loadWorktreeIsolation(loadCfg?: () => Promise<{
+    worktrees?: {
+        isolation?: WorktreeIsolationMode;
+    };
+}>): Promise<WorktreeIsolationMode>;
+
 /**
  * Pluggable adapter resolver — keeps the runtime package free of any
  * @agentproto/cli dep. The host (cli `serve`, playground, embedding
@@ -2566,6 +2756,158 @@ declare function declaredPresetToProviderPreset(decl: DeclaredAdapterPreset): Pr
  */
 declare function listPresets(env?: Record<string, string | undefined>, adapterPresets?: readonly DeclaredAdapterPreset[]): AdapterEntry<PresetInfo>[];
 
+/**
+ * Per-workspace state buckets — AIP-46 §State partitioning.
+ *
+ * AIP-46's premise is "a single host serve many bound directories", and
+ * §Workspaces delivered the addressing half of it: a slug resolves to a
+ * path. The state those directories generate stayed pooled in one global
+ * `~/.agentproto/sessions.json` with `workspaceSlug` demoted to a column
+ * on each row — a label, not a boundary.
+ *
+ * What that costs is measurable rather than theoretical. `HISTORY_CAP`
+ * bounds retention across the *union* of every workspace, so the cap is
+ * spent by whoever was busiest. A store pooling a few hundred rows from
+ * several workspaces sits at that ceiling in ordinary use, and the
+ * workspace contributing a handful of them is one busy afternoon in a
+ * NEIGHBOUR away from losing all of them — having done nothing itself.
+ * The eviction is silent and lands on the quietest workspace.
+ *
+ * This module is the slug→bucket rule and nothing more:
+ *
+ *   ~/.agentproto/
+ *   ├── workspaces.json          # the registry (workspaces-config.ts)
+ *   └── workspaces/              # one bucket per workspace (here)
+ *       ├── agentik-studio/sessions.json
+ *       └── default/sessions.json
+ *
+ * The registry (a file) and the state (a directory) are deliberate
+ * siblings: one names the workspaces, the other holds what each
+ * accumulated.
+ *
+ * ## Membership is the validation
+ *
+ * `workspaceSlug` arrives on a spawn request — it is caller input
+ * (`session-spawn.ts` passes `input.workspaceSlug` straight through when
+ * an explicit `cwd` accompanies it, so nothing sanitises it on the way
+ * to the descriptor). A bucket is a directory name. Joining the two
+ * without a check hands the caller `../../` under the daemon's own state
+ * root, as the daemon's UID.
+ *
+ * So a slug does not become a directory name by being cleaned up — it
+ * becomes one by coming *back from* the registry lookup. The registry's
+ * slugs were sanitised by `sanitizeSlug` on the way in, so the only
+ * strings that ever reach the filesystem are ones the host itself
+ * minted. An unregistered slug isn't rejected or escaped; it fails to
+ * match and lands in `default` like any other unregistered work. This is
+ * why the rule is membership rather than sanitisation: you cannot forget
+ * to validate a value you never chose.
+ *
+ * ## What this does NOT buy
+ *
+ * Partitioning bounds what a workspace's state *costs* other workspaces.
+ * It does not bound who may read it — every bucket is still served to
+ * every authorised caller, because no workspace-scoped credential
+ * exists to serve them differently (pairings carry no workspace concept
+ * at all; the orchestrator scope-token's `session_list` is daemon-wide
+ * by documented debt, `orchestrator-gateway.ts`). The files moved; the
+ * access did not. AIP-46 §Security Considerations says this in the
+ * negative — do not read this module as an isolation control.
+ */
+/** The bucket every record lands in when its slug doesn't resolve —
+ *  absent, empty, or naming a workspace that isn't registered.
+ *
+ *  A real bucket, not an error state. Refusing to persist an
+ *  unregistered session would make this a breaking change for every
+ *  one-off `cwd` spawn, and the obvious workaround (auto-register)
+ *  turns a registry of the user's intent into a registry of everything
+ *  that ever ran. The cost is stated plainly in the AIP: `default`'s
+ *  occupants get no separation from *each other* — registering a
+ *  workspace is what buys that. */
+declare const DEFAULT_BUCKET = "default";
+/** Root of the per-workspace state buckets. Sibling of the
+ *  `workspaces.json` registry that names them. */
+declare const BUCKETS_ROOT: () => string;
+/** The pre-partition global snapshot. Still read (to migrate from) and
+ *  never written after the split — see `migrateLegacySessionsFile`. */
+declare const LEGACY_SESSIONS_FILE: () => string;
+/** Marker recording that the legacy split already ran. Its presence —
+ *  not the legacy file's absence — is what makes migration
+ *  once-and-only-once, so a user who deletes rows from a bucket doesn't
+ *  get them resurrected on the next boot. */
+declare const migrationMarkerPath: (root: string) => string;
+declare const bucketDir: (root: string, slug: string) => string;
+declare const bucketSessionsFile: (root: string, slug: string) => string;
+/** Per-bucket transcript directory (AIP-46 §Layout).
+ *
+ *  Not yet wired: the registry still writes transcripts to the shared
+ *  `~/.agentproto/sessions/`. Moving them needs the read side to move
+ *  too, and several readers currently ignore the configured base dir
+ *  entirely (`http-server.ts` and `transcript-export.ts` call
+ *  `sessionEventsPath(id)` with no `baseDir`, so they resolve off
+ *  `homedir()` regardless) — a pre-existing bug that a partial move
+ *  would turn into missing transcripts. Exported so the follow-up has
+ *  the path rule in one place. The AIP makes transcripts a SHOULD, not
+ *  a MUST, for exactly this reason. */
+declare const bucketTranscriptDir: (root: string, slug: string) => string;
+declare const isSafeBucketSlug: (slug: string) => boolean;
+/**
+ * The slug→bucket rule (AIP-46 §Bucket resolution).
+ *
+ * 1. non-empty AND registered → that workspace's bucket
+ * 2. otherwise → `default`
+ *
+ * `registered` must come from the workspaces registry. Passing a set
+ * built from caller input defeats the entire point of this function.
+ */
+declare function resolveBucketSlug(workspaceSlug: string | undefined | null, registered: ReadonlySet<string>): string;
+/** Registered slugs, read fresh. Cheap (the registry is <1KB) and read
+ *  per persist rather than cached at boot, so a workspace registered
+ *  while the daemon is up starts bucketing immediately instead of
+ *  silently pooling into `default` until restart. Never throws: a
+ *  missing/corrupt registry degrades to "nothing is registered", i.e.
+ *  everything lands in `default` — today's pooled behaviour, which is
+ *  the right failure direction. */
+declare function readRegisteredSlugs(configPath?: string): ReadonlySet<string>;
+/** Bucket directories that exist on disk. Order is not meaningful. */
+declare function listBuckets(root: string): string[];
+interface MigrationMarker {
+    version: 1;
+    migratedAt: string;
+    /** Absolute path of the legacy artifact this split read from. Left
+     *  untouched on disk — recorded so the provenance survives. */
+    from: string;
+    /** Total records read out of the legacy artifact. */
+    rows: number;
+    /** Records landed, per bucket. Sums to `rows` — the migration never
+     *  drops a record it cannot place; it sends it to `default`. */
+    byBucket: Record<string, number>;
+}
+/**
+ * Split the legacy global snapshot into buckets (AIP-46 §Migration).
+ *
+ * **Additive by mandate.** The legacy file is opened read-only and left
+ * exactly where it is — never deleted, truncated, or rewritten. It is
+ * the user's data and their only rollback; the buckets are a derivative
+ * until they decide otherwise. Reclaiming it is a separate, human-gated
+ * call, and this module deliberately ships no GC: a real store is backed
+ * by a transcript directory that can reach hundreds of megabytes and may
+ * be someone's only copy of months of work — a deleter that guesses
+ * wrong there is unrecoverable.
+ *
+ * Idempotent via the marker, not via the legacy file's absence — the
+ * file stays, so absence would never fire and every boot would re-import
+ * rows the user had since deleted from a bucket.
+ *
+ * Returns the marker it wrote, or `null` when there was nothing to do
+ * (already migrated, or no legacy file).
+ */
+declare function migrateLegacySessionsFile(opts: {
+    root: string;
+    legacyFile: string;
+    registered: ReadonlySet<string>;
+}): MigrationMarker | null;
+
 /** A journal-file StepCache scoped to one cacheKey. Best-effort: read/parse
  *  failures degrade to "no cache" (a miss), never throw into the run. */
 declare function createFileStepCache(cacheKey: string, opts?: {
@@ -2690,6 +3032,26 @@ declare function readRuntimeMeta(workspace: string): Promise<{
  */
 declare function sweepStaleRuntimeMetas(workspaces: readonly string[], currentWorkspace: string): Promise<string[]>;
 
+/**
+ * Read-only probe: does a credential actually RESOLVE for an adapter slug's
+ * billing auth? Used by `adapter_list` to report an HONEST status instead of
+ * claiming "ready" on a host with zero credentials for an adapter that hard-
+ * fails every spawn (claude-code, `authEnforce: "always"`).
+ *
+ * THE TRAP (see the money regression test in `__tests__/auth-probe.test.ts`):
+ * a probe that answers "is auth configured?" by checking `providers.json`
+ * alone would report `true` for a spawn that still throws
+ * `missing_auth_credential` — the store lookup at `session-spawn.ts:612-617`
+ * is gated on `explicit` (PR #321: an unconfigured `always`-enforcing adapter
+ * must never pick up a leftover store key and bill org credits instead of the
+ * Max subscription). So this mirrors `session-spawn.ts`'s resolution exactly
+ * — same `resolveSpawnDefaults` + `resolveAuthSpec`, same explicit gate on
+ * the store lookup — rather than reimplementing the precedence: a second
+ * copy of this logic WILL drift, and the drift is denominated in money.
+ */
+
+declare function isAgentCliAuthConfigured(slug: string, descriptor: AdapterAuthDescriptor, model?: string): Promise<boolean>;
+
 /**
  * MCP tools for event-driven orchestration:
  *   - session_events_poll — cheap cursor-based snapshot of session events
@@ -2844,6 +3206,30 @@ interface CreateGatewayOptions {
      *  tool family, and the `/sessions/:id/pty` WebSocket. Without it,
      *  those routes return 501 / the MCP tools aren't registered. */
     spawnPty?: PtyFactory;
+    /** Enable filesystem persistence for every store this gateway owns —
+     *  the sessions registry plus the supervisor / routine / cron / workflow
+     *  / inbound-watcher run stores. Defaults to `true`, i.e. production is
+     *  unchanged.
+     *
+     *  Tests pass `false`. Without it, a test gateway writes its fake rows
+     *  into the *developer's real* `~/.agentproto/sessions.json` (and the
+     *  sibling `policies.json` / `routine-runs.json` / `cron-jobs.json` /
+     *  `workflow-runs.json`): those paths resolve off `homedir()`, and the
+     *  gateway opted each store into persistence unconditionally. Since
+     *  `loadHistorySnapshot` re-reads sessions.json at boot, the real daemon
+     *  then restores the fakes and shows them in the dashboard — and against
+     *  `HISTORY_CAP` (200) they evict genuine history.
+     *
+     *  The sibling stores already default to persist-off when constructed
+     *  directly (see `createRoutineRunner`); this knob is what lets a
+     *  gateway stop overriding that on their behalf. */
+    persist?: boolean;
+    /** Override the sessions-registry persistence path — tests pin a tmpdir
+     *  so an assertion can look at the file the gateway would have written
+     *  instead of the developer's real one. Defaults to
+     *  `~/.agentproto/sessions.json`. The structured-transcript dir follows
+     *  this path's parent, so pinning it isolates transcripts too. */
+    persistPath?: string;
     /** Override the per-boot bearer token. Default: `randomUUID()`.
      *  Tests can pin a known value; production should always let
      *  the gateway generate fresh. The token is written into
@@ -2881,6 +3267,16 @@ interface CreateGatewayOptions {
     /** Optional sandbox provider lister — mirrors `listAgentAdapters`.
      *  Overrides the default catalog-driven lister behind `list_sandbox_providers`. */
     listSandboxProviders?: SandboxProviderLister;
+    /**
+     * Optional git-worktree provisioner powering `agent_start.worktree` and the
+     * `worktrees.isolation` policy. Injected here (rather than defaulted inside
+     * the runtime like `resolveSandboxProvider`) because provisioning runs the
+     * `@agentproto/worktree` TOOL, a dependency the runtime deliberately does
+     * NOT take — see `worktree-identity.ts` / `worktree-isolation.ts`. The CLI
+     * wires it. Omitted → a spawn the policy says to isolate is rejected with
+     * `worktree_provisioner_not_enabled` (never silently spawned unisolated).
+     */
+    provisionWorktree?: WorktreeProvisioner;
     /**
      * Optional E2E pairing registry (see `createPairingRegistry`). When wired,
      * the gateway mounts the `/pairings/*` REST routes and the `pair_*` MCP
@@ -2938,4 +3334,4 @@ interface GatewayHandle {
  */
 declare function createGateway(opts: CreateGatewayOptions): Promise<GatewayHandle>;
 
-export { AdapterAuthDescriptor, type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type AttachPolicyInput, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, type CommitSpec, type CompletionPolicySupervisor, type CreateGatewayOptions, type CreateOfferInput, type CreatedOffer, DEFAULT_ORCHESTRATOR_TOOLS, DeclaredAdapterOption, type DeclaredAdapterPreset, type GateSpec, type GatewayHandle, type InboundWatcher, type JudgeGateSpec, type McpCredentialDeps, type OnFailSpec, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, PAIRINGS_VERSION, type PairingChannelContext, type PairingChannelHandle, type PairingChannelMode, type PairingRecord, type PairingRegistry, type PairingRegistryDeps, type PendingPermission, type PermissionRespondInput, type PermissionRespondResult, type PolicyRunState, type PolicyRunStatus, type PresetInfo, type PricingResolver, type RegisterBrowserInput, type RegisterPairingToolsOptions, type RegisterSessionInput, ResolvedAuthSpec, type RuntimeMeta, type SandboxAdapterInfo, type SandboxProviderCapabilities, type SandboxProviderHandle, type SandboxProviderLister, type SandboxProviderResolver, type ScopeTokenRegistry, type SessionDescriptor, type SessionKind, type SessionObserver, type SessionStatus, type SessionUsage, type SessionWaitEvent, type SessionWaitResult, type SessionsRegistry, type ShellGateSpec, type SpawnAgentInput, type SpawnSessionInput, type TokenPricing, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type UsageComputeInput, type UsageSource, type WatcherDescriptor, type WatcherStartInput, WorkspaceFs, composeSessionObservers, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createScopeTokenRegistry, daemonRegistryDir, declaredPresetToProviderPreset, deriveSessionUsage, formatToolCall, formatToolResult, getMcpCredentialDeps, listPresets, makeBrowserAdapterLister, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, projectSessionUsage, readDaemonRegistry, readRuntimeMeta, registerPairingTools, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };
+export { AdapterAuthDescriptor, type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type AttachPolicyInput, BUCKETS_ROOT, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, type CommitSpec, type CompletionPolicySupervisor, type CreateGatewayOptions, type CreateOfferInput, type CreatedOffer, DEFAULT_BUCKET, DEFAULT_ORCHESTRATOR_TOOLS, DEFAULT_WORKTREE_ISOLATION, DeclaredAdapterOption, type DeclaredAdapterPreset, type GateSpec, type GatewayHandle, type InboundWatcher, type JudgeGateSpec, LEGACY_SESSIONS_FILE, type McpCredentialDeps, type MigrationMarker, type OnFailSpec, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, PAIRINGS_VERSION, type PairingChannelContext, type PairingChannelHandle, type PairingChannelMode, type PairingRecord, type PairingRegistry, type PairingRegistryDeps, type PendingPermission, type PermissionRespondInput, type PermissionRespondResult, type PolicyRunState, type PolicyRunStatus, type PresetInfo, type PricingResolver, type RegisterBrowserInput, type RegisterPairingToolsOptions, type RegisterSessionInput, ResolvedAuthSpec, type RuntimeMeta, type SandboxAdapterInfo, type SandboxProviderCapabilities, type SandboxProviderHandle, type SandboxProviderLister, type SandboxProviderResolver, type ScopeTokenRegistry, type SessionDescriptor, type SessionKind, type SessionObserver, type SessionStatus, type SessionUsage, type SessionWaitEvent, type SessionWaitResult, type SessionsRegistry, type ShellGateSpec, type SpawnAgentInput, type SpawnSessionInput, type TokenPricing, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type UsageComputeInput, type UsageSource, WORKTREE_ISOLATION_ENV, type WatcherDescriptor, type WatcherStartInput, WorkspaceFs, type WorktreeDecision, type WorktreeField, WorktreeIsolationMode, type WorktreeProvisionOutcome, type WorktreeProvisionRequest, type WorktreeProvisioner, type WorktreeRequest, bucketDir, bucketSessionsFile, bucketTranscriptDir, composeSessionObservers, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createScopeTokenRegistry, daemonRegistryDir, decideWorktreeIsolation, declaredPresetToProviderPreset, deriveSessionUsage, formatToolCall, formatToolResult, getMcpCredentialDeps, isAgentCliAuthConfigured, isSafeBucketSlug, listBuckets, listPresets, loadWorktreeIsolation, makeBrowserAdapterLister, migrateLegacySessionsFile, migrationMarkerPath, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, normalizeWorktreeField, parseWorktreeIsolationMode, policyWatchesSession, projectSessionUsage, readDaemonRegistry, readRegisteredSlugs, readRuntimeMeta, registerPairingTools, resolveBucketSlug, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };