@zgeoff/atc 2.11.0 → 2.13.0

package/src/daemon/daemon.ts

@@ -1,38 +1,63 @@
+import { randomUUID } from 'node:crypto';
 import { unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import type { AdapterEvent, AgentAdapter } from '../agents/agent-adapter';
+import { planTypedLineInput } from '../agents/plan-typed-line-input';
+import { DaemonError } from '../protocol/daemon-error';
 import { MAX_CHUNK, PROTOCOL_V } from '../protocol/protocol';
 import type { EventMsg } from '../protocol/protocol';
+import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
 import type { HooksConfig } from '../shared/collect-hooks';
+import type { TargetConfigError } from '../shared/collect-targets';
 import { findDaemonRecord } from '../shared/find-daemon-record';
 import type { MessageID } from '../shared/message-id';
+import { isRecord } from '../shared/report';
 import type { SessionID } from '../shared/session-id';
+import { toMessageID } from '../shared/to-message-id';
 import { truncateToBytes } from '../shared/truncate-to-bytes';
+import type { IdempotencyRecord } from '../store/idempotency-record';
 import type { MessageOwner } from '../store/message-owner';
 import type { MessageRecord, MessageStatus } from '../store/message-record';
 import { StateStore } from '../store/state-store';
 import type { EventScope } from '../store/state-store';
 import type { TrailEntry } from '../store/trail-entry';
+import type { SessionWorkspace } from '../store/workspace-materialization';
 import { ANSWER_BYTE_CAP } from './answer-byte-cap';
 import { AttachRegistry } from './attach-registry';
 import { buildAgentList } from './build-agent-list';
+import { buildConfigRevision } from './build-config-revision';
+import { buildExecutionTargets } from './build-execution-targets';
+import type { ExecutionTarget } from './build-execution-targets';
 import { buildFleetEvents } from './build-fleet-events';
 import { buildMessageTrailEntry } from './build-message-trail-entry';
 import { buildReportTrailEntry } from './build-report-trail-entry';
 import { buildSessionEvent } from './build-session-event';
 import { buildSessionMessageEvent } from './build-session-message-event';
 import { buildSessionReportEvent } from './build-session-report-event';
+import { buildTargetAccess } from './build-target-access';
+import { buildTargetForbiddenError } from './build-target-forbidden-error';
+import { buildTargetList } from './build-target-list';
 import { claimDaemonLock } from './claim-daemon-lock';
 import { DaemonConnection } from './daemon-connection';
-import type { DaemonContext, OutputClient, TapClient } from './daemon-connection';
+import type {
+  DaemonContext,
+  MessageRefusal,
+  OutputClient,
+  SpawnParams,
+  TapClient,
+} from './daemon-connection';
+import { EffectRemainsError } from './effect-remains-error';
 import { EventSignal } from './event-signal';
 import { startHookServer } from './hooks';
 import type { HookEvent } from './hooks';
+import { IdempotencyLedger } from './idempotency-ledger';
 import { loadTranscriptPage } from './load-transcript-page';
 import { makeHookRunner } from './make-hook-runner';
 import type { HookScope } from './make-hook-runner';
+import { materializeWorkspace } from './materialize-workspace';
 import { mintMessageID } from './mint-message-id';
+import { mintSessionID } from './mint-session-id';
 import { parseReport } from './parse-report';
 import { PermissionRegistry } from './permission-registry';
 import { restoreFleet } from './restore-fleet';
@@ -43,7 +68,9 @@ import { SessionManager } from './sessions';
 import type { Session, SessionDescriptor, SessionState } from './sessions';
 import { startEventsServer } from './start-events-server';
 import { startHeadlessTurn } from './start-headless-turn';
+import { startSessionBridge } from './start-session-bridge';
 import { TapRegistry } from './tap-registry';
+import type { TargetAccess } from './target-access';
 import { writeDaemonRecord } from './write-daemon-record';
 
 export interface DaemonOptions {
@@ -59,6 +86,21 @@ export interface DaemonOptions {
   // grok adapter is unsupported, not a Claude spawn.
   readonly adapters?: readonly AgentAdapter[];
 
+  // Where sessions run, in config order; one `local` target on the local
+  // pseudo-terminal provider when unset. A spawn without a target runs on
+  // the default one: `local` when unset and the targets hold it, and none
+  // otherwise, which refuses such a spawn.
+  readonly targets?: readonly ExecutionTarget[];
+  readonly defaultTarget?: string | null;
+
+  // The target config problems the daemon started with. A target they cover
+  // refuses every session, and `agents.list` returns them.
+  readonly targetErrors?: readonly TargetConfigError[];
+
+  // The targets each principal may use; unset or null when the config has
+  // no principals, which leaves every principal the implicit local target.
+  readonly principals?: ReadonlyMap<string, readonly string[]> | null;
+
   // SQLite path for daemon state; a fleet.json at legacyFleetPath seeds the
   // fleet table once so upgrading keeps the restorable fleet.
   readonly dbPath: string;
@@ -93,9 +135,16 @@ export interface DaemonOptions {
   readonly restoreBootTimeoutMs?: number;
   readonly tapGraceMs?: number;
 
+  // How long a confirm token from `session.forget` stays usable.
+  readonly forgetConfirmMs?: number;
+
   // Called after a client-requested quit has stopped the daemon; the real
   // entrypoint exits the process, tests leave it unset.
   readonly onQuit?: () => void;
+
+  // Where background failures are reported, one line at a time; stderr
+  // when unset.
+  readonly log?: (line: string) => void;
 }
 
 export interface DaemonHandle {
@@ -109,6 +158,17 @@ export interface DaemonHandle {
 // it is refused.
 const TAP_GRACE_MS = 15_000;
 
+// How long a confirm token from a forget that destroys a host stays usable.
+const FORGET_CONFIRM_MS = 60_000;
+
+// The principal every request on the local socket acts as.
+const LOCAL_PRINCIPAL = 'local';
+
+// A completed idempotency key is kept this long after it completed, and the
+// sweep that drops older ones runs this often.
+const IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1000;
+const IDEMPOTENCY_SWEEP_MS = 60 * 60 * 1000;
+
 // How long startup waits for a daemon that is shutting down to release the
 // state lock before refusing to start.
 const LOCK_WAIT_MS = 2000;
@@ -148,7 +208,49 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
   const store = await StateStore.open(opts.dbPath, opts.legacyFleetPath);
 
-  const mgr = new SessionManager(opts.adapter, store, opts.statusPath, opts.adapters ?? []);
+  // Before any request is served: a workspace a stopped daemon left short
+  // of ready fails as interrupted, and a key left in progress by a daemon
+  // that stopped mid-effect is settled, so no retry can race either.
+  await store.reconcileMaterializations(Date.now());
+  await store.reconcileIdempotencyKeys(Date.now());
+
+  await tryRemoveExpiredIdempotencyKeys(store);
+
+  const idempotencySweep = setInterval(() => {
+    void tryRemoveExpiredIdempotencyKeys(store);
+  }, IDEMPOTENCY_SWEEP_MS);
+
+  idempotencySweep.unref();
+
+  const targets =
+    opts.targets ??
+    buildExecutionTargets([{ id: 'local', provider: 'local-pty', options: {} }]).targets;
+
+  const targetErrors = opts.targetErrors ?? [];
+  const principals = opts.principals ?? null;
+
+  const targetsByID = new Map(targets.map((target) => [target.id, target]));
+
+  const defaultTarget =
+    opts.defaultTarget === undefined
+      ? (targets.find((target) => target.id === 'local')?.id ?? null)
+      : opts.defaultTarget;
+
+  const configRevision = buildConfigRevision(targets, defaultTarget, targetErrors);
+
+  const mgr = new SessionManager(
+    opts.adapter,
+    store,
+    opts.statusPath,
+    opts.adapters ?? [],
+    targets,
+    targetErrors,
+  );
+
+  if (opts.log !== undefined) {
+    mgr.log = opts.log;
+  }
+
   const clients = new Set<DaemonConnection>();
 
   const runHooks = makeHookRunner(opts.hooks ?? {});
@@ -186,14 +288,22 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   const eventSignal = new EventSignal();
 
   // A trail write that fails never fails the message request or report behind it.
-  const recordTrailEntry = async (entry: TrailEntry) => {
+  // Returns false when the entry was not written: a failed write, or a
+  // report the trail already holds.
+  const recordTrailEntry = async (entry: TrailEntry): Promise<boolean> => {
+    let written: boolean;
+
     try {
-      await store.recordTrailEntry(entry);
+      written = await store.recordTrailEntry(entry);
     } catch {
-      return;
+      return false;
     }
 
-    eventSignal.emit();
+    if (written) {
+      eventSignal.emit();
+    }
+
+    return written;
   };
 
   // Notes a message status change in the trail before broadcasting it, so a
@@ -207,11 +317,37 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   };
 
   // A live session's scope also matches the rows it wrote under an earlier
-  // atc id, through the agent session id a restore carries on.
-  const buildEventScope = (sessionID: SessionID): EventScope => ({
-    atcID: sessionID,
-    agentSessionID: mgr.sessions.find((x) => x.id === sessionID)?.agentSessionID,
-  });
+  // atc id, through the agent session id a restore carries on. Under an
+  // access, the scope holds only the sessions on targets the access holds,
+  // so a session outside it matches nothing, as a session never seen does.
+  const buildEventScope = (
+    sessionID: SessionID | null,
+    access: TargetAccess | null,
+  ): EventScope | null => {
+    if (access === null) {
+      if (sessionID === null) {
+        return null;
+      }
+
+      const agentSessionID = mgr.sessions.find((x) => x.id === sessionID)?.agentSessionID;
+
+      return {
+        atcIDs: [sessionID],
+        agentSessionIDs: agentSessionID === undefined ? [] : [agentSessionID],
+      };
+    }
+
+    const visible = mgr.sessions.filter(
+      (x) => access.canUse(x) && (sessionID === null || x.id === sessionID),
+    );
+
+    return {
+      atcIDs: visible.map((x) => x.id),
+      agentSessionIDs: visible.flatMap((x) =>
+        x.agentSessionID === undefined ? [] : [x.agentSessionID],
+      ),
+    };
+  };
 
   // A message belongs to the live session holding its atc id or its agent
   // session id, else to the atc id it was sent to.
@@ -314,7 +450,10 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     } catch {}
   };
 
-  const applyReport = async (e: HookEvent) => {
+  // A report id, which a remote session's reporter gives each report,
+  // makes a resent note land once; a resent answer changes nothing, since
+  // only an unanswered message takes one.
+  const applyReport = async (e: HookEvent, reportID?: string) => {
     const report = parseReport(e.payload);
 
     if (report === null) {
@@ -328,11 +467,22 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         const capped = { ...report, text: truncateToBytes(report.text, ANSWER_BYTE_CAP) };
         const reportedAt = Date.now();
 
-        await recordTrailEntry(
-          buildReportTrailEntry(sender.id, sender.agentSessionID, capped, reportedAt),
+        const entry = buildReportTrailEntry(
+          sender.id,
+          sender.agentSessionID,
+          capped,
+          reportedAt,
+          reportID,
         );
 
-        emitEvent(buildSessionReportEvent(sender.id, capped, reportedAt), findHookScope(sender.id));
+        const written = await recordTrailEntry(entry);
+
+        if (written) {
+          emitEvent(
+            buildSessionReportEvent(sender.id, capped, reportedAt),
+            findHookScope(sender.id),
+          );
+        }
       }
 
       return;
@@ -421,7 +571,12 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
     const s = mgr.sessions.find((x) => x.id === sessionID);
 
-    s?.pty?.resize(dims.cols, dims.rows);
+    // A host that cannot resize keeps its terminal at the size it started
+    // with; the screen model still follows the clients.
+    if (s !== undefined && (mgr.findProvider(s)?.capabilities.resize ?? false)) {
+      s.pty?.resize(dims.cols, dims.rows);
+    }
+
     runtime?.screen?.updateDims(dims.cols, dims.rows);
 
     if (runtime !== undefined) {
@@ -478,6 +633,20 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     }
   };
 
+  // A spawned terminal starts on a fresh screen; a revived one keeps the
+  // screen its session already had.
+  mgr.onBoot = (s, cols, rows) => {
+    const runtime = runtimes.get(s.id);
+
+    if (runtime === undefined) {
+      return;
+    }
+
+    runtime.resetBoot({ cols, rows });
+
+    runtime.screen ??= new ScreenModel(cols, rows);
+  };
+
   mgr.onOutput = (s, data) => {
     const runtime = runtimes.get(s.id);
 
@@ -603,7 +772,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     );
   };
 
-  const reporter = startHookServer((e) => {
+  const applyHookEvent = (e: HookEvent) => {
     if (e.event === 'Report') {
       void applyReport(e);
 
@@ -650,10 +819,328 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         void store.writeLastUsedAgent(started.agent);
       }
     }
-  }, opts.reporterSocketPath);
+  };
+
+  const reporter = startHookServer(applyHookEvent, opts.reporterSocketPath);
+
+  // A remote harness reports through a socket that serves it alone, so a
+  // line that names any other session is dropped.
+  mgr.onRelay = (binding, relay) => {
+    startSessionBridge(relay, binding, {
+      findSession: (sessionID) => mgr.sessions.find((x) => x.id === sessionID),
+      applyHookEvent,
+      applyReport: async (sessionID, payload, reportID) => {
+        if (parseReport(payload) === null) {
+          return false;
+        }
+
+        await applyReport({ atcId: sessionID, event: 'Report', payload: { ...payload } }, reportID);
+
+        return true;
+      },
+      attachTap: (client, sessionID) => ctx.attachTap(client, sessionID),
+      ackMessage: (client, sessionID, messageID) => ctx.ackMessage(client, sessionID, messageID),
+      detachTap: (client) => {
+        taps.detachAll(client);
+      },
+    });
+  };
+
+  // A spawn with a workspace source materializes it first, and the session
+  // registers only once its workspace is ready, so no session ever lists
+  // over a half-built checkout. A spawn that throws once its process has
+  // started takes the session back before it throws, so a failed start
+  // leaves nothing running and a keyed retry spawns once. When taking it
+  // back fails too, the session may still stand, and the throw says so.
+  const startSpawn = async (
+    p: SpawnParams,
+    id: SessionID,
+  ): Promise<Readonly<Record<string, unknown>>> => {
+    const prepared =
+      p.workspace === null ? null : await materializeSpawnWorkspace(p, id, p.workspace);
+
+    const materialized = prepared?.kind === 'ready' ? prepared : null;
+    const warnings = materialized === null ? [] : materialized.warnings;
+
+    try {
+      const session = await startSpawnedSession(p, id, materialized);
+
+      return warnings.length === 0 ? { session } : { session, warnings };
+    } catch (error) {
+      try {
+        await mgr.removeFailedSpawn(id);
+      } catch (cleanupError) {
+        throw new EffectRemainsError(
+          `spawn of session ${id} failed and taking it back failed too`,
+          {
+            cause: cleanupError,
+          },
+        );
+      }
+
+      throw error;
+    }
+  };
+
+  // Materializes a spawn's workspace on its target. The target's identity
+  // binds when the materialization starts, and every provider call after
+  // passes the execution gate against that binding.
+  const materializeSpawnWorkspace = (
+    p: SpawnParams,
+    id: SessionID,
+    source: SpawnWorkspaceSource,
+  ) => {
+    const bound = mgr.requireExecution({ target: p.target, targetIdentity: null }, 'run');
+    const binding = { target: p.target, targetIdentity: bound.identity };
+
+    return materializeWorkspace(
+      {
+        sessionID: id,
+        target: p.target,
+        dir: p.cwd,
+        source,
+        inPlace: bound.provider.kind === 'local-pty',
+      },
+      {
+        requireProvider: (capability) => mgr.requireExecution(binding, capability).provider,
+        store,
+        log: (line) => {
+          mgr.log(line);
+        },
+      },
+    );
+  };
+
+  const startSpawnedSession = async (
+    p: SpawnParams,
+    id: SessionID,
+    materialized: Readonly<{
+      workspace: SessionWorkspace;
+      withheldEnv: readonly string[];
+    }> | null,
+  ): Promise<SessionDescriptor> => {
+    const s = await mgr.spawn(
+      p.cwd,
+      p.name,
+      p.prompt,
+      p.cols,
+      p.rows,
+      p.resume,
+      p.namedBy,
+      p.agent,
+      p.parent,
+      p.overrides,
+      id,
+      p.target,
+      materialized,
+    );
+
+    const runtime = runtimes.get(s.id);
+
+    if (runtime !== undefined) {
+      runtime.pendingLastUsed = true;
+    }
+
+    void store.recordSpawnDir(p.cwd);
+
+    return getDescriptor(mgr, s.id);
+  };
+
+  // A retried spawn answers with the session as it stands now when it is
+  // listed, else with the descriptor the first spawn answered. A key that
+  // start-up reconciliation completed has no stored answer, and its session
+  // lists only once the fleet is restored.
+  const loadSpawnReplay = (record: IdempotencyRecord): Readonly<Record<string, unknown>> => {
+    const listed = mgr.collectDescriptors().find((d) => d.id === record.effectRef);
+
+    if (listed !== undefined) {
+      return { session: listed };
+    }
+
+    const stored: unknown = record.result === null ? null : JSON.parse(record.result);
+
+    if (isRecord(stored)) {
+      return stored;
+    }
+
+    throw new DaemonError(
+      'no_such_session',
+      `the spawn under idempotency key '${record.key}' created session '${record.effectRef}', which is not listed; restore the fleet to list it`,
+      { effectRef: record.effectRef },
+    );
+  };
+
+  const ledger = new IdempotencyLedger(store, LOCAL_PRINCIPAL);
+
+  // Throws the refusal a fresh spawn to the target gets when the access
+  // does not reach the target, and the identity, a held spawn key recorded
+  // for its session. A key that records none is refused: nothing it holds
+  // shows where its session ran.
+  const requireReplayInReach = (record: IdempotencyRecord, access: TargetAccess): void => {
+    const bound = record.effectTarget;
+
+    if (bound === null) {
+      throw buildTargetForbiddenError(findReplayTarget(record));
+    }
+
+    if (!access.canUse(bound)) {
+      throw buildTargetForbiddenError(bound.target);
+    }
+  };
+
+  // Each confirm token a forget handed out, by token: the session it
+  // forgets, when it stops being taken, and whether a forget took it. A
+  // token stays known for one more lifetime after it expires, so a late
+  // forget learns it expired rather than that it never existed.
+  const confirmTokens = new Map<string, ConfirmToken>();
+
+  const forgetConfirmMs = opts.forgetConfirmMs ?? FORGET_CONFIRM_MS;
+
+  const claimConfirmToken = (sessionID: SessionID, token: string) => {
+    const now = Date.now();
+
+    for (const [held, entry] of confirmTokens) {
+      if (entry.expiresAt + forgetConfirmMs < now) {
+        confirmTokens.delete(held);
+      }
+    }
+
+    const entry = confirmTokens.get(token);
+    let reason: 'unknown' | 'used' | 'expired' | null = null;
+
+    if (entry === undefined || entry.session !== sessionID) {
+      reason = 'unknown';
+    } else if (entry.used) {
+      reason = 'used';
+    } else if (entry.expiresAt <= now) {
+      reason = 'expired';
+    }
+
+    if (reason !== null) {
+      throw new DaemonError(
+        'confirm_token_invalid',
+        `confirm token for session ${sessionID} is ${reason}; call session.forget without a token for a new one`,
+        { reason },
+      );
+    }
+
+    confirmTokens.set(token, {
+      session: sessionID,
+      expiresAt: entry?.expiresAt ?? now,
+      used: true,
+    });
+  };
+
+  // Why the session refuses a message right now, or null when it takes one.
+  const findMessageRefusal = (sessionID: SessionID): MessageRefusal | null => {
+    const s = mgr.sessions.find((x) => x.id === sessionID);
+
+    if (s === undefined) {
+      return 'missing';
+    }
+
+    if (!(s.pty !== null || (s.kind === 'headless' && s.state !== 'exited'))) {
+      return 'dead';
+    }
+
+    if (mgr.findAdapter(s.agent)?.takesMessages !== true) {
+      return 'unsupported';
+    }
+
+    const runtime = runtimes.get(sessionID);
+
+    if (
+      runtime !== undefined &&
+      runtime.startedAt !== null &&
+      !runtime.tapAttached &&
+      Date.now() - runtime.startedAt >= (opts.tapGraceMs ?? TAP_GRACE_MS)
+    ) {
+      return 'no_tap';
+    }
+
+    return null;
+  };
+
+  // Writes the message under the id given, notes it in the trail, and hands
+  // it to the session's tap when one is attached. Only the write itself can
+  // reject: every later step swallows its own failure, so a rejection means
+  // no message was written.
+  const writeAcceptedMessage = async (
+    sessionID: SessionID,
+    from: string,
+    text: string,
+    id: MessageID,
+  ): Promise<MessageRecord> => {
+    const s = mgr.sessions.find((x) => x.id === sessionID);
+    const previousWrite = lastMessageWrite;
+    const written = Promise.withResolvers<void>();
+
+    lastMessageWrite = written.promise;
+
+    await previousWrite;
+
+    const record: MessageRecord = {
+      id,
+      atcID: sessionID,
+      ...(s?.agentSessionID === undefined ? {} : { agentSessionID: s.agentSessionID }),
+      from,
+      text,
+      status: 'accepted',
+      sentAt: Date.now(),
+    };
+
+    try {
+      await store.writeMessage(record);
+
+      await recordMessageStatus(sessionID, record);
+    } finally {
+      written.resolve();
+    }
+
+    await drainInbox(sessionID);
+
+    return record;
+  };
+
+  // A retried send answers with the message's current status, so a caller
+  // that lost the first answer learns where its message stands now.
+  const loadMessageReplay = async (
+    record: IdempotencyRecord,
+  ): Promise<Readonly<Record<string, unknown>>> => {
+    const current = await store.findMessageByID(toMessageID(record.effectRef));
+
+    if (current !== null) {
+      return { message: current.id, status: current.status };
+    }
+
+    const stored: unknown = record.result === null ? null : JSON.parse(record.result);
+
+    if (isRecord(stored)) {
+      return stored;
+    }
+
+    throw new DaemonError(
+      'internal',
+      `the message under idempotency key '${record.key}' has no stored row`,
+      { effectRef: record.effectRef },
+    );
+  };
+
+  // Stops the headless runs a kill or forget ended, once the manager has
+  // acted: a session it removed already lost its run with its runtime, a
+  // session it left exited loses it here, and a sub-session it promoted, or
+  // any session of a kill or forget that failed, keeps working.
+  const stopEndedHeadlessRuns = (set: readonly Session[]) => {
+    for (const s of set) {
+      if (s.state === 'exited') {
+        runtimes.get(s.id)?.stopHeadlessRun();
+      }
+    }
+  };
 
   const ctx: DaemonContext = {
     build: opts.build,
+    daemonID: store.daemonID,
     collectSessions: () => mgr.collectDescriptors(),
     collectSpawnDirs: () => store.collectSpawnDirs(),
     collectAgents: () => ({
@@ -664,35 +1151,67 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         build: opts.build,
       },
       agents: buildAgentList(mgr.collectAdapters(), (bin) => Bun.which(bin) !== null),
+      targets: buildTargetList(targets, defaultTarget),
+      spawnDefaults: { agent: 'claude', target: defaultTarget },
+      configRevision,
+      targetErrors,
     }),
     collectFleet: () => store.loadFleet(),
     loadLastUsedAgent: () => store.loadLastUsedAgent(),
     findAdapter: (kind) => mgr.findAdapter(kind),
-    spawnSession: (p) => {
-      const s = mgr.spawn(
-        p.cwd,
-        p.name,
-        p.prompt,
-        p.cols,
-        p.rows,
-        p.resume,
-        p.namedBy,
-        p.agent,
-        p.parent,
-      );
-
-      const runtime = runtimes.get(s.id);
+    buildTargetAccess: (principal) => buildTargetAccess(principals, targetsByID, principal),
+    findSessionGrant: (id) => {
+      const s = mgr.sessions.find((x) => x.id === id);
 
-      if (runtime !== undefined) {
-        runtime.pendingLastUsed = true;
-        runtime.dims = { cols: p.cols, rows: p.rows };
+      return s === undefined ? null : { target: s.target, targetIdentity: s.targetIdentity };
+    },
+    findTargetIdentity: (target) => targets.find((x) => x.id === target)?.identity ?? null,
+    collectChildIDs: (id) => mgr.collectChildren(id).map((child) => child.id),
+    findPermissionSession: (request) => registry.findSessionID(request),
+    resolveSpawnTarget: (requested) => {
+      const target = requested ?? defaultTarget;
+      const refusal = mgr.findExecutionRefusal({ target, targetIdentity: null }, 'spawn');
+
+      if (refusal !== null) {
+        throw refusal;
+      }
 
-        runtime.screen = new ScreenModel(p.cols, p.rows);
+      if (target === null) {
+        throw new Error('a spawn without a target passed its checks');
       }
 
-      void store.recordSpawnDir(p.cwd);
+      return target;
+    },
+    requireWorkspaceTarget: (target) => {
+      mgr.requireExecution({ target, targetIdentity: null }, 'transfer');
+      mgr.requireExecution({ target, targetIdentity: null }, 'run');
+    },
+    spawnSession: (plan, keyed, access) => {
+      if (keyed === null) {
+        return startSpawn(plan(), mintSessionID());
+      }
 
-      return getDescriptor(mgr, s.id);
+      const effectRef = mintSessionID();
+
+      return ledger.run({
+        operation: 'session.spawn',
+        keyed,
+        effectRef,
+        start: () => startSpawn(plan(), effectRef),
+        settle: () => mgr.writeFleet(),
+        replay: (record) => {
+          if (access !== null) {
+            requireReplayInReach(record, access);
+          }
+
+          return loadSpawnReplay(record);
+        },
+        findEffectTarget: () => {
+          const s = mgr.sessions.find((x) => x.id === effectRef);
+
+          return s === undefined ? null : { target: s.target, targetIdentity: s.targetIdentity };
+        },
+      });
     },
     updateSession: (id, name, pinned) => mgr.updateSession(id, name, pinned),
     quitDaemon: () => {
@@ -707,20 +1226,60 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       }, 80);
     },
     killSession: async (id) => {
-      if (!mgr.sessions.some((s) => s.id === id)) {
+      const s = mgr.sessions.find((x) => x.id === id);
+
+      if (s === undefined) {
         return false;
       }
 
-      for (const child of mgr.collectChildren(id)) {
-        runtimes.get(child.id)?.stopHeadlessRun();
+      for (const live of [s, ...mgr.collectChildren(id)]) {
+        if (live.pty !== null) {
+          mgr.requireExecution(live, mgr.pickKillCapability(live));
+        }
       }
 
-      runtimes.get(id)?.stopHeadlessRun();
+      const set = [s, ...mgr.collectChildren(id)];
 
       await mgr.kill(id);
 
+      stopEndedHeadlessRuns(set);
+
       return true;
     },
+
+    // A forget on a target that cannot destroy its host forgets at once. On
+    // one that can, a forget without a token checks the target and answers
+    // with a token, and the forget that carries the token destroys the host.
+    forgetSession: async (id, confirmToken) => {
+      const s = mgr.sessions.find((x) => x.id === id);
+
+      if (s === undefined) {
+        return 'missing';
+      }
+
+      if (mgr.findProvider(s)?.capabilities.destroy === true) {
+        mgr.requireExecution(s, 'destroy');
+
+        if (confirmToken === undefined) {
+          const token = randomUUID();
+          const expiresAt = Date.now() + forgetConfirmMs;
+
+          confirmTokens.set(token, { session: id, expiresAt, used: false });
+
+          return { confirmToken: token, expiresAt };
+        }
+
+        claimConfirmToken(id, confirmToken);
+      }
+
+      const set = [s, ...mgr.collectChildren(id)];
+
+      const destroyed = await mgr.forget(id);
+
+      stopEndedHeadlessRuns(set);
+
+      return { forgotten: true, destroyed };
+    },
     ejectSession: (id, prompt) => {
       const s = mgr.sessions.find((x) => x.id === id);
 
@@ -738,6 +1297,9 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         return 'no_transcript';
       }
 
+      mgr.requireExecution(s, 'kill');
+      mgr.requireExecution(s, 'headless');
+
       const yanked = mgr.yankHeadless(id);
 
       if (yanked === null) {
@@ -761,7 +1323,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
       return 'ok';
     },
-    adoptSession: (id, cols, rows) => {
+    adoptSession: async (id, cols, rows) => {
       if (!hasResumableTranscript(mgr, id)) {
         return 'no_transcript';
       }
@@ -769,20 +1331,13 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       const runtime = runtimes.get(id);
 
       runtime?.stopHeadlessRun();
-      const adopted = mgr.adoptTerminal(id, cols, rows);
+
+      const adopted = await mgr.adoptTerminal(id, cols, rows);
 
       if (adopted === null) {
         return 'missing';
       }
 
-      if (runtime !== undefined) {
-        runtime.dims = { cols, rows };
-        runtime.startedAt = null;
-        runtime.tapAttached = false;
-
-        runtime.screen ??= new ScreenModel(cols, rows);
-      }
-
       scheduleResize(id);
 
       return 'ok';
@@ -821,6 +1376,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         return 'dead';
       }
 
+      mgr.requireExecution(s, 'attach');
       attachments.attach(sessionID, client, dims);
       mgr.attach(sessionID);
 
@@ -861,7 +1417,15 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         return 'missing';
       }
 
+      // A headless turn runs only through the session's own target, never
+      // anywhere else, and a dead session takes no input.
       if (s.kind === 'headless') {
+        mgr.requireExecution(s, 'headless');
+
+        if (s.state === 'exited') {
+          return 'dead';
+        }
+
         if ((runtimes.get(sessionID)?.headlessRun ?? null) !== null) {
           return 'busy';
         }
@@ -881,10 +1445,35 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         return 'dead';
       }
 
+      mgr.requireExecution(s, 'input');
       s.pty.write(data);
 
       return 'ok';
     },
+    writeSessionLine: (sessionID, text) => {
+      const s = mgr.sessions.find((x) => x.id === sessionID);
+
+      // A headless turn takes the line as its prompt, and a missing or dead
+      // session refuses a line as it refuses raw input.
+      if (s === undefined || s.kind === 'headless' || s.pty === null) {
+        return ctx.writeSessionInput(sessionID, text);
+      }
+
+      mgr.requireExecution(s, 'input');
+
+      const bracketedPaste = runtimes.get(sessionID)?.screen?.hasBracketedPaste() ?? false;
+      const adapter = mgr.findAdapter(s.agent);
+      const writes = adapter?.planLineInput?.(text, { bracketedPaste }) ?? planTypedLineInput(text);
+
+      // Every write goes out in the tick the request arrives in, so no input
+      // overtakes the line and none lands between the text and its submit
+      // key.
+      for (const data of writes) {
+        s.pty.write(data);
+      }
+
+      return 'ok';
+    },
     resizeSession: (client, sessionID, dims) => {
       if (!attachments.updateDims(sessionID, client, dims)) {
         return false;
@@ -950,9 +1539,9 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
 
       return { path, page };
     },
-    readEvents: async (afterID, limit, waitMs, sessionID) => {
+    readEvents: async (afterID, limit, waitMs, sessionID, access) => {
       const deadline = Date.now() + waitMs;
-      const scope = sessionID === null ? null : buildEventScope(sessionID);
+      const scope = buildEventScope(sessionID, access);
 
       // A wake for an event the read leaves out (a heartbeat, or another
       // session's event under a session filter) loops back to wait out the
@@ -979,60 +1568,51 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         await eventSignal.waitForNext(generation, remaining);
       }
     },
-    writeSessionMessage: async (sessionID, from, text) => {
-      const s = mgr.sessions.find((x) => x.id === sessionID);
+    writeSessionMessage: async (sessionID, from, text, keyed) => {
+      if (keyed === null) {
+        const refusal = findMessageRefusal(sessionID);
 
-      if (s === undefined) {
-        return 'missing';
-      }
+        if (refusal !== null) {
+          return refusal;
+        }
 
-      if (!(s.pty !== null || (s.kind === 'headless' && s.state !== 'exited'))) {
-        return 'dead';
-      }
+        const record = await writeAcceptedMessage(sessionID, from, text, mintMessageID());
 
-      if (mgr.findAdapter(s.agent)?.takesMessages !== true) {
-        return 'unsupported';
+        return { message: record.id, status: record.status };
       }
 
-      const runtime = runtimes.get(sessionID);
+      const effectRef = mintMessageID();
 
-      if (
-        runtime !== undefined &&
-        runtime.startedAt !== null &&
-        !runtime.tapAttached &&
-        Date.now() - runtime.startedAt >= (opts.tapGraceMs ?? TAP_GRACE_MS)
-      ) {
-        return 'no_tap';
-      }
+      try {
+        return await ledger.run({
+          operation: 'session.message',
+          keyed,
+          effectRef,
 
-      const previousWrite = lastMessageWrite;
-      const written = Promise.withResolvers<void>();
+          // A refusal throws, so the claim drops and a retry runs fresh.
+          start: async () => {
+            const refusal = findMessageRefusal(sessionID);
 
-      lastMessageWrite = written.promise;
+            if (refusal !== null) {
+              throw new MessageRefusedError(refusal);
+            }
 
-      await previousWrite;
+            const record = await writeAcceptedMessage(sessionID, from, text, effectRef);
 
-      const record: MessageRecord = {
-        id: mintMessageID(),
-        atcID: sessionID,
-        ...(s.agentSessionID === undefined ? {} : { agentSessionID: s.agentSessionID }),
-        from,
-        text,
-        status: 'accepted',
-        sentAt: Date.now(),
-      };
+            return { message: record.id, status: record.status };
+          },
 
-      try {
-        await store.writeMessage(record);
+          // The message row is the effect, and the start already wrote it.
+          settle: () => Promise.resolve(),
+          replay: (record) => loadMessageReplay(record),
+        });
+      } catch (error) {
+        if (error instanceof MessageRefusedError) {
+          return error.refusal;
+        }
 
-        await recordMessageStatus(sessionID, record);
-      } finally {
-        written.resolve();
+        throw error;
       }
-
-      await drainInbox(sessionID);
-
-      return record;
     },
     attachTap: (client, sessionID) => {
       const s = mgr.sessions.find((x) => x.id === sessionID);
@@ -1149,10 +1729,16 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
       client.dispose();
     }
 
+    clearInterval(idempotencySweep);
+
     server.stop(true);
     eventsServer?.stop();
     reporter.stop(true);
-    mgr.killAll();
+    mgr.detachAll();
+
+    for (const target of targets) {
+      target.provider?.dispose();
+    }
 
     for (const runtime of runtimes.values()) {
       runtime.dispose();
@@ -1216,6 +1802,12 @@ function hasResumableTranscript(mgr: SessionManager, id: SessionID): boolean {
     return false;
   }
 
+  // A remote session's transcript lives in its host, out of the daemon's
+  // reach, so the agent's session id alone makes it resumable.
+  if (mgr.findProvider(s)?.remote === true) {
+    return s.agentSessionID !== undefined;
+  }
+
   return adapter.canResume({
     ...(s.agentSessionID === undefined ? {} : { agentSessionID: s.agentSessionID }),
     ...(s.transcriptSource === undefined ? {} : { transcriptSource: s.transcriptSource }),
@@ -1231,3 +1823,45 @@ function getDescriptor(mgr: SessionManager, id: SessionID): SessionDescriptor {
 
   return d;
 }
+
+// A sweep that fails leaves the keys for the next one.
+async function tryRemoveExpiredIdempotencyKeys(store: StateStore): Promise<boolean> {
+  try {
+    await store.removeExpiredIdempotencyKeys(Date.now() - IDEMPOTENCY_TTL_MS);
+  } catch {
+    return false;
+  }
+
+  return true;
+}
+
+interface ConfirmToken {
+  readonly session: SessionID;
+  readonly expiresAt: number;
+  readonly used: boolean;
+}
+
+// Carries a message refusal out of a keyed send's start, so the claim drops
+// and the refusal still answers the request.
+class MessageRefusedError extends Error {
+  readonly refusal: MessageRefusal;
+
+  constructor(refusal: MessageRefusal) {
+    super(`message refused: ${refusal}`);
+
+    this.refusal = refusal;
+    this.name = 'MessageRefusedError';
+  }
+}
+
+// The target a held spawn key's stored answer holds its session on, for a
+// refusal of its replay; the answer holds no other target to name.
+function findReplayTarget(record: IdempotencyRecord): string {
+  const stored: unknown = record.result === null ? null : JSON.parse(record.result);
+  const session = isRecord(stored) ? stored['session'] : null;
+  const locator = isRecord(session) ? session['locator'] : null;
+
+  return isRecord(locator) && typeof locator['targetID'] === 'string'
+    ? locator['targetID']
+    : 'unknown';
+}