@spunto/build 0.3.0 → 0.4.0

package/src/script/setup-script.ts

@@ -0,0 +1,1932 @@
+import { AVAILABLE_FEATURES } from "../catalogs/index"
+import { codeServerGallery, parseGallery, registryInfo } from "../extensions/extension-registry"
+import {
+  EXTENSIONS_DIR,
+  FEATURE_ENTRYPOINTS_FILE,
+  FEATURE_ENTRYPOINTS_STAGING_FILE,
+  workerStatusPath,
+} from "../naming/index"
+import { stepEndLine, stepStartLine, type BuildStep, type BuildStepKind } from "../steps/build-steps"
+import type { SetupStatus } from "../types/index"
+import { localFeatureScript } from "./local-features"
+
+// ─── Internal helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Base64 of a string's UTF-8 bytes — what `b64(s)` produced before this
+ * file left Node behind.
+ *
+ * The two-step dance is not decoration: `btoa` takes a *binary string*, one code unit per byte, and
+ * throws above U+00FF. Handed a JavaScript string directly it would reject an `é` in a postCreate
+ * command, and a surrogate pair would encode to bytes no decoder reads back. These payloads are
+ * `base64 -d`'d inside the container, so a wrong byte is a broken worker, not a mojibake.
+ */
+function b64(value: string): string {
+  const bytes = new TextEncoder().encode(value)
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+}
+
+
+/** Single-quotes a value for safe embedding in a shell command. Survives being
+ *  nested inside a double-quoted `su -c "..."` context, unlike double quotes. */
+function shQuote(v: string): string {
+  return `'${v.replace(/'/g, `'\\''`)}'`
+}
+
+/**
+ * `export EXTENSIONS_GALLERY=…`, or nothing when the org is on the default (Open VSX) registry.
+ *
+ * Emitted into the generated scripts rather than relied on from the ambient environment: a
+ * `docker build` doesn't inherit the daemon's env at all, and the code-server loop runs under `su`,
+ * which is free to strip it. A blob we couldn't parse emits nothing — see lib/extension-registry.ts:
+ * handing code-server a gallery the picker didn't search would recreate the split-brain the org
+ * setting exists to close.
+ */
+function galleryExport(extensionsGallery?: string | null): string[] {
+  const forward = codeServerGallery(extensionsGallery)
+  return forward ? [`export EXTENSIONS_GALLERY=${shQuote(forward)}`] : []
+}
+
+/** Registry name, flattened to something safe to echo from a shell script. */
+function registryLabel(extensionsGallery?: string | null): string {
+  return registryInfo(parseGallery(extensionsGallery)).name.replace(/[^\w .:/-]/g, "") || "the configured registry"
+}
+
+/** Produces an `env KEY=val ...` prefix for injecting secrets into a single command. */
+function envPrefix(secrets?: Record<string, string>): string {
+  if (!secrets || Object.keys(secrets).length === 0) return ""
+  const pairs = Object.entries(secrets).map(([k, v]) => `${k}=${shQuote(v)}`).join(" ")
+  return `env ${pairs} `
+}
+
+/** A project repository, reduced to what the clone step needs. */
+type CloneRepo = {
+  provider: string
+  project: string
+  workspacePath: string
+  cloneUrl?: string
+  /** Project-level default branch for this repo (optional). */
+  branch?: string
+}
+
+/**
+ * Branch actually checked out for a repo: the worker-level choice (made at creation, applies to
+ * every repo of the project) wins over the project-level default carried by the repository itself.
+ * Empty/blank on both sides → undefined = clone the remote's default branch (HEAD), the historical
+ * behaviour.
+ */
+export function resolveRepoBranch(repo: { branch?: string | null }, workerBranch?: string | null): string | undefined {
+  return workerBranch?.trim() || repo.branch?.trim() || undefined
+}
+
+/**
+ * Clone block for one repository — shared by the legacy script and the orchestrated plan (RFC 0017)
+ * so the two generators can't drift apart. Returns the `--- Cloning … ---` header line separately
+ * because the legacy path stamps its phase status between the header and the block.
+ *
+ * Clone strategy, in order of preference:
+ *  0. Generic "git" repo (RFC 0013): clone the raw cloneUrl using the per-project deploy key.
+ *     Works for any SSH host (StrictHostKeyChecking off); GIT_SSH_COMMAND is a no-op for HTTPS.
+ *  1. Org GitHub App installation token (RFC 0012): clone over HTTPS x-access-token for
+ *     org-scoped read access, then rewrite the remote to SSH so push/pull use the user's
+ *     personal key — and the token never persists in .git/config.
+ *  2. User personal SSH key (legacy / fallback when org has no installation).
+ *  3. Plain HTTPS (public repos only).
+ *
+ * When a branch is requested, `git clone --branch` posts it directly (it also accepts a tag). A ref
+ * that doesn't exist makes git fail immediately ("Remote branch … not found in upstream origin")
+ * without leaving a half-cloned workspace: we turn that into an explicit message + `exit 1` so the
+ * setup stops in `error` instead of silently landing on the default branch.
+ */
+function cloneRepoBlock(params: {
+  repo: CloneRepo
+  index: number
+  total: number
+  homeDir: string
+  branch?: string
+  githubInstallationTokens?: Record<string, string>
+  userSshPrivateKey?: string
+}): { header: string; lines: string[] } {
+  const { repo: r, index, total, homeDir, branch, githubInstallationTokens, userSshPrivateKey } = params
+  // Pick the installation token for this repo's owner. A GitHub App installation only grants
+  // access to repos owned by its account, so the owner login (== installation accountLogin)
+  // uniquely selects the right token among the org's connected installations. Covers legacy
+  // repos with no stored installationId too, since resolution is by owner, not by id.
+  const owner = (r.project.split("/")[0] ?? "").toLowerCase()
+  const repoToken = githubInstallationTokens?.[owner]
+  const b = branch ? ` --branch ${shQuote(branch)}` : ""
+  const cloneCmd = r.provider === "git" && r.cloneUrl
+    ? `GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -i ${homeDir}/.ssh/mp_deploy_key" git clone${b} ${shQuote(r.cloneUrl)} /workspace/${r.workspacePath}`
+    : r.provider === "github" && repoToken
+    ? `git clone${b} https://x-access-token:${repoToken}@github.com/${r.project}.git /workspace/${r.workspacePath} && git -C /workspace/${r.workspacePath} remote set-url origin git@github.com:${r.project}.git`
+    : r.provider === "github" && userSshPrivateKey
+    ? `GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -i ${homeDir}/.ssh/mp_user_key" git clone${b} git@github.com:${r.project}.git /workspace/${r.workspacePath}`
+    : `git clone${b} https://github.com/${r.project} /workspace/${r.workspacePath}`
+
+  // Single-quoted only when a (user-provided) branch is interpolated; the plain form is kept
+  // verbatim for the no-branch case so the generated script is unchanged there.
+  const header = branch
+    ? `echo ${shQuote(`--- Cloning ${r.project} (branch ${branch}) (${index + 1}/${total}) ---`)}`
+    : `echo "--- Cloning ${r.project} (${index + 1}/${total}) ---"`
+  // Single quotes only: this message ends up inside the JSON status written by the failure trap.
+  const failMsg = `Clone of ${r.project} failed — branch '${branch}' does not exist on the remote (or the repo is unreachable)`
+  const lines = [
+    `if [ ! -d "/workspace/${r.workspacePath}/.git" ]; then`,
+    ...(branch
+      ? [
+          // set +e around the clone so the message below is emitted before the script aborts —
+          // `set -e` alone would kill the shell on the failing clone with only git's own output.
+          `  set +e`,
+          `  ${cloneCmd}`,
+          `  _CLONE_EXIT=$?`,
+          `  set -e`,
+          `  if [ $_CLONE_EXIT -ne 0 ]; then`,
+          //  Two readers for the same message, so both setup paths show it instead of the generic
+          //  "phase failed": the legacy failure trap reads MP_FAIL_MSG, the agent (RFC 0017) reads
+          //  the file after a non-zero phase (the phase's own output goes to PID 1, not to the exec).
+          `    MP_FAIL_MSG=${shQuote(failMsg)}`,
+          `    printf '%s' "$MP_FAIL_MSG" > ${homeDir}/.mp-fail-msg 2>/dev/null || true`,
+          `    echo "[setup] ✗ $MP_FAIL_MSG" >&2`,
+          `    exit 1`,
+          `  fi`,
+        ]
+      : [`  ${cloneCmd}`]),
+    `else`,
+    `  echo "${r.project}: already present, skipping clone"`,
+    `fi`,
+  ]
+  return { header, lines }
+}
+
+/**
+ * Git identity + SSH credentials written into the worker's home — shared by the legacy script and
+ * the orchestrated plan (RFC 0017) so the two generators can't drift apart.
+ *
+ * Everything here runs as root (both setup paths do), so every file it creates lands root-owned.
+ * The block therefore ends by handing `~/.ssh` back to the worker's user: ssh SILENTLY IGNORES a
+ * `~/.ssh/config` it can't read (no error, exit 0 — it just falls back to the default identity
+ * files), so a root-owned config doesn't break loudly, it makes every `git pull`/`push` over SSH
+ * fail authentication for no visible reason. The legacy path used to be saved by its final
+ * `chown -R` (step 8), which the orchestrated plan has no equivalent of; chowning right here fixes
+ * both, and also makes the credentials usable by everything that runs as the user *during* setup
+ * (postCreateCommand, dotfiles install script).
+ */
+function credentialsBlock(params: {
+  homeDir: string
+  username: string
+  userInfo?: { name: string; email?: string | null }
+  userSshPrivateKey?: string
+  projectDeployKey?: string
+}): string[] {
+  const { homeDir, username, userInfo, userSshPrivateKey, projectDeployKey } = params
+  const lines: string[] = []
+
+  if (userInfo) {
+    lines.push(`git config --global user.name ${JSON.stringify(userInfo.name)}`)
+    if (userInfo.email) lines.push(`git config --global user.email ${JSON.stringify(userInfo.email)}`)
+  }
+
+  if (userSshPrivateKey) {
+    lines.push(
+      'echo "Configuring user SSH key..."',
+      `mkdir -p ${homeDir}/.ssh`,
+      `printf '%b' ${JSON.stringify(userSshPrivateKey)} > ${homeDir}/.ssh/mp_user_key`,
+      `chmod 600 ${homeDir}/.ssh/mp_user_key`,
+      `grep -qF "mp_user_key" ${homeDir}/.ssh/config 2>/dev/null || printf 'Host *\\n  IdentityFile ${homeDir}/.ssh/mp_user_key\\n  StrictHostKeyChecking no\\n  IdentitiesOnly yes\\n' >> ${homeDir}/.ssh/config`,
+      `chmod 600 ${homeDir}/.ssh/config`,
+      'echo "User SSH key configured"',
+    )
+  }
+
+  // Per-project deploy key (RFC 0013) — used only for generic "git" repos, referenced per-clone
+  // via GIT_SSH_COMMAND (not added to ~/.ssh/config, so it never shadows the user's own key).
+  if (projectDeployKey) {
+    lines.push(
+      'echo "Configuring project deploy key..."',
+      `mkdir -p ${homeDir}/.ssh`,
+      `printf '%b' ${JSON.stringify(projectDeployKey)} > ${homeDir}/.ssh/mp_deploy_key`,
+      `chmod 600 ${homeDir}/.ssh/mp_deploy_key`,
+      'echo "Project deploy key configured"',
+    )
+  }
+
+  // See the block comment: root-written credentials are worthless to the user they're for.
+  if (userSshPrivateKey || projectDeployKey) {
+    lines.push(
+      `chmod 700 ${homeDir}/.ssh`,
+      `chown -R ${username}:${username} ${homeDir}/.ssh`,
+    )
+  }
+
+  return lines
+}
+
+type RS = { name: string; state: "pending" | "cloning" | "done" | "error" }
+type LS = "pending" | "running" | "done" | "error" | null
+
+function mkStatus(
+  phase: SetupStatus["phase"],
+  repos: RS[],
+  postCreate: LS,
+  postStart: LS,
+): string {
+  return JSON.stringify({ phase, repos, postCreate, postStart } satisfies SetupStatus)
+}
+
+function banner(title: string): string[] {
+  return [
+    "",
+    `echo "###########################################################"`,
+    `echo "### ${title}"`,
+    `echo "###########################################################"`,
+  ]
+}
+
+function buildFeatureInstallScript(ociRef: string, options?: Record<string, string>): string {
+  const match = ociRef.match(/^([^/]+)\/(.+):(.+)$/)
+  if (!match) return `echo "[feature] Invalid OCI ref: ${ociRef}"`
+  const [, registry, repo, tag] = match
+  const featureId = repo.split("/").pop()
+
+  const lines = [
+    `echo "[feature] Installing ${featureId}..."`,
+    `_FEAT_DIR=$(mktemp -d)`,
+    `echo "[feature] ${featureId}: fetching OCI token..."`,
+    `_FEAT_TOKEN=$(curl -fsSL "https://${registry}/token?scope=repository:${repo}:pull" | grep -o '"token":"[^"]*"' | cut -d'"' -f4)`,
+    `echo "[feature] ${featureId}: fetching manifest..."`,
+    `_FEAT_MANIFEST=$(curl -fsSL -H "Authorization: Bearer $_FEAT_TOKEN" -H "Accept: application/vnd.oci.image.manifest.v1+json" "https://${registry}/v2/${repo}/manifests/${tag}")`,
+    `_FEAT_DIGEST=$(echo "$_FEAT_MANIFEST" | grep -o '"digest":"sha256:[^"]*"' | tail -1 | cut -d'"' -f4)`,
+    `echo "[feature] ${featureId}: downloading layer $_FEAT_DIGEST..."`,
+    `curl -fsSL -H "Authorization: Bearer $_FEAT_TOKEN" "https://${registry}/v2/${repo}/blobs/$_FEAT_DIGEST" -o "$_FEAT_DIR/feature.tar"`,
+    `echo "[feature] ${featureId}: extracting $(wc -c < "$_FEAT_DIR/feature.tar") bytes..."`,
+    `(tar xzf "$_FEAT_DIR/feature.tar" -C "$_FEAT_DIR" 2>/dev/null || tar xf "$_FEAT_DIR/feature.tar" -C "$_FEAT_DIR")`,
+    `rm -f "$_FEAT_DIR/feature.tar"`,
+    `echo "[feature] ${featureId}: files extracted: $(ls "$_FEAT_DIR" | tr '\\n' ' ')"`,
+    `cd "$_FEAT_DIR"`,
+  ]
+
+  if (options) {
+    for (const [k, v] of Object.entries(options)) {
+      lines.push(`export ${k.toUpperCase()}=${JSON.stringify(v)}`)
+    }
+  }
+
+  lines.push(
+    `echo "[feature] ${featureId}: running install.sh..."`,
+    `chmod +x install.sh`,
+    `set +e`,
+    `./install.sh`,
+    `_FEAT_EXIT=$?`,
+    `set -e`,
+    `if [ -f "$_FEAT_DIR/devcontainer-feature.json" ]; then`,
+    `  _EP=$(grep -o '"entrypoint"[[:space:]]*:[[:space:]]*"[^"]*"' "$_FEAT_DIR/devcontainer-feature.json" | head -1 | cut -d'"' -f4)`,
+    `  if [ -n "$_EP" ]; then`,
+    `    echo "$_EP" >> " + FEATURE_ENTRYPOINTS_STAGING_FILE + "`,
+    `    echo "[feature] ${featureId}: registered entrypoint $_EP"`,
+    `  fi`,
+    `fi`,
+    `cd /`,
+    `rm -rf "$_FEAT_DIR"`,
+    `if [ $_FEAT_EXIT -ne 0 ]; then`,
+    `  echo "[feature] ${featureId} ✗ FAILED (exit $_FEAT_EXIT)"`,
+    `  exit $_FEAT_EXIT`,
+    `fi`,
+    `echo "[feature] ${featureId} ✓ installed"`,
+  )
+
+  return lines.join("\n")
+}
+
+function buildLocalFeatureInstallScript(featureId: string, scriptFile: string): string | null {
+  const scriptContent = localFeatureScript(scriptFile)
+  if (!scriptContent) return null
+  const encoded = b64(scriptContent)
+  return [
+    `echo "[feature] ${featureId}: running local install script..."`,
+    `echo "${encoded}" | base64 -d > /tmp/_mp_feature.sh`,
+    `chmod +x /tmp/_mp_feature.sh`,
+    `set +e`,
+    `/tmp/_mp_feature.sh`,
+    `_LOCAL_EXIT=$?`,
+    `set -e`,
+    `rm -f /tmp/_mp_feature.sh`,
+    `if [ $_LOCAL_EXIT -ne 0 ]; then`,
+    `  echo "[feature] ${featureId} ✗ FAILED (exit $_LOCAL_EXIT)"`,
+    `  exit $_LOCAL_EXIT`,
+    `fi`,
+    `echo "[feature] ${featureId} ✓ installed"`,
+  ].join("\n")
+}
+
+export type ResolvedFeature = { id: string; script: string; ociRef?: string }
+
+function resolveFeatures(
+  features: { id: string; ociRef?: string; options?: Record<string, string> }[],
+  warnId?: string,
+): ResolvedFeature[] {
+  const resolved: ResolvedFeature[] = []
+  for (const f of features) {
+    const known = AVAILABLE_FEATURES.find((af) => af.id === f.id)
+    if (known?.localScript) {
+      const script = buildLocalFeatureInstallScript(f.id, known.localScript)
+      if (script) {
+        resolved.push({ id: f.id, script })
+        continue
+      }
+      // A catalog entry naming a script this build doesn't ship: fall through to the OCI ref if the
+      // feature has one, rather than silently installing nothing.
+      if (warnId) console.warn(`[worker:${warnId}] Feature "${f.id}" names a local script we don't ship`)
+    }
+    const ociRef = f.ociRef ?? known?.ociRef
+    if (!ociRef) {
+      if (warnId) console.warn(`[worker:${warnId}] Unknown feature "${f.id}" (no ociRef or localScript), skipping`)
+      continue
+    }
+    const options = { ...known?.defaultOptions, ...f.options }
+    resolved.push({
+      id: f.id,
+      ociRef,
+      script: buildFeatureInstallScript(ociRef, Object.keys(options).length > 0 ? options : undefined),
+    })
+  }
+  return resolved
+}
+
+// ─── The two features every worker image is made of ───────────────────────────
+//
+// What a worker needs on top of its base image — a non-root user with sudo, an in-browser VS Code,
+// a terminal that survives a disconnect — used to be four hand-written blocks of this file, and the
+// same four blocks, forked and already drifting, in spunto-lite. Both sides speak the devcontainer
+// feature spec already (`buildFeatureInstallScript` below), so that spec is the seam: the shared
+// half is published as features and consumed identically, and nothing private has to be released to
+// share it.
+//
+//   common-utils (upstream)  →  spunto-pack (ours)  →  the project's own features
+//
+// `spunto-pack` is one feature rather than four (code-server / tmux / dtach / sshd) because the
+// fetcher below reads nothing but `entrypoint` out of a devcontainer-feature.json: `installsAfter`
+// and `dependsOn` are ignored, so features run in the order of the array and nothing resolves an
+// ordering for us. Inside a single install.sh the order is guaranteed by construction — and it
+// costs one OCI round-trip instead of four.
+const COMMON_UTILS_REF = "ghcr.io/devcontainers/features/common-utils:2"
+const SPUNTO_PACK_REF = "ghcr.io/coderhammer/features/spunto-pack:1"
+
+/**
+ * common-utils replaces the old "System & user" block: it creates `vscode`, drops a
+ * `/etc/sudoers.d/vscode` at 0440 (rather than appending to /etc/sudoers), and lays down the base
+ * toolchain — on Debian, RedHat, Alpine and azurelinux alike.
+ *
+ * None of these four options can be left at its default:
+ * - `username` pinned instead of `automatic`, whose candidate list starts with users the base image
+ *   may already have (`node` on a node:* base) — we'd configure sudo for the wrong user.
+ * - `upgradePackages` off: on by default, it runs a full distro upgrade in every image build.
+ * - `configureZshAsDefaultShell` on: the block it replaces made zsh the login shell, and every
+ *   worker terminal opens on it.
+ * - `installOhMyZsh` off, deliberately: oh-my-zsh lives in a *home directory*, which is per-worker
+ *   and per-user, and the setup script already installs it there (theme, plugins, aliases) at a
+ *   point where it knows whether the user has dotfiles of their own. Baking a `.zshrc` into the
+ *   image would put a file in the way of a dotfiles install script that expects to own it.
+ */
+function commonUtilsOptions(): Record<string, string> {
+  return {
+    username: "vscode",
+    upgradePackages: "false",
+    installZsh: "true",
+    configureZshAsDefaultShell: "true",
+    installOhMyZsh: "false",
+    installOhMyZshConfig: "false",
+  }
+}
+
+/**
+ * spunto-pack replaces the code-server / tmux / dtach / SSH-server blocks. Its defaults are already
+ * what a worker wants (code-server + both terminal backends + the system-wide tmux.conf), so only
+ * the SSH server is decided here: the package is worth its size only when a gateway key exists to
+ * actually reach it. The pack installs the package and stops there — host keys, sshd_config and who
+ * starts the daemon stay ours (docs/architecture-deep-dive.md § SSH gateway).
+ *
+ * Not strict: a base image where tmux won't install must still produce a usable worker, exactly as
+ * the best-effort blocks it replaces did.
+ */
+function spuntoPackOptions(params: { sshGatewayPublicKey?: string }): Record<string, string> {
+  return { installSshd: params.sshGatewayPublicKey ? "true" : "false" }
+}
+
+// The system-wide tmux configuration (mouse, OSC 52 clipboard, 50k scrollback, warm status bar)
+// now lives in spunto-pack's install.sh, where it is written to /etc/tmux.conf — same file, same
+// content, plus the version guard this copy never had: `set -as terminal-features` only exists from
+// tmux 3.2, and on an older base (Debian bullseye ships 3.1c) every client attaching to a worker
+// terminal got an "invalid option" banner to dismiss. The frontend's half of the clipboard story is
+// unchanged — see apps/next/lib/terminal-clipboard.ts.
+
+// ─── code-server user settings ───────────────────────────────────────────────
+//
+// Seeded into every worker at start (see buildStartScript §4b), no-clobber so they
+// stay user-overridable. Two of these make parallel worker tabs tellable apart:
+//   - window.title leads with the Spunto project name (injected as a literal — VS Code's
+//     `${rootName}` only knows the opened folder), so the project survives a narrow tab;
+//     the file name (`${activeEditorShort}`) trails.
+//   - workbench.colorCustomizations tints the window chrome (title/activity/status
+//     bars) with a per-project hue, Peacock-style, so the window itself is distinct.
+// NOTE: code-server's web server only forwards a hardcoded product.json whitelist to
+// the browser — "configurationDefaults" is NOT in that list, so patching product.json
+// is silently ignored client-side. These have to be seeded as real user settings.
+
+/** Deterministic 32-bit hash (djb2 xor) — a given project name always maps to the same hue. */
+function hashString(s: string): number {
+  let h = 5381
+  for (let i = 0; i < s.length; i++) h = ((h * 33) ^ s.charCodeAt(i)) >>> 0
+  return h
+}
+
+/** HSL (h∈[0,360), s,l∈[0,1]) → #rrggbb. */
+function hslToHex(h: number, s: number, l: number): string {
+  const c = (1 - Math.abs(2 * l - 1)) * s
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = l - c / 2
+  const [r, g, b] =
+    h < 60 ? [c, x, 0]
+    : h < 120 ? [x, c, 0]
+    : h < 180 ? [0, c, x]
+    : h < 240 ? [0, x, c]
+    : h < 300 ? [x, 0, c]
+    : [c, 0, x]
+  const to = (v: number) => Math.round((v + m) * 255).toString(16).padStart(2, "0")
+  return `#${to(r)}${to(g)}${to(b)}`
+}
+
+/** Per-project window chrome colors, derived from the project name so every worker of a
+ *  given project shares one recognizable hue on its title/activity/status bars. Backgrounds
+ *  are dark enough that white foregrounds stay readable across the whole hue circle. */
+function deriveProjectChromeColors(projectName: string): Record<string, string> {
+  const hue = hashString(projectName) % 360
+  const bg = hslToHex(hue, 0.6, 0.3)
+  const bgInactive = hslToHex(hue, 0.4, 0.24)
+  const fg = "#ffffff"
+  const fgMuted = "#ffffff99"
+  return {
+    "titleBar.activeBackground": bg,
+    "titleBar.activeForeground": fg,
+    "titleBar.inactiveBackground": bgInactive,
+    "titleBar.inactiveForeground": fgMuted,
+    "activityBar.background": bg,
+    "activityBar.foreground": fg,
+    "activityBar.inactiveForeground": fgMuted,
+    "statusBar.background": bg,
+    "statusBar.foreground": fg,
+    "statusBar.noFolderBackground": bg,
+    "statusBar.debuggingBackground": bg,
+  }
+}
+
+/** Default code-server user settings seeded into every worker. Kills dead Copilot UI, the
+ *  workspace-trust prompt and the secondary sidebar; makes the tab identifiable via window.title;
+ *  and, when `colorByProject` is on (org opt-in), tints the window chrome per project. See the
+ *  block comment above. */
+export function defaultVscodeUserSettings(opts?: {
+  projectName?: string
+  colorByProject?: boolean
+}): Record<string, unknown> {
+  const { projectName, colorByProject } = opts ?? {}
+  const settings: Record<string, unknown> = {
+    "chat.disableAIFeatures": true,
+    // Workers are ephemeral/single-purpose — the trust prompt only adds friction.
+    "security.workspace.trust.enabled": false,
+    // Ephemeral workers never have a persisted layout, so this always applies.
+    "workbench.secondarySideBar.defaultVisibility": "hidden",
+    // Spunto project name first so the project stays identifiable even in a narrow browser
+    // tab — VS Code's ${rootName} only knows the opened *folder* (e.g. "spunto"), not the
+    // Spunto project. Injected as a literal here (we have the name); the file (${activeEditorShort})
+    // trails. Falls back to ${rootName} when no project name is available.
+    "window.title": projectName
+      ? `${projectName}\${separator}\${activeEditorShort}`
+      : "${rootName}${separator}${activeEditorShort}",
+  }
+  // Per-project window color is opt-in at the org level (workerTabColors).
+  if (projectName && colorByProject) {
+    settings["workbench.colorCustomizations"] = deriveProjectChromeColors(projectName)
+  }
+  return settings
+}
+
+// ─── 1. buildImageScript ──────────────────────────────────────────────────────
+//
+// Runs once during prebuild (docker build / mp-build container).
+// Bakes in: curl, the two base features (common-utils → vscode user; spunto-pack → code-server,
+//           tmux, dtach, SSH server), the project's own devcontainer features, then its
+//           VS Code extensions (/opt/mp-extensions/).
+//
+// Prewarm images (RFC 0014) are no longer baked here: `docker build`'s `RUN` steps have no daemon
+// available, so RFC 0006 used to pull them into `docker load`-able tarballs via `crane`. That's now
+// done agent-side, after this script runs and the image exists — see
+// `apps/agent/src/docker.ts` (`bakeDindSeed`), which spins up a privileged container from the
+// freshly-built image (real dockerd available) and commits a pre-populated `/var/lib/docker` graph
+// back onto it. Docker's native volume pre-population then seeds each worker's DinD volume from
+// that graph at container creation — no `docker load` anywhere anymore.
+
+/**
+ * What the baked layer is made of, as a version.
+ *
+ * A project image (`mp-proj-…:vN`) is keyed by the project's *version*, which only moves when the
+ * project's own config does — so a change to this file alone leaves every already-built image in
+ * place, and new workers keep spawning on the old base. That is invisible until someone wonders why
+ * a fix shipped last week isn't in their container.
+ *
+ * So the recipe carries a version of its own, stamped on each build row and compared at spawn: a
+ * build made by an older recipe is stale, and the image is rebuilt exactly as if the project had
+ * been bumped. Bump this whenever a change here must reach existing projects.
+ *
+ * 1 → the hand-written blocks (vscode user, code-server, tmux, dtach, sshd).
+ * 2 → common-utils + spunto-pack.
+ */
+export const IMAGE_RECIPE_VERSION = 2
+
+export function buildImageScript(params: {
+  features: { id: string; ociRef?: string; options?: Record<string, string> }[]
+  vscodeExtensions?: string[]
+  sshGatewayPublicKey?: string
+  /** Project-level DinD opt-in (base image bakes Docker itself, no feature). See projects.dind. */
+  dind?: boolean
+  /**
+   * Org setting (organizations.extensionsGallery): raw code-server gallery blob the
+   * `--install-extension` calls below resolve ids against. Absent/unusable = Open VSX.
+   */
+  extensionsGallery?: string | null
+}): { script: string; hasDinD: boolean; resolvedFeatures: ResolvedFeature[]; steps: BuildStep[] } {
+  const lines: string[] = ["set -e"]
+
+  // Every block of the build declares itself, so the UI can show the whole plan upfront and light
+  // each block up as it runs (lib/build-steps.ts). The plan is emitted from the *same* call that
+  // emits the script, so the two can never list different blocks.
+  const steps: BuildStep[] = []
+  function block(
+    id: string,
+    label: string,
+    kind: BuildStepKind,
+    detail: string | undefined,
+    body: string[],
+  ): void {
+    steps.push({ id, label, kind, detail, state: "pending" })
+    lines.push("", stepStartLine(id), ...body, stepEndLine(id))
+  }
+
+  // Feature env vars (devcontainer spec — features use these to target the right user). They come
+  // *first*, before any feature runs: common-utils reads them to decide which user it creates and
+  // configures, so exporting them later (as this script used to) would have it fall back to its own
+  // `automatic` detection — which on a node base image picks the pre-existing `node` user, not ours.
+  // Outside any block: they have to stay set for everything that follows, and exporting them isn't
+  // a step.
+  lines.push(
+    "",
+    "export HOME=/root",
+    "export _REMOTE_USER=vscode",
+    "export _REMOTE_USER_HOME=/home/vscode",
+    "export _CONTAINER_USER=vscode",
+    "export _CONTAINER_USER_HOME=/home/vscode",
+  )
+
+  // curl stays inline, and can't become a feature: `buildFeatureInstallScript` *is* a curl script
+  // (OCI token, manifest, blob), so a base image without curl can't fetch the very feature that
+  // would install it. Chicken and egg. images/worker-base bakes curl in, but a project is free to
+  // point at any base image.
+  block("bootstrap", "Bootstrap", "runtime", "curl — what fetches every feature below", [
+    "if ! command -v curl >/dev/null 2>&1; then",
+    '  echo "[build] Installing curl (the feature fetcher\'s own dependency)..."',
+    "  (",
+    "    set +e",
+    "    if command -v apt-get >/dev/null 2>&1; then",
+    "      DEBIAN_FRONTEND=noninteractive apt-get update -qq 2>&1 && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends curl ca-certificates 2>&1",
+    "    elif command -v apk >/dev/null 2>&1; then",
+    "      apk add --no-cache curl ca-certificates 2>&1",
+    "    elif command -v dnf >/dev/null 2>&1; then",
+    "      dnf install -y curl ca-certificates 2>&1",
+    "    elif command -v yum >/dev/null 2>&1; then",
+    "      yum install -y curl ca-certificates 2>&1",
+    "    fi",
+    "    set -e",
+    "  )",
+    "fi",
+    'command -v curl >/dev/null 2>&1 || echo "[build] WARNING: curl unavailable — feature installs will fail"',
+  ])
+
+  const hasDinD = params.features.some((f) => f.id === "docker-in-docker") || !!params.dind
+  // The two features every worker image is made of, ahead of whatever the project picked. The user
+  // can select common-utils in the picker too — its options are then merged over ours rather than
+  // installed a second time.
+  const userCommonUtils = params.features.find((f) => f.id === "common-utils")
+  const baseFeatures = [
+    {
+      id: "common-utils",
+      ociRef: userCommonUtils?.ociRef ?? COMMON_UTILS_REF,
+      options: { ...commonUtilsOptions(), ...userCommonUtils?.options },
+    },
+    { id: "spunto-pack", ociRef: SPUNTO_PACK_REF, options: spuntoPackOptions(params) },
+  ]
+  const resolvedFeatures = resolveFeatures([
+    ...baseFeatures,
+    ...params.features.filter((f) => f.id !== "common-utils"),
+  ])
+
+  // Install features — one block each, so a feature that takes four minutes is visibly *the* thing
+  // the build is doing rather than an anonymous stretch of log.
+  for (const { id, script, ociRef } of resolvedFeatures) {
+    block(`feature:${id}`, id, "feature", ociRef, [`echo "[build] Installing feature: ${id}..."`, script])
+  }
+
+  // Save entrypoints to a durable location. Append (not overwrite) + dedup so an entrypoint
+  // already baked into the base image (e.g. a dockerd starter for projects.dind, see
+  // images/worker-base) survives alongside any registered by features installed here.
+  const finalizeBody = [
+    "if [ -f " + FEATURE_ENTRYPOINTS_STAGING_FILE + " ]; then",
+    "  touch " + FEATURE_ENTRYPOINTS_FILE,
+    "  cat " + FEATURE_ENTRYPOINTS_STAGING_FILE + " >> " + FEATURE_ENTRYPOINTS_FILE,
+    "  sort -u " + FEATURE_ENTRYPOINTS_FILE + " -o " + FEATURE_ENTRYPOINTS_FILE,
+    "  rm -f " + FEATURE_ENTRYPOINTS_STAGING_FILE,
+    '  echo "[build] Entrypoints saved to ' + FEATURE_ENTRYPOINTS_FILE + '"',
+    "fi",
+  ]
+
+  // Install VS Code extensions to a system path (not in /home, which is per-worker)
+  if (params.vscodeExtensions && params.vscodeExtensions.length > 0) {
+    const extLines = [
+      'echo "[build] Installing VS Code extensions to ' + EXTENSIONS_DIR + '..."',
+      "mkdir -p " + EXTENSIONS_DIR,
+      // Must precede the first install: this is what makes `--install-extension` resolve ids
+      // against the org's gallery instead of Open VSX.
+      ...galleryExport(params.extensionsGallery),
+    ]
+    const registry = registryLabel(params.extensionsGallery)
+    for (const ext of params.vscodeExtensions) {
+      extLines.push(
+        `echo "[build] Installing extension: ${ext}..."`,
+        `set +e`,
+        `code-server --extensions-dir ${EXTENSIONS_DIR} --install-extension ${JSON.stringify(ext)} 2>&1`,
+        `_EXT_EXIT=$?`,
+        `set -e`,
+        `if [ $_EXT_EXIT -ne 0 ]; then echo "[build] Extension ${ext} failed (exit $_EXT_EXIT) — ids are resolved against ${registry}; an id that isn't published there can't be installed. Continuing"; fi`,
+      )
+    }
+    extLines.push('echo "[build] Extensions installed"')
+    const n = params.vscodeExtensions.length
+    block("extensions", "VS Code extensions", "extensions", `${n} extension${n > 1 ? "s" : ""} · ${registry}`, extLines)
+  }
+
+  // Fix ownership (features may have created files in /home/vscode as root)
+  block("finalize", "Finalizing image", "finalize", "entrypoints, sudo, ownership", [
+    ...finalizeBody,
+    // common-utils writes /etc/sudoers.d/<user> only when it *creates* the user: a base image
+    // that already ships `vscode` is assumed to have configured sudo for it, which the
+    // devcontainer bases do and an arbitrary base may not. The block this replaced appended the
+    // rule unconditionally, and setup runs as `vscode` (dotfiles, postCreate) — so the guarantee
+    // is kept, in the file-per-user form rather than by editing /etc/sudoers.
+    // The check has to be the real thing: `sudo -l -U vscode` exits 0 even for a user with no
+    // rights at all (it prints the default env settings), so it answers a different question.
+    "if ! su vscode -c 'sudo -n true' >/dev/null 2>&1; then",
+    "  echo 'vscode ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/vscode",
+    "  chmod 0440 /etc/sudoers.d/vscode",
+    '  echo "[build] sudo NOPASSWD configured for vscode"',
+    "fi",
+    "chown -R vscode:vscode /home/vscode 2>/dev/null || true",
+    'echo "[build] Image build complete"',
+  ])
+
+  return { script: lines.join("\n"), hasDinD, resolvedFeatures, steps }
+}
+
+// ─── 2. buildSetupScript ──────────────────────────────────────────────────────
+//
+// Runs once on the first container start (marker: /home/vscode/.mp-setup-done).
+// Handles: ownership, credentials, shell customization, dotfiles, repo cloning,
+//          postCreateCommand, gcloud wrapper.
+// Does NOT run on subsequent starts — those only run buildStartScript.
+
+export type SetupScriptParams = {
+  project: {
+    repositories: { id: string; provider: string; project: string; workspacePath: string; installationId?: number; cloneUrl?: string; branch?: string }[]
+    features: { id: string; ociRef?: string; options?: Record<string, string> }[] | null
+    vscodeExtensions?: string[] | null
+    dind?: boolean | null
+    postCreateCommand: string | null
+    postStartCommand?: string | null
+  }
+  workerId: string
+  userInfo?: { name: string; email?: string | null }
+  userSshPrivateKey?: string
+  sshGatewayPublicKey?: string
+  skipFeatures?: boolean
+  dotfilesRepo?: string | null
+  userEnvSecrets?: Record<string, string>
+  // Short-lived org GitHub App installation tokens (RFC 0012), one per connected GitHub
+  // account keyed by lowercased owner login. When a repo's owner has a token, it's cloned via
+  // HTTPS x-access-token (org-scoped read access) and the remote is then rewritten to SSH so
+  // push/pull keep the user's personal git identity.
+  githubInstallationTokens?: Record<string, string>
+  // Decrypted per-project SSH deploy key (RFC 0013). Used to clone generic ("git") repos from a
+  // raw SSH URL. Written to ~/.ssh/mp_deploy_key and referenced per-clone via GIT_SSH_COMMAND.
+  projectDeployKey?: string
+  // Git branch chosen when this worker was created (workers.branch): checked out for every repo
+  // of the project, overriding each repository's own default branch. Null/absent → default branch.
+  branch?: string | null
+}
+
+export function buildSetupScript(params: SetupScriptParams): { script: string } {
+  const { project, workerId, userInfo, userSshPrivateKey, dotfilesRepo, userEnvSecrets, githubInstallationTokens, projectDeployKey, branch } = params
+  const homeDir = "/home/vscode"
+  const username = "vscode"
+
+  const repoNames = project.repositories.map((r) => r.project)
+  const hasPostCreate = !!project.postCreateCommand
+  const pc0: LS = hasPostCreate ? "pending" : null
+
+  const allReposPending: RS[] = repoNames.map((n) => ({ name: n, state: "pending" }))
+  const allReposDone: RS[] = repoNames.map((n) => ({ name: n, state: "done" }))
+
+  function reposAtClone(i: number, cur: "cloning" | "done"): RS[] {
+    return repoNames.map((n, j) => ({ name: n, state: j < i ? "done" : j === i ? cur : "pending" }))
+  }
+
+  const lines: string[] = []
+  const push = (...l: string[]) => lines.push(...l)
+  const mp = (json: string) => lines.push(`_mp ${JSON.stringify(json)}`)
+  // Stamp a phase-start timestamp (container-side) then write the status. `key` is a
+  // fixed identifier, never user input — safe to pass unquoted to _mp_stamp.
+  const mpAt = (json: string, key: string) => lines.push(`_mp_stamp ${key}`, `_mp ${JSON.stringify(json)}`)
+
+  // ── 1. Ownership ─────────────────────────────────────────────────────────
+  push(...banner("SETUP: OWNERSHIP"))
+  push(
+    `chown -R ${username}:${username} /workspace`,
+    `chown -R ${username}:${username} ${homeDir}`,
+  )
+
+  // ── 2. Credentials ────────────────────────────────────────────────────────
+  const hasCredentials = !!(userInfo || userSshPrivateKey || projectDeployKey)
+  if (hasCredentials) {
+    push(...banner("SETUP: CREDENTIALS"))
+    mpAt(mkStatus("credentials", allReposPending, pc0, null), "credentials")
+  }
+
+  push(...credentialsBlock({ homeDir, username, userInfo, userSshPrivateKey, projectDeployKey }))
+
+  // ── 3. Shell setup ────────────────────────────────────────────────────────
+  // Land in the workspace on a fresh interactive shell (code-server terminal +
+  // SSH login). If there is exactly one repo dir under /workspace, cd into it;
+  // otherwise cd into /workspace. Guarded by `$PWD == $HOME` so it only fires on
+  // a fresh login and never fights a user who has navigated elsewhere.
+  // `find` does its own globbing, so this stays safe under zsh's default
+  // `nomatch` (a bare `/workspace/*/` would error when the dir is empty).
+  const landInWorkspace = [
+    ``,
+    `# ── Spunto: land in workspace on fresh login ─────────────────────`,
+    `if [ "$PWD" = "$HOME" ] && [ -d /workspace ]; then`,
+    `  __mp_dirs=$(find /workspace -mindepth 1 -maxdepth 1 -type d -not -name '.*' 2>/dev/null)`,
+    `  __mp_n=$(printf '%s\\n' "$__mp_dirs" | grep -c .)`,
+    `  if [ "$__mp_n" = 1 ]; then cd "$__mp_dirs" 2>/dev/null; else cd /workspace 2>/dev/null; fi`,
+    `  unset __mp_dirs __mp_n`,
+    `fi`,
+  ].join("\n")
+
+  const bashrcSnippet = [
+    ``,
+    `# ── Spunto shell config ──────────────────────────────────────────`,
+    `__mp_ps1_git() {`,
+    `  local b`,
+    `  b=$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse --short HEAD 2>/dev/null) || return`,
+    `  printf ' \\e[0;33m(%s)\\e[0m' "$b"`,
+    `}`,
+    ``,
+    `PS1='\\n\\[\\e[0;2m\\]\\u@\\h\\[\\e[0m\\] \\[\\e[1;34m\\]\\w\\[\\e[0m\\]$(__mp_ps1_git)\\n\\[\\e[1;32m\\]❯\\[\\e[0m\\] '`,
+    ``,
+    `alias ll='ls -lah --color=auto'`,
+    `alias la='ls -A --color=auto'`,
+    `alias l='ls -CF --color=auto'`,
+    `alias gs='git status'`,
+    `alias gd='git diff'`,
+    `alias gl='git log --oneline --graph --decorate -20'`,
+    landInWorkspace,
+  ].join("\n")
+  const bashrcEncoded = b64(bashrcSnippet)
+
+  const zshrcAliasSnippet = [
+    ``,
+    `# ── Spunto config ────────────────────────────────────────────────`,
+    `setopt NO_BANG_HIST`,
+    `alias ll='ls -lah --color=auto'`,
+    `alias la='ls -A --color=auto'`,
+    `alias l='ls -CF --color=auto'`,
+    `alias gs='git status'`,
+    `alias gd='git diff'`,
+    `alias gl='git log --oneline --graph --decorate -20'`,
+    landInWorkspace,
+  ].join("\n")
+  const zshrcAliasEncoded = b64(zshrcAliasSnippet)
+
+  push(...banner("SETUP: SHELL"))
+  // Shell setup (oh-my-zsh install is network-bound and can dominate startup), so
+  // give it its own timing segment. Phase is unchanged — re-stated so the merged
+  // status keeps the phase the UI already shows while recording the shell start.
+  mpAt(mkStatus(hasCredentials ? "credentials" : "initializing", allReposPending, pc0, null), "shell")
+  push(
+    `echo ${JSON.stringify(bashrcEncoded)} | base64 -d >> ${homeDir}/.bashrc`,
+    `if command -v zsh >/dev/null 2>&1; then`,
+    `  if [ ! -d "${homeDir}/.oh-my-zsh" ]; then`,
+    `    echo "Installing oh-my-zsh..."`,
+    `    _OMZ_TMP=$(mktemp)`,
+    `    curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh -o "$_OMZ_TMP" 2>&1`,
+    `    chmod 644 "$_OMZ_TMP"`,
+    `    su ${username} -c "HOME=${homeDir} RUNZSH=no CHSH=no KEEP_ZSHRC=no bash $_OMZ_TMP" 2>&1 || true`,
+    `    rm -f "$_OMZ_TMP"`,
+    `  else`,
+    `    echo "oh-my-zsh already installed"`,
+    `  fi`,
+    `  sed -i 's/ZSH_THEME="robbyrussell"/ZSH_THEME="af-magic"/' ${homeDir}/.zshrc 2>/dev/null || true`,
+    `  sed -i 's/^plugins=(git)$/plugins=(git z)/' ${homeDir}/.zshrc 2>/dev/null || true`,
+    `  echo ${JSON.stringify(zshrcAliasEncoded)} | base64 -d >> ${homeDir}/.zshrc`,
+    `fi`,
+    // bash login shells (e.g. SSH when zsh is absent) read .profile, not .bashrc
+    `echo ${JSON.stringify(b64(landInWorkspace))} | base64 -d >> ${homeDir}/.profile`,
+  )
+
+  // ── 4. Dotfiles ───────────────────────────────────────────────────────────
+  if (dotfilesRepo) {
+    const dotfilesUrl = dotfilesRepo.startsWith("http") || dotfilesRepo.startsWith("git@")
+      ? dotfilesRepo
+      : `https://github.com/${dotfilesRepo}`
+    push(...banner("SETUP: DOTFILES"))
+    mpAt(mkStatus("dotfiles", allReposPending, pc0, null), "dotfiles")
+    push(
+      `echo "Cloning dotfiles from ${dotfilesUrl}..."`,
+      `set +e`,
+      `git clone ${JSON.stringify(dotfilesUrl)} ${homeDir}/dotfiles 2>&1`,
+      `_DOTS_EXIT=$?`,
+      `set -e`,
+      `if [ $_DOTS_EXIT -ne 0 ]; then`,
+      `  echo "Dotfiles clone failed (exit $_DOTS_EXIT) — continuing without dotfiles"`,
+      `else`,
+      `  echo "Dotfiles cloned"`,
+      // Cloned as root, but the install script below runs as the user (and so does whoever edits
+      // these files later) — hand the clone over before touching it.
+      `  chown -R ${username}:${username} ${homeDir}/dotfiles`,
+      `  _INSTALL_SCRIPT=""`,
+      `  for _candidate in install.sh bootstrap.sh setup.sh script/setup; do`,
+      `    if [ -f "${homeDir}/dotfiles/$_candidate" ]; then`,
+      `      _INSTALL_SCRIPT="$_candidate"`,
+      `      break`,
+      `    fi`,
+      `  done`,
+      `  if [ -n "$_INSTALL_SCRIPT" ]; then`,
+      `    echo "Running dotfiles install script: $_INSTALL_SCRIPT"`,
+      `    chmod +x "${homeDir}/dotfiles/$_INSTALL_SCRIPT"`,
+      `    set +e`,
+      `    su ${username} -c "cd ${homeDir}/dotfiles && ${envPrefix(userEnvSecrets)}./$_INSTALL_SCRIPT"`,
+      `    _DOTS_INST_EXIT=$?`,
+      `    set -e`,
+      `    if [ $_DOTS_INST_EXIT -ne 0 ]; then`,
+      `      echo "Dotfiles install script exited with $_DOTS_INST_EXIT — continuing"`,
+      `    else`,
+      `      echo "Dotfiles installed"`,
+      `    fi`,
+      `  else`,
+      `    echo "No install script found — symlinking dotfiles..."`,
+      `    for _f in "${homeDir}/dotfiles"/.*; do`,
+      `      _name=$(basename "$_f")`,
+      `      case "$_name" in .|..|.git|.gitignore|.gitmodules) continue ;; esac`,
+      `      ln -sf "$_f" "${homeDir}/$_name" && echo "  linked $_name"`,
+      `    done`,
+      `    echo "Dotfiles symlinked"`,
+      `  fi`,
+      `fi`,
+    )
+  }
+
+  // ── 5. Clone repos ────────────────────────────────────────────────────────
+  if (project.repositories.length > 0) {
+    push(...banner(`SETUP: CLONE REPOSITORIES (${project.repositories.length})`))
+  }
+  project.repositories.forEach((r, i) => {
+    const { header, lines: cloneLines } = cloneRepoBlock({
+      repo: r,
+      index: i,
+      total: project.repositories.length,
+      homeDir,
+      branch: resolveRepoBranch(r, branch),
+      githubInstallationTokens,
+      userSshPrivateKey,
+    })
+    push("")
+    push(header)
+    // Stamp the clone phase start once (first repo); _mp_stamp is first-write-wins.
+    mpAt(mkStatus("cloning", reposAtClone(i, "cloning"), pc0, null), "cloning")
+    push(...cloneLines)
+    mp(mkStatus("cloning", reposAtClone(i, "done"), pc0, null))
+  })
+
+  // ── 5b. Re-own /workspace after cloning ───────────────────────────────────
+  // Repos are cloned as root (the setup script runs as root), so the cloned
+  // directories end up root-owned. The initial chown (step 1) ran *before* the
+  // clone, so it didn't cover them. postCreateCommand runs as vscode, so without
+  // this the user can't write into the repo (e.g. `npm install` → EACCES on
+  // node_modules). Must run before postCreate, not just in the final step.
+  if (project.repositories.length > 0) {
+    push("", `chown -R ${username}:${username} /workspace`)
+  }
+
+  // ── 6. postCreateCommand ──────────────────────────────────────────────────
+  // Feature entrypoints (e.g. dockerd) are normally started in buildStartScript,
+  // but postCreateCommand runs before that. Start them here so commands like
+  // `docker run` work during postCreate. Also wait for the Docker socket if
+  // docker-in-docker is present.
+  // `project.dind` makes DinD available without the docker-in-docker feature (baked into the base
+  // image, see images/worker-base) — treat it like the feature for entrypoint start + docker wait.
+  const hasDinDFeature = (project.features?.some((f) => f.id === "docker-in-docker") ?? false) || !!project.dind
+  if (project.postCreateCommand && ((project.features && project.features.length > 0) || project.dind)) {
+    push(
+      "",
+      "if [ -f " + FEATURE_ENTRYPOINTS_FILE + " ]; then",
+      '  echo "--- Starting feature entrypoints for postCreate ---"',
+      "  while IFS= read -r _ep; do",
+      '    if [ -f "$_ep" ]; then',
+      '      echo "Starting entrypoint: $_ep"',
+      '      "$_ep" &',
+      "    fi",
+      "  done < " + FEATURE_ENTRYPOINTS_FILE,
+      "fi",
+    )
+    if (hasDinDFeature) {
+      push(
+        'echo "Waiting for Docker daemon..."',
+        "for _i in $(seq 1 30); do",
+        "  docker info >/dev/null 2>&1 && break",
+        "  sleep 1",
+        "done",
+        'docker info >/dev/null 2>&1 && echo "Docker daemon ready" || echo "Docker daemon not ready after 30s, continuing anyway"',
+      )
+    }
+  }
+
+  if (project.postCreateCommand) {
+    const postCreateDir = project.repositories.length === 1
+      ? `/workspace/${project.repositories[0].workspacePath}`
+      : "/workspace"
+    push(...banner("SETUP: POST CREATE"))
+    mpAt(mkStatus("lifecycle", allReposDone, "running", null), "postCreate")
+    const cmdEncoded = b64(project.postCreateCommand)
+    push(
+      `if [ ! -f "${homeDir}/.mp-post-create-done" ]; then`,
+      `  echo "--- Running postCreateCommand ---"`,
+      `  echo ${JSON.stringify(cmdEncoded)} | base64 -d > /tmp/mp_postcreate.sh`,
+      `  chmod +x /tmp/mp_postcreate.sh`,
+      `  su ${username} -c "cd ${postCreateDir} && bash /tmp/mp_postcreate.sh" 2>&1`,
+      `  rm -f /tmp/mp_postcreate.sh`,
+      `  touch "${homeDir}/.mp-post-create-done"`,
+      `  echo "postCreateCommand done"`,
+      `fi`,
+    )
+    mp(mkStatus("lifecycle", allReposDone, "done", null))
+  }
+
+  // ── 8. Final ownership + marker ───────────────────────────────────────────
+  push(
+    "",
+    `chown -R ${username}:${username} ${homeDir}`,
+    `chown -R ${username}:${username} /workspace`,
+    `touch ${homeDir}/.mp-setup-done`,
+    'echo "[setup] First-start setup complete"',
+  )
+
+  return { script: lines.join("\n") }
+}
+
+// ─── 3. buildStartScript ──────────────────────────────────────────────────────
+//
+// Runs on every container start (first and subsequent).
+// Handles: SSH server, feature entrypoints, worker env, extension copy,
+//          code-server start (as vscode), postStartCommand.
+
+export type StartScriptParams = {
+  project: {
+    name?: string
+    features: { id: string; ociRef?: string; options?: Record<string, string> }[] | null
+    vscodeExtensions?: string[] | null
+    dind?: boolean | null
+    postCreateCommand: string | null
+    postStartCommand: string | null
+    repositories: { project: string; workspacePath: string }[]
+  }
+  sshGatewayPublicKey?: string
+  /** Org opt-in (organizations.workerTabColors): tint the worker window chrome per project. */
+  colorTabsByProject?: boolean
+  /**
+   * Org setting (organizations.extensionsGallery): raw code-server gallery blob, exported into the
+   * code-server loop so the editor's own Extensions view searches the same registry the picker and
+   * the image build used. Absent/unusable = Open VSX.
+   */
+  extensionsGallery?: string | null
+}
+
+export function buildStartScript(params: StartScriptParams): { script: string; hasDinD: boolean } {
+  const { project, sshGatewayPublicKey, colorTabsByProject, extensionsGallery } = params
+  const homeDir = "/home/vscode"
+  const username = "vscode"
+
+  const features = project.features ?? []
+  const hasPostCreate = !!project.postCreateCommand
+  const hasPostStart = !!project.postStartCommand
+  const hasDinD = features.some((f) => f.id === "docker-in-docker") || !!project.dind
+
+  const allReposDone: RS[] = project.repositories.map((r) => ({ name: r.project, state: "done" }))
+
+  const lines: string[] = []
+  const push = (...l: string[]) => lines.push(...l)
+  const mp = (json: string) => lines.push(`_mp ${JSON.stringify(json)}`)
+  const mpAt = (json: string, key: string) => lines.push(`_mp_stamp ${key}`, `_mp ${JSON.stringify(json)}`)
+
+  // ── Session separator (visible in logs on every start/restart) ────────────
+  push(
+    `printf '\\033[2m%s\\033[0m\\n' "$(printf '─%.0s' {1..42})"`,
+    `printf '\\033[2m  ↺  Session · %s\\033[0m\\n' "$(date +%H:%M:%S)"`,
+    `printf '\\033[2m%s\\033[0m\\n' "$(printf '─%.0s' {1..42})"`,
+  )
+
+  // ── Reset status on restart so postStart stays blocking ───────────────────
+  // .mp-status.json lives on the persistent home volume, so on a *restart* it
+  // still holds the previous run's "ready" status. Emit a non-ready status at
+  // the very top of every start (before code-server / postStart) so a watcher
+  // waiting on postStart doesn't observe that stale "ready" before this start's
+  // postStartCommand has even begun. Only relevant when there is a postStart to
+  // wait for; on first start setup has just emitted lifecycle/postCreate=done,
+  // so this is a harmless no-op-equivalent restatement.
+  if (hasPostStart) {
+    mp(mkStatus("lifecycle", allReposDone, hasPostCreate ? "done" : null, "pending"))
+  }
+
+  // ── 1. SSH server ─────────────────────────────────────────────────────────
+  if (sshGatewayPublicKey) {
+    push(...banner("START: SSH SERVER"))
+    push(
+      "(",
+      "  set +e",
+      "  mkdir -p /run/sshd /var/run/sshd",
+      // Authorize the gateway key for the `vscode` user so SSH lands as the same
+      // user as code-server (not root), with their env, git creds and shell.
+      `  mkdir -p ${homeDir}/.ssh`,
+      `  chmod 700 ${homeDir}/.ssh`,
+      `  _GW_KEY=${JSON.stringify(sshGatewayPublicKey)}`,
+      `  grep -qF "$_GW_KEY" ${homeDir}/.ssh/authorized_keys 2>/dev/null || printf '%s\\n' "$_GW_KEY" >> ${homeDir}/.ssh/authorized_keys`,
+      `  chmod 600 ${homeDir}/.ssh/authorized_keys`,
+      `  chown -R ${username}:${username} ${homeDir}/.ssh`,
+      "  printf '\\nPubkeyAuthentication yes\\nPasswordAuthentication no\\nChallengeResponseAuthentication no\\nUsePAM no\\n' >> /etc/ssh/sshd_config",
+      "  ssh-keygen -A 2>&1",
+      "  if command -v /usr/sbin/sshd >/dev/null 2>&1; then",
+      "    /usr/sbin/sshd 2>&1 &",
+      "  elif command -v /usr/bin/sshd >/dev/null 2>&1; then",
+      "    /usr/bin/sshd 2>&1 &",
+      "  else",
+      '    echo "SSH server: sshd binary not found"',
+      "  fi",
+      '  echo "SSH server started"',
+      "  set -e",
+      ")",
+    )
+  }
+
+  // ── 2. Feature entrypoints ────────────────────────────────────────────────
+  push(
+    "",
+    "if [ -f " + FEATURE_ENTRYPOINTS_FILE + " ]; then",
+    '  echo "--- Starting feature entrypoints ---"',
+    "  while IFS= read -r _ep; do",
+    '    if [ -f "$_ep" ]; then',
+    '      echo "Starting entrypoint: $_ep"',
+    '      "$_ep" &',
+    "    fi",
+    "  done < " + FEATURE_ENTRYPOINTS_FILE,
+    "fi",
+  )
+
+  // ── 3. Persist env vars for VS Code terminal login shells ─────────────────
+  push(
+    "",
+    "# Persist worker env for login shells (VS Code integrated terminals read /etc/environment)",
+    "for _var in WORKER_SLUG BASE_DOMAIN PUBLIC_PROTOCOL GITHUB_TOKEN GITHUB_USER GOOGLE_APPLICATION_CREDENTIALS; do",
+    '  _val=$(printenv "$_var" 2>/dev/null || true)',
+    '  [ -n "$_val" ] && echo "${_var}=${_val}" >> /etc/environment || true',
+    "done",
+  )
+
+  // ── 4. Copy prebuilt extensions ───────────────────────────────────────────
+  push(
+    "",
+    'if [ -d ' + EXTENSIONS_DIR + ' ] && [ "$(ls -A ' + EXTENSIONS_DIR + ' 2>/dev/null)" ]; then',
+    `  mkdir -p ${homeDir}/.local/share/code-server/extensions`,
+    `  cp -rn ${EXTENSIONS_DIR}/. ${homeDir}/.local/share/code-server/extensions/ 2>/dev/null || true`,
+    `  chown -R ${username}:${username} ${homeDir}/.local`,
+    "fi",
+  )
+
+  // ── 4b. Seed code-server user settings (no-clobber, stays user-overridable) ─
+  // Reordered window.title + per-project window color make parallel worker tabs
+  // tellable apart at a glance (see defaultVscodeUserSettings). Written no-clobber
+  // (guarded on the file, not `cp -n`) so a user's own settings.json survives restarts.
+  const vscodeSettings = JSON.stringify(
+    defaultVscodeUserSettings({ projectName: project.name, colorByProject: colorTabsByProject }),
+    null,
+    2,
+  )
+  push(
+    "",
+    `mkdir -p ${homeDir}/.local/share/code-server/User`,
+    `if [ ! -f ${homeDir}/.local/share/code-server/User/settings.json ]; then`,
+    `  echo ${JSON.stringify(b64(vscodeSettings))} | base64 -d > ${homeDir}/.local/share/code-server/User/settings.json`,
+    `  chown -R ${username}:${username} ${homeDir}/.local`,
+    "fi",
+  )
+
+  // ── 4c. Restore the user's PORT secret for code-server's own terminal panel ─
+  // code-server reads $PORT to override --bind-addr (see § 5 below), so its
+  // whole process tree — including the integrated terminal it spawns — inherits
+  // PORT=8080 unless corrected. `terminal.integrated.env.linux` lets VS Code
+  // inject env overrides into terminals it spawns without touching the server
+  // process itself, so a `PORT` project secret still reaches the user's shell.
+  // Uses code-server's own bundled node (guaranteed present regardless of the
+  // devcontainer base image) since jq/node aren't guaranteed there.
+  const seedTerminalPortEnv = [
+    "const fs = require('fs')",
+    "const path = process.env.MP_SETTINGS_PATH",
+    "let settings = {}",
+    "try { settings = JSON.parse(fs.readFileSync(path, 'utf8')) } catch {}",
+    "settings['terminal.integrated.env.linux'] = { ...settings['terminal.integrated.env.linux'], PORT: process.env.MP_ORIGINAL_PORT }",
+    "fs.writeFileSync(path, JSON.stringify(settings, null, 2))",
+  ].join("\n")
+  const seedTerminalPortEnvEncoded = b64(seedTerminalPortEnv)
+
+  push(
+    "",
+    'if [ -n "${PORT:-}" ]; then',
+    "  _mp_cs_bin=$(command -v code-server 2>/dev/null || true)",
+    '  if [ -n "$_mp_cs_bin" ]; then',
+    '    _mp_cs_bin=$(readlink -f "$_mp_cs_bin" 2>/dev/null || echo "$_mp_cs_bin")',
+    '    _mp_cs_node="$(dirname "$(dirname "$_mp_cs_bin")")/lib/node"',
+    '    if [ -x "$_mp_cs_node" ]; then',
+    `      mkdir -p ${homeDir}/.local/share/code-server/User`,
+    `      echo ${JSON.stringify(seedTerminalPortEnvEncoded)} | base64 -d > ${homeDir}/.mp_seed_terminal_port.js`,
+    `      MP_ORIGINAL_PORT="$PORT" MP_SETTINGS_PATH="${homeDir}/.local/share/code-server/User/settings.json" "$_mp_cs_node" ${homeDir}/.mp_seed_terminal_port.js`,
+    `      rm -f ${homeDir}/.mp_seed_terminal_port.js`,
+    `      chown -R ${username}:${username} ${homeDir}/.local`,
+    "    fi",
+    "  fi",
+    "fi",
+  )
+
+  // ── 5. Start code-server as vscode ────────────────────────────────────────
+  // Write the restart-loop to a temp script so quoting stays clean.
+  // Single-quoted heredoc: $VARS are NOT expanded here, they expand when the script runs
+  // (env is inherited from the start script via `su vscode` without -l).
+  // Write the restart-loop using base64 to avoid heredoc issues in DinD contexts
+  // where dockerd startup can affect /tmp mount visibility for child processes.
+  // Script lives in home dir (persistent volume) rather than /tmp.
+  const codeServerLoop = [
+    "#!/bin/bash",
+    "export SHELL=$(command -v zsh 2>/dev/null || echo /bin/bash)",
+    // Makes the editor's own Extensions view search the same registry the picker and the image
+    // build used (org setting — see lib/extension-registry.ts). Nothing when the org is on Open VSX.
+    ...galleryExport(extensionsGallery),
+    "while true; do",
+    '  VSCODE_PROXY_URI="${PUBLIC_PROTOCOL}://${WORKER_SLUG}-{{port}}.${BASE_DOMAIN}" \\',
+    // PORT is overridden here (not unset globally) so a project secret named
+    // PORT can't make code-server bind elsewhere. This also leaks PORT=8080
+    // into code-server's own process tree (its integrated terminal included) —
+    // § 4c above restores the original value for that terminal specifically.
+    // apps/agent/src/terminal.ts (dashboard's separate terminal feature) is a
+    // different process tree entirely and was never affected.
+    "    PORT=8080 code-server --bind-addr 0.0.0.0:8080 --auth none /workspace 2>&1",
+    '  echo "[start] code-server exited ($?), restarting in 3s..."',
+    "  sleep 3",
+    "done",
+  ].join("\n")
+  const codeServerEncoded = b64(codeServerLoop)
+
+  push(
+    ...banner("START: CODE-SERVER"),
+    `echo ${JSON.stringify(codeServerEncoded)} | base64 -d > ${homeDir}/.mp_codeserver.sh`,
+    `chmod +x ${homeDir}/.mp_codeserver.sh`,
+    `su ${username} -s /bin/bash -c "${homeDir}/.mp_codeserver.sh" &`,
+  )
+
+  // ── 6. postStartCommand ───────────────────────────────────────────────────
+  // Wait for Docker if feature entrypoints were started — regardless of whether
+  // the project explicitly lists docker-in-docker. Some images have Docker in
+  // the base image or via a differently-named feature. Strategy: give the socket
+  // up to 5s to appear; if it shows up, wait up to 30s for the daemon to be ready.
+  if (project.postStartCommand) {
+    push(
+      "",
+      "if [ -f " + FEATURE_ENTRYPOINTS_FILE + " ]; then",
+      "  for _i in 1 2 3 4 5; do [ -S /var/run/docker.sock ] && break || sleep 1; done",
+      "  if [ -S /var/run/docker.sock ]; then",
+      '    echo "Waiting for Docker daemon..."',
+      "    for _i in $(seq 1 30); do docker info >/dev/null 2>&1 && break; sleep 1; done",
+      '    docker info >/dev/null 2>&1 && echo "Docker daemon ready" || echo "Docker daemon not ready, continuing"',
+      "  fi",
+      "fi",
+    )
+  }
+
+  if (project.postStartCommand) {
+    const postStartDir = project.repositories.length === 1
+      ? `/workspace/${project.repositories[0].workspacePath}`
+      : "/workspace"
+    push(...banner("START: POST START"))
+    mpAt(mkStatus("lifecycle", allReposDone, hasPostCreate ? "done" : null, "running"), "postStart")
+    const cmdEncoded = b64(project.postStartCommand)
+    push(
+      `echo "--- Running postStartCommand ---"`,
+      `echo ${JSON.stringify(cmdEncoded)} | base64 -d > /tmp/mp_poststart.sh`,
+      `chmod +x /tmp/mp_poststart.sh`,
+      `su ${username} -c "cd ${postStartDir} && bash /tmp/mp_poststart.sh" 2>&1`,
+      `rm -f /tmp/mp_poststart.sh`,
+      `echo "postStartCommand done"`,
+    )
+    mp(mkStatus("lifecycle", allReposDone, hasPostCreate ? "done" : null, "done"))
+  }
+
+  // ── 7. Ready ─────────────────────────────────────────────────────────────
+  push(...banner("READY"))
+  mpAt(mkStatus("ready", allReposDone, hasPostCreate ? "done" : null, hasPostStart ? "done" : null), "ready")
+  // Setup + start succeeded — disarm the failure trap (see buildWorkerScript _mp_fail) so a later
+  // container stop or a code-server restart-loop blip never gets reported as a setup failure.
+  push("_MP_DONE=1")
+  push("", "wait")
+
+  return { script: lines.join("\n"), hasDinD }
+}
+
+// ─── buildWorkerScript ────────────────────────────────────────────────────────
+//
+// Assembles the full container CMD by combining setup + start.
+// Setup runs only on first start (marker file guards it).
+// Start runs on every start.
+
+// ─── RFC 0017: agent-orchestrated setup (behind WORKER_SETUP_ORCHESTRATOR=agent) ──
+//
+// The functions below power the *new* model where the agent (not the container) drives setup:
+// `buildContainerScript` is the passive CMD (serve code-server + stay alive, no setup, no status
+// machinery), and `buildSetupPlan` returns the ordered phases the agent execs one by one, each
+// wrapped in a native OTel span. The legacy `buildWorkerScript`/`buildSetupScript`/`buildStartScript`
+// above are left untouched — the runner picks the path by flag, defaulting to legacy. See RFC 0017.
+
+/** One setup phase the agent execs via `docker exec`, wrapped in a native OTel span. */
+export type SetupPhase = {
+  /** Timing-key / span-suffix (`setup.<id>`) and the phase's short identity. */
+  id: "credentials" | "shell" | "dotfiles" | "clone" | "postCreate" | "postStart"
+  /** Human label for logs. */
+  label: string
+  /** Self-contained bash (runs as root via `docker exec`; `su vscode` inside where needed). */
+  script: string
+  /** Re-run on every start (restart included). Only postStart; the rest is first-start-only. */
+  runsOnRestart: boolean
+  /** Full SetupStatus to persist when this phase starts / finishes (mirrors legacy `mkStatus`). */
+  statusStart: SetupStatus
+  statusEnd: SetupStatus
+}
+
+// The passive container CMD. Same "serve + stay alive" blocks as buildStartScript (SSH, feature
+// entrypoints, env persistence, extensions, code-server settings + restart loop) — MINUS the setup
+// status machinery, the lifecycle commands and any OTLP/timing emission (the agent owns all of that
+// now). Ends by signalling readiness (`.mp-container-up`) then `wait`. Blocks are duplicated from
+// buildStartScript on purpose: the legacy path stays byte-identical (prod default) until it's
+// deleted once WORKER_SETUP_ORCHESTRATOR=agent becomes the default. See RFC 0017 §2.1.
+export function buildContainerScript(params: StartScriptParams): { script: string; hasDinD: boolean } {
+  const { project, sshGatewayPublicKey, colorTabsByProject, extensionsGallery } = params
+  const homeDir = "/home/vscode"
+  const username = "vscode"
+
+  const features = project.features ?? []
+  const hasDinD = features.some((f) => f.id === "docker-in-docker") || !!project.dind
+
+  const lines: string[] = ["set -e", "export HOME=/home/vscode"]
+  const push = (...l: string[]) => lines.push(...l)
+
+  // ── Session separator (visible in logs on every start/restart) ────────────
+  push(
+    `printf '\\033[2m%s\\033[0m\\n' "$(printf '─%.0s' {1..42})"`,
+    `printf '\\033[2m  ↺  Session · %s\\033[0m\\n' "$(date +%H:%M:%S)"`,
+    `printf '\\033[2m%s\\033[0m\\n' "$(printf '─%.0s' {1..42})"`,
+  )
+
+  // ── 1. SSH server ─────────────────────────────────────────────────────────
+  if (sshGatewayPublicKey) {
+    push(...banner("START: SSH SERVER"))
+    push(
+      "(",
+      "  set +e",
+      "  mkdir -p /run/sshd /var/run/sshd",
+      `  mkdir -p ${homeDir}/.ssh`,
+      `  chmod 700 ${homeDir}/.ssh`,
+      `  _GW_KEY=${JSON.stringify(sshGatewayPublicKey)}`,
+      `  grep -qF "$_GW_KEY" ${homeDir}/.ssh/authorized_keys 2>/dev/null || printf '%s\\n' "$_GW_KEY" >> ${homeDir}/.ssh/authorized_keys`,
+      `  chmod 600 ${homeDir}/.ssh/authorized_keys`,
+      `  chown -R ${username}:${username} ${homeDir}/.ssh`,
+      "  printf '\\nPubkeyAuthentication yes\\nPasswordAuthentication no\\nChallengeResponseAuthentication no\\nUsePAM no\\n' >> /etc/ssh/sshd_config",
+      "  ssh-keygen -A 2>&1",
+      "  if command -v /usr/sbin/sshd >/dev/null 2>&1; then",
+      "    /usr/sbin/sshd 2>&1 &",
+      "  elif command -v /usr/bin/sshd >/dev/null 2>&1; then",
+      "    /usr/bin/sshd 2>&1 &",
+      "  else",
+      '    echo "SSH server: sshd binary not found"',
+      "  fi",
+      '  echo "SSH server started"',
+      "  set -e",
+      ")",
+    )
+  }
+
+  // ── 2. Feature entrypoints ────────────────────────────────────────────────
+  push(
+    "",
+    "if [ -f " + FEATURE_ENTRYPOINTS_FILE + " ]; then",
+    '  echo "--- Starting feature entrypoints ---"',
+    "  while IFS= read -r _ep; do",
+    '    if [ -f "$_ep" ]; then',
+    '      echo "Starting entrypoint: $_ep"',
+    '      "$_ep" &',
+    "    fi",
+    "  done < " + FEATURE_ENTRYPOINTS_FILE,
+    "fi",
+  )
+
+  // ── 3. Persist env vars for VS Code terminal login shells ─────────────────
+  push(
+    "",
+    "# Persist worker env for login shells (VS Code integrated terminals read /etc/environment)",
+    "for _var in WORKER_SLUG BASE_DOMAIN PUBLIC_PROTOCOL GITHUB_TOKEN GITHUB_USER GOOGLE_APPLICATION_CREDENTIALS; do",
+    '  _val=$(printenv "$_var" 2>/dev/null || true)',
+    '  [ -n "$_val" ] && echo "${_var}=${_val}" >> /etc/environment || true',
+    "done",
+  )
+
+  // ── 4. Copy prebuilt extensions ───────────────────────────────────────────
+  push(
+    "",
+    'if [ -d ' + EXTENSIONS_DIR + ' ] && [ "$(ls -A ' + EXTENSIONS_DIR + ' 2>/dev/null)" ]; then',
+    `  mkdir -p ${homeDir}/.local/share/code-server/extensions`,
+    `  cp -rn ${EXTENSIONS_DIR}/. ${homeDir}/.local/share/code-server/extensions/ 2>/dev/null || true`,
+    `  chown -R ${username}:${username} ${homeDir}/.local`,
+    "fi",
+  )
+
+  // ── 4b. Seed code-server user settings (no-clobber) ───────────────────────
+  const vscodeSettings = JSON.stringify(
+    defaultVscodeUserSettings({ projectName: project.name, colorByProject: colorTabsByProject }),
+    null,
+    2,
+  )
+  push(
+    "",
+    `mkdir -p ${homeDir}/.local/share/code-server/User`,
+    `if [ ! -f ${homeDir}/.local/share/code-server/User/settings.json ]; then`,
+    `  echo ${JSON.stringify(b64(vscodeSettings))} | base64 -d > ${homeDir}/.local/share/code-server/User/settings.json`,
+    `  chown -R ${username}:${username} ${homeDir}/.local`,
+    "fi",
+  )
+
+  // ── 4c. Restore the user's PORT secret for code-server's own terminal panel ─
+  const seedTerminalPortEnv = [
+    "const fs = require('fs')",
+    "const path = process.env.MP_SETTINGS_PATH",
+    "let settings = {}",
+    "try { settings = JSON.parse(fs.readFileSync(path, 'utf8')) } catch {}",
+    "settings['terminal.integrated.env.linux'] = { ...settings['terminal.integrated.env.linux'], PORT: process.env.MP_ORIGINAL_PORT }",
+    "fs.writeFileSync(path, JSON.stringify(settings, null, 2))",
+  ].join("\n")
+  const seedTerminalPortEnvEncoded = b64(seedTerminalPortEnv)
+  push(
+    "",
+    'if [ -n "${PORT:-}" ]; then',
+    "  _mp_cs_bin=$(command -v code-server 2>/dev/null || true)",
+    '  if [ -n "$_mp_cs_bin" ]; then',
+    '    _mp_cs_bin=$(readlink -f "$_mp_cs_bin" 2>/dev/null || echo "$_mp_cs_bin")',
+    '    _mp_cs_node="$(dirname "$(dirname "$_mp_cs_bin")")/lib/node"',
+    '    if [ -x "$_mp_cs_node" ]; then',
+    `      mkdir -p ${homeDir}/.local/share/code-server/User`,
+    `      echo ${JSON.stringify(seedTerminalPortEnvEncoded)} | base64 -d > ${homeDir}/.mp_seed_terminal_port.js`,
+    `      MP_ORIGINAL_PORT="$PORT" MP_SETTINGS_PATH="${homeDir}/.local/share/code-server/User/settings.json" "$_mp_cs_node" ${homeDir}/.mp_seed_terminal_port.js`,
+    `      rm -f ${homeDir}/.mp_seed_terminal_port.js`,
+    `      chown -R ${username}:${username} ${homeDir}/.local`,
+    "    fi",
+    "  fi",
+    "fi",
+  )
+
+  // ── 5. Start code-server as vscode ────────────────────────────────────────
+  const codeServerLoop = [
+    "#!/bin/bash",
+    "export SHELL=$(command -v zsh 2>/dev/null || echo /bin/bash)",
+    // Same org-level gallery export as the legacy loop above — the two blocks are duplicated on
+    // purpose (RFC 0017 §2.1), so this one has to be kept in step by hand.
+    ...galleryExport(extensionsGallery),
+    "while true; do",
+    '  VSCODE_PROXY_URI="${PUBLIC_PROTOCOL}://${WORKER_SLUG}-{{port}}.${BASE_DOMAIN}" \\',
+    "    PORT=8080 code-server --bind-addr 0.0.0.0:8080 --auth none /workspace 2>&1",
+    '  echo "[start] code-server exited ($?), restarting in 3s..."',
+    "  sleep 3",
+    "done",
+  ].join("\n")
+  const codeServerEncoded = b64(codeServerLoop)
+  push(
+    ...banner("START: CODE-SERVER"),
+    `echo ${JSON.stringify(codeServerEncoded)} | base64 -d > ${homeDir}/.mp_codeserver.sh`,
+    `chmod +x ${homeDir}/.mp_codeserver.sh`,
+    `su ${username} -s /bin/bash -c "${homeDir}/.mp_codeserver.sh" &`,
+  )
+
+  // ── 6. Signal "container infra up" then stay alive ────────────────────────
+  // The agent waits for this marker before running setup phases that touch Docker (postCreate),
+  // guaranteeing feature entrypoints (dockerd) and env are in place. See RFC 0017 §2.3.
+  push(
+    "",
+    `touch ${homeDir}/.mp-container-up`,
+    'echo "[container] ready — setup orchestrated by the agent"',
+    "",
+    "wait",
+  )
+
+  return { script: lines.join("\n"), hasDinD }
+}
+
+export function buildWorkerScript(params: {
+  setupScript: string
+  startScript: string
+  project: {
+    postCreateCommand: string | null
+    postStartCommand: string | null
+    repositories: { project: string }[]
+  }
+}): string {
+  const { setupScript, startScript, project } = params
+  const hasPostCreate = !!project.postCreateCommand
+  const hasPostStart = !!project.postStartCommand
+
+  const allReposPending: RS[] = project.repositories.map((r) => ({ name: r.project, state: "pending" }))
+
+  const initialStatus = mkStatus(
+    "initializing",
+    allReposPending,
+    hasPostCreate ? "pending" : null,
+    hasPostStart ? "pending" : null,
+  )
+
+  return [
+    "set -e",
+    "export HOME=/home/vscode",
+    "",
+    // ── Per-phase start timings (worker start-time visibility) ────────────────
+    // Each phase transition stamps a millisecond-epoch timestamp *container-side*
+    // (one clock, unbiased by the backend's 1.5s poll) into a persistent
+    // accumulator file, which `_mp` then merges into .mp-status.json under a
+    // `timings` key on every write. First-write-wins per key, so a restart — which
+    // re-runs only the start script, not setup — never overwrites the original
+    // spawn timings. See docs/worker-states.md § Setup timings.
+    "_MP_TFILE=/home/vscode/.mp-timings",
+    "_mp_now() {",
+    "  local n",
+    // Milliseconds epoch. `date +%s%N` = seconds + 9-digit nanoseconds on both GNU and
+    // uutils coreutils (the latter, shipped by some base images, ignores the `%3N`
+    // width and would emit raw nanoseconds — 19 digits that overflow JS safe integers);
+    // dividing by 1e6 in bash 64-bit arithmetic yields a safe 13-digit ms value. Falls
+    // back to seconds×1000 when `%N` is unsupported (busybox → non-numeric output).
+    "  n=$(date +%s%N 2>/dev/null || true)",
+    "  case \"$n\" in ''|*[!0-9]*) printf '%s' \"$(date +%s 2>/dev/null || echo 0)000\"; return ;; esac",
+    "  printf '%s' \"$(( n / 1000000 ))\"",
+    "}",
+    "_mp_stamp() {",
+    "  if grep -q \"\\\"$1\\\":\" \"$_MP_TFILE\" 2>/dev/null; then return 0; fi",
+    "  local now; now=\"$(_mp_now)\"",
+    "  if [ -s \"$_MP_TFILE\" ]; then printf ',' >> \"$_MP_TFILE\"; fi",
+    "  printf '\"%s\":%s' \"$1\" \"$now\" >> \"$_MP_TFILE\" || true",
+    // Native OTel: emit this phase transition as a real OTLP span through the node
+    // collector (|| true + suspends set -e inside the fn — telemetry never breaks setup).
+    "  _mp_span_on_stamp \"$1\" \"$now\" || true",
+    "}",
+    // mp-status.json lives in the home dir (persistent volume), not /tmp — when a
+    // DinD feature starts dockerd in the background, /tmp's mount visibility can
+    // change for sibling processes (same issue that affected the code-server
+    // restart script, see buildStartScript), silently dropping status writes.
+    "_mp() {",
+    "  local j=\"$1\" t=''",
+    "  if [ -s \"$_MP_TFILE\" ]; then t=\"$(cat \"$_MP_TFILE\" 2>/dev/null || true)\"; fi",
+    // Splice `,"timings":{…}` in before the status object's closing brace.
+    "  if [ -n \"$t\" ]; then j=\"${j%?},\\\"timings\\\":{$t}}\"; fi",
+    // Remember the last status written so the failure trap (_mp_fail) can re-emit it with
+    // phase=error, preserving repos/postCreate/postStart/timings the UI already shows.
+    "  _MP_LAST=\"$j\"",
+    "  printf '%s' \"$j\" > " + workerStatusPath("/home/vscode") + " || true",
+    "}",
+    "",
+    // ── Native OTel setup spans (emitted by this script, not backdated in the API) ──
+    // Each phase is emitted as a real OTLP span to the node agent's collector (the
+    // auto-injected OTEL_EXPORTER_OTLP_ENDPOINT); the agent forwards to /otlp where org.id
+    // /node.id are stamped server-side. MP_SETUP_TRACEPARENT (the job.worker.spawn span,
+    // injected by the runner) gives the traceId + parent span, so the whole `worker.setup`
+    // subtree nests under the spawn trace. No trace context (or no curl) → silently skipped.
+    "MP_TRACE_ID=''; MP_JOB_SPAN=''",
+    "if [ -n \"${MP_SETUP_TRACEPARENT:-}\" ]; then",
+    "  MP_TRACE_ID=$(printf '%s' \"$MP_SETUP_TRACEPARENT\" | cut -d- -f2)",
+    "  MP_JOB_SPAN=$(printf '%s' \"$MP_SETUP_TRACEPARENT\" | cut -d- -f3)",
+    "fi",
+    "MP_SETUP_SPAN=''; MP_SETUP_START=''; MP_PREV_PHASE=''; MP_PREV_TS=''",
+    // Failure-trap state. _MP_DONE flips to 1 once setup+start reach `ready` (see buildStartScript),
+    // disarming _mp_fail so a normal container stop / code-server hiccup after ready never looks like
+    // a setup failure. _MP_LAST holds the most recent status JSON (set by _mp) for the error re-emit.
+    "_MP_DONE=0; _MP_LAST=''",
+    "_mp_rand_id() { od -An -tx1 -N8 /dev/urandom 2>/dev/null | tr -d ' \\n'; }",
+    "_mp_phase_span_name() {",
+    "  case \"$1\" in",
+    "    initializing) echo 'setup.initialize' ;;",
+    "    credentials) echo 'setup.credentials' ;;",
+    "    shell) echo 'setup.shell' ;;",
+    "    cloning) echo 'setup.clone' ;;",
+    "    postCreate) echo 'setup.postCreate' ;;",
+    "    postStart) echo 'setup.postStart' ;;",
+    "    *) echo \"setup.$1\" ;;",
+    "  esac",
+    "}",
+    // Emit one OTLP/HTTP JSON span, backgrounded + short timeout so it never adds latency
+    // to (or blocks) the setup path. Args: name start_ms end_ms span_id parent_span_id phase.
+    "_mp_span_emit() {",
+    "  if [ -z \"$MP_TRACE_ID\" ] || [ -z \"${OTEL_EXPORTER_OTLP_ENDPOINT:-}\" ]; then return 0; fi",
+    "  if ! command -v curl >/dev/null 2>&1; then return 0; fi",
+    // Optional $7 = error message and $8 = exit code turn this into a native ERROR span
+    // (OTel status code 2 + a setup.exit_code attribute) — that's what makes a failed
+    // clone/postCreate/postStart show up red in the waterfall instead of as a hole.
+    "  local name=\"$1\" s_ns=$(( $2 * 1000000 )) e_ns=$(( $3 * 1000000 )) sid=\"$4\" pid=\"$5\" phase=\"$6\" errmsg=\"${7:-}\" ecode=\"${8:-}\" dur=$(( $3 - $2 )) attrs='' status=''",
+    "  if [ -n \"$phase\" ]; then attrs=\"{\\\"key\\\":\\\"setup.phase\\\",\\\"value\\\":{\\\"stringValue\\\":\\\"$phase\\\"}},{\\\"key\\\":\\\"setup.duration_ms\\\",\\\"value\\\":{\\\"intValue\\\":\\\"$dur\\\"}}\"; fi",
+    "  if [ -n \"$ecode\" ]; then [ -n \"$attrs\" ] && attrs=\"$attrs,\"; attrs=\"${attrs}{\\\"key\\\":\\\"setup.exit_code\\\",\\\"value\\\":{\\\"intValue\\\":\\\"$ecode\\\"}}\"; fi",
+    "  if [ -n \"$errmsg\" ]; then status=\",\\\"status\\\":{\\\"code\\\":2,\\\"message\\\":\\\"$errmsg\\\"}\"; fi",
+    "  local body=\"{\\\"resourceSpans\\\":[{\\\"resource\\\":{\\\"attributes\\\":[{\\\"key\\\":\\\"service.name\\\",\\\"value\\\":{\\\"stringValue\\\":\\\"spunto-worker\\\"}},{\\\"key\\\":\\\"spunto.worker.slug\\\",\\\"value\\\":{\\\"stringValue\\\":\\\"${WORKER_SLUG:-}\\\"}}]},\\\"scopeSpans\\\":[{\\\"scope\\\":{\\\"name\\\":\\\"spunto.setup\\\"},\\\"spans\\\":[{\\\"traceId\\\":\\\"$MP_TRACE_ID\\\",\\\"spanId\\\":\\\"$sid\\\",\\\"parentSpanId\\\":\\\"$pid\\\",\\\"name\\\":\\\"$name\\\",\\\"kind\\\":1,\\\"startTimeUnixNano\\\":\\\"$s_ns\\\",\\\"endTimeUnixNano\\\":\\\"$e_ns\\\",\\\"attributes\\\":[$attrs]$status}]}]}]}\"",
+    "  ( curl -s -m 3 -o /dev/null -X POST \"$OTEL_EXPORTER_OTLP_ENDPOINT/v1/traces\" -H 'Content-Type: application/json' -d \"$body\" || true ) &",
+    "}",
+    // Called on each new phase stamp. The first stamp opens the `worker.setup` window; every
+    // later stamp closes the previous phase as a child span; `ready` also emits the parent.
+    "_mp_span_on_stamp() {",
+    "  if [ -z \"$MP_TRACE_ID\" ]; then return 0; fi",
+    "  local key=\"$1\" now=\"$2\"",
+    "  if [ -z \"$MP_SETUP_SPAN\" ]; then",
+    "    MP_SETUP_SPAN=$(_mp_rand_id); MP_SETUP_START=\"$now\"; MP_PREV_PHASE=\"$key\"; MP_PREV_TS=\"$now\"; return 0",
+    "  fi",
+    "  _mp_span_emit \"$(_mp_phase_span_name \"$MP_PREV_PHASE\")\" \"$MP_PREV_TS\" \"$now\" \"$(_mp_rand_id)\" \"$MP_SETUP_SPAN\" \"$MP_PREV_PHASE\"",
+    "  if [ \"$key\" = ready ]; then",
+    "    _mp_span_emit 'worker.setup' \"$MP_SETUP_START\" \"$now\" \"$MP_SETUP_SPAN\" \"$MP_JOB_SPAN\" ''",
+    "  else",
+    "    MP_PREV_PHASE=\"$key\"; MP_PREV_TS=\"$now\"",
+    "  fi",
+    "}",
+    // ── Native error spans on setup failure (the direct goal of this refactor) ──
+    // set -e makes any uncaught failure abort the CMD; before PR #115 that just left the worker
+    // stuck at its last status with a hole in the trace. This EXIT trap turns that same failure
+    // into: (1) a real OTLP span in ERROR (status code 2 + exit code + the in-flight phase), so the
+    // failing clone/postCreate/postStart shows up red under worker.setup, and (2) a phase=error
+    // status write so the API poller flips the worker to `error` with a message. It fires only on a
+    // non-zero exit and only before `ready` (_MP_DONE guards the normal path); the short sleep lets
+    // the 1.5s poll read the error status before the container exits.
+    "_mp_fail() {",
+    "  local code=$?",
+    // We're already exiting — never let errexit abort the trap before it writes the error status.
+    "  set +e",
+    "  [ \"$_MP_DONE\" = 1 ] && return 0",
+    "  [ \"$code\" = 0 ] && return 0",
+    "  _MP_DONE=1",
+    "  local phase now msg j",
+    "  phase=\"$MP_PREV_PHASE\"",
+    "  [ -z \"$phase\" ] && phase=$(printf '%s' \"$_MP_LAST\" | sed -n 's/.*\"phase\":\"\\([^\"]*\\)\".*/\\1/p')",
+    "  [ -z \"$phase\" ] && phase=initializing",
+    "  now=\"$(_mp_now)\"",
+    // A phase that knows *why* it failed (e.g. a clone on a branch that doesn't exist) sets
+    // MP_FAIL_MSG before exiting, so the UI shows that instead of the generic phase message.
+    "  msg=\"${MP_FAIL_MSG:-setup phase $phase failed (exit $code)}\"",
+    "  echo \"[setup] ✗ $msg\" >&2",
+    // Best-effort error spans: close the failing phase (child of worker.setup) then worker.setup
+    // itself in ERROR. On a restart (postStart failure) the setup window was never opened, so emit
+    // a single worker.setup error span under the job span instead.
+    "  if [ -n \"$MP_TRACE_ID\" ]; then",
+    "    if [ -n \"$MP_SETUP_SPAN\" ]; then",
+    "      _mp_span_emit \"$(_mp_phase_span_name \"$phase\")\" \"${MP_PREV_TS:-$now}\" \"$now\" \"$(_mp_rand_id)\" \"$MP_SETUP_SPAN\" \"$phase\" \"$msg\" \"$code\"",
+    "      _mp_span_emit 'worker.setup' \"${MP_SETUP_START:-$now}\" \"$now\" \"$MP_SETUP_SPAN\" \"$MP_JOB_SPAN\" '' \"$msg\" \"$code\"",
+    "    else",
+    "      _mp_span_emit 'worker.setup' \"${MP_PREV_TS:-$now}\" \"$now\" \"$(_mp_rand_id)\" \"$MP_JOB_SPAN\" \"$phase\" \"$msg\" \"$code\"",
+    "    fi",
+    "  fi",
+    // Flip .mp-status.json to phase=error (preserving the rest) so monitorSetup surfaces it.
+    "  j=\"$_MP_LAST\"",
+    "  if [ -n \"$j\" ]; then",
+    "    j=$(printf '%s' \"$j\" | sed 's/\"phase\":\"[^\"]*\"/\"phase\":\"error\"/')",
+    "    j=\"${j%?},\\\"error\\\":\\\"$msg\\\"}\"",
+    "  else",
+    "    j=\"{\\\"phase\\\":\\\"error\\\",\\\"repos\\\":[],\\\"postCreate\\\":null,\\\"postStart\\\":null,\\\"error\\\":\\\"$msg\\\"}\"",
+    "  fi",
+    "  printf '%s' \"$j\" > " + workerStatusPath("/home/vscode") + " || true",
+    // Bridge the API's 1.5s poll interval before the container actually exits.
+    "  sleep 5 || true",
+    "}",
+    "trap _mp_fail EXIT",
+    "",
+    "# ─── First-start setup (runs once) ───────────────────────────────────────",
+    "if [ ! -f /home/vscode/.mp-setup-done ]; then",
+    "  touch " + workerStatusPath("/home/vscode") + " && chmod 666 " + workerStatusPath("/home/vscode"),
+    "  _mp_stamp initializing",
+    `  _mp ${JSON.stringify(initialStatus)}`,
+    setupScript,
+    "fi",
+    "",
+    "# ─── Every-start ─────────────────────────────────────────────────────────",
+    startScript,
+  ].join("\n")
+}
+
+// ─── buildSetupPlan (RFC 0017) ─────────────────────────────────────────────────
+//
+// The ordered phases the agent execs one by one (each in its own `docker exec` + OTel span) when
+// WORKER_SETUP_ORCHESTRATOR=agent. Reuses the exact bash blocks from buildSetupScript/buildStartScript
+// (clone strategies, oh-my-zsh, dotfiles, lifecycle) MINUS the `_mp`/`_mp_stamp`/OTLP machinery — the
+// agent owns status + spans now. Each phase carries the SetupStatus to persist at its start/end
+// (mirrors the legacy `mkStatus(...)` writes) so the DB/UI progression is identical. See RFC 0017 §2.2.
+
+export function buildSetupPlan(params: SetupScriptParams): {
+  phases: SetupPhase[]
+  initialStatus: SetupStatus
+  readyStatus: SetupStatus
+} {
+  const { project, userInfo, userSshPrivateKey, dotfilesRepo, userEnvSecrets, githubInstallationTokens, projectDeployKey, branch } = params
+  const homeDir = "/home/vscode"
+  const username = "vscode"
+
+  const repoNames = project.repositories.map((r) => r.project)
+  const hasPostCreate = !!project.postCreateCommand
+  const hasPostStart = !!project.postStartCommand
+  const pc0: LS = hasPostCreate ? "pending" : null
+  const ps0: LS = hasPostStart ? "pending" : null
+  const pcDone: LS = hasPostCreate ? "done" : null
+  const psDone: LS = hasPostStart ? "done" : null
+
+  const allReposPending: RS[] = repoNames.map((n) => ({ name: n, state: "pending" }))
+  const allReposCloning: RS[] = repoNames.map((n) => ({ name: n, state: "cloning" }))
+  const allReposDone: RS[] = repoNames.map((n) => ({ name: n, state: "done" }))
+
+  const status = (
+    phase: SetupStatus["phase"],
+    repos: RS[],
+    postCreate: LS,
+    postStart: LS,
+  ): SetupStatus => ({ phase, repos, postCreate, postStart })
+
+  const initialStatus = status("initializing", allReposPending, pc0, ps0)
+  const readyStatus = status("ready", allReposDone, pcDone, psDone)
+
+  const phases: SetupPhase[] = []
+  const hasCredentials = !!(userInfo || userSshPrivateKey || projectDeployKey)
+
+  // ── credentials (+ ownership) ─────────────────────────────────────────────
+  {
+    const l: string[] = ["set -e", ...banner("SETUP: OWNERSHIP"),
+      `chown -R ${username}:${username} /workspace`,
+      `chown -R ${username}:${username} ${homeDir}`,
+    ]
+    if (hasCredentials) l.push(...banner("SETUP: CREDENTIALS"))
+    l.push(...credentialsBlock({ homeDir, username, userInfo, userSshPrivateKey, projectDeployKey }))
+    const st = status(hasCredentials ? "credentials" : "initializing", allReposPending, pc0, ps0)
+    phases.push({ id: "credentials", label: "Credentials & ownership", script: l.join("\n"), runsOnRestart: false, statusStart: st, statusEnd: st })
+  }
+
+  // ── shell (bashrc/zsh/oh-my-zsh, land-in-workspace) ───────────────────────
+  {
+    const landInWorkspace = [
+      ``,
+      `# ── Spunto: land in workspace on fresh login ─────────────────────`,
+      `if [ "$PWD" = "$HOME" ] && [ -d /workspace ]; then`,
+      `  __mp_dirs=$(find /workspace -mindepth 1 -maxdepth 1 -type d -not -name '.*' 2>/dev/null)`,
+      `  __mp_n=$(printf '%s\\n' "$__mp_dirs" | grep -c .)`,
+      `  if [ "$__mp_n" = 1 ]; then cd "$__mp_dirs" 2>/dev/null; else cd /workspace 2>/dev/null; fi`,
+      `  unset __mp_dirs __mp_n`,
+      `fi`,
+    ].join("\n")
+    const bashrcSnippet = [
+      ``,
+      `# ── Spunto shell config ──────────────────────────────────────────`,
+      `__mp_ps1_git() {`,
+      `  local b`,
+      `  b=$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse --short HEAD 2>/dev/null) || return`,
+      `  printf ' \\e[0;33m(%s)\\e[0m' "$b"`,
+      `}`,
+      ``,
+      `PS1='\\n\\[\\e[0;2m\\]\\u@\\h\\[\\e[0m\\] \\[\\e[1;34m\\]\\w\\[\\e[0m\\]$(__mp_ps1_git)\\n\\[\\e[1;32m\\]❯\\[\\e[0m\\] '`,
+      ``,
+      `alias ll='ls -lah --color=auto'`,
+      `alias la='ls -A --color=auto'`,
+      `alias l='ls -CF --color=auto'`,
+      `alias gs='git status'`,
+      `alias gd='git diff'`,
+      `alias gl='git log --oneline --graph --decorate -20'`,
+      landInWorkspace,
+    ].join("\n")
+    const bashrcEncoded = b64(bashrcSnippet)
+    const zshrcAliasSnippet = [
+      ``,
+      `# ── Spunto config ────────────────────────────────────────────────`,
+      `setopt NO_BANG_HIST`,
+      `alias ll='ls -lah --color=auto'`,
+      `alias la='ls -A --color=auto'`,
+      `alias l='ls -CF --color=auto'`,
+      `alias gs='git status'`,
+      `alias gd='git diff'`,
+      `alias gl='git log --oneline --graph --decorate -20'`,
+      landInWorkspace,
+    ].join("\n")
+    const zshrcAliasEncoded = b64(zshrcAliasSnippet)
+    const l: string[] = ["set -e", ...banner("SETUP: SHELL"),
+      `echo ${JSON.stringify(bashrcEncoded)} | base64 -d >> ${homeDir}/.bashrc`,
+      `if command -v zsh >/dev/null 2>&1; then`,
+      `  if [ ! -d "${homeDir}/.oh-my-zsh" ]; then`,
+      `    echo "Installing oh-my-zsh..."`,
+      `    _OMZ_TMP=$(mktemp)`,
+      `    curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh -o "$_OMZ_TMP" 2>&1`,
+      `    chmod 644 "$_OMZ_TMP"`,
+      `    su ${username} -c "HOME=${homeDir} RUNZSH=no CHSH=no KEEP_ZSHRC=no bash $_OMZ_TMP" 2>&1 || true`,
+      `    rm -f "$_OMZ_TMP"`,
+      `  else`,
+      `    echo "oh-my-zsh already installed"`,
+      `  fi`,
+      `  sed -i 's/ZSH_THEME="robbyrussell"/ZSH_THEME="af-magic"/' ${homeDir}/.zshrc 2>/dev/null || true`,
+      `  sed -i 's/^plugins=(git)$/plugins=(git z)/' ${homeDir}/.zshrc 2>/dev/null || true`,
+      `  echo ${JSON.stringify(zshrcAliasEncoded)} | base64 -d >> ${homeDir}/.zshrc`,
+      `fi`,
+      `echo ${JSON.stringify(b64(landInWorkspace))} | base64 -d >> ${homeDir}/.profile`,
+      // Same reason as in credentialsBlock: this phase runs as root, so any rc file it had to
+      // *create* (.bashrc/.zshrc/.profile absent from the image) is root-owned. The legacy script's
+      // final `chown -R` covered that; here each phase leaves the home consistent on its own.
+      `chown -R ${username}:${username} ${homeDir}`,
+    ]
+    const st = status(hasCredentials ? "credentials" : "initializing", allReposPending, pc0, ps0)
+    phases.push({ id: "shell", label: "Shell setup", script: l.join("\n"), runsOnRestart: false, statusStart: st, statusEnd: st })
+  }
+
+  // ── dotfiles ──────────────────────────────────────────────────────────────
+  if (dotfilesRepo) {
+    const dotfilesUrl = dotfilesRepo.startsWith("http") || dotfilesRepo.startsWith("git@")
+      ? dotfilesRepo
+      : `https://github.com/${dotfilesRepo}`
+    const l: string[] = ["set -e", ...banner("SETUP: DOTFILES"),
+      `echo "Cloning dotfiles from ${dotfilesUrl}..."`,
+      `set +e`,
+      `git clone ${JSON.stringify(dotfilesUrl)} ${homeDir}/dotfiles 2>&1`,
+      `_DOTS_EXIT=$?`,
+      `set -e`,
+      `if [ $_DOTS_EXIT -ne 0 ]; then`,
+      `  echo "Dotfiles clone failed (exit $_DOTS_EXIT) — continuing without dotfiles"`,
+      `else`,
+      `  echo "Dotfiles cloned"`,
+      // Cloned as root, but the install script below runs as the user (and so does whoever edits
+      // these files later) — hand the clone over before touching it.
+      `  chown -R ${username}:${username} ${homeDir}/dotfiles`,
+      `  _INSTALL_SCRIPT=""`,
+      `  for _candidate in install.sh bootstrap.sh setup.sh script/setup; do`,
+      `    if [ -f "${homeDir}/dotfiles/$_candidate" ]; then`,
+      `      _INSTALL_SCRIPT="$_candidate"`,
+      `      break`,
+      `    fi`,
+      `  done`,
+      `  if [ -n "$_INSTALL_SCRIPT" ]; then`,
+      `    echo "Running dotfiles install script: $_INSTALL_SCRIPT"`,
+      `    chmod +x "${homeDir}/dotfiles/$_INSTALL_SCRIPT"`,
+      `    set +e`,
+      `    su ${username} -c "cd ${homeDir}/dotfiles && ${envPrefix(userEnvSecrets)}./$_INSTALL_SCRIPT"`,
+      `    _DOTS_INST_EXIT=$?`,
+      `    set -e`,
+      `    if [ $_DOTS_INST_EXIT -ne 0 ]; then`,
+      `      echo "Dotfiles install script exited with $_DOTS_INST_EXIT — continuing"`,
+      `    else`,
+      `      echo "Dotfiles installed"`,
+      `    fi`,
+      `  else`,
+      `    echo "No install script found — symlinking dotfiles..."`,
+      `    for _f in "${homeDir}/dotfiles"/.*; do`,
+      `      _name=$(basename "$_f")`,
+      `      case "$_name" in .|..|.git|.gitignore|.gitmodules) continue ;; esac`,
+      `      ln -sf "$_f" "${homeDir}/$_name" && echo "  linked $_name"`,
+      `    done`,
+      `    echo "Dotfiles symlinked"`,
+      `  fi`,
+      `fi`,
+    ]
+    const st = status("dotfiles", allReposPending, pc0, ps0)
+    phases.push({ id: "dotfiles", label: "Dotfiles", script: l.join("\n"), runsOnRestart: false, statusStart: st, statusEnd: st })
+  }
+
+  // ── clone repos ────────────────────────────────────────────────────────────
+  if (project.repositories.length > 0) {
+    const l: string[] = ["set -e", ...banner(`SETUP: CLONE REPOSITORIES (${project.repositories.length})`)]
+    project.repositories.forEach((r, i) => {
+      const { header, lines: cloneLines } = cloneRepoBlock({
+        repo: r,
+        index: i,
+        total: project.repositories.length,
+        homeDir,
+        branch: resolveRepoBranch(r, branch),
+        githubInstallationTokens,
+        userSshPrivateKey,
+      })
+      l.push("", header, ...cloneLines)
+    })
+    // Re-own after cloning (repos cloned as root; postCreate runs as vscode).
+    l.push("", `chown -R ${username}:${username} /workspace`)
+    phases.push({
+      id: "clone",
+      label: "Clone repositories",
+      script: l.join("\n"),
+      runsOnRestart: false,
+      statusStart: status("cloning", allReposCloning, pc0, ps0),
+      statusEnd: status("cloning", allReposDone, pc0, ps0),
+    })
+  }
+
+  // ── postCreate ──────────────────────────────────────────────────────────────
+  if (project.postCreateCommand) {
+    const hasDinDFeature = (project.features?.some((f) => f.id === "docker-in-docker") ?? false) || !!project.dind
+    const postCreateDir = project.repositories.length === 1
+      ? `/workspace/${project.repositories[0].workspacePath}`
+      : "/workspace"
+    const l: string[] = ["set -e"]
+    // Feature entrypoints are started by the passive CMD; just wait for the Docker daemon here.
+    if (hasDinDFeature) {
+      l.push(
+        'echo "Waiting for Docker daemon..."',
+        "for _i in $(seq 1 30); do",
+        "  docker info >/dev/null 2>&1 && break",
+        "  sleep 1",
+        "done",
+        'docker info >/dev/null 2>&1 && echo "Docker daemon ready" || echo "Docker daemon not ready after 30s, continuing anyway"',
+      )
+    }
+    l.push(...banner("SETUP: POST CREATE"))
+    const cmdEncoded = b64(project.postCreateCommand)
+    l.push(
+      `if [ ! -f "${homeDir}/.mp-post-create-done" ]; then`,
+      `  echo "--- Running postCreateCommand ---"`,
+      `  echo ${JSON.stringify(cmdEncoded)} | base64 -d > /tmp/mp_postcreate.sh`,
+      `  chmod +x /tmp/mp_postcreate.sh`,
+      `  su ${username} -c "cd ${postCreateDir} && bash /tmp/mp_postcreate.sh" 2>&1`,
+      `  rm -f /tmp/mp_postcreate.sh`,
+      `  touch "${homeDir}/.mp-post-create-done"`,
+      `  echo "postCreateCommand done"`,
+      `fi`,
+    )
+    phases.push({
+      id: "postCreate",
+      label: "postCreateCommand",
+      script: l.join("\n"),
+      runsOnRestart: false,
+      statusStart: status("lifecycle", allReposDone, "running", ps0),
+      statusEnd: status("lifecycle", allReposDone, "done", ps0),
+    })
+  }
+
+  // ── postStart (runs on every start, restart included) ─────────────────────
+  if (project.postStartCommand) {
+    const postStartDir = project.repositories.length === 1
+      ? `/workspace/${project.repositories[0].workspacePath}`
+      : "/workspace"
+    const l: string[] = ["set -e",
+      // Same defensive Docker wait as legacy: some images ship Docker under a different name.
+      "if [ -f " + FEATURE_ENTRYPOINTS_FILE + " ]; then",
+      "  for _i in 1 2 3 4 5; do [ -S /var/run/docker.sock ] && break || sleep 1; done",
+      "  if [ -S /var/run/docker.sock ]; then",
+      '    echo "Waiting for Docker daemon..."',
+      "    for _i in $(seq 1 30); do docker info >/dev/null 2>&1 && break; sleep 1; done",
+      '    docker info >/dev/null 2>&1 && echo "Docker daemon ready" || echo "Docker daemon not ready, continuing"',
+      "  fi",
+      "fi",
+      ...banner("START: POST START"),
+    ]
+    const cmdEncoded = b64(project.postStartCommand)
+    l.push(
+      `echo "--- Running postStartCommand ---"`,
+      `echo ${JSON.stringify(cmdEncoded)} | base64 -d > /tmp/mp_poststart.sh`,
+      `chmod +x /tmp/mp_poststart.sh`,
+      `su ${username} -c "cd ${postStartDir} && bash /tmp/mp_poststart.sh" 2>&1`,
+      `rm -f /tmp/mp_poststart.sh`,
+      `echo "postStartCommand done"`,
+    )
+    phases.push({
+      id: "postStart",
+      label: "postStartCommand",
+      script: l.join("\n"),
+      runsOnRestart: true,
+      statusStart: status("lifecycle", allReposDone, pcDone, "running"),
+      statusEnd: status("lifecycle", allReposDone, pcDone, "done"),
+    })
+  }
+
+  return { phases, initialStatus, readyStatus }
+}