@moondeck/station 0.0.0-stage → 1.0.0

package/lib/stopped-task-status-queue.ts

@@ -0,0 +1,120 @@
+/**
+ * Best-effort task.status frames have no acknowledgement, but they must at
+ * least survive bridge disconnects within this host process. The local task
+ * mirror remains the authority at flush time so a later Resume wins over an
+ * older queued stop.
+ */
+/**
+ * Why the host stopped the task, when the host knows.
+ *
+ * `"manual"` is ADR-028's local-UI Stop — a person at the machine pressed it.
+ * Everything else the host reports through this frame is automatic (writable
+ * -container quarantine during a runtime activation or a shared-volume
+ * repair), and carries no reason. The cloud needs the difference because
+ * ADR-144 lets a collaborator resume a task that stopped on its own but not
+ * one a human deliberately paused, and until now both arrived as the same
+ * three fields.
+ */
+export type StoppedTaskReason = "manual";
+
+interface StoppedTaskState {
+  status: string;
+  runEpoch: number;
+}
+
+interface PendingStoppedTaskStatus {
+  reason: StoppedTaskReason | undefined;
+  runEpoch: number | undefined;
+}
+
+export class StoppedTaskStatusQueue {
+  private readonly pending = new Map<string, PendingStoppedTaskStatus>();
+
+  constructor(
+    private readonly stateForTask: (
+      taskId: string,
+    ) => StoppedTaskState | null | undefined,
+  ) {}
+
+  enqueue(
+    taskId: string,
+    reason?: StoppedTaskReason,
+    runEpoch?: number,
+  ): void {
+    const previous = this.pending.get(taskId);
+    const previousEpoch = previous?.runEpoch ?? 0;
+    const nextEpoch = runEpoch ?? 0;
+    // A command result can arrive after the next assignment has already
+    // queued its own status. Run epochs are monotonic, so an older result must
+    // not replace the newer pending truth (or donate its reason to it).
+    if (previous !== undefined && nextEpoch < previousEpoch) return;
+    // A reason, once known, STICKS across a re-enqueue. The same task can be
+    // queued twice before a flush — an operator Stop, then a quarantine sweep
+    // that finds its container already down — and the automatic pass arriving
+    // second does not make the human's decision retroactively automatic.
+    // Dropping it would silently hand the task back to every collaborator.
+    this.pending.set(taskId, {
+      reason:
+        previous !== undefined && previousEpoch === nextEpoch
+          ? reason ?? previous.reason
+          : reason,
+      runEpoch,
+    });
+  }
+
+  /** A failed taskUp may have stopped a legacy runtime before recreation lost
+   * Docker. Queue the physical truth after the command result is published. */
+  enqueueStoppedTaskUp(command: string, args: readonly unknown[]): boolean {
+    if (command !== "taskUp") return false;
+    const input = args[0];
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return false;
+    }
+    const task = (input as { task?: unknown }).task;
+    if (!task || typeof task !== "object" || Array.isArray(task)) return false;
+    const taskId = (task as { id?: unknown }).id;
+    const state = typeof taskId === "string" ? this.stateForTask(taskId) : null;
+    if (typeof taskId !== "string" || state?.status !== "stopped") {
+      return false;
+    }
+    const hasRunEpoch = Object.hasOwn(task, "runEpoch");
+    const inputRunEpoch = (task as { runEpoch?: unknown }).runEpoch;
+    if (hasRunEpoch) {
+      if (
+        !Number.isSafeInteger(inputRunEpoch) ||
+        (inputRunEpoch as number) < 1 ||
+        inputRunEpoch !== state.runEpoch
+      ) {
+        return false;
+      }
+    } else if (state.runEpoch !== 0) {
+      // Never relabel a delayed v0 taskUp result as the current v1 run.
+      return false;
+    }
+    const runEpoch = hasRunEpoch ? (inputRunEpoch as number) : undefined;
+    this.enqueue(taskId, undefined, runEpoch);
+    return true;
+  }
+
+  flush(
+    publish: (
+      taskId: string,
+      reason?: StoppedTaskReason,
+      runEpoch?: number,
+    ) => void,
+  ): void {
+    for (const [taskId, pending] of [...this.pending]) {
+      const state = this.stateForTask(taskId);
+      if (
+        state?.status === "stopped" &&
+        (pending.runEpoch === undefined
+          ? state.runEpoch === 0
+          : state.runEpoch === pending.runEpoch)
+      ) {
+        if (pending.runEpoch === undefined) publish(taskId, pending.reason);
+        else publish(taskId, pending.reason, pending.runEpoch);
+      }
+      this.pending.delete(taskId);
+    }
+  }
+}

