@north-light/cli 0.3.560 → 0.3.562

package/dist/types.d.ts

@@ -405,6 +405,18 @@ export interface ScopeConfig {
     /** The money ledger. `take_pct` (0-100, default 0) is Northlight's take on each priced model or tool charge; at 0 no take rows are written. */
     ledger?: {
         take_pct?: number;
+        /** USD per GB-hour of Blaxel sandbox awake time; the `ledger-sandbox` lane writes no rows while it is unset. */
+        sandbox_usd_per_gb_hour?: number;
+        /** Seconds a sandbox stays awake after its broker goes idle or exits (default 30). */
+        sandbox_standby_s?: number;
+        /** USD per GB-month of R2 storage; the `ledger-storage` lane writes no `r2` rows while it is unset. */
+        storage_usd_per_gb_month?: number;
+        /** USD per GB-month of Blaxel sandbox disk; the `ledger-storage` lane writes no `blaxel` rows while it is unset. */
+        sandbox_disk_usd_per_gb_month?: number;
+        /** USD of sandbox and storage a billing account uses free each UTC month (default 50); `billed_usd` on those rows is the part above it. */
+        infra_free_usd_per_month?: number;
+        /** The `ledger-r2` lane moves closed months into the blob store only while this is true (off until 5b is accepted). */
+        r2_move?: boolean;
     };
     /** Conversation store configuration for the daemon. */
     store?: {

package/docs/sdk/release-notes.md

@@ -7,6 +7,10 @@ description: Behavior changes in @north-light/sdk that an app must act on, newes
 
 Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
 
+## 0.3.562
+
+A cloud role's runtime (one with `CRTR_DIRECTORY_URL` and `CRTR_PUBLIC_API_URL` set) accepts a directory person bearer on its TCP listener: the caller acts as that person and reads only the nodes that person may read; schedules, charges, files and provider calls are refused `403 permission_error` to it. Any other listener still refuses a person bearer `401`, now with the code `person_bearer_not_supported` (was `person_bearer_not_supported_on_cloud_role`). A cloud role also answers `GET /v1/runtime/vendor-status` and `POST /v1/runtime/vendor-account-remove` for the person the directory's token names, and refuses a token that names no person `401`.
+
 ## 0.3.560
 
 A read waits through a hosted runtime being created or replaced, instead of failing with `503`. No new option.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.560",
+  "version": "0.3.562",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -70,6 +70,9 @@
     "scripts/postinstall.mjs",
     "scripts/patch-pi-tree-root-ordering.mjs",
     "scripts/install-runtime.mjs",
+    "scripts/sandbox-start.mjs",
+    "scripts/sandbox-bootstrap.sh",
+    "scripts/git-credential-crtr",
     "scripts/lib/isolation-env.mjs",
     "scripts/lib/canvas-schema-gate.mjs",
     "scripts/lib/pack-args.mjs",
@@ -98,7 +101,7 @@
     "build:plugin": "tsc -p packages/crouter-plugin/tsconfig.json",
     "typecheck": "tsc --noEmit && tsc -p src/doc-editor/tsconfig.json",
     "typecheck:pi-packages": "npx tsc -p src/builtin-pi-packages/pi-crtr-extensions/tsconfig.json",
-    "test:runtime-packaging": "node --test scripts/runtime-smoke.test.mjs scripts/pack-args.test.mjs scripts/ensure-native-linux.test.mjs scripts/release-version.test.mjs",
+    "test:runtime-packaging": "node --test scripts/runtime-smoke.test.mjs scripts/pack-args.test.mjs scripts/ensure-native-linux.test.mjs scripts/release-version.test.mjs scripts/sandbox-start.test.mjs",
     "contract:check": "node scripts/contract.mjs check",
     "contract:surface": "node scripts/contract.mjs generate",
     "docs:check-reference": "npm exec --workspace @north-light/docs -- tsx scripts/check-reference.ts",
@@ -122,7 +125,7 @@
     "test:seam": "npm run build && npm run test:seam:built",
     "test:sdk": "npm run build:api && npm run build:identity && node --conditions=crtr-src --import tsx/esm --test --test-timeout=60000 'packages/crouter-sdk/src/__tests__/*.test.ts' 'packages/crouter-sdk/src/__tests__/integration/*.test.ts'",
     "test:sdk:pg": "node -e \"if (!process.env.TEST_DATABASE_URL) { console.error('test:sdk:pg needs TEST_DATABASE_URL (a disposable PostgreSQL), e.g. docker run --rm -d -e POSTGRES_PASSWORD=pw -p 127.0.0.1:55432:5432 postgres:18-alpine; TEST_DATABASE_URL=postgres://postgres:pw@127.0.0.1:55432/postgres'); process.exit(1) }\" && node --conditions=crtr-src --import tsx/esm --test --test-timeout=60000 'packages/crouter-sdk/src/**/__tests__/**/*.pg.test.ts'",
-    "test:seam:built": "CRTR_NO_DAEMON_AUTOSTART=1 node scripts/test-lane.mjs -- node --import ./scripts/test-env-scrub.mjs --test --test-concurrency=$(node -p 'Math.min(4, Math.max(2, require(`node:os`).availableParallelism() - 2))') --test-timeout=180000 ${CRTR_TEST_SHARD:+--test-shard=$CRTR_TEST_SHARD} 'dist/**/__tests__/seam/*.test.js'",
+    "test:seam:built": "CRTR_NO_DAEMON_AUTOSTART=1 node scripts/test-lane.mjs -- node --import ./scripts/test-env-scrub.mjs --test --test-concurrency=$(node -p 'Math.min(4, Math.max(2, require(`node:os`).availableParallelism() - 2))') --test-timeout=180000 ${CRTR_TEST_SHARD:+--test-shard=$CRTR_TEST_SHARD} 'dist/**/__tests__/seam/*.test.js' scripts/sandbox-bootstrap.test.mjs scripts/sandbox-clone.test.mjs",
     "test:all": "npm test && npm run test:integration && npm run test:seam",
     "test:isolated": "node scripts/test-isolated.mjs",
     "build:identity": "tsc -p packages/crouter-identity/tsconfig.json"
@@ -141,7 +144,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.560",
+    "@north-light/identity": "0.3.562",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.560",
+  "version": "0.3.562",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.560",
+  "version": "0.3.562",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.560",
+      "version": "0.3.562",
       "hasInstallScript": true,
       "license": "UNLICENSED",
       "workspaces": [
@@ -24,7 +24,7 @@
         "@milkdown/preset-gfm": "^7.22.3",
         "@milkdown/prose": "^7.22.3",
         "@milkdown/utils": "^7.22.3",
-        "@north-light/identity": "0.3.560",
+        "@north-light/identity": "0.3.562",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -12455,17 +12455,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/api",
-      "version": "0.3.560",
+      "version": "0.3.562",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.560",
+      "version": "0.3.562",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.560",
+      "version": "0.3.562",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12473,21 +12473,21 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.560",
+      "version": "0.3.562",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.560",
-        "@north-light/identity": "0.3.560"
+        "@north-light/api": "0.3.562",
+        "@north-light/identity": "0.3.562"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.560",
+      "version": "0.3.562",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.560",
-        "@north-light/identity": "0.3.560",
-        "@north-light/plugin": "0.3.560",
+        "@north-light/api": "0.3.562",
+        "@north-light/identity": "0.3.562",
+        "@north-light/plugin": "0.3.562",
         "jose": "^6.2.1"
       },
       "bin": {

package/scripts/git-credential-crtr

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// scripts/git-credential-crtr — git credential helper for github.com (design-fleet, Components: Git credential helper; C-A2).
+// `git-credential-crtr get` reads git's key=value request on stdin and answers username/password from
+// `POST /v1/environments/<id>/git-credential` through the broker's relay socket (`CRTR_API_SOCKET`), which holds the
+// node token; this process never sees it. It caches nothing. `store` and `erase` do nothing.
+import { readFileSync } from 'node:fs';
+import { request } from 'node:http';
+
+const [, , action] = process.argv;
+if (action !== 'get') process.exit(0);
+
+const fields = Object.fromEntries(readFileSync(0, 'utf8').split('\n').filter((l) => l.includes('=')).map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]));
+if (fields.host !== 'github.com') process.exit(0);
+
+const fail = (message) => { process.stderr.write(`git-credential-crtr: ${message}\n`); process.exit(1); };
+const socketPath = process.env.CRTR_API_SOCKET ?? fail('CRTR_API_SOCKET is not set');
+let environmentId = process.env.CRTR_ENVIRONMENT_ID;
+if (!environmentId) {
+  try { environmentId = readFileSync(`${process.env.CRTR_HOME ?? '/var/lib/crtr'}/environment-id`, 'utf8').trim(); } catch { fail('the environment id is unknown'); }
+}
+const body = JSON.stringify({ host: fields.host, ...(fields.path ? { path: fields.path } : {}) });
+const req = request({ socketPath, path: `/v1/environments/${environmentId}/git-credential`, method: 'POST', headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) }, timeout: 30_000 }, (res) => {
+  let text = '';
+  res.on('data', (c) => { text += c; });
+  res.on('end', () => {
+    if (res.statusCode !== 200) return fail(`the control plane answered ${res.statusCode}: ${text.slice(0, 300)}`);
+    const out = JSON.parse(text);
+    process.stdout.write(`username=${out.username}\npassword=${out.password}\npasswordExpiryUtc=${Math.floor(Date.parse(out.expiry) / 1000)}\n`);
+  });
+});
+req.on('error', (e) => fail(e.message));
+req.on('timeout', () => { req.destroy(); fail('timed out'); });
+req.end(body);

