@moondeck/station 0.0.1 → 1.0.1

package/lib/agents/types.ts

@@ -0,0 +1,254 @@
+/**
+ * The agent abstraction.
+ *
+ * uai drives Claude Code and Codex in their structured modes (see
+ * docs/interaction-model.md). Both — plus a mock for testing — implement
+ * the same `AgentSession` interface, so the orchestrator and chat UI
+ * never branch on which CLI is behind a given agent.
+ *
+ * An "agent" is a roster entry on a project, not a hardcoded
+ * Claude/Codex pair. A project can run one agent or several; each has a
+ * stable `id` used for addressing (`@<id>`).
+ */
+
+import { z } from "zod";
+
+import type { EngineUsageWindow } from "../../src/protocol";
+import type { TaskEnvironmentAgentSessionSurface } from "../task-environment/types";
+
+/** The host-advertised adapter kind ("claude" | "codex" | "gemini" | …). */
+export const AgentKind = z
+  .string()
+  .min(1)
+  .regex(/^[a-z0-9][a-z0-9_-]*$/, "kind must be lowercase letters, digits, _ or -");
+export type AgentKind = z.infer<typeof AgentKind>;
+
+/** A task agent (ADR-021/ADR-022) — materialised onto a task.
+ *
+ *  `id` must be URL-safe (letters, digits, `_`, `-`) because it is the
+ *  `@<id>` mention token. `kind` selects the adapter; `model` is passed
+ *  through to the CLI. There is no `role` field. `initialPrompt` (if set)
+ *  drives this agent's first turn at container-ready. */
+/** Reference material (a link or inline document) materialised onto an agent
+ *  from its persona + team (ADR-046). The host writes these to a per-agent
+ *  SKILL.md at session start. */
+export const RosterSkill = z.object({
+  name: z.string().min(1),
+  type: z.string().min(1), // 'link' | 'document' | 'package' (ADR-047)
+  value: z.string(),
+  // ADR-047 package skills: 'git' | 'cli' install mode + (git) repo subpath.
+  source: z.string().nullable().optional(),
+  subpath: z.string().nullable().optional(),
+});
+export type RosterSkill = z.infer<typeof RosterSkill>;
+
+export const RosterAgent = z.object({
+  id: z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z0-9_-]+$/, "id must be url-safe: letters, digits, _ or -"),
+  label: z.string().min(1), // display name
+  kind: AgentKind,
+  model: z.string().min(1).optional(),
+  effort: z.string().min(1).optional(), // CLI reasoning level, passed through
+  // ADR-157 addendum §7: preferred cloud-leased AI account.
+  accountId: z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9_.:-]+$/)
+    .optional(),
+  accountBinding: z.enum(["required", "preferred"]).optional(),
+  defaultPrompt: z.string().optional(), // persona
+  initialPrompt: z.string().optional(), // first-turn instructions, this task only
+  skills: z.array(RosterSkill).optional(), // ADR-046 reference material
+  permissions: z.array(z.string()).optional(), // ADR-048 `uai` CLI capabilities
+  // ADR-128: which upstream protocol a Uai-engine model speaks — resolved
+  // cloud-side from the model catalog; selects the delegated adapter.
+  uaiProvider: z.enum(["anthropic", "openai"]).optional(),
+  builtIn: z.literal("astronaut").optional(), // ADR-157: the cloud-built Astronaut only
+  // ADR-157 §3: signed into the agent's task token as `g` (see agentCliEnv).
+  tokenGeneration: z.string().min(1).max(64).optional(),
+});
+export type RosterAgent = z.infer<typeof RosterAgent>;
+
+/** A task's agents — distinct ids so a mention routes unambiguously. May be
+ *  empty (a scratchpad task with no crew). */
+export const Roster = z
+  .array(RosterAgent)
+  .refine((agents) => new Set(agents.map((a) => a.id)).size === agents.length, {
+    message: "agent ids must be unique within a roster",
+  });
+export type Roster = z.infer<typeof Roster>;
+
+/**
+ * Parse a task's `agents` JSON into a validated Roster. Falls back to an
+ * empty roster if malformed.
+ */
+export function parseRoster(raw: string): Roster {
+  try {
+    const parsed = Roster.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : [];
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Events an agent session emits as it works. The orchestrator persists
+// these to `uai_messages` and streams them to the browser.
+// ---------------------------------------------------------------------------
+
+/**
+ * Token + cost accounting for one turn, extracted from the agent CLI's result
+ * envelope where it reports it (Claude Code gives `usage` + `total_cost_usd`
+ * directly). Powers per-task cost visibility for self-hosted users and the
+ * metering pipeline for managed Uai-provided AI. All fields optional — an
+ * engine that doesn't report a dimension omits it.
+ */
+export interface AgentUsage {
+  /** Model the CLI actually billed (may differ from the configured model, e.g. a sub-agent). */
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheCreateTokens?: number;
+  /** Total USD for the turn, as reported by the CLI (authoritative when present). */
+  costUsd?: number;
+}
+
+/** Secret-free account usage exactly as an engine CLI reported it. The
+ * orchestrator adds task/account identity only after proving the session is
+ * running on a cloud-leased account. */
+export interface AgentAccountUsage {
+  status: "allowed" | "warning" | "limited";
+  resetsAt?: number;
+  usingOverage?: boolean;
+  windows: EngineUsageWindow[];
+  source: "claude-rate-limit-event" | "codex-rate-limits" | "error-text" | "cursor-period-usage";
+  observedAt: number;
+  /** Which provider capacity this reading can prove usable again. Claude emits
+   * one event per named window; Codex snapshots cover every window. Internal
+   * runner metadata only: it is deliberately not part of engine.usage. */
+  coverage?:
+    | { kind: "window"; window: string }
+    | { kind: "all-windows" };
+}
+
+export type AgentEvent =
+  /** A chunk of streaming assistant text. Appended to the in-progress message. */
+  | { type: "message_delta"; text: string }
+  /** The assistant message finished. `text` is the full final text. */
+  | { type: "message_complete"; text: string }
+  /** The agent invoked a tool / ran a command. Rendered as a card. */
+  | { type: "tool_call"; id: string; title: string; detail: string }
+  /** ADR-083: the designated secretary invoked Uai's typed dispatch tool. */
+  | {
+      type: "dispatch";
+      dispatchId: string;
+      recipients: string[];
+      instruction: string;
+    }
+  /** The agent needs approval before proceeding. */
+  | { type: "permission_request"; id: string; title: string; detail: string }
+  /** The agent addressed another agent — uai routes this as a peer message. */
+  | { type: "peer_message"; toAgentId: string; text: string }
+  /** The provider turn is done; it may have absorbed multiple deliveries.
+   *  `usage` carries this turn's token/cost accounting when the CLI reports it. */
+  | {
+      type: "turn_complete";
+      usage?: AgentUsage;
+      aborted?: boolean;
+      /** Logical deliveries combined into this one provider turn (default 1). */
+      settles?: number;
+    }
+  /** Account-level capacity reported by the engine CLI. This never contains
+   * credentials or provider account identifiers. */
+  | { type: "account_usage"; usage: AgentAccountUsage }
+  /** A nonterminal operation failed; leave the current message running. */
+  | { type: "notice"; message: string }
+  /** A recoverable error surfaced by the agent. `retryable` marks errors the
+   *  orchestrator can fail over from — "rate_limit" triggers account rotation
+   *  (ADR-076). */
+  | {
+      type: "error";
+      message: string;
+      /** Host-only full diagnostic for classification. Never put on the wire. */
+      diagnosticMessage?: string;
+      /** A short, scrubbed account of an upstream failure on a custom connection
+       *  (HTTP status and an excerpt of its message), safe for the chat. Set only
+       *  by the connection sanitizer (custom-connection-runtime.ts). */
+      detail?: string;
+      /** Provider RPC error code, when supplied. */
+      code?: number;
+      /** The adapter has ended the accepted turn, including before output. */
+      aborted?: boolean;
+      retryable?: "rate_limit";
+      /** Parsed from the same rate-limit error text, when unambiguous. */
+      resetsAt?: number;
+    }
+  /** The underlying process exited. */
+  | { type: "exit"; code: number };
+
+export type AgentEventHandler = (event: AgentEvent) => void;
+
+/**
+ * A live session with one agent. Implementations: ClaudeSession
+ * (stream-json), CodexSession (codex app-server), MockAgentSession.
+ */
+export interface AgentSession {
+  /** The roster id this session is for. */
+  readonly agentId: string;
+  /** Which agent kind backs it ("claude" | "codex" | …). */
+  readonly kind: AgentKind;
+
+  /** Send a user (or routed peer) message into the agent. */
+  send(text: string): Promise<void>;
+
+  /** Interrupt the agent's current turn (ESC). Idempotent / safe when idle. */
+  interrupt(): Promise<void>;
+
+  /** Resolve a pending permission request. */
+  resolvePermission(
+    requestId: string,
+    decision: "accept" | "decline",
+  ): Promise<void>;
+
+  /** Subscribe to events. Returns an unsubscribe function. */
+  onEvent(handler: AgentEventHandler): () => void;
+
+  /** Tear the session down. Idempotent. */
+  close(): Promise<void>;
+}
+
+/**
+ * Constructs an AgentSession for a roster entry. The orchestrator is
+ * handed one of these; swapping mock ⇄ real adapters is changing the
+ * factory, nothing else.
+ */
+export interface AgentSessionFactory {
+  create(args: {
+    taskId: string;
+    agent: RosterAgent;
+    /** Provider-owned process/session surface for this task environment. */
+    environment: TaskEnvironmentAgentSessionSurface;
+    /** Initial briefing — project.defaultPrompt — sent on session start. */
+    systemPreamble: string;
+    /** Host-derived restricted execution policy (ADR-083). Never supplied by
+     *  the browser or stored on the roster entry. */
+    executionProfile?: "communicator" | "astronaut";
+    /** Durable runners are keyed by task+agent. Host-owned launch settings
+     *  supply a compatibility key so restart recovery replaces, rather than
+     *  attaches, a process launched with incompatible model/effort/policy. */
+    attachCompatibilityKey?: string;
+    /** ADR-048: extra per-agent process environment (e.g. this agent's own
+     *  UAI_TASK_TOKEN so its `uai` CLI carries only its own permissions). */
+    agentEnv?: Record<string, string>;
+    /** ADR-128: engine config overrides a DELEGATING adapter prepends (codex
+     *  `-c key=value`), e.g. the Uai Managed Engine's model-provider block
+     *  that points codex at the inference gateway. Never from the roster. */
+    cliConfigOverrides?: string[];
+    /** Host-generated per-launch Claude settings; never from roster input. */
+    claudeSettings?: Record<string, unknown>;
+  }): Promise<AgentSession>;
+}

package/lib/agents/uai.ts

@@ -0,0 +1,106 @@
+/**
+ * The Uai Managed Engine (ADR-128) — not a harness, a delegation.
+ *
+ * The customer picks "Uai Managed Engine" and one of Uai's models; under
+ * the hood this adapter spawns the EXISTING claude or codex adapter
+ * (chosen by the model's provider, resolved cloud-side into
+ * `agent.uaiProvider`) with the environment pointed at the inference
+ * gateway: base URL swapped, the agent's own task token as the API
+ * credential, and the host's real provider credentials explicitly
+ * BLANKED so a BYO host's Claude subscription can never be billed for a
+ * Uai-engine turn. The gateway meters usage server-side and the cloud
+ * debits credits — this file never sees money.
+ *
+ * The model slug passes through verbatim: the underlying CLI sends it as
+ * the request's `model`, and the gateway maps slug → upstream id.
+ */
+
+import { STATION_DEFAULT_GATEWAY_URL } from "../../src/station-identity";
+import { codexProviderOverrides, endpointAuthEnv } from "../custom-connection-launch";
+import { factoryFor, register, supportsExecutionProfile } from "./registry";
+import type { AgentSession, AgentSessionFactory } from "./types";
+
+const DEFAULT_GATEWAY_URL = STATION_DEFAULT_GATEWAY_URL;
+
+export function gatewayUrl(): string {
+  return process.env.UAI_INFERENCE_GATEWAY_URL || DEFAULT_GATEWAY_URL;
+}
+
+/** The env override set for a delegated session. Exported for tests. */
+export function uaiGatewayEnv(
+  provider: "anthropic" | "openai",
+  url: string,
+  taskToken: string,
+): Record<string, string> {
+  return endpointAuthEnv(provider, url, taskToken, "bearer", "UAI_INFERENCE_TOKEN");
+}
+
+/**
+ * Codex does NOT follow `OPENAI_BASE_URL` / `OPENAI_API_KEY` for its default
+ * provider any more: with a ChatGPT login present it opens
+ * `wss://api.openai.com/v1/responses` directly and sends no bearer (live
+ * 2026-09-12: "401 Missing bearer or basic authentication", five
+ * reconnects, turn never answered). A dedicated model provider pins the
+ * gateway as the base URL, the HTTP Responses wire (the gateway serves
+ * `/v1/responses`, not WebSockets), and the task token via `env_key`;
+ * `requires_openai_auth=false` keeps the host's Codex login out of a
+ * gateway-billed session. Codex parses `-c` values as TOML, hence the
+ * quotes on strings.
+ */
+export function uaiCodexOverrides(url: string): string[] {
+  const base = `${url.replace(/\/+$/, "")}/v1`;
+  return codexProviderOverrides(base, { provider: "uai", name: "Moondeck AI", envKey: "UAI_INFERENCE_TOKEN" });
+}
+
+const create: AgentSessionFactory["create"] = async (args): Promise<AgentSession> => {
+  const provider = args.agent.uaiProvider === "openai" ? "openai" : "anthropic";
+  const delegateKind = provider === "openai" ? "codex" : "claude";
+  const delegate = factoryFor(delegateKind);
+  if (!delegate) {
+    throw new Error(`uai engine: no ${delegateKind} adapter registered to delegate to`);
+  }
+  // ADR-157 §7: the runner checked the profile against the `uai` kind, but the
+  // delegate is what enforces it. Refuse rather than run an Astronaut on a
+  // delegate that would ignore the profile.
+  if (
+    args.executionProfile &&
+    !supportsExecutionProfile(delegateKind, args.executionProfile)
+  ) {
+    throw new Error(
+      `uai engine: the ${delegateKind} adapter cannot enforce execution profile "${args.executionProfile}"`,
+    );
+  }
+  const taskToken = args.agentEnv?.UAI_TASK_TOKEN;
+  if (!taskToken) {
+    // agentCliEnv mints one for every managed-engine agent, permissions or
+    // not; none here means the task has no owner, API url or CLI secret.
+    throw new Error(
+      "uai engine: this agent has no task token (the task has no CLI identity yet) — restart the task",
+    );
+  }
+  return delegate.create({
+    ...args,
+    agentEnv: {
+      ...(args.agentEnv ?? {}),
+      ...uaiGatewayEnv(provider, gatewayUrl(), taskToken),
+    },
+    ...(provider === "openai" ? { cliConfigOverrides: uaiCodexOverrides(gatewayUrl()) } : {}),
+  });
+};
+
+register({
+  kind: "uai",
+  label: "Moondeck AI",
+  // The model catalog is cloud data (ADR-128); the composer sources it from
+  // /api/org/inference/models, never from host capabilities. Advertising an
+  // empty list here simply marks the kind spawnable on this host.
+  supportedModels: () => [],
+  supportedEfforts: () => [],
+  // Always available: the engine needs no host-side credential — auth is
+  // the per-agent task token, billing is the org's credits.
+  available: () => true,
+  // ADR-157: `create` forwards the profile to the Claude or Codex delegate,
+  // and both enforce it.
+  executionProfiles: [{ id: "astronaut", mechanism: "uai-delegated-astronaut-v1" }],
+  create,
+});

package/lib/agents/usage.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared token/cost extraction for a stream-json `result` envelope (ADR-071
+ * metering). Claude Code reports snake_case `usage` plus `total_cost_usd` and
+ * per-model `modelUsage`. cursor-agent 2026.10.x reports camelCase counts and
+ * no cost: `{inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens}`.
+ * Snake_case wins when a field is present, so Claude's path is unchanged.
+ *
+ * Codex (app-server protocol) and Kimi/Grok (plain text streams) report no
+ * token/cost data through this extractor.
+ */
+
+import type { AgentUsage } from "./types";
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/** Claude's name when it is a number, otherwise Cursor 2026.10's. */
+function firstNum(claude: unknown, cursor: unknown): number | undefined {
+  const primary = num(claude);
+  return primary !== undefined ? primary : num(cursor);
+}
+
+/** Pull AgentUsage from a `result` line, or undefined when none is reported. */
+export function extractResultUsage(
+  json: Record<string, unknown>,
+): AgentUsage | undefined {
+  const u = isObj(json.usage) ? json.usage : {};
+  const models = isObj(json.modelUsage) ? Object.keys(json.modelUsage) : [];
+  const usage: AgentUsage = {
+    model: models.length ? models.join(", ") : undefined,
+    inputTokens: firstNum(u.input_tokens, u.inputTokens),
+    outputTokens: firstNum(u.output_tokens, u.outputTokens),
+    cacheReadTokens: firstNum(u.cache_read_input_tokens, u.cacheReadTokens),
+    cacheCreateTokens: firstNum(u.cache_creation_input_tokens, u.cacheWriteTokens),
+    costUsd: num(json.total_cost_usd),
+  };
+  // Nothing usable reported → omit rather than send an empty object.
+  return Object.values(usage).some((v) => v !== undefined) ? usage : undefined;
+}

package/lib/apple-one-off.ts

@@ -0,0 +1,277 @@
+/**
+ * A one-off container on the Apple runtime (ADR-106), and nothing of it left
+ * behind (#p2jdax).
+ *
+ * `container run --rm` removes only a container that started. A run the
+ * runtime refuses leaves a created-never-started container, and those wedge
+ * the runtime's apiserver: `run` and `delete` hang while `list` and
+ * `inspect` still answer, until the runtime's services are recycled, which
+ * restarts every Apple task (apple-runtime-recycle.ts). A client killed at
+ * its bound (no answer in time, output past its bound) can leave one too, or
+ * a container that goes on running what it was abandoned for. So every
+ * one-off container is named in the closed grammar the recycle's sweep
+ * deletes, with a random part no other run's name has, labelled as Uai's,
+ * and labelled with a token only its own run carries; and its run is
+ * settled after it ends:
+ *
+ * - absent (the runtime says it is not found): done;
+ * - its own (Uai's label and its run's token, on exactly that name):
+ *   deleted, then proven gone; deleted again if it is not; still there, it
+ *   is what wedges the runtime, so the runtime's remedy is asked for, and it
+ *   is proven gone after. Only the runtime's own activation restarts its
+ *   services (it recovers every task after); all other work, and every
+ *   watch, asks the runtime's owner for that activation instead
+ *   (askRuntimeOwnerOnce);
+ * - of that name but not its own: never touched (a name alone is no proof);
+ * - unobservable (the runtime does not answer): nothing is deleted or
+ *   recycled on a guess.
+ *
+ * Whatever is left unproven is watched a while longer, and so is the name of
+ * a run whose client never reported its end (its container can still be
+ * created after): each look that finds it its own settles it again, and the
+ * watch ends only once it is proven gone or removed, or its time is up.
+ */
+
+import { randomBytes } from "node:crypto";
+
+import { MAINTENANCE_CONTAINER_LABEL, type AppleRecycleOutcome } from "./apple-runtime-recycle";
+
+/** The label only one run's container carries: its token. */
+export const MAINTENANCE_TOKEN_LABEL = "io.moondeck.maintenance.token";
+
+/** One run of the Apple `container` CLI. */
+export interface AppleCliResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export type AppleCli = (args: string[], timeoutMs: number) => Promise<AppleCliResult>;
+
+export interface AppleOneOffDeps {
+  cli: AppleCli;
+  /** The runtime's remedy for a container of a run's own that will not go
+   *  (see the module comment). */
+  recycle: () => Promise<AppleRecycleOutcome>;
+  /** Tests only: how the watch waits. */
+  delay?: (ms: number) => Promise<void>;
+}
+
+/** One one-off container: its name, and the token only its run carries. */
+export interface AppleOneOff {
+  readonly name: string;
+  readonly token: string;
+}
+
+/** What a one-off container's name may name, within the recycle sweep's
+ *  grammar (MAINTENANCE_CONTAINER_NAME_RE). */
+const PURPOSE = /^[a-z]+(?:-[a-z]+)*$/;
+const INSPECT_TIMEOUT_MS = 15_000;
+const DELETE_TIMEOUT_MS = 30_000;
+const DELETE_ATTEMPTS = 2;
+/** A watched name is looked for again after each of these waits. */
+const WATCH_MS: readonly number[] = [5_000, 15_000, 60_000, 180_000, 600_000];
+
+let sequence = 0;
+
+/** A new one-off container: a name no other run has had, and its token. */
+export function newAppleOneOff(purpose: string): AppleOneOff {
+  if (!PURPOSE.test(purpose)) throw new Error(`a malformed one-off container purpose: ${purpose}`);
+  sequence += 1;
+  return {
+    name: `moondeck-maint-${purpose}-${process.pid}-${sequence}-${randomBytes(8).toString("hex")}`,
+    token: randomBytes(16).toString("hex"),
+  };
+}
+
+/** The `container run` arguments that name a one-off container, mark it
+ *  Uai's (what the recycle's sweep goes by) and give it its run's token
+ *  (what alone authorizes deleting it here). */
+export function appleOneOffRunArgs(oneOff: AppleOneOff): string[] {
+  return [
+    "--name",
+    oneOff.name,
+    "-l",
+    `${MAINTENANCE_CONTAINER_LABEL}=1`,
+    "-l",
+    `${MAINTENANCE_TOKEN_LABEL}=${oneOff.token}`,
+  ];
+}
+
+/** What one inspection of a one-off container's name finds. */
+export type AppleOneOffPresence = "ours" | "absent" | "foreign" | "unknown";
+
+/**
+ * One observation of `oneOff`'s name: absent only on the runtime's own "not
+ * found"; its own only with Uai's label and its run's token on exactly that
+ * container; of that name without them, foreign; anything else (no answer,
+ * an answer that does not parse), unknown.
+ */
+export async function appleOneOffPresence(cli: AppleCli, oneOff: AppleOneOff): Promise<AppleOneOffPresence> {
+  const { name } = oneOff;
+  const inspected = await cli(["inspect", name], INSPECT_TIMEOUT_MS);
+  if (inspected.code === 0) {
+    try {
+      const parsed = JSON.parse(inspected.stdout) as Array<{
+        id?: unknown;
+        configuration?: { labels?: Record<string, unknown> };
+      }>;
+      if (!Array.isArray(parsed) || parsed.length !== 1 || parsed[0]?.id !== name) return "unknown";
+      const labels = parsed[0]?.configuration?.labels;
+      return labels?.[MAINTENANCE_CONTAINER_LABEL] === "1" && labels?.[MAINTENANCE_TOKEN_LABEL] === oneOff.token
+        ? "ours"
+        : "foreign";
+    } catch {
+      return "unknown";
+    }
+  }
+  if (
+    inspected.code !== null &&
+    inspected.stdout.trim() === "" &&
+    inspected.stderr.split("\n").some((line) => line.trim() === `Error: container not found: ${name}`)
+  ) {
+    return "absent";
+  }
+  return "unknown";
+}
+
+/** How a one-off container's run was settled. */
+export type AppleOneOffSettlement =
+  /** Nothing of that name is there. */
+  | "absent"
+  /** Its own was there: deleted, and proven gone. */
+  | "removed"
+  /** Its own would not go: the runtime's remedy took it, and it is proven
+   *  gone. */
+  | "recycled"
+  /** Of that name but not its own: left untouched. */
+  | "foreign"
+  /** Neither proven gone nor removed. */
+  | "unproven";
+
+/**
+ * Settle `oneOff`'s container once (see the module comment). Never
+ * rejects.
+ */
+export async function settleAppleOneOff(deps: AppleOneOffDeps, oneOff: AppleOneOff): Promise<AppleOneOffSettlement> {
+  const { name } = oneOff;
+  try {
+    let presence = await appleOneOffPresence(deps.cli, oneOff);
+    if (presence === "absent") return "absent";
+    // Only its own is ever deleted.
+    for (let attempt = 0; attempt < DELETE_ATTEMPTS && presence === "ours"; attempt += 1) {
+      await deps.cli(["delete", "--force", name], DELETE_TIMEOUT_MS);
+      presence = await appleOneOffPresence(deps.cli, oneOff);
+    }
+    if (presence === "absent") return "removed";
+    if (presence !== "ours") return leftAlone(name, presence);
+    // Its own, and it will not go: what wedges the runtime.
+    console.warn(`[host-agent] one-off container ${name} could not be deleted; asking for the Apple runtime's remedy`);
+    const outcome = await deps.recycle();
+    presence = await appleOneOffPresence(deps.cli, oneOff);
+    if (presence === "absent") return "recycled";
+    console.warn(
+      `[host-agent] one-off container ${name} is still there (${
+        outcome.recycled ? "the runtime's services were recycled" : outcome.reason
+      }); it is watched, and removed once it can be`,
+    );
+    return "unproven";
+  } catch (error) {
+    console.warn(
+      `[host-agent] one-off container ${name} could not be settled: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return "unproven";
+  }
+}
+
+function leftAlone(name: string, presence: "foreign" | "unknown"): AppleOneOffSettlement {
+  if (presence === "foreign") {
+    console.warn(`[host-agent] a container named ${name} is not this run's own; leaving it untouched`);
+    return "foreign";
+  }
+  console.warn(`[host-agent] could not observe one-off container ${name}; nothing is deleted or recycled on a guess`);
+  return "unproven";
+}
+
+/**
+ * The runtime's remedy for work outside its activation: ask the runtime's
+ * owner, at most once for one run, to recheck the runtime
+ * (container-runtime.ts requestContainerRuntimeRecheck). Its activation
+ * restarts the services of a runtime it finds wedged, then recovers every
+ * task; this never restarts them itself.
+ */
+export function askRuntimeOwnerOnce(
+  recheck: (reason: string) => boolean,
+  reason: string,
+): () => Promise<Extract<AppleRecycleOutcome, { recycled: false }>> {
+  let asked: boolean | null = null;
+  return async () => {
+    asked ??= recheck(reason);
+    return {
+      recycled: false,
+      reason: asked ? "its owner was asked to recheck the runtime" : "no owner of the runtime was there to ask",
+    };
+  };
+}
+
+/**
+ * Whether a run's settlement leaves its name to watch: anything unproven,
+ * and, when its client never reported its end (`lateCreation`: its
+ * container can still be created after), anything short of removed.
+ */
+export function appleOneOffNeedsWatch(settled: AppleOneOffSettlement, lateCreation: boolean): boolean {
+  if (settled === "removed" || settled === "recycled") return false;
+  return settled === "unproven" || lateCreation;
+}
+
+/**
+ * Watch `oneOff`'s name: look for it again after each wait, and settle it
+ * whenever it is found its own; one that cannot be observed, or is not its
+ * own (when `lateCreation`, the name may be its own's later), is looked for
+ * again. Resolves once it is removed or proven gone (absent ends the watch
+ * only where nothing of the run can be created after), or the watch's time
+ * is up; never rejects.
+ */
+export async function watchAppleOneOff(
+  deps: AppleOneOffDeps,
+  oneOff: AppleOneOff,
+  options: { lateCreation: boolean },
+): Promise<AppleOneOffSettlement> {
+  const delay = deps.delay ?? defaultDelay;
+  let last: AppleOneOffSettlement = "unproven";
+  for (const wait of WATCH_MS) {
+    await delay(wait);
+    let presence: AppleOneOffPresence;
+    try {
+      presence = await appleOneOffPresence(deps.cli, oneOff);
+    } catch {
+      presence = "unknown";
+    }
+    if (presence === "absent" || presence === "foreign") {
+      if (!options.lateCreation) return presence;
+      last = presence;
+      continue;
+    }
+    if (presence === "unknown") {
+      last = "unproven";
+      continue;
+    }
+    const settled = await settleAppleOneOff(deps, oneOff);
+    if (settled === "removed" || settled === "recycled") return settled;
+    if (settled !== "unproven" && !options.lateCreation) return settled;
+    last = settled;
+  }
+  return last;
+}
+
+function defaultDelay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+/** Tests only: the name sequence, from the start. */
+export function resetAppleOneOffNamesForTests(): void {
+  sequence = 0;
+}