package/lib/task-container-cli.ts

@@ -0,0 +1,269 @@
+/**
+ * Backend-aware CLI access to TASK app containers for the auxiliary
+ * subsystems that predate the TaskEnvironment provider (GitHub credential
+ * injection, git identity, Codex reinjection, skills). Found live 2026-08-16:
+ * these spawned the literal `docker` binary with Compose replica names, so on
+ * a Docker-free Apple host every agent session start died at the credential
+ * step with spawn ENOENT.
+ *
+ * The exec/cp verbs are flag-compatible across Docker and the bundled Apple
+ * CLI, so most callers only need the command + container-name translation
+ * here. Verbs that differ (ps/rm/inventory) get explicit helpers.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+
+import {
+  appleContainerRuntimeBinding,
+  pinnedContainerRuntimeProvider,
+} from "./container-runtime";
+import { dockerCli, type DockerResult } from "./docker-exec";
+import { assertSafeHostTaskId } from "./task-identity";
+
+export interface TaskContainerBackend {
+  command: string;
+  apple: boolean;
+}
+
+/** The pin, not the readiness-gated identity: session ensure and recovery
+ * both run while the public state can still be `checking`. */
+export function taskContainerBackend(): TaskContainerBackend {
+  if (pinnedContainerRuntimeProvider() === "apple-container") {
+    const binding = appleContainerRuntimeBinding();
+    if (binding !== null) {
+      return { command: binding.containerCliPath, apple: true };
+    }
+  }
+  return { command: "docker", apple: false };
+}
+
+/** The app container's name under the selected backend: Compose replica
+ * naming for Docker, the provider's fixed name for Apple (must match
+ * appleTaskContainerName in task-environment/apple-container.ts). */
+export function taskAppContainerName(taskId: string): string {
+  assertSafeHostTaskId(taskId);
+  const lowered = taskId.toLowerCase();
+  return taskContainerBackend().apple
+    ? `moondeck-task-${lowered}-app`
+    : `task-${lowered}-app-1`;
+}
+
+/** dockerCli-compatible runner that targets the selected backend. Every kill
+ * (deadline or overflow) forces settlement within a bounded grace. */
+export function taskContainerCli(
+  args: string[],
+  opts: {
+    input?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+  } = {},
+): Promise<DockerResult> {
+  const backend = taskContainerBackend();
+  if (!backend.apple) return dockerCli(args, opts);
+  return new Promise<DockerResult>((resolve) => {
+    const child = nodeSpawn(backend.command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (status: number | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ status, stdout, stderr });
+    };
+    const killAndSettle = (): void => {
+      child.kill("SIGKILL");
+      const settle = setTimeout(() => finish(null), 5_000);
+      settle.unref?.();
+    };
+    const timer = setTimeout(killAndSettle, opts.timeoutMs ?? 30_000);
+    timer.unref?.();
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout += chunk;
+      if (
+        opts.maxOutputBytes !== undefined &&
+        stdout.length + stderr.length > opts.maxOutputBytes
+      ) {
+        killAndSettle();
+      }
+    });
+    child.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+      if (
+        opts.maxOutputBytes !== undefined &&
+        stdout.length + stderr.length > opts.maxOutputBytes
+      ) {
+        killAndSettle();
+      }
+    });
+    child.stdin.on("error", () => {});
+    if (opts.input !== undefined) child.stdin.write(opts.input);
+    child.stdin.end();
+    child.on("error", () => finish(null));
+    child.on("close", (code) => finish(code));
+  });
+}
+
+export type TaskContainerState =
+  | { kind: "running" }
+  | { kind: "stopped"; state: string }
+  | { kind: "absent" }
+  | { kind: "unknown"; detail: string };
+
+/** Backend-aware state probe for one exact task app container. Absence is
+ * proven only by the complete not-found error naming the container (Apple)
+ * or an empty exact-name filter answer (Docker); anything else is unknown. */
+export async function taskAppContainerState(
+  containerName: string,
+  run: typeof taskContainerCli = taskContainerCli,
+): Promise<TaskContainerState> {
+  const backend = taskContainerBackend();
+  if (backend.apple) {
+    const inspected = await run(["inspect", containerName], {
+      timeoutMs: 30_000,
+      maxOutputBytes: 1024 * 1024,
+    });
+    if (inspected.status !== 0) {
+      if (
+        inspected.stdout.trim() === "" &&
+        inspected.stderr
+          .split("\n")
+          .some(
+            (line) =>
+              line.trim() === `Error: container not found: ${containerName}`,
+          )
+      ) {
+        return { kind: "absent" };
+      }
+      return {
+        kind: "unknown",
+        detail: inspected.stderr.trim().slice(0, 300) || "inspect failed",
+      };
+    }
+    try {
+      const parsed = JSON.parse(inspected.stdout) as Array<{
+        id?: unknown;
+        status?: { state?: unknown };
+      }>;
+      if (
+        !Array.isArray(parsed) ||
+        parsed.length !== 1 ||
+        parsed[0]?.id !== containerName
+      ) {
+        return { kind: "unknown", detail: "inspect shape is invalid" };
+      }
+      const state = parsed[0]?.status?.state;
+      if (typeof state !== "string") {
+        return { kind: "unknown", detail: "inspect state is missing" };
+      }
+      return state === "running"
+        ? { kind: "running" }
+        : { kind: "stopped", state };
+    } catch {
+      return { kind: "unknown", detail: "inspect output is not JSON" };
+    }
+  }
+  const listed = await run(
+    [
+      "ps",
+      "--all",
+      "--filter",
+      `name=^/${containerName}$`,
+      "--format",
+      "{{.State}}",
+    ],
+    { timeoutMs: 30_000, maxOutputBytes: 64 * 1024 },
+  );
+  if (listed.status !== 0) {
+    return {
+      kind: "unknown",
+      detail: listed.stderr.trim().slice(0, 300) || "docker ps failed",
+    };
+  }
+  const states = listed.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (states.length === 0) return { kind: "absent" };
+  if (states.length !== 1) {
+    return { kind: "unknown", detail: `${states.length} containers matched` };
+  }
+  return states[0] === "running"
+    ? { kind: "running" }
+    : { kind: "stopped", state: states[0]! };
+}
+
+/** Force-remove one exact task app container and prove its absence. */
+export async function removeTaskAppContainer(
+  containerName: string,
+  run: typeof taskContainerCli = taskContainerCli,
+): Promise<void> {
+  const backend = taskContainerBackend();
+  const removed = await run(
+    backend.apple
+      ? ["delete", "--force", containerName]
+      : ["rm", "--force", containerName],
+    { timeoutMs: 60_000, maxOutputBytes: 64 * 1024 },
+  );
+  if (removed.status !== 0 && backend.apple) {
+    // Deleting an already-absent container is success; anything else is not.
+    const state = await taskAppContainerState(containerName, run);
+    if (state.kind === "absent") return;
+    throw new Error(
+      `remove ${containerName} failed: ${removed.stderr.trim().slice(0, 300)}`,
+    );
+  }
+  const after = await taskAppContainerState(containerName, run);
+  if (after.kind !== "absent") {
+    throw new Error(`remove ${containerName} was not verified`);
+  }
+}
+
+/** Names of RUNNING task app containers under the selected backend. */
+export async function listRunningTaskAppContainerNames(
+  run: typeof taskContainerCli = taskContainerCli,
+): Promise<string[] | null> {
+  const backend = taskContainerBackend();
+  if (backend.apple) {
+    const listed = await run(["list", "--format", "json"], {
+      timeoutMs: 30_000,
+      maxOutputBytes: 8 * 1024 * 1024,
+    });
+    if (listed.status !== 0) return null;
+    try {
+      const parsed = JSON.parse(listed.stdout) as Array<{
+        configuration?: { id?: unknown };
+        status?: { state?: unknown };
+      }>;
+      if (!Array.isArray(parsed)) return null;
+      // `container list` without --all already returns running containers,
+      // but the state check keeps this honest against CLI behavior drift.
+      return parsed
+        .filter(
+          (item) =>
+            item?.status?.state === undefined ||
+            item?.status?.state === "running",
+        )
+        .map((item) => item?.configuration?.id)
+        .filter(
+          (id): id is string =>
+            typeof id === "string" && /^moondeck-task-[a-z0-9][a-z0-9_-]*-app$/.test(id),
+        );
+    } catch {
+      return null;
+    }
+  }
+  const listed = await run(
+    ["ps", "--filter", "status=running", "--format", "{{.Names}}"],
+    { timeoutMs: 30_000, maxOutputBytes: 1024 * 1024 },
+  );
+  if (listed.status !== 0) return null;
+  return listed.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}