package/scripts/sandbox-bootstrap.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+# scripts/sandbox-bootstrap.sh — the Blaxel runner's process command (design-fleet, Wake call step 5; C-A2).
+#
+# Runs as root in the sandbox's `broker-<execution id>` process. Environment: CRTR_NODE_TOKEN, CRTR_RELEASE,
+# CRTR_RELEASE_URL, CRTR_RELEASE_SHA256 and the rest the runner set. Once per sandbox it creates the `crtr` user
+# (`crtrd` refuses root) and its directories; it installs the release if it is absent (download, sha256 check,
+# unpack into a temp dir, rename into place, keep three), then hands over to `crtr-sandbox-start` as `crtr`.
+# The node token reaches the start script on stdin, never in its environment, so no process of user `crtr` can
+# read it from /proc. A failed download or checksum exits non-zero and prints `crtr-sandbox-start: failed <reason>`
+# as its last line (the runner's `status` reports that reason).
+set -eu
+
+fail() { echo "crtr-sandbox-start: failed $1${2:+ ($2)}" >&2; exit "${3:-1}"; }
+
+: "${CRTR_RELEASE:?}" "${CRTR_RELEASE_URL:?}" "${CRTR_RELEASE_SHA256:?}" "${CRTR_NODE_TOKEN:?}"
+case "$CRTR_RELEASE" in *[!A-Za-z0-9._-]*|'') fail bad_release "$CRTR_RELEASE" ;; esac
+
+ROOT=${CRTR_SANDBOX_ROOT:-/opt/crtr}
+RELEASES="$ROOT/releases"
+RELEASE_DIR="$RELEASES/$CRTR_RELEASE"
+RUN_USER=${CRTR_RUN_USER:-crtr}
+
+if ! id "$RUN_USER" >/dev/null 2>&1; then
+  adduser -D -h "/home/$RUN_USER" -s /bin/sh "$RUN_USER" || fail user_create
+fi
+mkdir -p /run/crtr /var/lib/crtr /work "$RELEASES"
+chown "$RUN_USER" /run/crtr /var/lib/crtr /work
+# pi's grep tool wants ripgrep; installing it once per sandbox avoids a GitHub download at the first grep.
+if ! command -v rg >/dev/null 2>&1; then apk add --no-cache ripgrep >/dev/null 2>&1 || echo "crtr-sandbox-start: ripgrep not installed" >&2; fi
+
+if [ ! -f "$RELEASE_DIR/.complete" ]; then
+  tmp=$(mktemp -d "$RELEASES/.tmp.XXXXXX")
+  trap 'rm -rf "$tmp"' EXIT
+  wget -q -O "$tmp/runtime.tar.gz" "$CRTR_RELEASE_URL" || fail release_download "$CRTR_RELEASE"
+  actual=$(sha256sum "$tmp/runtime.tar.gz" | cut -d' ' -f1)
+  [ "$actual" = "$CRTR_RELEASE_SHA256" ] || fail release_checksum "expected $CRTR_RELEASE_SHA256, got $actual"
+  mkdir "$tmp/unpack"
+  tar -xzf "$tmp/runtime.tar.gz" -C "$tmp/unpack" || fail release_unpack
+  : > "$tmp/unpack/.complete"
+  # A concurrent start installing the same release wins the rename; both leave a complete directory.
+  if ! mv "$tmp/unpack" "$RELEASE_DIR" 2>/dev/null; then [ -f "$RELEASE_DIR/.complete" ] || fail release_install; fi
+  rm -rf "$tmp"
+  trap - EXIT
+fi
+ln -sfn "$RELEASE_DIR" "$ROOT/current.new" && mv -T "$ROOT/current.new" "$ROOT/current"
+# Keep the three newest releases (the current one among them).
+ls -1t "$RELEASES" 2>/dev/null | grep -v '^\.' | tail -n +4 | while read -r old; do
+  [ "$old" = "$CRTR_RELEASE" ] || rm -rf "${RELEASES:?}/$old"
+done
+
+token=$CRTR_NODE_TOKEN
+unset CRTR_NODE_TOKEN
+# `su -p` keeps the rest of the environment; the start script derives HOME and the layout itself.
+printf '%s' "$token" | exec su -p -s /bin/sh "$RUN_USER" -c "exec node '$RELEASE_DIR/scripts/sandbox-start.mjs'"

