@runuai/host 0.9.14 → 0.9.43

package/README.md

@@ -6,7 +6,7 @@ that runs parallel AI coding tasks in ephemeral Docker containers on a machine
 your machine to the Uai cloud and runs the task containers locally. It also
 serves a small read-only monitor UI on `127.0.0.1` (ADR-028).
 
-One process does two things:
+One process does three things:
 
 - **Cloud bridge** — a host-initiated *outbound* WSS to
   `wss://app.runuai.com/host` carrying every command/tunnel. The cloud never
@@ -14,6 +14,9 @@ One process does two things:
 - **Local UI** — an HTTP server on `127.0.0.1:5876` (next free port if taken):
   connection badge, service info, active tasks, recent events. Localhost only,
   no auth, read-only — mutations come from the cloud, not here.
+- **MCP gateway** — a credential-injecting HTTP proxy for task containers,
+  bound to `127.0.0.1:5877` by default. Listener failures retry with capped
+  backoff and are advertised to the cloud as bounded health state.
 
 ## Requirements
 
@@ -40,9 +43,10 @@ uai-host install      # per-user service: launchd (macOS) / systemd --user (Linu
 uai-host start
 ```
 
-The host generates its **own** bridge credential locally and sends the cloud
-only a hash — the secret never leaves the machine (ADR-015). Once started it
-appears in your org and can run tasks. Data + config live under `~/.uai`
+The host generates its **own** bridge credential locally. The cloud persists
+only its hash; the raw credential transits authenticated TLS for bridge auth
+and existing-host attachment but is not stored there (ADR-015). Once started
+it appears in your org and can run tasks. Data + config live under `~/.uai`
 (`~/.uai/.env.local`, `~/.uai/data/`); from a repo checkout they stay under the
 repo instead. The monitor UI is at `http://127.0.0.1:5876` (exact port in
 `uai-host status`).
@@ -51,7 +55,11 @@ repo instead. The monitor UI is at `http://127.0.0.1:5876` (exact port in
 
 ```
 setup --cloud <wss-url> --enroll <token>
-                     claim this machine via an enrollment token (writes config)
+                     claim this machine, or enroll its existing identity in
+                     the token's workspace
+enroll <token> [--cloud <wss-url>]
+                     first-time setup, or attach this machine to another
+                     workspace; uses the stored cloud URL when available
 install [--dry-run]  install as a per-user service for this OS
 uninstall            remove the service
 start | stop         control the installed service
@@ -63,6 +71,9 @@ pair <token>         store a host token directly (manual fallback for setup)
 open                 open the local UI in your browser
 ```
 
+`enroll` is available in host version 0.9.15 and newer. Its compatible cloud
+endpoint is intentionally deployed before that host release.
+
 `--dry-run` on `install` (and start/stop/…) prints the unit file + load
 commands without touching launchd/systemd.
 
@@ -72,6 +83,12 @@ Runs identically with no display: install via the same flow, skip `uai-host
 open`, and use `uai-host status` for everything the UI shows. The UI stays
 reachable over an SSH port-forward to `127.0.0.1:5876` if you want it.
 
+At boot, task and channel starts wait for the initial agent-CLI maintenance
+pass to settle before any in-container writer or runner executes. The cloud
+host page shows this short preparation state. It also shows MCP gateway
+listener failures while the host retries them; gateway health is independent
+of ordinary task admission.
+
 ## Security
 
 Tasks run in ephemeral containers and **do not** mount your live AI session

package/db/migrations/0014_host_inventory_event_index.sql

@@ -0,0 +1 @@
+CREATE INDEX `uai_host_events_task_id_idx` ON `uai_host_events` (`task_id`);

package/db/migrations/0015_host_settings.sql

@@ -0,0 +1,9 @@
+CREATE TABLE `host_settings` (
+	`id` text PRIMARY KEY DEFAULT 'host' NOT NULL,
+	`retain_terminal_history` integer DEFAULT true NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch() * 1000) NOT NULL,
+	CONSTRAINT "host_settings_singleton" CHECK (`host_settings`.`id` = 'host'),
+	CONSTRAINT "host_settings_retention_boolean" CHECK (`host_settings`.`retain_terminal_history` IN (0, 1))
+);
+--> statement-breakpoint
+INSERT INTO `host_settings` (`id`, `retain_terminal_history`) VALUES ('host', true);

