@moondeck/station 0.0.1 → 1.0.1

package/lib/agent-errors.ts

@@ -0,0 +1,22 @@
+import { stripVTControlCharacters } from "node:util";
+
+import { captureHostError, scrubHostString } from "./obs";
+
+/** Provider errors can quote requests. Keep chat copy short and on one line;
+ * diagnostic reporting retains the full length with the host's redaction. */
+export function agentErrorMessage(message: string): string {
+  const line = stripVTControlCharacters(scrubHostString(message))
+    .replace(/[\s\u0000-\u001f\u007f-\u009f]+/g, " ").trim();
+  return line.length > 300 ? `${line.slice(0, 299).trimEnd()}…` : line;
+}
+
+export function reportAgentError(
+  message: string,
+  context: { taskId: string; agentId: string; engine: string; rpcCode?: number },
+  { capture = true }: { capture?: boolean } = {},
+): void {
+  const diagnostic = scrubHostString(message);
+  console.warn(`[agent] ${context.taskId}/${context.agentId}: ${diagnostic}`);
+  // This uses the existing disclosure/opt-out gate and Sentry scrubber.
+  if (capture) captureHostError(new Error(diagnostic), context);
+}

package/lib/agent.ts

@@ -0,0 +1,672 @@
+/**
+ * Typed wrapper around the host-agent shell scripts.
+ *
+ * The agent's wire contract (docs/agent.md):
+ *   success → stdout: { ok: true, data: ... }
+ *   failure → stderr: { ok: false, error: { code, message, step?, exit_code? } }
+ *   non-zero exit on failure.
+ *
+ * This module shells out to scripts/agent/*.sh (or UAI_AGENT_DIR/*.sh in
+ * production), pipes UAI_DB_PATH + UAI_DATA_DIR into the child, parses
+ * the JSON, and returns typed result objects — or throws AgentError.
+ *
+ * Same-process for MVP (per ADR-004). When uai is extracted to a hosted
+ * product, this module becomes a JSON-RPC client over a websocket; the
+ * surface stays the same.
+ */
+
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+import {
+  createTaskEnvironmentDownCommandDb,
+  createTaskDownCommandDb,
+  createTaskStatusCommandDb,
+  createTaskUpCommandDb,
+  removeCommandDb,
+} from "./command-db";
+import { env } from "./env";
+import { containerRuntimeStandardAssetsRoot } from "./container-runtime";
+import { getDecryptedForProject } from "./host-env";
+import { PreviewPortRuntimesSchema } from "./preview-ports";
+import { getHostTask } from "./runtime-state";
+import { ENGINE_CREDENTIAL_ENV_NAMES } from "./engine-credential-env";
+import { activeSecretsProxy } from "./secrets-proxy/host";
+import { closeTaskUpTrustSteps, finishTaskUpTrustSteps, writeTaskUpTrustSteps } from "./secrets-proxy/task-trust";
+import { removeTaskIdentity, writeTaskIdentity } from "./ssh";
+import type { TaskGitCredentialHold } from "./credential-consumers/github";
+import type { TaskWriteEnvironment } from "./credential-consumers/task-files";
+import { serveCloneCredentials, type CloneCredentialService } from "./git-clone-credentials";
+import { taskGatewayHost } from "./mcp-gateway";
+import type { ProjectEnvMode } from "./task-environment/types";
+import { isProjectEnvSchemaObservation, type ProjectEnvSchemaObservation, type TaskDownInput, type TaskLaunchInput } from "../src/protocol";
+
+export type { TaskLaunchInput } from "../src/protocol";
+
+/**
+ * ADR-154 §12: a start on cloud credentials. Only ever whole: the hold and
+ * the runtime-ready writes come together, so no such start reaches its
+ * runtime without what the runner writes into it.
+ */
+export interface LeasedTaskUp {
+  /**
+   * The owner's GitHub sign-in and SSH key, held for this start
+   * (`holdTaskGitCredentials`). The host-side clone reaches them only
+   * through this process's own sockets, for as long as task-up runs; a hold
+   * taken back aborts task-up. No key file is written and the runner's own
+   * store is never read.
+   */
+  clone: TaskGitCredentialHold;
+  /**
+   * The task's runtime exists and nothing in it has run yet (task-up pauses
+   * before uai-init, a machine before its clones): write what the runner
+   * writes into it, its owner's GitHub configuration and SSH key recorded
+   * for cleanup, before anything that may need them runs. A rejection stops
+   * the start.
+   */
+  runtimeReady: (environment: TaskWriteEnvironment, signal: AbortSignal) => Promise<void>;
+  /** This exact start carries a task-machine Files session.  Machine task-up
+   * skips its legacy copy/mount path only in this case; owned leased tasks do
+   * not receive a Files session and keep their normal Files behavior. */
+  filesV1?: true;
+}
+
+/** Refuses a start on cloud credentials that is not whole, or not this
+ *  start's: before anything is provisioned, cloned or written. */
+export function assertLeasedTaskUp(
+  leased: LeasedTaskUp | undefined,
+  task: { id: string; runEpoch?: number },
+): void {
+  if (leased === undefined) return;
+  if (!leased.clone || typeof leased.runtimeReady !== "function") {
+    throw new Error("a start on cloud credentials needs its hold and its runtime-ready writes together");
+  }
+  if (leased.clone.assignment.taskId !== task.id || leased.clone.assignment.runEpoch !== task.runEpoch) {
+    throw new Error("the credentials held for this start are another task's or another run's");
+  }
+}
+
+export interface TaskUpCredentials {
+  /** Path to the task owner's private, ephemeral Git credential cache. */
+  githubCredentialSocket?: string;
+  /** ADR-154 §12: a task on cloud credentials. */
+  leased?: LeasedTaskUp;
+  /** Fresh ADR-153 generation credential. The raw bytes are forwarded only
+   * over stdin and are never serialized into a task row, argv, or env. */
+  taskGateway?: {
+    generation: string;
+    secret: Uint8Array;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Locate the agent scripts. They ship inside the package, so by default we
+// resolve them relative to this module — which works identically in a repo
+// checkout (host-agent/scripts/agent) and an npm install
+// (node_modules/@runuai/host/scripts/agent). An explicit UAI_AGENT_DIR
+// overrides this (e.g. hacking on scripts against a running host).
+// ---------------------------------------------------------------------------
+
+function packageAgentScriptsDir(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "scripts", "agent");
+}
+
+function agentDir(): string {
+  return env.agentDir ?? packageAgentScriptsDir();
+}
+
+// ---------------------------------------------------------------------------
+// Result schemas. Each command shares the success envelope and produces a
+// command-specific `data` payload.
+// ---------------------------------------------------------------------------
+
+const ErrorPayload = z.object({
+  code: z.string(),
+  message: z.string(),
+  step: z.string().optional(),
+  exit_code: z.number().optional(),
+});
+
+const SuccessEnvelope = <T extends z.ZodTypeAny>(data: T) =>
+  z.object({ ok: z.literal(true), data });
+
+const FailureEnvelope = z.object({
+  ok: z.literal(false),
+  error: ErrorPayload,
+});
+
+// task-up
+const TaskUpData = z.object({
+  composeProject: z.string(),
+  worktreePath: z.string(),
+  codeServerPort: z.number().int().positive().optional(),
+  previewPorts: PreviewPortRuntimesSchema.optional(),
+  /** Degraded start: uai-init failed twice; surfaced as a feed system note. */
+  initWarning: z.string().optional(),
+  /** ADR-153: whether this start put the secrets proxy's CA, and its pins,
+   *  into the task. Absent from a task-up that predates them. */
+  secretsProxyTrust: z.enum(["installed", "failed", "skipped"]).optional(),
+  secretsProxyPins: z.enum(["installed", "failed", "skipped"]).optional(),
+  /** ADR-153 §4: each project's schema observation, as the runner stored it
+   *  before anything in the task started (a task machine reports its own). */
+  envSchemas: z.array(z.custom<ProjectEnvSchemaObservation>(isProjectEnvSchemaObservation)).optional(),
+});
+export type TaskUpResult = z.infer<typeof TaskUpData>;
+
+// task-down
+/** task-down.sh destroys the task's runtime AND its directory (worktree +
+ *  task-private Git data), so it refuses without this explicit terminal
+ *  intent. Only the cloud taskDown reaches these two calls: the handler in
+ *  src/index.ts, and a credential cleanup under that same command
+ *  (`reason: "teardown"`, task-credential-cleanup.ts). */
+const TASK_DOWN_TERMINAL_ENV = Object.freeze({ UAI_TASK_DOWN_TERMINAL: "1" });
+
+const TaskDownData = z
+  .object({
+    status: z.string().optional(),
+    alreadyGone: z.boolean().optional(),
+  })
+  .passthrough();
+export type TaskDownResult = z.infer<typeof TaskDownData>;
+
+// task-status
+const TaskStatusData = z.object({
+  composeRunning: z.boolean(),
+  containers: z.array(z.string()),
+  worktreePresent: z.boolean(),
+});
+export type TaskStatusResult = z.infer<typeof TaskStatusData>;
+
+// ---------------------------------------------------------------------------
+// Error type. All call sites should `catch (err)` and use `AgentError.is`.
+// ---------------------------------------------------------------------------
+
+export class AgentError extends Error {
+  override readonly name = "AgentError";
+  readonly code: string;
+  readonly step: string | undefined;
+  readonly exitCode: number | undefined;
+
+  constructor(
+    code: string,
+    message: string,
+    options: { step?: string; exitCode?: number; cause?: unknown } = {},
+  ) {
+    super(
+      message,
+      options.cause === undefined ? undefined : { cause: options.cause },
+    );
+    this.code = code;
+    this.step = options.step;
+    this.exitCode = options.exitCode;
+  }
+
+  static is(err: unknown): err is AgentError {
+    return err instanceof AgentError;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal: run an agent script and parse the JSON envelope.
+// ---------------------------------------------------------------------------
+
+/** How long a withdrawn script has to end on SIGTERM before SIGKILL. */
+const WITHDRAWN_KILL_GRACE_MS = 5_000;
+
+/** What a start on cloud credentials says when they were withdrawn under it. */
+export const CREDENTIALS_WITHDRAWN_MESSAGE =
+  "The task's credentials were withdrawn while it was starting: removed, refused or replaced in the cloud. Start the task again.";
+/** How often task-up's handshake directory is looked at for its events. */
+const HANDSHAKE_POLL_MS = 100;
+
+/**
+ * The environment every host script (task-up, task-down, task-status) runs
+ * with: the runner's own, then every root a script derives a path from,
+ * resolved here and passed explicitly, so no script falls back to a default.
+ * Projects, tasks, browsers and shared files live under the workspace root,
+ * credentials under the owner's home. Rehearsal #2 (2026-11-02): the station's
+ * root defaults to ~/.moondeck (env.ts) but nothing passed it, so task-up
+ * built under _common.sh's own fallback, ~/.uai, and docker.ts refused the
+ * stack it returned. The packaged-runtime check in
+ * scripts/host-runtime/workspace-root-smoke.mjs calls this from an archive.
+ */
+export function agentScriptEnv(
+  commandDbPath: string,
+  runnerEnv: NodeJS.ProcessEnv = process.env,
+  extraEnv: Record<string, string> = {},
+): NodeJS.ProcessEnv {
+  return {
+    ...runnerEnv,
+    UAI_DB_PATH: commandDbPath,
+    UAI_DATA_DIR: env.dataDir,
+    UAI_WORKSPACE_ROOT: env.workspaceRoot,
+    UAI_OWNER_HOME: process.env.UAI_OWNER_HOME?.trim() || homedir(),
+    UAI_STANDARD_CONTAINER_ASSETS_DIR:
+      containerRuntimeStandardAssetsRoot() ??
+      join(packageAgentScriptsDir(), "..", "..", "images", "standard", "container"),
+    ...extraEnv,
+  };
+}
+
+async function runAgent<T extends z.ZodTypeAny>(
+  scriptName: string,
+  args: string[],
+  dataSchema: T,
+  commandDbPath: string,
+  extraEnv: Record<string, string> = {},
+  stdinPayload?: string,
+  /** Aborted when what the script runs on is withdrawn (ADR-154): the
+   *  script and everything it started, its process group, end. */
+  withdrawn?: AbortSignal,
+  /** Names the script never inherits from the runner's own environment
+   *  (ADR-154: a start on cloud credentials gets none of the runner's). */
+  withoutRunnerEnv: ReadonlySet<string> = new Set(),
+): Promise<z.infer<T>> {
+  const scriptPath = resolve(agentDir(), scriptName);
+  const runnerEnv = Object.fromEntries(
+    Object.entries(process.env).filter(([name]) => !withoutRunnerEnv.has(name)),
+  );
+
+  const child = spawn(scriptPath, args, {
+    // Its own process group when it may be withdrawn, so ending it ends
+    // every git and container CLI it started.
+    detached: withdrawn !== undefined,
+    stdio: [stdinPayload === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+    env: agentScriptEnv(commandDbPath, runnerEnv, extraEnv),
+  });
+
+  let stdoutBuf = "";
+  let stderrBuf = "";
+  child.stdout?.on("data", (chunk) => {
+    stdoutBuf += chunk.toString("utf8");
+  });
+  child.stderr?.on("data", (chunk) => {
+    stderrBuf += chunk.toString("utf8");
+  });
+  if (stdinPayload !== undefined && child.stdin) {
+    // A script that exits before consuming stdin may close the pipe first.
+    // The process exit/error below is authoritative; do not turn EPIPE into an
+    // unhandled stream error in the host agent.
+    child.stdin.on("error", () => {});
+    child.stdin.end(stdinPayload);
+  }
+
+  let killTimer: ReturnType<typeof setTimeout> | undefined;
+  const endGroup = (signal: NodeJS.Signals): void => {
+    try {
+      if (child.pid !== undefined) process.kill(-child.pid, signal);
+    } catch {
+      // Already gone.
+    }
+  };
+  const onWithdrawn = (): void => {
+    endGroup("SIGTERM");
+    killTimer = setTimeout(() => endGroup("SIGKILL"), WITHDRAWN_KILL_GRACE_MS);
+  };
+  if (withdrawn?.aborted) onWithdrawn();
+  else withdrawn?.addEventListener("abort", onWithdrawn, { once: true });
+
+  let exitCode: number;
+  try {
+    exitCode = await new Promise((res, rej) => {
+      child.on("error", rej);
+      child.on("close", (code) => res(code ?? 0));
+    });
+  } finally {
+    withdrawn?.removeEventListener("abort", onWithdrawn);
+    clearTimeout(killTimer);
+  }
+  if (withdrawn?.aborted) {
+    endGroup("SIGKILL");
+    throw new AgentError("CREDENTIALS_WITHDRAWN", CREDENTIALS_WITHDRAWN_MESSAGE, { exitCode });
+  }
+
+  // Try to parse whichever stream has the JSON. On failure the agent puts
+  // its envelope on stderr; on success, on stdout.
+  if (exitCode !== 0) {
+    // Log the full stderr so the dev terminal shows the underlying tool's
+    // output (docker's stderr, git's stderr, etc.) — the shell agent only
+    // surfaces the code + step on the structured envelope.
+    if (stderrBuf.trim()) {
+      console.error(
+        `[uai-agent] ${scriptName} stderr (exit ${exitCode}):\n${stderrBuf.trim()}`,
+      );
+    }
+    const parsed = tryParseLastJsonLine(stderrBuf);
+    if (parsed) {
+      const failure = FailureEnvelope.safeParse(parsed);
+      if (failure.success) {
+        throw new AgentError(
+          failure.data.error.code,
+          composeFailureMessage(failure.data.error.message, stderrBuf),
+          {
+            step: failure.data.error.step,
+            exitCode: failure.data.error.exit_code ?? exitCode,
+          },
+        );
+      }
+    }
+    throw new AgentError(
+      "AGENT_UNKNOWN_FAILURE",
+      `${scriptName} exited ${exitCode}: ${stderrBuf.trim() || "no stderr"}`,
+      { exitCode },
+    );
+  }
+
+  const parsed = tryParseLastJsonLine(stdoutBuf);
+  if (!parsed) {
+    throw new AgentError(
+      "AGENT_BAD_OUTPUT",
+      `${scriptName} stdout was not JSON: ${stdoutBuf.trim().slice(0, 200)}`,
+      { exitCode },
+    );
+  }
+  const envelope = SuccessEnvelope(dataSchema).safeParse(parsed);
+  if (!envelope.success) {
+    throw new AgentError(
+      "AGENT_BAD_OUTPUT",
+      `${scriptName} returned unexpected shape: ${envelope.error.message}`,
+      { exitCode },
+    );
+  }
+  return envelope.data.data;
+}
+
+/**
+ * The agent may log info lines to stderr alongside the JSON envelope.
+ * On stdout we expect a single trailing JSON object; on stderr the
+ * envelope is the last line. This helper takes the last non-empty line
+ * and parses it as JSON.
+ */
+function tryParseLastJsonLine(buf: string): unknown {
+  const trimmed = buf.trim();
+  if (!trimmed) return null;
+  const lines = trimmed.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = (lines[i] ?? "").trim();
+    if (!line) continue;
+    try {
+      return JSON.parse(line);
+    } catch {
+      // Keep walking back; agent log lines are not JSON.
+    }
+  }
+  return null;
+}
+
+/**
+ * The FAILING TOOL's output from a script's stderr — the docker/git/apt lines
+ * that actually say WHY a step failed, dropping our own `[uai-agent] step:`
+ * breadcrumbs and the `{"ok":false,…}` envelope. The bash envelope's message
+ * is generic ("agent step failed"); this is what makes it specific so the
+ * reason reaches the cloud UI instead of only the host log — useless when the
+ * host is a remote user's machine (live 2026-07-22, "compose_up_failed" with
+ * no why). Bounded to the last few lines so a build log doesn't flood the UI.
+ */
+/**
+ * The operator-facing failure text: the envelope's message LEADS and the
+ * tool output follows. The scripts' emit_err messages are curated
+ * instructions ("close another running task, then press Resume") —
+ * replacing them with the stderr tail buried exactly the sentence the
+ * operator needed under VZ/git noise (live 2026-08-17, twice in one day).
+ * The tool detail still ships, because a message alone can lack the WHY
+ * (the 2026-07-22 lesson the old detail-first ordering encoded).
+ */
+export function composeFailureMessage(
+  envelopeMessage: string,
+  stderrBuf: string,
+): string {
+  const detail = toolStderrDetail(stderrBuf);
+  return detail ? `${envelopeMessage}\n${detail}` : envelopeMessage;
+}
+
+export function toolStderrDetail(stderr: string): string {
+  const lines = stderr
+    .split(/\r?\n/)
+    .map((l) => l.replace(/\s+$/, ""))
+    .filter((l) => l.trim().length > 0)
+    .filter((l) => !l.startsWith("[uai-agent"))
+    .filter((l) => !l.trimStart().startsWith('{"ok"'));
+  return lines
+    .slice(-6)
+    .map((l) => (l.length > 300 ? `${l.slice(0, 300)}…` : l))
+    .join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Public API. One function per agent command.
+// ---------------------------------------------------------------------------
+
+export const agent = {
+  async taskUp(
+    input: TaskLaunchInput,
+    credentials: TaskUpCredentials = {},
+    envMode: ProjectEnvMode = "baked",
+    /** The task's runtime as the provider reaches it once task-up has
+     *  created it: where `credentials.leased.runtimeReady` writes. */
+    runtimeEnvironment?: () => TaskWriteEnvironment,
+  ): Promise<TaskUpResult> {
+    const leased = credentials.leased;
+    if (leased && credentials.githubCredentialSocket) {
+      throw new Error("a task on cloud credentials never uses the station's own GitHub credential");
+    }
+    assertLeasedTaskUp(leased, input.task);
+    if (leased && !runtimeEnvironment) {
+      throw new Error("this runtime cannot pause task-up for its runtime-ready writes");
+    }
+    const commandDbPath = createTaskUpCommandDb(input);
+    // Materialize the creator's per-user SSH key for commit signing and the
+    // explicit no-GitHub-connection transport fallback (ADR-029). A task on
+    // cloud credentials gets no key file: the runner writes the task's key
+    // itself, and serves the clone's from memory.
+    const identityDir = leased ? null : writeTaskIdentity(input.task.id, input.task.ownerUserId);
+    let cloneService: CloneCredentialService | null = null;
+    // ADR-154 §12: task-up says where it is with event files in a private
+    // directory (event-clone-done, then event-runtime-ready), never on the
+    // stderr its subprocesses share, and finds the runtime-ready answer
+    // there. Each event is taken once, in order. The runtime-ready writes
+    // are one operation, abortable by the hold, joined before task-up's
+    // outcome is returned whatever it is.
+    const handshakeDir = leased ? mkdtempSync(join("/tmp", "uai-task-handshake-")) : null;
+    if (handshakeDir) chmodSync(handshakeDir, 0o700);
+    let cloneDone = false;
+    let runtimeReadyWrites: Promise<void> | null = null;
+    const answer = (value: "continue" | "abort"): void => {
+      try {
+        const staged = join(handshakeDir!, ".runtime-ready");
+        writeFileSync(staged, `${value}\n`, { mode: 0o600 });
+        renameSync(staged, join(handshakeDir!, "runtime-ready"));
+      } catch {
+        // task-up already ended: nothing waits for the answer.
+      }
+    };
+    const takeEvents = (): void => {
+      if (!handshakeDir) return;
+      if (!cloneDone && existsSync(join(handshakeDir, "event-clone-done"))) {
+        cloneDone = true;
+        // The host's clones and fetches are over: stop serving them.
+        void cloneService?.close();
+      }
+      if (runtimeReadyWrites || !existsSync(join(handshakeDir, "event-runtime-ready"))) return;
+      if (!cloneDone) {
+        // Out of order: not task-up's.
+        runtimeReadyWrites = Promise.resolve();
+        answer("abort");
+        return;
+      }
+      runtimeReadyWrites = (async () => {
+        let value: "continue" | "abort" = "abort";
+        try {
+          const signal = leased!.clone.signal;
+          if (signal.aborted) throw new Error("the task's credentials were withdrawn");
+          await leased!.runtimeReady(runtimeEnvironment!(), signal);
+          value = "continue";
+        } catch (error) {
+          console.warn(
+            `[uai-agent] task ${input.task.id}: runtime-ready writes failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+        answer(value);
+      })();
+    };
+    const poller = handshakeDir ? setInterval(takeEvents, HANDSHAKE_POLL_MS) : null;
+    try {
+      // Per-(project, key) env values must NEVER enter task-up's host process
+      // environment. Besides ordinary app names, projects can declare names such
+      // as BASH_ENV, PATH, GIT_CONFIG_*, or UAI_*; exposing those before the host
+      // clone would let container-owned configuration influence host commands or
+      // read another credential boundary. Send one JSON object over stdin
+      // instead. task-up feeds it directly to Compose as an in-memory override,
+      // so values reach only the task container and are never written to disk.
+      // On a key collision the LEAD project (position 0) wins: iterate in
+      // descending position order so position-0 assignments apply last.
+      const projectEnv: Record<string, string> = {};
+      if (envMode === "baked") {
+        const orderedProjects = [...input.projects].sort(
+          (a, b) => b.position - a.position,
+        );
+        for (const project of orderedProjects) {
+          Object.assign(projectEnv, getDecryptedForProject(project.id));
+        }
+      }
+      const extraEnv: Record<string, string> = {
+        UAI_PROJECT_ENV_MODE: envMode,
+      };
+      if (handshakeDir) extraEnv.UAI_TASK_HANDSHAKE_DIR = handshakeDir;
+      if (identityDir) extraEnv.UAI_TASK_IDENTITY_DIR = identityDir;
+      // Only a non-secret socket path crosses into Bash. The token itself was
+      // seeded over stdin and never enters argv, env, project data, Compose, or
+      // the task container.
+      if (credentials.githubCredentialSocket) {
+        extraEnv.UAI_GITHUB_CREDENTIAL_SOCKET =
+          credentials.githubCredentialSocket;
+      }
+      if (leased) {
+        cloneService = await serveCloneCredentials(leased.clone);
+        Object.assign(extraEnv, cloneService.env);
+      }
+      let stdinPayload: string;
+      if (envMode === "loader") {
+        const gateway = credentials.taskGateway;
+        if (!gateway || gateway.secret.byteLength !== 32) {
+          throw new Error(
+            "loader task is missing its gateway generation credential",
+          );
+        }
+        extraEnv.UAI_TASK_GATEWAY_GENERATION = gateway.generation;
+        extraEnv.UAI_TASK_GATEWAY_HOST = await taskGatewayHost();
+        // ADR-153: what task-up installs before anything runs in the task.
+        // Public material only; absent under the kill switch.
+        // The start holds the task's root writes until its result is
+        // recorded, so no older writer (a recovery, a re-pin) lands over
+        // them while uai-init runs.
+        const secretsProxy = activeSecretsProxy();
+        if (secretsProxy !== null) {
+          // task-up reports each step's outcome into it as it goes, so the
+          // task's readiness is exact even while uai-init already runs.
+          const stepsDir = await writeTaskUpTrustSteps(env.dataDir, input.task.id, secretsProxy.runtime);
+          if (stepsDir !== null) extraEnv.UAI_SECRETS_PROXY_DIR = stepsDir;
+        }
+        const secretCopy = Buffer.from(gateway.secret);
+        try {
+          stdinPayload = secretCopy.toString("base64");
+        } finally {
+          secretCopy.fill(0);
+        }
+      } else {
+        stdinPayload = JSON.stringify(projectEnv);
+      }
+      let result: TaskUpResult;
+      try {
+        result = await runAgent(
+          "task-up.sh",
+          [input.task.id],
+          TaskUpData,
+          commandDbPath,
+          extraEnv,
+          stdinPayload,
+          leased?.clone.signal,
+          // ADR-154 §6: no default slot. A start on cloud credentials gets
+          // the runner's own engine sign-ins in neither its env nor files.
+          leased ? ENGINE_CREDENTIAL_ENV_NAMES : undefined,
+        );
+      } catch (error) {
+        finishTaskUpTrustSteps(env.dataDir, input.task.id, null);
+        throw error;
+      }
+      // What this start actually installed. A start that did not get the CA
+      // in is retried by the trust watcher once the task runs.
+      finishTaskUpTrustSteps(env.dataDir, input.task.id, result);
+      if (result.secretsProxyTrust === "failed") activeSecretsProxy()?.runtime.requestTrustDelivery();
+      return result;
+    } finally {
+      if (poller) clearInterval(poller);
+      // Joined, whatever task-up's outcome: nothing it began still writes
+      // into the task once this returns.
+      await runtimeReadyWrites;
+      await cloneService?.close();
+      if (handshakeDir) rmSync(handshakeDir, { recursive: true, force: true });
+      closeTaskUpTrustSteps(env.dataDir, input.task.id);
+      removeCommandDb(commandDbPath);
+      removeTaskIdentity(input.task.id);
+    }
+  },
+
+  async taskDown(input: TaskDownInput): Promise<TaskDownResult> {
+    const commandDbPath = createTaskDownCommandDb(
+      input,
+      getHostTask(input.taskId),
+    );
+    try {
+      return await runAgent(
+        "task-down.sh",
+        [input.taskId],
+        TaskDownData,
+        commandDbPath,
+        TASK_DOWN_TERMINAL_ENV,
+      );
+    } finally {
+      removeCommandDb(commandDbPath);
+    }
+  },
+
+  /** ADR-101 Phase C: idempotent teardown from a durable environment locator.
+   * Cloud command metadata is intentionally unnecessary at this boundary. */
+  async taskEnvironmentDown(taskId: string): Promise<TaskDownResult> {
+    const commandDbPath = createTaskEnvironmentDownCommandDb(
+      taskId,
+      getHostTask(taskId),
+    );
+    try {
+      return await runAgent(
+        "task-down.sh",
+        [taskId],
+        TaskDownData,
+        commandDbPath,
+        TASK_DOWN_TERMINAL_ENV,
+      );
+    } finally {
+      removeCommandDb(commandDbPath);
+    }
+  },
+
+  async taskStatus(taskId: string): Promise<TaskStatusResult> {
+    const commandDbPath = createTaskStatusCommandDb(taskId, getHostTask(taskId));
+    try {
+      return await runAgent(
+        "task-status.sh",
+        [taskId],
+        TaskStatusData,
+        commandDbPath,
+      );
+    } finally {
+      removeCommandDb(commandDbPath);
+    }
+  },
+};
+
+export type Agent = typeof agent;