package/scripts/sandbox-start.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+// scripts/sandbox-start.mjs — `crtr-sandbox-start` (design-fleet, Wake call step 5.1–5.9; C-A2).
+//
+//   node sandbox-start.mjs              start: the node token arrives on stdin (the bootstrap pipes it), the rest in env
+//   node sandbox-start.mjs --wake <id>  signal the broker of execution <id> with SIGUSR1; exit 3 (no_broker) when none runs
+//
+// Plain node, no imports from dist/. A failing start prints `crtr-sandbox-start: failed <reason>` as its last
+// line (the runner's `status` reads it) and exits non-zero.
+import { spawn, spawnSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const EXIT_NO_BROKER = 3;
+const here = dirname(fileURLToPath(import.meta.url));
+
+class StartFailure extends Error {
+  constructor(reason, detail) { super(detail ?? reason); this.reason = reason; }
+}
+
+/** Broker processes of this sandbox: `{pid, execution}` for each `broker-cli.js ... --epoch <execution> <node>` command line. */
+export function findBrokers(procRoot = '/proc') {
+  const out = [];
+  for (const name of readdirSync(procRoot)) {
+    if (!/^\d+$/.test(name)) continue;
+    let argv;
+    try { argv = readFileSync(join(procRoot, name, 'cmdline'), 'utf8').split('\0'); } catch { continue; }
+    const entry = argv.findIndex((a) => a.endsWith('broker-cli.js'));
+    if (entry < 0) continue;
+    const epoch = argv.indexOf('--epoch', entry);
+    if (epoch < 0 || argv[epoch + 1] === undefined) continue;
+    out.push({ pid: Number(name), execution: argv[epoch + 1], node: argv.filter((a) => a !== '').at(-1) });
+  }
+  return out;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function stopBroker(pid) {
+  try { process.kill(pid, 'SIGTERM'); } catch { return; }
+  for (let i = 0; i < 100; i++) {
+    await sleep(100);
+    try { process.kill(pid, 0); } catch { return; }
+  }
+  try { process.kill(pid, 'SIGKILL'); } catch { /* gone */ }
+}
+
+export function wake(executionId, brokers = findBrokers()) {
+  const found = brokers.find((b) => b.execution === executionId);
+  if (!found) return EXIT_NO_BROKER;
+  process.kill(found.pid, 'SIGUSR1');
+  return 0;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8').trim();
+}
+
+async function api(baseUrl, token, method, path, body) {
+  const response = await fetch(`${baseUrl.replace(/\/$/, '')}${path}`, {
+    method, headers: { authorization: `Bearer ${token}`, ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(30_000),
+  });
+  return response;
+}
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, { encoding: 'utf8', ...options });
+}
+
+/** Whether `path` lies inside `root` (both resolved). */
+export function within(root, path) {
+  const r = resolve(root) + sep;
+  return (resolve(path) + sep).startsWith(r);
+}
+
+/** Step 5.9: a daemon-side extension path under `dist/` maps into the installed release; any other path must already lie in the release or the agent dir. */
+export function mapExtension(path, release, agentDir) {
+  const marker = `${sep}dist${sep}`;
+  const at = path.lastIndexOf(marker);
+  if (at >= 0 && !within(release, path) && !within(agentDir, path)) {
+    const mapped = join(release, path.slice(at + 1));
+    if (existsSync(mapped)) return mapped;
+  }
+  if (!within(release, path) && !within(agentDir, path)) throw new StartFailure('extension_unavailable', `extension path ${path} lies outside the release and the agent dir`);
+  if (!existsSync(path)) throw new StartFailure('extension_unavailable', `extension ${path} does not exist`);
+  return path;
+}
+
+function lstatExists(path) {
+  try { lstatSync(path); return true; } catch { return false; }
+}
+
+function gitIn(cwd, args, timeoutMs) {
+  return run('git', args, { cwd, timeout: timeoutMs });
+}
+
+/** A short-lived credential relay for the start script's own git calls (the broker's relay does not exist until the script ends). It answers
+ *  only `POST /v1/environments/<id>/git-credential`, forwarding it to the control plane with the node token this process holds; the socket
+ *  lives in a private directory and the token is neither written to disk nor placed in any child's environment. */
+async function credentialRelay(apiUrl, token, environmentId) {
+  const dir = mkdtempSync(join(tmpdir(), 'crtr-credential-'));
+  const socketPath = join(dir, 'api.sock');
+  const route = `/v1/environments/${environmentId}/git-credential`;
+  const server = createServer((req, res) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', async () => {
+      if (req.method !== 'POST' || req.url !== route) return void res.writeHead(404).end();
+      try {
+        const upstream = await api(apiUrl, token, 'POST', route, JSON.parse(Buffer.concat(chunks).toString('utf8')));
+        res.writeHead(upstream.status, { 'content-type': 'application/json' }).end(await upstream.text());
+      } catch (error) { res.writeHead(502).end(String(error?.message ?? error)); }
+    });
+  });
+  await new Promise((resolveListen, rejectListen) => { server.once('error', rejectListen); server.listen(socketPath, resolveListen); });
+  return { socketPath, close: async () => { await new Promise((r) => server.close(r)); rmSync(dir, { recursive: true, force: true }); } };
+}
+
+/** `git` in `cwd` without blocking the event loop (the credential relay must keep answering while it runs). */
+function gitAsync(cwd, args, timeoutMs, env) {
+  return new Promise((resolveGit) => {
+    const child = spawn('git', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], timeout: timeoutMs });
+    let stderr = '';
+    child.stderr.on('data', (c) => { stderr += c; });
+    child.stdout.resume();
+    child.on('error', (error) => resolveGit({ status: 1, stderr: String(error?.message ?? error) }));
+    child.on('close', (status) => resolveGit({ status, stderr }));
+  });
+}
+
+async function start(env) {
+  const need = (name) => { const v = env[name]; if (!v) throw new StartFailure('bad_environment', `${name} is not set`); return v; };
+  const apiUrl = need('CRTR_API_URL');
+  const executionId = need('CRTR_EXECUTION_ID');
+  const releaseDir = realpathSync(env.CRTR_RELEASE_DIR ?? resolve(here, '..'));
+  // 5.1 token first; nothing is started or stopped before the control plane accepts it.
+  const token = env.CRTR_NODE_TOKEN ?? await readStdin();
+  if (!/^[A-Za-z0-9_-]{43}$/.test(token)) throw new StartFailure('token_missing', 'no node token on stdin');
+  let response;
+  try { response = await api(apiUrl, token, 'GET', `/v1/executions/${executionId}/start`); }
+  catch (error) { throw new StartFailure('bundle_unreachable', String(error?.message ?? error)); }
+  if (response.status === 401 || response.status === 403) throw new StartFailure('token_rejected', `the control plane answered ${response.status}`);
+  if (!response.ok) throw new StartFailure('bundle_failed', `the control plane answered ${response.status}`);
+  const bundle = await response.json();
+
+  // 5.2 a broker of this execution is signalled; a broker of another execution is stopped.
+  const brokers = findBrokers(env.CRTR_PROC_ROOT ?? '/proc').filter((b) => b.node === bundle.node.id);
+  if (brokers.some((b) => b.execution === executionId)) { wake(executionId, brokers); return null; }
+  for (const b of brokers) await stopBroker(b.pid);
+
+  const root = env.CRTR_HOME ?? '/var/lib/crtr';
+  const home = join(root, 'apps', bundle.node.app.replace(/^app:/, ''), 'home');
+  const agentDir = join(home, '.pi', 'agent');
+  const work = env.CRTR_WORK_DIR ?? '/work';
+  mkdirSync(agentDir, { recursive: true });
+  // The recipe image installs its pi packages into one agent dir of its own (RECIPE_PI_AGENT_DIR in image-build.ts); every app's agent dir links to
+  // that install, so the packages load whichever app the node runs in.
+  const recipeAgent = join(root, 'recipe-pi-agent');
+  for (const tree of ['npm', 'git']) {
+    const source = join(recipeAgent, tree);
+    const target = join(agentDir, tree);
+    if (!existsSync(source)) continue;
+    if (!lstatExists(target)) symlinkSync(source, target);
+    else if (!lstatSync(target).isSymbolicLink() || readlinkSync(target) !== source) throw new StartFailure('recipe_packages_unavailable', `${target} exists and is not the recipe image's ${source}`);
+  }
+
+  // 5.4 git: the credential helper, and the identity only when the bundle carries one.
+  const gitEnv = { ...env, HOME: home };
+  const gitConfig = (key, value) => run('git', ['config', '--global', key, value], { env: gitEnv });
+  gitConfig('credential.https://github.com.helper', join(releaseDir, 'scripts', 'git-credential-crtr'));
+  if (bundle.git_identity) { gitConfig('user.name', bundle.git_identity.name); gitConfig('user.email', bundle.git_identity.email); }
+
+  // 5.5 plugins, once per revision.
+  const marker = join(work, '.crtr', 'plugins-revision');
+  const have = existsSync(marker) ? readFileSync(marker, 'utf8').trim() : null;
+  if (have !== String(bundle.plugins_revision) && bundle.plugins.length > 0) {
+    const crtr = join(releaseDir, 'bin', 'crtr');
+    const pluginEnv = { ...gitEnv, NPM_CONFIG_PREFIX: join(home, '.npm-global'), CRTR_HOME: root, CRTR_NO_AUTO_INIT: '1' };
+    const crtrRun = (args) => run(process.execPath, [crtr, ...args], { env: pluginEnv, timeout: 300_000 });
+    const detail = (r) => (r.stderr || r.stdout || '').slice(0, 300);
+    // A plugin of a marketplace is installed as `<marketplace name>/<plugin>`; the bundle names only the marketplace's url and ref, so the name is what
+    // `pkg market add` reports. Adding re-clones, so a marketplace added once per start is current. A plugin already installed (an earlier revision) is
+    // removed first, since install refuses an installed name.
+    const marketplaces = new Map();
+    for (const plugin of bundle.plugins) {
+      if ('path' in plugin.source) throw new StartFailure('plugin_source_unreachable', `${plugin.name}: its source is ${plugin.source.path} on the machine that registered it, which a sandbox cannot read`);
+      const { url, ref } = plugin.source.marketplace;
+      if (!url) throw new StartFailure('plugin_source_unreachable', `${plugin.name}: its marketplace has no url`);
+      const key = `${url}\0${ref ?? ''}`;
+      if (!marketplaces.has(key)) {
+        const added = crtrRun(['--json', 'pkg', 'market', 'add', url, ...(ref ? ['--ref', ref] : []), '--scope', 'user']);
+        let name;
+        try { name = JSON.parse(added.stdout).name; } catch { /* reported below */ }
+        if (added.status !== 0 || typeof name !== 'string') throw new StartFailure('plugin_install_failed', `${plugin.name}: marketplace ${url}: ${detail(added)}`);
+        marketplaces.set(key, name);
+      }
+      const removed = crtrRun(['pkg', 'plugin', 'remove', plugin.name, '--scope', 'user']);
+      if (removed.status !== 0 && !/not found/i.test(removed.stderr + removed.stdout)) throw new StartFailure('plugin_install_failed', `${plugin.name}: remove: ${detail(removed)}`);
+      const installed = crtrRun(['pkg', 'plugin', 'install', `${marketplaces.get(key)}/${plugin.name}`, '--scope', 'user']);
+      if (installed.status !== 0) throw new StartFailure('plugin_install_failed', `${plugin.name}: ${detail(installed)}`);
+    }
+  }
+  if (have !== String(bundle.plugins_revision)) { mkdirSync(dirname(marker), { recursive: true }); writeFileSync(marker, String(bundle.plugins_revision)); }
+
+  // 5.6 fetch only, never clone and never move a working tree; a failure is recorded and the start continues. The fetch reaches a private
+  // repository through the credential helper, over a relay of this process (see credentialRelay) because the broker's does not exist yet.
+  const fetchFailures = [];
+  const cloned = (bundle.recipe?.repositories ?? []).filter((repo) => existsSync(join(work, repo.name, '.git')));
+  if (cloned.length > 0) {
+    const environment = bundle.node.environment_id;
+    const relay = environment ? await credentialRelay(apiUrl, token, environment) : null;
+    const fetchEnv = { ...gitEnv, GIT_TERMINAL_PROMPT: '0', ...(relay ? { CRTR_API_SOCKET: relay.socketPath, CRTR_ENVIRONMENT_ID: environment } : {}) };
+    delete fetchEnv.CRTR_NODE_TOKEN;
+    try {
+      for (const repo of cloned) {
+        const r = await gitAsync(join(work, repo.name), ['fetch', '--prune'], 60_000, fetchEnv);
+        if (r.status !== 0) fetchFailures.push({ repository: repo.name, error: r.stderr.slice(0, 300) });
+      }
+    } finally { await relay?.close(); }
+  }
+
+  // 5.7 the managed worktree request (D102): the node's branch in the recipe repository's one clone, never a second checkout.
+  const worktree = bundle.launch.worktree;
+  if (worktree) {
+    const dir = join(work, worktree.repository);
+    if (!existsSync(join(dir, '.git'))) throw new StartFailure('cwd_missing', `${dir} holds no clone of ${worktree.repository}`);
+    const current = gitIn(dir, ['symbolic-ref', '--short', '-q', 'HEAD'], 10_000).stdout?.trim();
+    if (current !== worktree.branch) {
+      const exists = gitIn(dir, ['rev-parse', '--verify', '-q', `refs/heads/${worktree.branch}`], 10_000).status === 0;
+      const r = gitIn(dir, exists ? ['switch', worktree.branch] : ['switch', '-c', worktree.branch, worktree.base], 30_000);
+      if (r.status !== 0) throw new StartFailure('worktree_failed', `${worktree.branch}: ${(r.stderr || '').slice(0, 300)}`);
+    }
+  }
+
+  // 5.7 directories and the cwd.
+  const cwd = bundle.node.cwd;
+  if (!existsSync(cwd)) {
+    const inside = (bundle.recipe?.repositories ?? []).some((repo) => within(join(work, repo.name), cwd));
+    if (inside) throw new StartFailure('cwd_missing', `${cwd} lies in a repository that was never cloned`);
+    mkdirSync(cwd, { recursive: true });
+  }
+  const nodeId = bundle.node.id;
+  const environmentId = bundle.node.environment_id;
+  if (environmentId) writeFileSync(join(root, 'environment-id'), environmentId);
+  const appRoot = join(root, 'apps', bundle.node.app.replace(/^app:/, ''));
+  const runDir = join(env.CRTR_RUN_ROOT ?? '/run/crtr', 'nodes', nodeId);
+  for (const dir of ['context', 'reports', 'attachments', 'worktree'].map((d) => join(appRoot, 'nodes', nodeId, d))
+    .concat([join(root, 'runtime', 'nodes', nodeId, 'job'), join(runDir, 'job')])) mkdirSync(dir, { recursive: true });
+
+  // 5.8 the broker's local inputs.
+  const launch = bundle.launch;
+  const brokerEntry = join(releaseDir, 'dist', 'core', 'runtime', 'broker-cli.js');
+  const argv = [...launch.argv];
+  for (let i = 0; i < argv.length; i++) if (argv[i] === '-e') argv[i + 1] = mapExtension(argv[i + 1], releaseDir, agentDir);
+  // As host.ts does: the scopes file exists only when the recipe's env names one, holding `scopes ?? []`.
+  const scopesFile = launch.env?.CRTR_SCOPES_FILE !== undefined ? join(runDir, 'scopes.json') : null;
+  if (scopesFile) writeFileSync(scopesFile, JSON.stringify(launch.scopes ?? []));
+  const models = launch.models;
+  if (models) writeFileSync(join(agentDir, 'models.json'), `${JSON.stringify(models, null, 2)}\n`);
+  writeFileSync(join(runDir, 'broker-launch.json'), JSON.stringify({ ...launch, argv }));
+  const settingsPath = join(agentDir, 'settings.json');
+  const builtin = join(releaseDir, 'dist', 'builtin-pi-packages', 'pi-crtr-extensions');
+  let settings = {};
+  if (existsSync(settingsPath)) settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+  const packages = Array.isArray(settings.packages) ? settings.packages : [];
+  if (!packages.includes(builtin)) packages.push(builtin);
+  const recipeSettings = join(recipeAgent, 'settings.json');
+  if (existsSync(recipeSettings)) {
+    for (const entry of JSON.parse(readFileSync(recipeSettings, 'utf8')).packages ?? []) {
+      if (!packages.some((have) => JSON.stringify(have) === JSON.stringify(entry))) packages.push(entry);
+    }
+  }
+  writeFileSync(settingsPath, `${JSON.stringify({ ...settings, packages })}\n`);
+
+  // 5.9 the broker, with the token on fd 3 and not in its environment.
+  const brokerEnv = { ...env, ...launch.env, HOME: home, PI_CODING_AGENT_DIR: agentDir, CRTR_HOME: root, CRTR_RUNTIME_HOME: join(root, 'runtime'),
+    CRTR_FRONT_DOOR: '1', CRTR_EXECUTION_ID: executionId, CRTR_API_URL: apiUrl, CRTR_NO_AUTO_INIT: '1',
+    CRTR_PLUGINS_REVISION: String(bundle.plugins_revision), ...(environmentId ? { CRTR_ENVIRONMENT_ID: environmentId } : {}), ...(scopesFile ? { CRTR_SCOPES_FILE: scopesFile } : {}),
+    PATH: `${join(releaseDir, 'bin')}:${env.PATH ?? '/usr/local/bin:/usr/bin:/bin'}` };
+  for (const name of ['CRTR_NODE_TOKEN', 'CRTR_RELEASE_URL', 'CRTR_RELEASE_SHA256']) delete brokerEnv[name];
+  const child = spawn(process.execPath, [brokerEntry, '--canvas-home', join(root, 'runtime'), '--epoch', executionId, nodeId],
+    { cwd, env: brokerEnv, stdio: ['ignore', 'inherit', 'inherit', 'pipe'] });
+  child.stdio[3].end(token);
+  const exited = new Promise((resolveExit) => child.on('exit', (code, signal) => resolveExit(code ?? (signal ? 128 : 1))));
+  for (const sig of ['SIGTERM', 'SIGINT']) process.on(sig, () => child.kill(sig));
+  // The failure is a node log record (`POST /v1/nodes/:id/records/log`, the route a broker's events use); a refused post goes to the process log (`bl logs`).
+  for (const failure of fetchFailures) {
+    const record = JSON.stringify({ v: 1, ts: new Date().toISOString(), level: 'warn', event: 'sandbox.fetch.failed', component: 'broker', operation_id: randomBytes(16).toString('hex'), node_id: nodeId, fields: failure });
+    try {
+      const posted = await api(apiUrl, token, 'POST', `/v1/nodes/${nodeId}/records/log`, { record, expected_execution_id: executionId });
+      if (!posted.ok) throw new Error(`the control plane answered ${posted.status}`);
+    } catch (error) { console.error(`sandbox.fetch.failed ${record} (not recorded: ${error?.message ?? error})`); }
+  }
+  return await exited;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  try {
+    if (args[0] === '--wake') {
+      if (!args[1]) throw new StartFailure('bad_arguments', '--wake needs an execution id');
+      const code = wake(args[1], findBrokers(process.env.CRTR_PROC_ROOT ?? '/proc'));
+      if (code === EXIT_NO_BROKER) console.error('crtr-sandbox-start: failed no_broker');
+      process.exit(code);
+    }
+    const code = await start(process.env);
+    process.exit(code ?? 0);
+  } catch (error) {
+    const reason = error instanceof StartFailure ? error.reason : 'start_failed';
+    console.error(`crtr-sandbox-start: ${error.message}`);
+    console.error(`crtr-sandbox-start: failed ${reason}`);
+    process.exit(1);
+  }
+}