package/db/migrations/0016_task_environment.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `uai_host_tasks` ADD `environment_provider` text;--> statement-breakpoint
+ALTER TABLE `uai_host_tasks` ADD `environment_locator` text CONSTRAINT `uai_host_tasks_environment_pair` CHECK ((`environment_provider` IS NULL) = (`environment_locator` IS NULL));

package/db/migrations/meta/_journal.json

@@ -99,6 +99,27 @@
       "when": 1786045000000,
       "tag": "0013_github_credential_generations",
       "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "6",
+      "when": 1786406400000,
+      "tag": "0014_host_inventory_event_index",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1786406401000,
+      "tag": "0015_host_settings",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "6",
+      "when": 1786406402000,
+      "tag": "0016_task_environment",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -9,49 +9,99 @@
 import { sql } from "drizzle-orm";
 import {
   blob,
+  check,
+  index,
   integer,
   primaryKey,
   sqliteTable,
   text,
 } from "drizzle-orm/sqlite-core";
 
-export const hostTasks = sqliteTable("uai_host_tasks", {
-  taskId: text("task_id").primaryKey(),
-  codeServerPort: integer("code_server_port"),
-  previewPorts: text("preview_ports").notNull().default("[]"),
-  composeProject: text("compose_project"),
-  worktreePath: text("worktree_path"),
-  statusMirror: text("status_mirror"),
-  // Owner + project slugs — received in TaskLaunchInput at task-up and
-  // persisted here so the local UI (ADR-028) can show "who/what" without a
-  // cloud round-trip. The cloud stays the audit authority.
-  ownerUserId: text("owner_user_id"),
-  ownerEmail: text("owner_email"),
-  ownerName: text("owner_name"),
-  projectSlugs: text("project_slugs").notNull().default("[]"),
-  lockedAt: integer("locked_at", { mode: "number" }),
-  startedAt: integer("started_at", { mode: "number" }),
-  endedAt: integer("ended_at", { mode: "number" }),
-  updatedAt: integer("updated_at", { mode: "number" })
-    .notNull()
-    .default(sql`(unixepoch() * 1000)`),
-});
+export const hostTasks = sqliteTable(
+  "uai_host_tasks",
+  {
+    taskId: text("task_id").primaryKey(),
+    codeServerPort: integer("code_server_port"),
+    previewPorts: text("preview_ports").notNull().default("[]"),
+    composeProject: text("compose_project"),
+    worktreePath: text("worktree_path"),
+    // ADR-101 Phase C. Null rows predate the provider seam and are inferred as
+    // Docker Compose only when their legacy runtime identity is complete.
+    environmentProvider: text("environment_provider"),
+    environmentLocator: text("environment_locator"),
+    statusMirror: text("status_mirror"),
+    // Owner + project slugs — received in TaskLaunchInput at task-up and
+    // persisted here so the local UI (ADR-028) can show "who/what" without a
+    // cloud round-trip. The cloud stays the audit authority.
+    ownerUserId: text("owner_user_id"),
+    ownerEmail: text("owner_email"),
+    ownerName: text("owner_name"),
+    projectSlugs: text("project_slugs").notNull().default("[]"),
+    lockedAt: integer("locked_at", { mode: "number" }),
+    startedAt: integer("started_at", { mode: "number" }),
+    endedAt: integer("ended_at", { mode: "number" }),
+    updatedAt: integer("updated_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+  },
+  (table) => ({
+    environmentPair: check(
+      "uai_host_tasks_environment_pair",
+      sql`(${table.environmentProvider} IS NULL) = (${table.environmentLocator} IS NULL)`,
+    ),
+  }),
+);
 
 export type HostTask = typeof hostTasks.$inferSelect;
 export type NewHostTask = typeof hostTasks.$inferInsert;
 
+// Singleton host-local settings row (ADR-100). Runtime switches that must be
+// visible before SQLite opens remain in `.env.local`; retention policy belongs
+// here because it governs owner-facing local history only. Correctness
+// tombstones and orphan-GC evidence are never controlled by this setting.
+export const hostSettings = sqliteTable(
+  "host_settings",
+  {
+    id: text("id").primaryKey().default("host"),
+    retainTerminalHistory: integer("retain_terminal_history", {
+      mode: "boolean",
+    })
+      .notNull()
+      .default(true),
+    updatedAt: integer("updated_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+  },
+  (table) => ({
+    singleton: check("host_settings_singleton", sql`${table.id} = 'host'`),
+    retentionBoolean: check(
+      "host_settings_retention_boolean",
+      sql`${table.retainTerminalHistory} IN (0, 1)`,
+    ),
+  }),
+);
+
+export type HostSettings = typeof hostSettings.$inferSelect;
+export type NewHostSettings = typeof hostSettings.$inferInsert;
+
 // Host-side task lifecycle event log (ADR-028). HostEvent (the agent-output
 // stream) is forwarded to the cloud, not stored; this table is the local
 // `/api/events` feed — appended on task.created/started/ended (+ ship).
-export const hostEvents = sqliteTable("uai_host_events", {
-  id: text("id").primaryKey(), // ulid
-  taskId: text("task_id").notNull(),
-  kind: text("kind").notNull(), // task.created | task.started | task.ended | task.ship
-  ts: integer("ts", { mode: "number" })
-    .notNull()
-    .default(sql`(unixepoch() * 1000)`),
-  detail: text("detail"),
-});
+export const hostEvents = sqliteTable(
+  "uai_host_events",
+  {
+    id: text("id").primaryKey(), // ulid
+    taskId: text("task_id").notNull(),
+    kind: text("kind").notNull(), // task.created | task.started | task.ended | task.ship
+    ts: integer("ts", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+    detail: text("detail"),
+  },
+  (t) => ({
+    taskIdIdx: index("uai_host_events_task_id_idx").on(t.taskId),
+  }),
+);
 
 export type HostEventRow = typeof hostEvents.$inferSelect;
 export type NewHostEventRow = typeof hostEvents.$inferInsert;

package/images/standard/Dockerfile

@@ -10,8 +10,9 @@
 # Design points:
 #   - Debian bookworm-slim base, non-root `node` user (home /home/node).
 #   - asdf at /opt/asdf with plugins for nodejs/python/golang/ruby/rust.
-#     Concrete runtime versions are installed lazily at task-up by uai-init,
-#     cached on the host-wide named volume mounted at /opt/asdf-data.
+#     Before Compose starts a task, a host-controlled maintenance container
+#     materializes its declared versions into the host-wide /opt/asdf-data
+#     volume. uai-init only installs task-local dependencies afterward.
 #   - A default ~/.tool-versions (asdf global fallback) pins a working Node +
 #     Python so the agent CLIs and a 0-project scratchpad always have a runtime;
 #     a project's own .tool-versions takes precedence (asdf dir walk).
@@ -65,6 +66,7 @@ RUN apt-get update \
       tk-dev \
       tmux \
       unzip \
+      util-linux \
       xz-utils \
       zlib1g-dev \
       zsh \
@@ -121,18 +123,33 @@ RUN groupadd --gid 1000 node \
 
 ENV ASDF_DIR=/opt/asdf
 ENV ASDF_DATA_DIR=/opt/asdf-data
+ENV ASDF_CONFIG_FILE=/dev/null
+ENV ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=.tool-versions
+ENV COREPACK_HOME=/opt/asdf-data/corepack
+ENV COREPACK_DEFAULT_TO_LATEST=0
+ENV COREPACK_ENABLE_AUTO_PIN=0
+ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+ENV COREPACK_ENV_FILE=0
+ENV COREPACK_ENABLE_PROJECT_SPEC=1
+ENV COREPACK_ENABLE_STRICT=1
+ENV COREPACK_ENABLE_UNSAFE_CUSTOM_URLS=0
+ENV COREPACK_INTEGRITY_CHECK=1
+ENV COREPACK_ENABLE_NETWORK=0
+ENV COREPACK_NPM_REGISTRY=https://registry.npmjs.org
 # Leave the tool-versions filename at asdf's default (`.tool-versions`) so asdf
 # walks UP from the cwd and a project's /workspace/<slug>/.tool-versions wins.
 # The baked default lives at the node user's home (~/.tool-versions) as asdf's
 # global fallback for tasks with no project file (agent CLIs, scratchpad).
-# Do NOT set ASDF_DEFAULT_TOOL_VERSIONS_FILENAME to an absolute path — that
-# overrides the search *filename* and bypasses project files entirely (it made
+# Keep ASDF_DEFAULT_TOOL_VERSIONS_FILENAME as the basename above, never an
+# absolute path: an absolute value bypasses project files entirely (it made
 # asdf read only /etc/.tool-versions, ignoring per-project pins).
 
 RUN git clone --depth 1 --branch "$ASDF_VERSION" https://github.com/asdf-vm/asdf.git "$ASDF_DIR" \
  && mkdir -p "$ASDF_DATA_DIR" \
+ && touch "$ASDF_DATA_DIR/.uai-maintenance.lock" \
  && chown -R node:node "$ASDF_DIR" "$ASDF_DATA_DIR" \
- && chmod -R g+rwX "$ASDF_DATA_DIR"
+ && chmod -R g+rwX "$ASDF_DATA_DIR" \
+ && chmod 0664 "$ASDF_DATA_DIR/.uai-maintenance.lock"
 
 # Make asdf available on PATH + shell init for BOTH root and node, for login
 # and non-login shells (uai-init runs as node via a non-interactive exec).
@@ -172,8 +189,8 @@ RUN su node -c 'sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/oh
 # 4. asdf plugins + the root default runtimes.
 #
 # Plugins are added for all common runtimes; only the root defaults are
-# *installed* at build time. Other versions are installed lazily by uai-init
-# and cached on the /opt/asdf-data volume.
+# *installed* at build time. A pre-Compose maintenance container installs
+# project versions into the shared /opt/asdf-data volume.
 #
 # Run as node so the install lands in /opt/asdf-data owned by node.
 # ---------------------------------------------------------------------------
@@ -183,14 +200,17 @@ RUN su node -c 'sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/oh
 # scratchpad tasks). A project file takes precedence via asdf's dir walk. The
 # `tool-versions` file in this directory is the AUTHORITATIVE source.
 COPY tool-versions /home/node/.tool-versions
-RUN chmod 0644 /home/node/.tool-versions \
+COPY --chown=root:root container/corepack-version /usr/local/share/uai/corepack-version
+COPY --chown=root:root container/uai-materialize-runtimes /usr/local/bin/uai-materialize-runtimes
+RUN chmod 0644 /home/node/.tool-versions /usr/local/share/uai/corepack-version \
+ && chmod 0755 /usr/local/bin/uai-materialize-runtimes \
  && chown node:node /home/node/.tool-versions
 
 USER node
 
 # Add plugins for all common runtimes, then install exactly the versions the
 # default ~/.tool-versions pins (read straight from the file so there is one
-# source of truth). Other versions install lazily at task-up via uai-init.
+# source of truth). Other versions install in the pre-Compose materializer.
 RUN bash -lc '\
   set -e; \
   . /opt/asdf/asdf.sh; \
@@ -214,7 +234,13 @@ RUN bash -lc '\
 RUN bash -lc '\
   set -e; \
   . /opt/asdf/asdf.sh; \
-  npm install -g @anthropic-ai/claude-code @openai/codex; \
+  COREPACK_VERSION="$(sed -n "1p" /usr/local/share/uai/corepack-version)"; \
+  printf "%s" "$COREPACK_VERSION" | grep -Eq "^[0-9]+\\.[0-9]+\\.[0-9]+$"; \
+  npm install -g @anthropic-ai/claude-code @openai/codex "corepack@$COREPACK_VERSION" \
+    --registry=https://registry.npmjs.org/ \
+    --userconfig=/dev/null \
+    --globalconfig=/dev/uai-empty-npmrc; \
+  corepack enable; \
   curl -fsSL https://code-server.dev/install.sh | sh -s -- --method standalone --prefix /home/node/.local; \
   asdf reshim nodejs; \
 '

package/images/standard/README.md

@@ -13,10 +13,12 @@ See [`docs/runtime.md`](../../../docs/runtime.md) for the authoritative spec.
   uid/gid 1000). The container runs as `node`; uai-init and the agent CLIs
   expect `/home/node`.
 - **asdf** at `/opt/asdf`, data dir `/opt/asdf-data` (the host-wide
-  `uai-asdf-data` volume mounts there). Plugins pre-added for `nodejs`,
-  `python`, `golang`, `ruby`, `rust`. Only the root defaults are installed at
-  build time; other versions install lazily at task-up via `uai-init` and are
-  cached on the data volume.
+  `uai-asdf-data` volume mounts there read-only in task apps). Plugins
+  pre-added for `nodejs`, `python`, `golang`, `ruby`, `rust`. Only the root
+  defaults are installed at build time; after worktree resolution, a
+  host-controlled pre-start maintenance container is the bounded, locked
+  read-write user that installs and proves other versions before the task app
+  exists.
 - **Default `~/.tool-versions`** (asdf's global fallback, at `/home/node`)
   pinning a default Node + Python. The `tool-versions` file in this directory is
   the authoritative source for the numbers; the `Dockerfile` `COPY`s it to
@@ -37,7 +39,18 @@ See [`docs/runtime.md`](../../../docs/runtime.md) for the authoritative spec.
 - **code-server** (the Editor pane), **gh**, **git**, **curl**,
   **ca-certificates**, **jq**, **ripgrep**, **tmux**, **direnv**, **uv**,
   plus `build-essential` and the `-dev` libraries asdf's build plugins need.
-- **`uai-init`** baked at `/usr/local/bin/uai-init`.
+- **`uai-materialize-runtimes`** baked at
+  `/usr/local/bin/uai-materialize-runtimes`; it is the credential-free,
+  workspace-read-only shared-cache writer used before Compose starts a task.
+  The host supplies the selected project slugs at the fixed, read-only
+  `/run/uai/runtime-projects` allowlist; only those immediate Git worktrees are
+  inspected, so workspace control/shared directories cannot become projects.
+- **`uai-init`** baked at `/usr/local/bin/uai-init`; it installs task-local
+  dependencies and starts code-server, but does not mutate asdf runtimes.
+- **Task-private npm globals** under `/home/node/.local/share/uai-npm`, with
+  cache/logs under `/home/node/.cache/uai-npm`. The shared asdf shims and
+  system controls remain ahead of this prefix's `bin` on `PATH`, and
+  `ASDF_SKIP_RESHIM=1` prevents npm's asdf hook from writing shared shims.
 - `WORKDIR /workspace`; `CMD ["sleep","infinity"]`.
 
 Codex credentials are **not** baked in or mounted — task-up `docker cp`s them
@@ -50,7 +63,8 @@ is bind-mounted read-only by the generated compose.
 | --- | --- |
 | Standard image tag | `uai-standard:dev` |
 | Per-task derived image (only with `extra`) | `uai-task-<taskId>` |
-| Shared asdf data volume | `uai-asdf-data` → `/opt/asdf-data` |
+| Shared asdf data volume | app: `uai-asdf-data:/opt/asdf-data:ro`; maintenance: `:rw` |
+| Task npm prefix / cache | `/home/node/.local/share/uai-npm` / `/home/node/.cache/uai-npm` |
 | Compose service name | `app` (container `task-<taskId>-app-1`) |
 | In-container workspace | `/workspace` |
 | code-server port | `8080` (inside the container) |
@@ -77,37 +91,61 @@ steps below are for local image iteration only.
 # 1. Build.
 docker build -t uai-standard:dev host-agent/images/standard
 
-# 2. Create the shared asdf data volume + a throwaway workspace.
+# 2. Create the shared asdf data volume + a throwaway Git worktree and the
+#    host-controlled selected-project allowlist.
 docker volume create uai-asdf-data
-mkdir -p /tmp/uai-smoke/workspace/demo
+mkdir -p /tmp/uai-smoke/workspace/demo/.git
 printf 'nodejs 22.11.0\n' > /tmp/uai-smoke/workspace/demo/.tool-versions
-printf '{"name":"demo","packageManager":"npm@10"}\n' \
+printf '{"name":"demo","packageManager":"pnpm@10.15.0"}\n' \
   > /tmp/uai-smoke/workspace/demo/package.json
+printf 'demo\n' > /tmp/uai-smoke/runtime-projects
 
-# 3. Run the container the way compose would (service `app`, workspace bind,
+# 3. Materialize before the app exists, the way task-up does.
+docker run --rm --user node --workdir /workspace \
+  -v /tmp/uai-smoke/workspace:/workspace:ro \
+  -v /tmp/uai-smoke/runtime-projects:/run/uai/runtime-projects:ro \
+  -v uai-asdf-data:/opt/asdf-data:rw \
+  uai-standard:dev /usr/bin/timeout --signal=TERM --kill-after=10s 600s \
+  /usr/local/bin/uai-materialize-runtimes
+
+# 4. Run the container the way compose would (service `app`, workspace bind,
 #    asdf cache volume, code-server port published on loopback).
 docker run -d --name uai-smoke \
   -v /tmp/uai-smoke/workspace:/workspace \
-  -v uai-asdf-data:/opt/asdf-data \
+  -v /tmp/uai-smoke/runtime-projects:/run/uai/runtime-projects:ro \
+  -v uai-asdf-data:/opt/asdf-data:ro \
+  -e ASDF_SKIP_RESHIM=1 \
+  -e NPM_CONFIG_PREFIX=/home/node/.local/share/uai-npm \
+  -e npm_config_prefix=/home/node/.local/share/uai-npm \
+  -e NPM_CONFIG_CACHE=/home/node/.cache/uai-npm \
+  -e npm_config_cache=/home/node/.cache/uai-npm \
+  -e NPM_CONFIG_LOGS_DIR=/home/node/.cache/uai-npm/_logs \
+  -e npm_config_logs_dir=/home/node/.cache/uai-npm/_logs \
+  -e NPM_CONFIG_UMASK=0002 -e npm_config_umask=0002 \
+  -e 'PATH=/opt/asdf-data/shims:/opt/asdf/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/node/.local/share/uai-npm/bin' \
   -p 127.0.0.1::8080 \
   uai-standard:dev
 
-# 4. Sanity-check the baked toolchain (bare exec — no profile sourced).
+# 5. Prove isolation and sanity-check the baked toolchain (bare exec — no
+#    profile sourced).
+docker exec uai-smoke sh -c \
+  '! touch /opt/asdf-data/.uai-app-write-probe 2>/dev/null && test "$(npm config get prefix)" = /home/node/.local/share/uai-npm'
 docker exec uai-smoke bash -lc 'asdf --version && node -v && python --version'
 docker exec uai-smoke claude --version
 docker exec uai-smoke codex --version
 
-# 5. Run uai-init: per-folder asdf install + deps, then code-server on 8080.
+# 6. Run uai-init: task-local deps + code-server on 8080.
 docker exec uai-smoke /usr/local/bin/uai-init
 docker exec uai-smoke bash -lc 'curl -sf http://127.0.0.1:8080/healthz || \
   curl -sf -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/'
 
-# 6. Tear down.
+# 7. Tear down.
 docker rm -f uai-smoke
 ```
 
-Expected: step 4 prints the asdf version and the root-default Node + Python;
-`claude` / `codex` resolve; step 5 launches code-server bound to
+Expected: step 5 proves the app cannot write the shared cache and npm resolves
+the private prefix, then prints the asdf version and root-default Node +
+Python; `claude` / `codex` resolve; step 6 launches code-server bound to
 `0.0.0.0:8080` and the HTTP probe returns a 2xx/3xx.
 
 ## Notes / gotchas
@@ -118,5 +156,12 @@ Expected: step 4 prints the asdf version and the root-default Node + Python;
 - **First-use asdf cost.** The first task needing a given runtime version pays
   the download/build time; results persist on `uai-asdf-data` for every later
   task on the host.
-- **`uai-init` always exits 0.** A failing per-folder install logs and is
-  skipped so one bad repo never blocks task-up; code-server is still launched.
+- **Rolling recovery is preserve-and-recreate.** Before shared maintenance, an
+  upgraded host stops legacy writable/non-current apps and leaves their
+  worktrees intact. Docker mount modes are immutable, so only an exact current
+  read-only app can recover in place; explicit Resume recreates anything else.
+- **Ordinary `uai-init` failures remain best-effort.** A failing task-local
+  dependency install logs and is skipped so one bad repo never blocks editor
+  startup. Runtime materialization is separate and fail-closed before the app
+  starts; a workspace runtime-authority violation exits 78 so the host can
+  quarantine the container instead of treating it as ready.

package/images/standard/container/corepack-version

@@ -0,0 +1 @@
+0.33.0