@runuai/host 0.9.167 → 0.9.168

package/lib/task-project-ops.ts

@@ -0,0 +1,1052 @@
+/**
+ * ADR-161 §2.3 / §2.4: add a repository to a RUNNING task.
+ *
+ * The cloud drives one durable operation per add; this module is the
+ * runner's half: four fenced commands and the journal that makes them safe
+ * to repeat, lose, or interrupt.
+ *
+ * - **Prepare** clones the repository *inside the task's own runtime, as the
+ *   task user*, into a hidden staging folder of the task's workspace
+ *   (`/workspace/.uai/.project-staging/<op>/repo`). Staging is task-writable
+ *   by design (the owner's decision on PR #641): nothing tells the agents
+ *   about it before the repository is ready, and compensation discards
+ *   whatever is in it, so an agent's edit there is lost on purpose. The clone
+ *   is self-contained:
+ *   its own `.git/` object store, no alternates, no Git metadata outside the
+ *   folder, so a running Docker or Apple container (whose bind mounts cannot
+ *   grow) and a task machine see it the same way. No Git ever runs on the
+ *   runner's host against task data (docs/agent-notes.md, "Security
+ *   invariants"), and the clone authenticates with exactly the credentials the
+ *   task's own runtime already holds for its owner.
+ * - **Activate** first persists an *activation intent* (the operation, the
+ *   staging and target paths, and a random activation id the staged clone
+ *   carries in `.git/uai-activation`), then renames the clone to
+ *   `/workspace/<slug>` with one rename(2), then persists `published`. A
+ *   crash between any two of those steps is recovered from the disk, never
+ *   guessed: the target holding the clone with that id (and the staging path
+ *   gone) proves publication; the staging path holding it (and the target
+ *   absent) proves the opposite; anything else is `uncertain` and nothing is
+ *   deleted.
+ * - After publication, Activate installs the project into the task's env
+ *   spec, then runs dependency setup as the task user, without privileges,
+ *   best-effort. A failed step is a warning (`ready_with_warning`), never a
+ *   rollback: package managers run arbitrary lifecycle scripts, and Uai does
+ *   not pretend to undo them. Runtimes are never installed live: a project
+ *   whose `.tool-versions` names one the task lacks gets a warning to restart
+ *   the task, whose ordinary task-up materializes it (§2.4, as built).
+ * - **Compensate** removes only a staged clone that was provably never
+ *   published.
+ * - **Status** answers the journal, with any intent resolved from the disk.
+ *
+ * Every command names the run (`runEpoch`) and the project-set revision it
+ * belongs to. A run the runner has not admitted is refused, and once a
+ * revision has begun activating or has compensated, no command for an older
+ * revision publishes.
+ */
+
+import { randomBytes } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+import type {
+  ProjectEnvSchemaObservation,
+  TaskCommandProject,
+  TaskProjectActivateInput,
+  TaskProjectActivateResult,
+  TaskProjectCompensateInput,
+  TaskProjectCompensateResult,
+  TaskProjectMilestone,
+  TaskProjectPrepareInput,
+  TaskProjectPrepareResult,
+  TaskProjectRefusal,
+  TaskProjectStatusInput,
+  TaskProjectStatusResult,
+} from "../src/protocol";
+import { RUNTIME_AUTHORITY_ENV } from "./runtime-authority";
+import type {
+  TaskEnvironmentExecRequest,
+  TaskEnvironmentExecResult,
+  TaskEnvironmentHandle,
+} from "./task-environment/types";
+
+/** The task user every live-project step runs as. Never root. */
+export const TASK_PROJECT_USER = "node";
+
+const SLUG = /^[a-z0-9-]{1,64}$/;
+const OPERATION_ID = /^[0-9A-Za-z]{10,64}$/;
+const ACTIVATION_ID = /^[0-9a-f]{32}$/;
+/** Git remotes a task may clone: GitHub/GitLab-style HTTPS and SSH only.
+ *  Never `file://`, `ext::` or a leading dash a Git option could take. */
+const REPO_URL = /^(?:https:\/\/[A-Za-z0-9.-]+(?::\d+)?\/|ssh:\/\/[A-Za-z0-9._-]+@[A-Za-z0-9.-]+(?::\d+)?\/|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:)[A-Za-z0-9._~\/-]+$/;
+const BRANCH = /^(?!-)(?!.*\.\.)(?!.*\/\/)[A-Za-z0-9._\/-]{1,200}$/;
+
+export const TASK_PROJECT_CLONE_TIMEOUT_MS = 10 * 60_000;
+export const TASK_PROJECT_SETUP_TIMEOUT_MS = 15 * 60_000;
+const SHORT_TIMEOUT_MS = 60_000;
+const OUTPUT_BYTES = 256 * 1024;
+
+const NON_INTERACTIVE_GIT_ENV: Readonly<Record<string, string>> = Object.freeze({
+  GIT_TERMINAL_PROMPT: "0",
+  GCM_INTERACTIVE: "never",
+  GIT_SSH_COMMAND: "ssh -o BatchMode=yes",
+});
+
+// ---------------------------------------------------------------------------
+// The journal
+// ---------------------------------------------------------------------------
+
+type JournalMilestone =
+  | "prepared"
+  | "activation_intent"
+  | "published"
+  | "ready"
+  | "ready_with_warning"
+  | "compensated";
+
+export interface TaskProjectJournal {
+  v: 1;
+  operationId: string;
+  taskId: string;
+  runEpoch: number;
+  projectSetRevision: number;
+  projectId: string;
+  slug: string;
+  activationId: string;
+  stagingPath: string;
+  targetPath: string;
+  head: string | null;
+  milestone: JournalMilestone;
+  warning: string | null;
+  updatedAt: number;
+}
+
+/** The highest project-set revision that began activating or compensated:
+ *  no older revision publishes after it. */
+interface TaskProjectFence {
+  v: 1;
+  revision: number;
+}
+
+function syncDirectory(path: string): void {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY);
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** tmp (O_EXCL|O_NOFOLLOW, 0600) + fsync + rename + directory fsync: a crash
+ *  leaves either the old record or the new one, never a torn one. */
+function writeDurable(path: string, value: unknown): void {
+  const staged = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  let fd: number | null = null;
+  try {
+    fd = openSync(
+      staged,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+      0o600,
+    );
+    writeFileSync(fd, `${JSON.stringify(value)}\n`, "utf8");
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+    renameSync(staged, path);
+    syncDirectory(dirname(path));
+  } catch (error) {
+    if (fd !== null) closeSync(fd);
+    try {
+      unlinkSync(staged);
+    } catch {
+      // The staged file never existed or is already gone.
+    }
+    throw error;
+  }
+}
+
+function readDurable(path: string): unknown {
+  let info;
+  try {
+    info = lstatSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new Error(`live-project journal entry is not a regular file: ${path}`);
+  }
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    return JSON.parse(readFileSync(fd, "utf8"));
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function isJournal(value: unknown): value is TaskProjectJournal {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.v === 1 &&
+    typeof v.operationId === "string" &&
+    OPERATION_ID.test(v.operationId) &&
+    typeof v.taskId === "string" &&
+    Number.isSafeInteger(v.runEpoch) &&
+    Number.isSafeInteger(v.projectSetRevision) &&
+    typeof v.projectId === "string" &&
+    typeof v.slug === "string" &&
+    SLUG.test(v.slug) &&
+    typeof v.activationId === "string" &&
+    ACTIVATION_ID.test(v.activationId) &&
+    typeof v.stagingPath === "string" &&
+    typeof v.targetPath === "string" &&
+    (v.head === null || typeof v.head === "string") &&
+    typeof v.milestone === "string" &&
+    ["prepared", "activation_intent", "published", "ready", "ready_with_warning", "compensated"].includes(
+      v.milestone,
+    ) &&
+    (v.warning === null || typeof v.warning === "string")
+  );
+}
+
+export class TaskProjectJournalStore {
+  constructor(private readonly dirFor: (taskId: string) => string) {}
+
+  private dir(taskId: string): string {
+    const dir = join(this.dirFor(taskId), "project-ops");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const info = lstatSync(dir);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw new Error("the live-project journal directory is not a private directory");
+    }
+    return dir;
+  }
+
+  read(taskId: string, operationId: string): TaskProjectJournal | null {
+    if (!OPERATION_ID.test(operationId)) throw new Error("invalid operation id");
+    const value = readDurable(join(this.dir(taskId), `${operationId}.json`));
+    if (value === null) return null;
+    if (!isJournal(value) || value.operationId !== operationId || value.taskId !== taskId) {
+      throw new Error("the live-project journal entry is malformed");
+    }
+    return value;
+  }
+
+  write(journal: TaskProjectJournal): void {
+    writeDurable(join(this.dir(journal.taskId), `${journal.operationId}.json`), {
+      ...journal,
+      updatedAt: Date.now(),
+    });
+  }
+
+  fence(taskId: string): number {
+    const value = readDurable(join(this.dir(taskId), "fence.json")) as TaskProjectFence | null;
+    if (value === null) return 0;
+    if (value.v !== 1 || !Number.isSafeInteger(value.revision)) {
+      throw new Error("the live-project fence is malformed");
+    }
+    return value.revision;
+  }
+
+  raiseFence(taskId: string, revision: number): void {
+    if (revision <= this.fence(taskId)) return;
+    writeDurable(join(this.dir(taskId), "fence.json"), { v: 1, revision } satisfies TaskProjectFence);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The scripts (literal argv; every value arrives as a positional argument)
+// ---------------------------------------------------------------------------
+
+/**
+ * $1 staging repo path, $2 target path, $3 repo URL, $4 task branch,
+ * $5 activation id, $6 the project's fallback `.tool-versions` ("" for none).
+ * Exit 3: the target already exists. The last stdout line is the checked-out
+ * commit, or `empty` for a repository with no commits.
+ */
+export const PREPARE_SCRIPT = `set -eu
+staging=$1 target=$2 url=$3 branch=$4 id=$5 tool_versions=\${6:-}
+if [ -e "$target" ] || [ -L "$target" ]; then
+  echo "uai: $target already exists" >&2
+  exit 3
+fi
+rm -rf -- "$staging"
+mkdir -p -- "$(dirname -- "$staging")"
+git clone --quiet --no-hardlinks --origin origin -- "$url" "$staging"
+cd -- "$staging"
+if git rev-parse --verify --quiet "refs/remotes/origin/$branch^{commit}" >/dev/null; then
+  git checkout --quiet -B "$branch" "refs/remotes/origin/$branch"
+  git branch --quiet --set-upstream-to="origin/$branch" "$branch"
+elif git rev-parse --verify --quiet "HEAD^{commit}" >/dev/null; then
+  current=$(git symbolic-ref --quiet --short HEAD || true)
+  if [ "$current" != "$branch" ]; then
+    git checkout --quiet -b "$branch"
+  fi
+else
+  # An empty remote: the first commit lands on the task branch, as at start.
+  git symbolic-ref HEAD "refs/heads/$branch"
+fi
+# The project's fallback runtimes, only when the repository ships none
+# (task-up.sh's seeding, so the setup check sees what a start would).
+if [ -n "$tool_versions" ] && [ ! -e .tool-versions ] && [ ! -L .tool-versions ]; then
+  printf '%s\\n' "$tool_versions" > .tool-versions
+fi
+printf '%s\\n' "$id" > .git/uai-activation
+git rev-parse --verify --quiet "HEAD^{commit}" || echo empty
+`;
+
+/**
+ * $1 staging, $2 target, $3 activation id. One rename(2). Exit 0: renamed
+ * (or already renamed by this activation). Exit 3: the target is someone
+ * else's. Exit 4: the staged clone is not this activation's.
+ */
+export const RENAME_SCRIPT = `set -eu
+staging=$1 target=$2 id=$3
+marker() { cat -- "$1/.git/uai-activation" 2>/dev/null || true; }
+if [ -e "$target" ] || [ -L "$target" ]; then
+  if [ ! -L "$target" ] && [ "$(marker "$target")" = "$id" ] && [ ! -e "$staging" ]; then
+    exit 0
+  fi
+  exit 3
+fi
+if [ -L "$staging" ] || [ ! -d "$staging" ] || [ "$(marker "$staging")" != "$id" ]; then
+  exit 4
+fi
+mv -T -- "$staging" "$target"
+`;
+
+/** $1 staging, $2 target, $3 activation id. Prints exactly one verdict. */
+export const RESOLVE_SCRIPT = `set -u
+staging=$1 target=$2 id=$3
+marker() { cat -- "$1/.git/uai-activation" 2>/dev/null || true; }
+target_ours=0 staging_ours=0
+if [ -d "$target" ] && [ ! -L "$target" ] && [ "$(marker "$target")" = "$id" ]; then target_ours=1; fi
+if [ -d "$staging" ] && [ ! -L "$staging" ] && [ "$(marker "$staging")" = "$id" ]; then staging_ours=1; fi
+if [ "$target_ours" = 1 ] && [ ! -e "$staging" ] && [ ! -L "$staging" ]; then echo published
+elif [ "$staging_ours" = 1 ] && [ ! -e "$target" ] && [ ! -L "$target" ]; then echo not_published
+else echo uncertain
+fi
+`;
+
+/** $1 repository, then git's own arguments. */
+export const GIT_IN_SCRIPT = `set -eu
+repo=$1
+shift
+exec git -C "$repo" "$@"
+`;
+
+/** $1 staging op directory. Removes only what Prepare made. */
+export const COMPENSATE_SCRIPT = `set -eu
+rm -rf -- "$1"
+`;
+
+/** $1 target. Prints the Git top level as the runtime sees it. */
+export const TOPLEVEL_SCRIPT = `set -eu
+cd -- "$1"
+git rev-parse --show-toplevel
+`;
+
+/**
+ * Run in the published folder as the task user, with the task's project env:
+ * the same per-folder heuristics as uai-init's install_folder_deps, but each
+ * failure is reported instead of swallowed. Runtimes are only checked.
+ *
+ * The result travels on this script's stdout as `uai-setup-<nonce> <kind>
+ * <text>` lines, and nothing else writes there: every installer runs with
+ * stdout sent to stderr and stdin from /dev/null. The nonce arrives on this
+ * script's stdin, never in argv or the environment, so a repository's
+ * lifecycle scripts can neither read it nor forge a result line (PR #641
+ * review).
+ */
+export const SETUP_SCRIPT = `set -u
+IFS= read -r nonce || nonce=""
+case "$nonce" in *[!0-9a-f]*|"") echo "uai: setup needs its nonce" >&2; exit 64 ;; esac
+mark() { printf 'uai-setup-%s %s %s\\n' "$nonce" "$1" "$2"; }
+quiet() { "$@" </dev/null 1>&2; }
+# The effective requirements: this folder's .tool-versions (the repository's,
+# or the project's fallback Prepare seeded, as at start), parsed and checked
+# with the startup materializer's rules (uai-materialize-runtimes,
+# validate_manifest/validate_version). Every selector is either proven
+# usable or reported: a probe that can't run, or one it skips, never reads as
+# installed (asdf 0.14 prints "not installed" on stderr).
+check_runtime() {
+  tool=$1 version=$2
+  case "$version" in
+    system) return 0 ;;
+    path:*)
+      suffix=\${version#path:}
+      case "$suffix" in
+        ""|/*|"~"*) mark invalid-runtime "$tool $version (path: must name a directory inside the repository)"; return 0 ;;
+      esac
+      resolved=$(realpath -e -- "$suffix" 2>/dev/null) || { mark invalid-runtime "$tool $version (path: does not resolve)"; return 0; }
+      here=$(realpath -e -- . 2>/dev/null) || here=$PWD
+      case "$resolved" in
+        "$here"/*) [ -d "$resolved" ] || mark invalid-runtime "$tool $version (path: is not a directory)" ;;
+        *) mark invalid-runtime "$tool $version (path: escapes the repository)" ;;
+      esac
+      return 0
+      ;;
+    ref:*)
+      suffix=\${version#ref:}
+      case "$suffix" in
+        ""|*/*) mark invalid-runtime "$tool $version (ref: needs one path segment)"; return 0 ;;
+      esac
+      [[ "$suffix" =~ ^[[:alnum:]][[:alnum:].+_@-]*$ ]] || { mark invalid-runtime "$tool $version (malformed ref:)"; return 0; }
+      ;;
+    ref-*|*/*) mark invalid-runtime "$tool $version (a start would refuse this version)"; return 0 ;;
+    *)
+      [[ "$version" =~ ^[[:alnum:]][[:alnum:].+_@-]*$ ]] || { mark invalid-runtime "$tool $version (malformed version)"; return 0; }
+      ;;
+  esac
+  case "/$version/" in *"/../"*|*"/./"*|*"//"*) mark invalid-runtime "$tool $version (unsafe version path)"; return 0 ;; esac
+  if ! command -v asdf >/dev/null 2>&1; then
+    mark missing-runtime "$tool $version (no asdf to check it)"
+  elif ! asdf where "$tool" "$version" </dev/null >/dev/null 2>&1; then
+    mark missing-runtime "$tool $version"
+  fi
+}
+if [ -L .tool-versions ]; then
+  mark invalid-runtime ".tool-versions (a symbolic link; a start would refuse it)"
+elif [ -f .tool-versions ]; then
+  if LC_ALL=C grep -q '[[:cntrl:]]' .tool-versions; then
+    mark invalid-runtime ".tool-versions (control characters; a start would refuse it)"
+  else
+    while IFS= read -r line || [ -n "$line" ]; do
+      line=\${line%%#*}
+      read -r -a fields <<< "$line" || true
+      [ "\${#fields[@]}" -gt 0 ] || continue
+      tool=\${fields[0]}
+      if [ "\${#fields[@]}" -lt 2 ] || [[ ! "$tool" =~ ^[a-z0-9][a-z0-9_-]*$ ]]; then
+        mark invalid-runtime "$line (a start would refuse this line)"
+        continue
+      fi
+      case "$tool" in
+        nodejs|python|golang|ruby|rust)
+          for version in "\${fields[@]:1}"; do check_runtime "$tool" "$version"; done
+          ;;
+        pnpm|yarn)
+          # Corepack's, as at start: one exact pinned version.
+          if [ "\${#fields[@]}" -ne 2 ] || [[ ! "\${fields[1]}" =~ ^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+            mark invalid-runtime "$tool \${fields[*]:1} (must pin one exact version)"
+          fi
+          ;;
+        *) mark invalid-runtime "$tool (not a runtime a task can install)" ;;
+      esac
+    done < .tool-versions
+  fi
+fi
+if [ -f package.json ]; then
+  pm=$(jq -r '.packageManager // ""' package.json 2>/dev/null </dev/null | sed 's/@.*//' || true)
+  if [ -z "$pm" ]; then
+    if [ -f pnpm-lock.yaml ]; then pm=pnpm
+    elif [ -f yarn.lock ]; then pm=yarn
+    elif [ -f bun.lockb ] || [ -f bun.lock ]; then pm=bun
+    else pm=npm
+    fi
+  fi
+  case "$pm" in
+    pnpm) quiet pnpm install || mark failed-step "pnpm install" ;;
+    yarn) quiet yarn install || mark failed-step "yarn install" ;;
+    bun) quiet bun install || mark failed-step "bun install" ;;
+    *) quiet npm install --no-audit --no-fund || mark failed-step "npm install" ;;
+  esac
+fi
+if [ -f pyproject.toml ]; then
+  quiet uv sync || mark failed-step "uv sync"
+elif [ -f requirements.txt ]; then
+  { quiet uv venv && quiet uv pip install -r requirements.txt; } || mark failed-step "uv pip install"
+fi
+if [ -f Cargo.toml ]; then quiet cargo build || mark failed-step "cargo build"; fi
+if [ -f go.mod ]; then quiet go mod download || mark failed-step "go mod download"; fi
+exit 0
+`;
+
+// ---------------------------------------------------------------------------
+// The commands
+// ---------------------------------------------------------------------------
+
+/** A warning reaches chat and every agent's note: one line, bounded. */
+export const TASK_PROJECT_WARNING_MAX = 4096;
+
+/** Control characters (newlines included) and whitespace runs become one space. */
+export function oneLine(value: string): string {
+  return value.replace(/[\s\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, " ").trim();
+}
+
+export function boundWarning(value: string): string {
+  const line = oneLine(value);
+  return line.length > TASK_PROJECT_WARNING_MAX ? `${line.slice(0, TASK_PROJECT_WARNING_MAX - 1)}…` : line;
+}
+
+/** Only lines carrying this run's nonce count; each item is one bounded
+ *  line, and at most 20 of each kind are kept. */
+export function parseSetupResult(
+  stdout: string,
+  nonce: string,
+): { missing: string[]; invalid: string[]; failed: string[] } {
+  const missing: string[] = [];
+  const invalid: string[] = [];
+  const failed: string[] = [];
+  const prefix = `uai-setup-${nonce} `;
+  for (const raw of stdout.split("\n")) {
+    if (!raw.startsWith(prefix)) continue;
+    const rest = raw.slice(prefix.length);
+    const space = rest.indexOf(" ");
+    if (space < 0) continue;
+    const kind = rest.slice(0, space);
+    const item = oneLine(rest.slice(space + 1)).slice(0, 200);
+    if (!item) continue;
+    if (kind === "missing-runtime" && missing.length < 20) missing.push(item);
+    if (kind === "invalid-runtime" && invalid.length < 20) invalid.push(item);
+    if (kind === "failed-step" && failed.length < 20) failed.push(item);
+  }
+  return { missing, invalid, failed };
+}
+
+export type TaskProjectEnvironment = Pick<TaskEnvironmentHandle, "exec" | "descriptor">;
+
+export interface TaskProjectOpsDeps {
+  journal: TaskProjectJournalStore;
+  /** The task's runtime while its current run is live; null otherwise. */
+  environment(taskId: string): Promise<TaskProjectEnvironment | null>;
+  /** Whether `runEpoch` is the task's admitted, open run right now. */
+  runIsCurrent(taskId: string, runEpoch: number): boolean;
+  /** Runs `fn` in the task's lifecycle slot (short critical sections only). */
+  inLifecycleSlot<T>(taskId: string, fn: () => Promise<T>): Promise<T>;
+  credentials(): "cloud" | "own";
+  /** The grant the run holds now (cloud credentials), else null. */
+  installedGrant(
+    taskId: string,
+    runEpoch: number,
+  ): { runEpoch: number; manifestRevision: number; manifestDigest: string } | null;
+  /** Whether the task's env serves `projectId` for this run now. */
+  envServes(taskId: string, runEpoch: number, projectId: string): boolean;
+  /** Every project the run's env serves now (cloud credentials), else null. */
+  servedProjectIds(taskId: string, runEpoch: number): string[] | null;
+  /** Whether the running environment can take a project live: it has a
+   *  persisted env spec and a live env gateway to extend. */
+  liveProjectsSupported(taskId: string): boolean;
+  /** Reads and stores the `.env.schema` observation of a fresh clone (git
+   *  run in it); the stored one when there is one. */
+  captureEnvSchema(
+    taskId: string,
+    projectId: string,
+    git: (args: string[]) => Promise<Buffer | null>,
+  ): Promise<ProjectEnvSchemaObservation>;
+  storedEnvSchema(taskId: string, projectId: string): ProjectEnvSchemaObservation | null;
+  /** Adds the project (and its preview URL literals) to the task's persisted
+   *  env spec and always re-points the live resolver at it. Idempotent;
+   *  throws when the environment can't take it. */
+  installProjectEnv(
+    taskId: string,
+    runEpoch: number,
+    project: TaskCommandProject,
+    previewEnv: Record<string, string>,
+  ): void;
+  /** Test seam: called right after the rename, before `published` is
+   *  journaled. Throwing simulates a crash at the worst moment. */
+  afterRename?: () => void;
+  now?: () => number;
+}
+
+function refused<T extends { outcome: string }>(
+  reason: TaskProjectRefusal | "uncertain",
+  message: string,
+): T {
+  return { outcome: "refused", reason, message } as unknown as T;
+}
+
+function text(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("utf8");
+}
+
+function tail(value: string, max = 600): string {
+  const trimmed = value.trim();
+  return trimmed.length > max ? `…${trimmed.slice(trimmed.length - max)}` : trimmed;
+}
+
+function scriptRequest(
+  script: string,
+  name: string,
+  args: readonly string[],
+  options: {
+    cwd: string;
+    timeoutMs: number;
+    profile?: TaskEnvironmentExecRequest["projectEnvProfile"];
+  },
+): TaskEnvironmentExecRequest {
+  return {
+    argv: [
+      "/usr/bin/timeout",
+      "--signal=KILL",
+      String(Math.ceil(options.timeoutMs / 1000)),
+      "/bin/bash",
+      "-c",
+      script,
+      name,
+      ...args,
+    ],
+    cwd: options.cwd,
+    user: TASK_PROJECT_USER,
+    env: { ...RUNTIME_AUTHORITY_ENV, ...NON_INTERACTIVE_GIT_ENV },
+    projectEnvProfile: options.profile ?? "maintenance",
+    timeoutMs: options.timeoutMs + 15_000,
+    maxOutputBytes: OUTPUT_BYTES,
+  };
+}
+
+function paths(workspacePath: string, operationId: string, slug: string) {
+  const root = workspacePath.replace(/\/+$/, "");
+  const opDir = `${root}/.uai/.project-staging/${operationId}`;
+  return { opDir, stagingPath: `${opDir}/repo`, targetPath: `${root}/${slug}` };
+}
+
+const ACCESS_DENIED = [
+  /authentication failed/i,
+  /permission denied \(publickey/i,
+  /repository not found/i,
+  /could not read (username|password)/i,
+  /terminal prompts disabled/i,
+  /access denied/i,
+  /\b403\b/,
+  /host key verification failed/i,
+];
+
+export function classifyCloneFailure(result: TaskEnvironmentExecResult): {
+  reason: TaskProjectRefusal;
+  message: string;
+} {
+  const stderr = text(result.stderr);
+  if (result.exitCode === 3) {
+    return { reason: "workspace_path_taken", message: tail(stderr) || "the target folder already exists" };
+  }
+  if (ACCESS_DENIED.some((pattern) => pattern.test(stderr))) {
+    return {
+      reason: "repo_access_denied",
+      message:
+        `the task's credentials cannot read this repository: ${tail(stderr, 300)}. ` +
+        "Fix the owner's GitHub App/user access or SSH key, then retry.",
+    };
+  }
+  return {
+    reason: "clone_failed",
+    message: tail(stderr) || `the clone exited ${result.exitCode ?? result.signal ?? "?"}`,
+  };
+}
+
+export class TaskProjectOps {
+  /** One live-project command at a time per task. */
+  private readonly tails = new Map<string, Promise<unknown>>();
+
+  constructor(private readonly deps: TaskProjectOpsDeps) {}
+
+  private serialized<T>(taskId: string, fn: () => Promise<T>): Promise<T> {
+    const previous = this.tails.get(taskId) ?? Promise.resolve();
+    const run = previous.catch(() => undefined).then(fn);
+    const settled = run.catch(() => undefined);
+    this.tails.set(taskId, settled);
+    void settled.then(() => {
+      if (this.tails.get(taskId) === settled) this.tails.delete(taskId);
+    });
+    return run;
+  }
+
+  private fenceFails(input: { taskId: string; runEpoch: number; projectSetRevision?: number }):
+    | { reason: TaskProjectRefusal; message: string }
+    | null {
+    if (!this.deps.runIsCurrent(input.taskId, input.runEpoch)) {
+      return {
+        reason: "not_running",
+        message: `run ${input.runEpoch} is not this task's admitted, open run`,
+      };
+    }
+    if (
+      input.projectSetRevision !== undefined &&
+      input.projectSetRevision < this.deps.journal.fence(input.taskId)
+    ) {
+      return {
+        reason: "stale",
+        message: `project-set revision ${input.projectSetRevision} is older than one this runner already activated or compensated`,
+      };
+    }
+    return null;
+  }
+
+  prepare(input: TaskProjectPrepareInput): Promise<TaskProjectPrepareResult> {
+    return this.serialized(input.taskId, async () => {
+      if (!OPERATION_ID.test(input.operationId)) throw new Error("invalid operation id");
+      if (!SLUG.test(input.project.slug)) throw new Error("invalid project slug");
+      if (!REPO_URL.test(input.project.repoUrl)) {
+        return refused<TaskProjectPrepareResult>("clone_failed", "the repository URL is not an HTTPS or SSH Git remote");
+      }
+      if (!BRANCH.test(input.branch)) throw new Error("invalid task branch");
+      const fenced = this.fenceFails(input);
+      if (fenced) return refused<TaskProjectPrepareResult>(fenced.reason, fenced.message);
+
+      const existing = this.deps.journal.read(input.taskId, input.operationId);
+      if (existing) {
+        if (existing.milestone === "compensated") {
+          return refused<TaskProjectPrepareResult>("compensated", "this operation was compensated");
+        }
+        return {
+          outcome: "prepared",
+          head: existing.head,
+          envSchema: this.deps.storedEnvSchema(input.taskId, existing.projectId),
+        };
+      }
+      if (!this.deps.liveProjectsSupported(input.taskId)) {
+        return refused<TaskProjectPrepareResult>(
+          "unsupported_environment",
+          "this task's environment fixes its env at start, so it can't take a repository while it runs",
+        );
+      }
+
+      const environment = await this.deps.environment(input.taskId);
+      if (!environment) {
+        return refused<TaskProjectPrepareResult>("not_running", "the task's runtime is not available");
+      }
+      const where = paths(environment.descriptor.workspacePath, input.operationId, input.project.slug);
+      const activationId = randomBytes(16).toString("hex");
+      const result = await environment.exec(
+        scriptRequest(
+          PREPARE_SCRIPT,
+          "uai-project-prepare",
+          [
+            where.stagingPath,
+            where.targetPath,
+            input.project.repoUrl,
+            input.branch,
+            activationId,
+            input.project.toolVersions ?? "",
+          ],
+          { cwd: environment.descriptor.workspacePath, timeoutMs: TASK_PROJECT_CLONE_TIMEOUT_MS },
+        ),
+      );
+      if (result.exitCode !== 0) {
+        const failure = classifyCloneFailure(result);
+        // Leave nothing half-cloned behind; the folder is ours alone.
+        await environment
+          .exec(
+            scriptRequest(COMPENSATE_SCRIPT, "uai-project-compensate", [where.opDir], {
+              cwd: environment.descriptor.workspacePath,
+              timeoutMs: SHORT_TIMEOUT_MS,
+            }),
+          )
+          .catch(() => undefined);
+        return refused<TaskProjectPrepareResult>(failure.reason, failure.message);
+      }
+      // The run may have ended during a long clone.
+      const after = this.fenceFails(input);
+      if (after) return refused<TaskProjectPrepareResult>(after.reason, after.message);
+      const lines = text(result.stdout).trim().split("\n");
+      const last = lines[lines.length - 1]?.trim() ?? "";
+      const head = /^[0-9a-f]{40,64}$/.test(last) ? last : null;
+      // ADR-153 §4: the schema observation is read from the fresh clone and
+      // stored before the project reaches any env consumer (Activate).
+      const envSchema = await this.deps.captureEnvSchema(input.taskId, input.project.id, async (args) => {
+        const ran = await environment.exec(
+          scriptRequest(GIT_IN_SCRIPT, "uai-project-git", [where.stagingPath, ...args], {
+            cwd: environment.descriptor.workspacePath,
+            timeoutMs: SHORT_TIMEOUT_MS,
+          }),
+        );
+        return ran.exitCode === 0 ? Buffer.from(ran.stdout) : null;
+      });
+      this.deps.journal.write({
+        v: 1,
+        operationId: input.operationId,
+        taskId: input.taskId,
+        runEpoch: input.runEpoch,
+        projectSetRevision: input.projectSetRevision,
+        projectId: input.project.id,
+        slug: input.project.slug,
+        activationId,
+        stagingPath: where.stagingPath,
+        targetPath: where.targetPath,
+        head,
+        milestone: "prepared",
+        warning: null,
+        updatedAt: Date.now(),
+      });
+      return { outcome: "prepared", head, envSchema };
+    });
+  }
+
+  /** Reads the disk for an intent with no `published`. Journals `published`
+   *  when proven. Call inside the lifecycle slot. */
+  private async resolveIntent(
+    journal: TaskProjectJournal,
+    environment: TaskProjectEnvironment,
+  ): Promise<"published" | "not_published" | "uncertain"> {
+    const result = await environment.exec(
+      scriptRequest(
+        RESOLVE_SCRIPT,
+        "uai-project-resolve",
+        [journal.stagingPath, journal.targetPath, journal.activationId],
+        { cwd: environment.descriptor.workspacePath, timeoutMs: SHORT_TIMEOUT_MS },
+      ),
+    );
+    if (result.exitCode !== 0) return "uncertain";
+    const verdict = text(result.stdout).trim();
+    if (verdict === "published") {
+      this.deps.journal.write({ ...journal, milestone: "published" });
+      return "published";
+    }
+    return verdict === "not_published" ? "not_published" : "uncertain";
+  }
+
+  activate(input: TaskProjectActivateInput): Promise<TaskProjectActivateResult> {
+    return this.serialized(input.taskId, async () => {
+      const fenced = this.fenceFails(input);
+      if (fenced) return refused<TaskProjectActivateResult>(fenced.reason, fenced.message);
+      let journal = this.deps.journal.read(input.taskId, input.operationId);
+      if (!journal) return refused<TaskProjectActivateResult>("not_prepared", "this operation was never prepared here");
+      if (journal.milestone === "compensated") {
+        return refused<TaskProjectActivateResult>("compensated", "this operation was compensated");
+      }
+      if (journal.milestone === "ready" || journal.milestone === "ready_with_warning") {
+        return { outcome: journal.milestone, warning: journal.warning };
+      }
+      if (journal.projectId !== input.project.id || journal.slug !== input.project.slug) {
+        throw new Error("the activation names a different project than its preparation");
+      }
+      const environment = await this.deps.environment(input.taskId);
+      if (!environment) return refused<TaskProjectActivateResult>("not_running", "the task's runtime is not available");
+
+      // Intent, rename and `published` happen in the lifecycle slot, so a
+      // stop or teardown never lands between the run check and the rename.
+      const publication = await this.deps.inLifecycleSlot(input.taskId, async () => {
+        const inSlot = this.fenceFails(input);
+        if (inSlot) return { refused: inSlot } as const;
+        let current = this.deps.journal.read(input.taskId, input.operationId)!;
+        if (current.milestone === "activation_intent") {
+          const verdict = await this.resolveIntent(current, environment);
+          if (verdict === "uncertain") return { uncertain: true } as const;
+          current = this.deps.journal.read(input.taskId, input.operationId)!;
+        }
+        if (current.milestone === "prepared" || current.milestone === "activation_intent") {
+          if (input.grant !== null) {
+            const installed = this.deps.installedGrant(input.taskId, input.runEpoch);
+            if (
+              !installed ||
+              installed.manifestRevision !== input.grant.manifestRevision ||
+              installed.manifestDigest !== input.grant.manifestDigest
+            ) {
+              return {
+                refused: {
+                  reason: "grant_not_installed" as const,
+                  message: `this run holds ${installed ? `grant ${installed.manifestRevision}` : "no grant"}, not ${input.grant.manifestRevision}`,
+                },
+              } as const;
+            }
+          }
+          if (!this.deps.envServes(input.taskId, input.runEpoch, input.project.id)) {
+            return {
+              refused: {
+                reason: "grant_not_installed" as const,
+                message: "the task's env does not serve this project yet",
+              },
+            } as const;
+          }
+          // No older revision may publish once this one has begun.
+          this.deps.journal.raiseFence(input.taskId, input.projectSetRevision);
+          if (current.milestone === "prepared") {
+            current = { ...current, milestone: "activation_intent" };
+            this.deps.journal.write(current);
+          }
+          const renamed = await environment.exec(
+            scriptRequest(
+              RENAME_SCRIPT,
+              "uai-project-publish",
+              [current.stagingPath, current.targetPath, current.activationId],
+              { cwd: environment.descriptor.workspacePath, timeoutMs: SHORT_TIMEOUT_MS },
+            ),
+          );
+          if (renamed.exitCode !== 0) {
+            const verdict = await this.resolveIntent(current, environment);
+            if (verdict === "published") {
+              current = this.deps.journal.read(input.taskId, input.operationId)!;
+            } else if (verdict === "not_published" && renamed.exitCode === 3) {
+              return {
+                refused: {
+                  reason: "workspace_path_taken" as const,
+                  message: `${current.targetPath} appeared before the rename`,
+                },
+              } as const;
+            } else {
+              return { uncertain: true } as const;
+            }
+          } else {
+            this.deps.afterRename?.();
+            current = { ...current, milestone: "published" };
+            this.deps.journal.write(current);
+          }
+        }
+        return { journal: current } as const;
+      });
+      if ("refused" in publication && publication.refused) {
+        return refused<TaskProjectActivateResult>(publication.refused.reason, publication.refused.message);
+      }
+      if ("uncertain" in publication) {
+        return {
+          outcome: "uncertain",
+          message: "the activation intent is recorded but the disk proves neither outcome; nothing was removed",
+        };
+      }
+      journal = publication.journal;
+
+      // Published. Everything below repairs forward and never deletes. The
+      // Git root and the env install are REQUIRED: a failure leaves the
+      // journal at `published` and answers `incomplete`, so a repeated
+      // Activate repairs them. Only dependency setup ends in a warning.
+      const toplevel = await environment.exec(
+        scriptRequest(TOPLEVEL_SCRIPT, "uai-project-toplevel", [journal.targetPath], {
+          cwd: environment.descriptor.workspacePath,
+          timeoutMs: SHORT_TIMEOUT_MS,
+        }),
+      );
+      if (toplevel.exitCode !== 0 || text(toplevel.stdout).trim() !== journal.targetPath) {
+        return refused<TaskProjectActivateResult>(
+          "incomplete",
+          `Git does not see ${journal.targetPath} as its own repository root yet`,
+        );
+      }
+      try {
+        this.deps.installProjectEnv(input.taskId, input.runEpoch, input.project, input.previewEnv);
+      } catch (error) {
+        return refused<TaskProjectActivateResult>(
+          "incomplete",
+          `the project's env is not installed for this run yet: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      const warnings: string[] = [];
+      const nonce = randomBytes(16).toString("hex");
+      const setup = await environment
+        .exec({
+          ...scriptRequest(SETUP_SCRIPT, "uai-project-setup", [], {
+            cwd: journal.targetPath,
+            timeoutMs: TASK_PROJECT_SETUP_TIMEOUT_MS,
+            profile: "task",
+          }),
+          stdin: new TextEncoder().encode(`${nonce}\n`),
+        })
+        .catch((error: unknown) => ({ error }));
+      if ("error" in setup) {
+        warnings.push(`dependency setup could not run: ${String((setup as { error: unknown }).error)}`);
+      } else {
+        const { missing, invalid, failed } = parseSetupResult(text(setup.stdout), nonce);
+        if (invalid.length > 0) {
+          warnings.push(
+            `the repository's .tool-versions has entries a task start would refuse (${invalid.join(", ")}); fix them before the task restarts`,
+          );
+        }
+        if (missing.length > 0) {
+          warnings.push(
+            `runtimes this repository asks for are not installed in this task (${missing.join(", ")}). ` +
+              "Uai doesn't install runtimes or extend the task's runtime allowlist while it runs; restart the task to install them",
+          );
+        }
+        if (failed.length > 0) warnings.push(`dependency setup failed: ${failed.join(", ")}`);
+        if (setup.exitCode !== 0 && failed.length === 0) {
+          warnings.push(`dependency setup exited ${setup.exitCode ?? setup.signal ?? "?"}`);
+        }
+      }
+      const warning = warnings.length > 0 ? boundWarning(warnings.join("; ")) : null;
+      const milestone = warning === null ? "ready" : "ready_with_warning";
+      this.deps.journal.write({ ...journal, milestone, warning });
+      return { outcome: milestone, warning };
+    });
+  }
+
+  /**
+   * Discards a staged clone that was provably never published — and with
+   * it anything an agent wrote there (staging is task-writable by design).
+   * Fenced like publication: only for this task's admitted run, only for the
+   * operation's own run and revision, and decided inside the lifecycle slot.
+   */
+  compensate(input: TaskProjectCompensateInput): Promise<TaskProjectCompensateResult> {
+    return this.serialized(input.taskId, async () => {
+      const environment = await this.deps.environment(input.taskId);
+      if (!environment) {
+        return refused<TaskProjectCompensateResult>("not_running", "the task's runtime is not available");
+      }
+      return this.deps.inLifecycleSlot(input.taskId, async () => {
+        if (!this.deps.runIsCurrent(input.taskId, input.runEpoch)) {
+          return refused<TaskProjectCompensateResult>(
+            "not_running",
+            `run ${input.runEpoch} is not this task's admitted, open run`,
+          );
+        }
+        const current = this.deps.journal.read(input.taskId, input.operationId);
+        // The fence first, even for a repeat: a cached `compensated` answers
+        // only the run and revision it was for (PR #641 re-review).
+        if (current && (current.runEpoch !== input.runEpoch || current.projectSetRevision !== input.projectSetRevision)) {
+          return refused<TaskProjectCompensateResult>("stale", "this compensation names another run or revision than the operation");
+        }
+        if (current?.milestone === "compensated") return { outcome: "compensated" } as const;
+        if (current && ["published", "ready", "ready_with_warning"].includes(current.milestone)) {
+          return refused<TaskProjectCompensateResult>("published", "the repository was published; recovery rolls forward");
+        }
+        if (current?.milestone === "activation_intent") {
+          const verdict = await this.resolveIntent(current, environment);
+          if (verdict === "published") {
+            return refused<TaskProjectCompensateResult>("published", "the repository was published; recovery rolls forward");
+          }
+          if (verdict === "uncertain") {
+            return refused<TaskProjectCompensateResult>("uncertain", "the disk proves neither outcome; nothing was removed");
+          }
+        }
+        const where = paths(environment.descriptor.workspacePath, input.operationId, current?.slug ?? "x");
+        const removed = await environment.exec(
+          scriptRequest(COMPENSATE_SCRIPT, "uai-project-compensate", [where.opDir], {
+            cwd: environment.descriptor.workspacePath,
+            timeoutMs: SHORT_TIMEOUT_MS,
+          }),
+        );
+        if (removed.exitCode !== 0) throw new Error(`could not remove the staged clone: ${tail(text(removed.stderr))}`);
+        this.deps.journal.raiseFence(input.taskId, input.projectSetRevision);
+        if (current) this.deps.journal.write({ ...current, milestone: "compensated" });
+        return { outcome: "compensated" } as const;
+      });
+    });
+  }
+
+  status(input: TaskProjectStatusInput): Promise<TaskProjectStatusResult> {
+    return this.serialized(input.taskId, async () => {
+      const credentials = this.deps.credentials();
+      const live = this.deps.runIsCurrent(input.taskId, input.runEpoch);
+      const base = {
+        installedGrant: live && credentials === "cloud" ? this.deps.installedGrant(input.taskId, input.runEpoch) : null,
+        envServes: live && this.deps.envServes(input.taskId, input.runEpoch, input.projectId),
+        servedProjectIds: live && credentials === "cloud" ? this.deps.servedProjectIds(input.taskId, input.runEpoch) : null,
+        credentials,
+      };
+      let journal = this.deps.journal.read(input.taskId, input.operationId);
+      if (!journal) return { milestone: "none", warning: null, ...base };
+      let milestone: TaskProjectMilestone;
+      if (journal.milestone === "activation_intent") {
+        const environment = await this.deps.environment(input.taskId);
+        if (!environment) throw new Error("the task's runtime is not available to resolve its activation");
+        milestone = await this.deps.inLifecycleSlot(input.taskId, async () => {
+          journal = this.deps.journal.read(input.taskId, input.operationId)!;
+          if (journal.milestone !== "activation_intent") return journal.milestone as TaskProjectMilestone;
+          return this.resolveIntent(journal, environment);
+        });
+      } else {
+        milestone = journal.milestone;
+      }
+      return { milestone, warning: journal.warning, ...base };
+    });
+  }
+}