@openparachute/agent 0.2.3-rc.5 → 0.2.3-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.3-rc.5",
+  "version": "0.2.3-rc.7",
   "description": "Vault-native agents for Claude Code — a #agent/definition note + an inbound message becomes a sandboxed claude turn; the reply is written back as a note. Messaging gateway on :1941.",
   "license": "AGPL-3.0",
   "type": "module",

package/src/agent-defs.ts

@@ -389,6 +389,15 @@ export function parseAgentDef(note: {
   }
 
   // Filesystem read scope.
+  //
+  // NOTE (step-up, agent#80): `filesystem: "full"` is the dangerous, full-disk
+  // case. The step-up PIN gate is enforced on the HTTP spawn path only
+  // (`POST /api/agents` in daemon.ts). This VAULT-NATIVE path (a #agent/definition
+  // note with `filesystem: full`) is NOT step-up-gated — registering it requires
+  // `vault:write` to author the note, which is itself separately scope-gated, so a
+  // step-up challenge here would gate a capability the caller already had to hold a
+  // write credential to reach. If the threat model is ever revisited (e.g. less-
+  // trusted note authors), this is the gap to close.
   const filesystem = metaStr(meta.filesystem);
   if (filesystem !== undefined) {
     if (filesystem !== "workspace" && filesystem !== "full") {

package/src/auth.ts

@@ -40,6 +40,7 @@
 import { validateHubJwt, HubJwtError } from "./hub-jwt.ts";
 import { extractBearer } from "@openparachute/scope-guard";
 import { consumeTicket } from "./ui-ticket.ts";
+import { isStepUpTokenValid, isStepUpConfigured } from "./step-up.ts";
 
 /** Agent scopes, declared here so callers share one spelling. */
 export const SCOPE_READ = "agent:read" as const;
@@ -227,3 +228,81 @@ export function requireSseTicket(url: URL, scope: string): Response | null {
   }
   return null;
 }
+
+/**
+ * The header a request carries the step-up token on (agent#80). The terminal
+ * WebSocket — which `new WebSocket()` can't set a header on — uses the
+ * `?step_up=` query param instead (mirroring the `?token=` exception).
+ */
+export const STEP_UP_TOKEN_HEADER = "x-step-up-token";
+
+/** Extract a presented step-up token: the header first, then `?step_up=` when allowed. */
+export function extractStepUpToken(req: Request, url: URL, allowQueryParam = false): string | null {
+  const header = req.headers.get(STEP_UP_TOKEN_HEADER);
+  if (header && header.length > 0) return header;
+  if (allowQueryParam) {
+    const q = url.searchParams.get("step_up");
+    if (q && q.length > 0) return q;
+  }
+  return null;
+}
+
+/**
+ * SECOND-FACTOR gate (agent#80) for the genuinely dangerous `agent:admin` actions:
+ * set/rotate credentials, open a terminal, spawn a `filesystem: full` agent. The
+ * caller runs {@link requireScope}(`agent:admin`) FIRST; this asserts — IN ADDITION —
+ * a valid step-up token (the operator entered their PIN recently).
+ *
+ *   - Step-up NOT configured (no PIN set) → returns `{ ok: false, reason: "setup" }`.
+ *     The caller maps it to `403 { error: "step_up_required", reason: "setup" }` so
+ *     the UI runs its FIRST-TIME PIN-setup flow before the action.
+ *   - PIN configured + valid token → `{ ok: true }` (the action proceeds).
+ *   - PIN configured + missing/expired token → `{ ok: false, reason: "token" }` →
+ *     `403 { error: "step_up_required" }` so the UI PROMPTS for the PIN.
+ *
+ * The 403 is deliberately DISTINCT from `requireScope`'s 401 (no/invalid Bearer):
+ * a 401 means "re-authenticate", a 403 `step_up_required` means "enter your PIN".
+ * The step-up token NEVER widens scope — the request already passed `agent:admin`;
+ * this is purely a recency re-confirm on top.
+ *
+ * `allowQueryParam: true` accepts `?step_up=` for the terminal WebSocket only.
+ * Pure in-memory token check — no I/O on the gated request path, no secret logged.
+ */
+export function requireStepUp(
+  req: Request,
+  url: URL,
+  allowQueryParam = false,
+  opts?: { configured?: () => boolean; valid?: (token: string | null) => boolean },
+): { ok: true } | { ok: false; response: Response } {
+  const isConfigured = opts?.configured ?? (() => isStepUpConfigured());
+  const isValid = opts?.valid ?? ((t: string | null) => isStepUpTokenValid(t));
+  if (!isConfigured()) {
+    // No PIN yet — the UI must set one before this action can proceed.
+    return {
+      ok: false,
+      response: json(
+        {
+          error: "step_up_required",
+          reason: "setup",
+          message: "set a step-up PIN before performing this action",
+        },
+        403,
+      ),
+    };
+  }
+  const token = extractStepUpToken(req, url, allowQueryParam);
+  if (!isValid(token)) {
+    return {
+      ok: false,
+      response: json(
+        {
+          error: "step_up_required",
+          reason: "token",
+          message: "enter your step-up PIN to confirm this action",
+        },
+        403,
+      ),
+    };
+  }
+  return { ok: true };
+}

package/src/daemon.ts

@@ -87,6 +87,8 @@ import {
   requireScope,
   mintSseTicket,
   requireSseTicket,
+  requireStepUp,
+  grantsScope,
   extractToken,
   json as authJson,
   SCOPE_READ,
@@ -95,6 +97,15 @@ import {
   SCOPE_ADMIN,
   SCOPE_TERMINAL,
 } from "./auth.ts";
+import {
+  isStepUpConfigured,
+  isValidPinFormat,
+  setStepUpPin,
+  verifyStepUpPin,
+  mintStepUpToken,
+  stepUpLimiter,
+  StepUpPinFormatError,
+} from "./step-up.ts";
 import { mintTicket } from "./ui-ticket.ts";
 import {
   createTerminalWsHandlers,
@@ -103,6 +114,7 @@ import {
 import { TERMINAL_UI_HTML } from "./terminal-ui.ts";
 import { serveTerminalAsset } from "./terminal-assets.ts";
 import { isSpaPath, serveSpa, spaDistDir } from "./spa-serve.ts";
+import { runBootPreflight, type PreflightResult } from "./preflight.ts";
 import {
   buildSpecFromBody,
   setupProgrammaticSpawn,
@@ -1190,6 +1202,12 @@ export async function authorizeTerminalUpgrade(
   const denied = await requireScope(req, url, SCOPE_TERMINAL, true);
   if (denied) return { ok: false, response: denied };
 
+  // STEP-UP required (agent#80): a terminal is a raw host shell — the single most
+  // dangerous capability. allowQueryParam: true so the WS presents the step-up
+  // token as `?step_up=` (it can't set the `X-Step-Up-Token` header).
+  const step = requireStepUp(req, url, true);
+  if (!step.ok) return { ok: false, response: step.response };
+
   // tmux session name convention: `<name>-agent`. Attach a viewer pty to THIS
   // session; the session itself is created by the spawn path.
   const session = `${agentName}-agent`;
@@ -1294,6 +1312,13 @@ export function createFetchHandler(
       url: string;
       tokenPresent: boolean;
     }>;
+    /**
+     * The boot dependency-PREFLIGHT result (agent#156) — surfaced on `/health` so the
+     * admin UI can show that programmatic turns will fail until the missing deps
+     * (`bwrap`/`rg`/`socat`/`claude`) are installed. `main` passes the boot check;
+     * absent (a plain createFetchHandler / tests) → omitted from `/health`.
+     */
+    preflight?: PreflightResult;
   },
 ): (req: Request, server?: { upgrade: (req: Request, opts: { data: TerminalWsData }) => boolean }) => Promise<Response> {
   // The per-channel turn-event SSE registry — subscribers of the live "watch it
@@ -1486,6 +1511,10 @@ export function createFetchHandler(
     // (`programmatic · idle|working|queued:N`) instead of `mcp_sessions` — a
     // programmatic agent has no live subscriber, so SSE/MCP counts don't describe it.
     if (url.pathname === "/health") {
+      // Surface the boot dependency-preflight (agent#156) so the admin UI can show
+      // that programmatic turns will fail until the missing deps are installed. Only
+      // present when `main` passed the boot check (absent in a plain handler/tests).
+      const preflight = opts?.preflight;
       return json({
         status: "ok",
         channels: [...channels.values()].map((c) => ({
@@ -1504,6 +1533,15 @@ export function createFetchHandler(
             status: s.state === "queued" ? `queued:${s.queued}` : s.state,
           };
         }),
+        ...(preflight
+          ? {
+              dependencies: {
+                ok: preflight.ok,
+                // The binary names missing on PATH — what programmatic turns need installed.
+                missing: preflight.missing.map((d) => d.bin),
+              },
+            }
+          : {}),
       });
     }
 
@@ -1791,6 +1829,169 @@ export function createFetchHandler(
       }
     }
 
+    // ---------------------------------------------------------------------
+    // STEP-UP AUTH (PIN) — second factor for high-privilege actions (agent#80).
+    //
+    // The dangerous `agent:admin` actions (set credentials, open a terminal,
+    // spawn a `filesystem: full` agent) require a step-up token IN ADDITION to
+    // the `agent:admin` Bearer. This block is the PIN setup + exchange surface;
+    // the gating lives at each dangerous endpoint (via `requireStepUp`).
+    //
+    //   GET  /api/step-up          → { configured } — is a PIN set? (UI: setup vs prompt)
+    //   POST /api/step-up { pin }  → validate PIN (rate-limited) → { stepUpToken, expires_at }
+    //   POST /api/step-up/pin { newPin, currentPin? } → set/rotate the PIN
+    //
+    // All `agent:admin`-gated (the operator's cookie-minted Bearer). The PIN is
+    // hashed+salted server-side (step-up.ts); it is NEVER returned or logged.
+    // Externally hub strips `/agent`, so these are `<hub>/agent/api/step-up`.
+    // ---------------------------------------------------------------------
+    if (url.pathname === "/api/step-up" && req.method === "GET") {
+      const denied = await requireScope(req, url, SCOPE_ADMIN);
+      if (denied) return denied;
+      // Whether a PIN is configured — the UI branches setup-flow vs PIN-prompt.
+      return json({ configured: isStepUpConfigured() });
+    }
+
+    if (url.pathname === "/api/step-up" && req.method === "POST") {
+      // Exchange: validate the PIN, then mint a short-lived step-up token. The
+      // session must already hold `agent:admin` (this is a SECOND factor on top,
+      // never a substitute — the token carries no scope of its own).
+      let claims;
+      try {
+        const token = extractToken(req, url);
+        if (!token) return json({ error: "unauthorized", message: "Bearer token required" }, 401);
+        claims = await validateHubJwt(token);
+      } catch (err) {
+        return json(
+          { error: "unauthorized", message: err instanceof Error ? err.message : "invalid token" },
+          401,
+        );
+      }
+      if (!grantsScope(claims.scopes, SCOPE_ADMIN)) {
+        return json(
+          { error: "insufficient_scope", message: `requires ${SCOPE_ADMIN}`, granted: claims.scopes },
+          403,
+        );
+      }
+      // No PIN configured yet — there's nothing to exchange. Tell the UI to run
+      // its first-time setup (distinct from a wrong-PIN 401).
+      if (!isStepUpConfigured()) {
+        return json(
+          { error: "step_up_not_configured", message: "set a step-up PIN first (POST /api/step-up/pin)" },
+          409,
+        );
+      }
+      let body: { pin?: unknown };
+      try {
+        body = (await req.json()) as typeof body;
+      } catch {
+        return json({ error: "invalid JSON body" }, 400);
+      }
+      if (typeof body.pin !== "string" || body.pin.length === 0) {
+        return json({ error: "body.pin (non-empty string) is required" }, 400);
+      }
+      // Rate-limit BEFORE the (expensive, brute-forceable) argon2 verify, keyed by
+      // the operator subject — a stolen-cookie attacker can't grind the PIN. A
+      // DENIED attempt returns 429 (the limiter does not count it again).
+      const limited = stepUpLimiter.checkAndRecord(`step-up:${claims.sub}`);
+      if (!limited.allowed) {
+        return new Response(
+          JSON.stringify({
+            error: "rate_limited",
+            message: "too many PIN attempts — wait before retrying",
+            retry_after_seconds: limited.retryAfterSeconds,
+          }),
+          {
+            status: 429,
+            headers: {
+              "content-type": "application/json",
+              "retry-after": String(limited.retryAfterSeconds ?? 60),
+            },
+          },
+        );
+      }
+      const ok = await verifyStepUpPin(body.pin);
+      if (!ok) {
+        // Wrong PIN — 401. The attempt already counted toward the lockout above.
+        // Never echo the PIN back.
+        return json({ error: "invalid_pin", message: "incorrect PIN" }, 401);
+      }
+      // Correct PIN — clear the attempt bucket (a fresh window for the next time)
+      // and mint a reusable, short-TTL step-up token.
+      stepUpLimiter.clear(`step-up:${claims.sub}`);
+      const { token: stepUpToken, expiresAt } = mintStepUpToken();
+      return json({ stepUpToken, expires_at: new Date(expiresAt).toISOString() });
+    }
+
+    if (url.pathname === "/api/step-up/pin" && req.method === "POST") {
+      // Set (first time) or rotate the step-up PIN. agent:admin-gated; if a PIN
+      // already exists, the CURRENT PIN must be supplied + verified (rotation
+      // needs the old PIN, so a hijacked session can't silently replace it).
+      let claims;
+      try {
+        const token = extractToken(req, url);
+        if (!token) return json({ error: "unauthorized", message: "Bearer token required" }, 401);
+        claims = await validateHubJwt(token);
+      } catch (err) {
+        return json(
+          { error: "unauthorized", message: err instanceof Error ? err.message : "invalid token" },
+          401,
+        );
+      }
+      if (!grantsScope(claims.scopes, SCOPE_ADMIN)) {
+        return json(
+          { error: "insufficient_scope", message: `requires ${SCOPE_ADMIN}`, granted: claims.scopes },
+          403,
+        );
+      }
+      let body: { newPin?: unknown; currentPin?: unknown };
+      try {
+        body = (await req.json()) as typeof body;
+      } catch {
+        return json({ error: "invalid JSON body" }, 400);
+      }
+      if (!isValidPinFormat(body.newPin)) {
+        return json({ error: "body.newPin must be 4–12 digits" }, 400);
+      }
+      // Rotation: a PIN already exists → require + verify the current one (rate-limited).
+      // SHARES the exchange bucket (same `step-up:<sub>` key) on purpose: both verify
+      // the PIN, so an attacker can't get a fresh grind window by alternating endpoints.
+      if (isStepUpConfigured()) {
+        const limited = stepUpLimiter.checkAndRecord(`step-up:${claims.sub}`);
+        if (!limited.allowed) {
+          return new Response(
+            JSON.stringify({
+              error: "rate_limited",
+              message: "too many PIN attempts — wait before retrying",
+              retry_after_seconds: limited.retryAfterSeconds,
+            }),
+            {
+              status: 429,
+              headers: {
+                "content-type": "application/json",
+                "retry-after": String(limited.retryAfterSeconds ?? 60),
+              },
+            },
+          );
+        }
+        if (typeof body.currentPin !== "string" || !(await verifyStepUpPin(body.currentPin))) {
+          return json(
+            { error: "invalid_pin", message: "the current PIN is required to change it" },
+            401,
+          );
+        }
+        stepUpLimiter.clear(`step-up:${claims.sub}`);
+      }
+      try {
+        await setStepUpPin(body.newPin);
+      } catch (err) {
+        if (err instanceof StepUpPinFormatError) return json({ error: err.message }, 400);
+        return json({ error: `failed to set PIN: ${(err as Error).message}` }, 500);
+      }
+      // Echo back only the fact of the write — never the PIN.
+      return json({ ok: true, configured: true });
+    }
+
     // ---------------------------------------------------------------------
     // Claude OAuth credential store (design §6) — the per-channel secret a
     // launched agent session runs on (`CLAUDE_CODE_OAUTH_TOKEN`). Same
@@ -1810,11 +2011,15 @@ export function createFetchHandler(
 
       if (req.method === "GET") {
         // Inspect WITHOUT leaking the secret: whether a default is set + which
-        // channels carry an override (names only).
+        // channels carry an override (names only). A status read — no step-up.
         return json(describeClaudeCredentials(defaultStateDir()));
       }
 
-      // POST — set the default / operator-level token.
+      // POST — set the default / operator-level token. STEP-UP required (agent#80):
+      // setting a credential can exfiltrate the operator's Claude token.
+      const step = requireStepUp(req, url);
+      if (!step.ok) return step.response;
+
       let credBody: { token?: unknown };
       try {
         credBody = (await req.json()) as typeof credBody;
@@ -1837,6 +2042,10 @@ export function createFetchHandler(
     if (credMatch && (req.method === "POST" || req.method === "DELETE")) {
       const denied = await requireScope(req, url, SCOPE_ADMIN);
       if (denied) return denied;
+      // STEP-UP required (agent#80): both set + remove of a per-channel Claude
+      // credential are high-privilege credential-store mutations.
+      const step = requireStepUp(req, url);
+      if (!step.ok) return step.response;
       const channel = decodeURIComponent(credMatch[1]!);
 
       if (req.method === "DELETE") {
@@ -1891,9 +2100,15 @@ export function createFetchHandler(
 
       if (req.method === "GET") {
         // Inspect WITHOUT leaking values: names per channel + the default layer.
+        // A status read — no step-up.
         return json(describeChannelEnv(defaultStateDir()));
       }
 
+      // STEP-UP required (agent#80): set/remove of an env secret (GH_TOKEN,
+      // CLOUDFLARE_API_TOKEN, …) is a credential-store mutation.
+      const step = requireStepUp(req, url);
+      if (!step.ok) return step.response;
+
       let envBody: { channel?: unknown; name?: unknown; value?: unknown };
       try {
         envBody = (await req.json()) as typeof envBody;
@@ -1987,6 +2202,15 @@ export function createFetchHandler(
         throw err;
       }
 
+      // STEP-UP required (agent#80) ONLY for the dangerous filesystem case: a
+      // `filesystem: "full"` agent runs UNSANDBOXED with read access to the whole
+      // disk. Ordinary sandboxed (workspace-confined) spawns stay frictionless —
+      // gate just the high-blast-radius case.
+      if (spec.filesystem === "full") {
+        const step = requireStepUp(req, url);
+        if (!step.ok) return step.response;
+      }
+
       // CHANNEL EXCLUSION: a channel routes inbound to at most one agent. Refuse a
       // spawn for a DIFFERENT programmatic agent onto an already-occupied wake channel
       // (re-spawning the SAME name onto its OWN channel is the idempotent-replace path).
@@ -3030,6 +3254,14 @@ function main(): void {
   mkdirSync(STATE_DIR, { recursive: true });
   mkdirSync(INBOX_DIR, { recursive: true });
 
+  // BOOT DEPENDENCY PREFLIGHT (agent#156). A fresh box can't run a programmatic
+  // `claude -p` turn until bwrap/rg/socat + the claude CLI are on PATH — pre-#156
+  // each surfaced only as a failed *turn*, one at a time. Check them ONCE at boot and
+  // log a single clear warning (with the install one-liners) when any is missing. It's
+  // advisory, never fatal: the daemon may run only attached-backend agents that need
+  // none of these, so we warn + keep serving. The result is also surfaced on /health.
+  const preflight = runBootPreflight();
+
   // Verify the one MCP SDK internal our HTTP-MCP delivery accounting reads
   // (`_streamMapping['_GET_stream']`, see assertMcpSdkStreamContract). A screaming
   // boot error on SDK drift beats discovering it as silent message loss later.
@@ -3146,7 +3378,7 @@ function main(): void {
     buildInstantiateDeps(channels, registry, deliveryState, programmatic, attachedQueue),
   );
 
-  const fetchHandler = createFetchHandler(channels, registry, { deliveryState, programmatic, attachedQueue, turnEvents, jobStore, runner, agentDefs });
+  const fetchHandler = createFetchHandler(channels, registry, { deliveryState, programmatic, attachedQueue, turnEvents, jobStore, runner, agentDefs, preflight });
   const server = Bun.serve<TerminalWsData, never>({
     port: PORT,
     hostname: "127.0.0.1",

package/src/preflight.ts

@@ -0,0 +1,139 @@
+/**
+ * Boot-time dependency PREFLIGHT (agent#156).
+ *
+ * A freshly-provisioned box can't run a programmatic `claude -p` turn until the
+ * sandbox deps (`bwrap`, `rg`, `socat`) AND the `claude` CLI are installed — but
+ * pre-#156 each missing piece surfaced ONLY as a failed *turn*, one at a time, so
+ * an operator discovered them serially (install bwrap → next turn fails on rg →
+ * install rg → next turn fails on claude → …).
+ *
+ * This lifts the check to DAEMON BOOT: resolve each required binary on PATH ONCE
+ * and log a single clear warning naming exactly what's missing + the one-liner to
+ * fix it. It is a WARNING, never a crash — the daemon may run only `attached`-backend
+ * agents (which don't spawn `claude -p` and need no sandbox/claude), so a missing
+ * dep means "programmatic turns will fail until …", not "the daemon can't start."
+ *
+ * Deliberately NOT a full doctor framework — a focused boot preflight + clear log is
+ * the whole of #156. (`spawn-deps.ts`'s turn-time check still stands as the last line
+ * of defence for a dep removed AFTER boot.)
+ */
+
+/**
+ * One required external binary the programmatic backend needs on PATH, with the
+ * one-liner that installs it on a fresh Debian/Ubuntu box (the #156 reproduction).
+ */
+interface RequiredDep {
+  /** The binary name resolved on PATH (`Bun.which`). */
+  bin: string;
+  /** Human label for the warning. */
+  label: string;
+  /** The install hint shown when it's missing. */
+  hint: string;
+  /**
+   * True when this dep is only required on LINUX. On macOS the sandbox uses Seatbelt
+   * (built in, no helper binaries), so the bubblewrap egress-proxy deps (`bwrap`,
+   * `socat`) aren't needed — flagging them on a Mac deploy (the documented preferred
+   * self-host path) would be a false-positive that trains operators to ignore the
+   * preflight. So they're checked on Linux only. (`rg` is NOT linux-only: the runtime's
+   * deny-path scan needs a real ripgrep on macOS too. `claude` is needed everywhere.)
+   */
+  linuxOnly?: boolean;
+}
+
+/**
+ * The deps a programmatic `claude -p` turn needs. `bwrap`/`socat` are the LINUX
+ * bubblewrap sandbox deps the runtime shells out to (bubblewrap is the containment,
+ * socat bridges the egress proxy) — not needed under macOS Seatbelt, so `linuxOnly`.
+ * `rg` (ripgrep) does the deny-path scan on EVERY platform (the macOS sandbox needs a
+ * real `rg` too). `claude` is the CLI the turn runs, required everywhere. The platform
+ * filter is applied in {@link checkProgrammaticDeps}.
+ */
+export const REQUIRED_DEPS: readonly RequiredDep[] = [
+  { bin: "bwrap", label: "bubblewrap (bwrap)", hint: "apt install bubblewrap", linuxOnly: true },
+  { bin: "rg", label: "ripgrep (rg)", hint: "apt install ripgrep" },
+  { bin: "socat", label: "socat", hint: "apt install socat", linuxOnly: true },
+  {
+    bin: "claude",
+    label: "Claude Code CLI (claude)",
+    hint: "curl -fsSL https://claude.ai/install.sh | bash  (native build — no node/npm needed)",
+  },
+] as const;
+
+/** A resolver from binary name → absolute path (or null when not on PATH). Injectable for tests. */
+export type WhichFn = (bin: string) => string | null;
+
+/** The default resolver — Bun.which against the daemon's PATH. */
+export const realWhich: WhichFn = (bin) => Bun.which(bin);
+
+/** Which {@link REQUIRED_DEPS} apply on the given platform (drops `linuxOnly` deps off Linux). */
+export function depsForPlatform(platform: NodeJS.Platform = process.platform): RequiredDep[] {
+  return REQUIRED_DEPS.filter((d) => !d.linuxOnly || platform === "linux");
+}
+
+/** The outcome of {@link checkProgrammaticDeps}: which required deps are missing + a ready-to-log warning. */
+export interface PreflightResult {
+  /** The deps NOT resolvable on PATH (empty = all present). */
+  missing: RequiredDep[];
+  /** True when every required dep resolved (nothing to warn about). */
+  ok: boolean;
+  /**
+   * The formatted multi-line warning to log, or null when nothing is missing. Lists
+   * each missing dep + its install one-liner, framed as "programmatic turns will fail
+   * until …" (attached-backend agents are unaffected).
+   */
+  warning: string | null;
+}
+
+/**
+ * PURE check: resolve each platform-applicable {@link REQUIRED_DEPS} binary via `which`
+ * and build the missing-deps result + warning text. No I/O beyond the injected `which`;
+ * no logging (the caller logs). Cheap + idempotent — safe to call at boot. `platform` is
+ * injectable so a test can assert the macOS filter without running on a Mac.
+ */
+export function checkProgrammaticDeps(
+  which: WhichFn = realWhich,
+  platform: NodeJS.Platform = process.platform,
+): PreflightResult {
+  const missing = depsForPlatform(platform).filter((d) => {
+    try {
+      return !which(d.bin);
+    } catch {
+      // A which() fault is treated as "can't confirm it's present" → report it missing
+      // (better a spurious advisory than silently swallowing a real gap).
+      return true;
+    }
+  });
+  if (missing.length === 0) return { missing: [], ok: true, warning: null };
+  const lines = missing.map((d) => `    - ${d.label}: ${d.hint}`);
+  const warning =
+    `parachute-agent: PREFLIGHT — ${missing.length} dependency/dependencies for programmatic ` +
+    `(claude -p) turns is/are NOT on PATH. Programmatic-backend turns will FAIL until installed ` +
+    `(attached-backend agents are unaffected):\n${lines.join("\n")}`;
+  return { missing, ok: false, warning };
+}
+
+/**
+ * Run the boot preflight: check the deps and LOG the warning once (via `console.warn`)
+ * when anything is missing. Returns the {@link PreflightResult} so the caller can also
+ * surface the missing-deps state elsewhere (e.g. `/health`). Never throws — the daemon
+ * keeps booting regardless.
+ */
+export function runBootPreflight(
+  which: WhichFn = realWhich,
+  platform: NodeJS.Platform = process.platform,
+): PreflightResult {
+  let result: PreflightResult;
+  try {
+    result = checkProgrammaticDeps(which, platform);
+  } catch (err) {
+    // Defensive: the preflight must never break boot. An unexpected fault is reported
+    // HONESTLY (ok:false + the error in the warning) rather than a false "all clear" —
+    // but it's still non-fatal; the daemon boots and the turn-time check in
+    // spawn-deps.ts remains the real guard.
+    const msg = `parachute-agent: boot preflight errored (continuing, dependency state UNKNOWN): ${(err as Error).message}`;
+    console.error(msg);
+    return { missing: [], ok: false, warning: msg };
+  }
+  if (result.warning) console.warn(result.warning);
+  return result;
+}

package/src/spawn-agent.ts

@@ -428,6 +428,22 @@ export function buildAgentChildEnv(
   }
   if (!out.PATH) out.PATH = "/usr/local/bin:/usr/bin:/bin";
 
+  // IS_SANDBOX=1 — signal to claude that it is running INSIDE a sandbox (agent#155).
+  // The programmatic turn always launches inside a bwrap/Seatbelt sandbox (that IS the
+  // containment), so `--dangerously-skip-permissions` is safe — but Claude Code REFUSES
+  // that flag under root/sudo ("cannot be used with root/sudo privileges for security
+  // reasons") UNLESS `IS_SANDBOX` is set, which makes EVERY turn error on a daemon that
+  // runs as root (e.g. the friends/team box). Setting it here makes the fix permanent +
+  // automatic (it was being worked around per-deploy via the env store, which is lost on
+  // reset). It defaults to "1" for every sandboxed turn but honors an explicit operator
+  // value from `channelEnv` (already laid down above) — so an operator who deliberately
+  // sets it can still override. NB: IS_SANDBOX is NOT in SANDBOX_ENV_ALLOWLIST and is not
+  // set by `seedAgentHome`, so it survives `mergeSandboxLaunchEnv` un-clobbered — it can
+  // never be reset to empty by the env-merge layering.
+  if (typeof out.IS_SANDBOX !== "string" || out.IS_SANDBOX.length === 0) {
+    out.IS_SANDBOX = "1";
+  }
+
   // The interactive subscription credential (design §6). Explicitly the ONLY
   // Claude auth var set; ANTHROPIC_API_KEY is intentionally absent. Set LAST so no
   // channel-injected var can ever override the session's managed auth.