@openparachute/agent 0.2.3-rc.6 → 0.2.3-rc.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.3-rc.6",
+  "version": "0.2.3-rc.8",
   "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/daemon.ts

@@ -66,6 +66,7 @@ import {
   DEFAULT_HUB_ORIGIN,
 } from "./def-vaults.ts";
 import { mintScopedToken, vaultScope } from "./mint-token.ts";
+import { registerAllDefVaultTriggers } from "./def-vault-triggers.ts";
 import { GrantsClient } from "./grants.ts";
 import { resolveEffectiveEnv } from "./effective-env.ts";
 import { VaultJobStore, validateJob, vaultTransportFor, type Job } from "./jobs.ts";
@@ -114,6 +115,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,
@@ -1311,6 +1313,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
@@ -1503,6 +1512,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) => ({
@@ -1521,6 +1534,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),
+              },
+            }
+          : {}),
       });
     }
 
@@ -3233,6 +3255,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.
@@ -3349,7 +3379,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",
@@ -3502,6 +3532,29 @@ function main(): void {
     const bindings = await resolveDefVaults({ hubOrigin: getHubOrigin(), managerBearer });
     for (const b of bindings) agentDefs.addVault(b);
     if (bindings.length === 0) return; // nothing bound — vault-native path idle.
+
+    // AUTO-REGISTER the per-def-vault runtime triggers (agent#157) so "define an
+    // agent → it runs" needs NO manual trigger setup + NO restart-to-pick-up:
+    //   - the def-watch create/edit triggers, BARE-keyed (`agent/definition`) so a
+    //     created/edited def auto-fires the rescan — upsert-by-name REPLACES any
+    //     stale `#agent/definition`-keyed `conn_agentdefs-*` row the hub provisioned;
+    //   - the inbound trigger (`agent/message/inbound` + has_metadata:[agent]) so a
+    //     new inbound note wakes the agent without a hand-registered trigger.
+    // Mints the admin (triggers API) + agent:send (webhook bearer) tokens the same
+    // way the hub's Connections engine does (attenuated to the operator bearer).
+    // Best-effort: a mint refusal / unreachable vault is logged, never fatal — the
+    // 60s loadAll poll below stays the correctness floor. Skipped with no operator
+    // bearer (can't mint) — the vault-native path still runs own-vault.
+    if (managerBearer) {
+      await registerAllDefVaultTriggers(bindings, { hubOrigin: getHubOrigin(), managerBearer }).catch(
+        (err) => {
+          console.warn(
+            `parachute-agent: def-vault trigger auto-registration failed (continuing): ${(err as Error).message}`,
+          );
+        },
+      );
+    }
+
     const n = await agentDefs.loadAll();
     console.log(
       `parachute-agent: vault-native agent defs — ${n} instantiated from ${bindings.length} def-vault(s).`,

package/src/def-vault-triggers.ts

@@ -0,0 +1,317 @@
+/**
+ * Auto-register the per-def-vault runtime triggers the daemon needs so that
+ * "just define an agent in the vault and it works" — no manual trigger setup, no
+ * `parachute restart agent` to pick up a new/edited def (agent#157).
+ *
+ * Two wiring gaps this closes:
+ *
+ *  1. **Def-watch triggers were stale `#`-keyed.** A def-vault carried
+ *     `conn_agentdefs-create-<vault>` / `conn_agentdefs-edit-<vault>` triggers
+ *     keyed on the PRE-canonicalization tag `#agent/definition`. Since defs are
+ *     now bare `agent/definition`, those triggers never fired → creating/editing
+ *     a def did NOT auto-rescan; only the 60s `loadAll` poll converged it. We
+ *     re-register them BARE-keyed on (re)start, upsert-by-name, so the stale
+ *     `#`-keyed rows are REPLACED in place (the runtime triggers API is an upsert
+ *     by `name`, and we reuse the hub's `conn_agentdefs-{create,edit}-<vault>`
+ *     names so our POST overwrites the hub-provisioned ones).
+ *
+ *  2. **The inbound trigger was never auto-registered.** Defining a def + the
+ *     daemon discovering it (the channel appears) is NOT enough — nothing wakes
+ *     the agent until an `agent_inbound` trigger fires the inbound webhook. The
+ *     hub provisioned it only via the operator's explicit "Connect" click (or the
+ *     hub Connections builder); a fresh box needed it registered BY HAND. We now
+ *     register ONE inbound trigger per def-vault on (re)start (one trigger routes
+ *     ALL agents in the vault by `metadata.agent`).
+ *
+ * ## How this mirrors the hub's provisioning path
+ *
+ * The hub's Connections engine (`parachute-hub/src/admin-connections.ts`) already
+ * registers these triggers by:
+ *   - minting a `vault:<v>:admin` token (the triggers API is ADMIN-scoped — a
+ *     webhook trigger exfiltrates note data, so even listing is admin, not write),
+ *   - minting an `agent:send` webhook bearer for `action.auth.bearer`,
+ *   - POSTing `{ name, events, when, action }` to
+ *     `<vaultUrl>/vault/<v>/api/triggers` (upsert by name),
+ *   - naming the def-watch triggers `conn_agentdefs-{create,edit}-<vault>`.
+ *
+ * We do the SAME thing, daemon-side, on boot — reusing the daemon's own
+ * `mintScopedToken` (attenuated to the operator bearer) for BOTH mints. This is
+ * the credential the hub uses too; the daemon already holds the operator bearer
+ * (it mints the def-vault `vault:<v>:write` token the same way), so the admin mint
+ * succeeds exactly when the operator's authority covers it.
+ *
+ * ## Scope caveat (admin mint)
+ *
+ * The triggers API requires `vault:<v>:admin`. The def-vault token the daemon
+ * persists in `agent-vaults.json` is only `vault:<v>:write`, so we CANNOT register
+ * triggers with that token — we MINT a short-lived `vault:<v>:admin` token against
+ * the operator bearer instead. If the operator bearer's own authority doesn't cover
+ * `vault:<v>:admin`, the hub returns `invalid_scope` on the mint (the same bound the
+ * hub's own provisioning hits) — we log + skip, never crash boot. The 60s `loadAll`
+ * poll remains the correctness floor either way.
+ *
+ * ## Webhook URL
+ *
+ * The webhook points at `<hub-origin>/agent/api/vault/{inbound,agent-def}` — the
+ * hub origin + the agent module's `/agent` proxy mount + the action endpoint
+ * (mirrors the hub's `buildWebhook` and the `AGENT_*_VAULT_TRIGGER_TEMPLATE`
+ * placeholders). The hub reverse-proxies `/agent/*` to the loopback daemon, so
+ * this works co-located AND exposed; and the daemon validates the webhook bearer's
+ * `iss` against the hub origin anyway, so the hub origin is the right base.
+ *
+ * Best-effort throughout: every failure is caught + logged, never thrown — a
+ * def-vault with no admin authority (or an unreachable vault) must never block the
+ * daemon from serving, and the poll fallback covers reactivity.
+ */
+
+import type { DefVaultBinding } from "./agent-defs.ts";
+import { mintScopedToken, vaultScope, MintError } from "./mint-token.ts";
+import { DEFAULT_DEF_VAULT_URL } from "./def-vaults.ts";
+import { AGENT_VAULT_TRIGGER_TEMPLATE } from "./transports/vault.ts";
+
+/** The bare def-discriminator tag the def-watch triggers filter on (post-canonicalization). */
+export const DEFINITION_TAG = "agent/definition";
+/**
+ * The inbound trigger's `when` predicate. SOURCED from the existing
+ * {@link AGENT_VAULT_TRIGGER_TEMPLATE} (`src/transports/vault.ts`) — the
+ * module-owned shape the hub already substitutes — so the daemon's
+ * auto-registration produces a SEMANTICALLY IDENTICAL trigger to the
+ * hub-Connections path (bare `agent/message/inbound` tag, `has_metadata:[agent]`,
+ * `missing_metadata:[channel_inbound_rendered_at]`). Reusing the one source of
+ * truth keeps the two registration paths from drifting on the field names.
+ *
+ * (The real loop guard is the vault engine's own `<triggerName>_rendered_at`
+ * marker, checked unconditionally regardless of `missing_metadata`. The
+ * `missing_metadata` clause is the module-owned belt — kept identical so both
+ * paths upsert cleanly over the same trigger.)
+ */
+const INBOUND_WHEN = AGENT_VAULT_TRIGGER_TEMPLATE.when;
+/** The bare inbound-message child tag the inbound trigger fires on (from the template). */
+export const INBOUND_TAG = INBOUND_WHEN.tags[0];
+
+/** The `agent:send` scope minted for every webhook `action.auth.bearer`. */
+const WEBHOOK_SCOPE = "agent:send";
+/** Short TTL for the throwaway `vault:<v>:admin` registration token. */
+const ADMIN_MINT_TTL_SECONDS = 60;
+
+/**
+ * The shape POSTed to `<vaultUrl>/vault/<v>/api/triggers`. The vault validates
+ * `events` ⊆ {created, updated} (NO `deleted` — so the def-watch is two triggers,
+ * create + edit, not one create/updated/deleted trigger).
+ */
+export interface VaultTriggerInput {
+  name: string;
+  events: Array<"created" | "updated">;
+  when: {
+    tags: string[];
+    has_metadata?: string[];
+    missing_metadata?: string[];
+  };
+  action: {
+    webhook: string;
+    send: "json";
+    auth?: { bearer: string };
+  };
+}
+
+/**
+ * The stable def-watch trigger name for a (vault, kind). MUST match the hub's
+ * `conn_${defReloadId(vault, kind)}` (web/ui/src/lib/hub.ts → `agentdefs-<kind>-<vault>`,
+ * hub admin-connections → `conn_<id>`) so our upsert REPLACES any stale `#`-keyed
+ * trigger the hub provisioned, rather than orphaning it alongside a new one.
+ */
+export function defWatchTriggerName(vault: string, kind: "create" | "edit"): string {
+  return `conn_agentdefs-${kind}-${vault}`;
+}
+
+/**
+ * The inbound trigger name for a vault. ONE per def-vault — it routes ALL agents
+ * by `metadata.agent`, so it isn't per-agent. Stable so the POST upserts in place.
+ */
+export function inboundTriggerName(vault: string): string {
+  return `conn_agentinbound-${vault}`;
+}
+
+/** Build the webhook URL `<hub-origin>/agent/api/vault/<endpoint>`. */
+function buildWebhook(hubOrigin: string, endpoint: string): string {
+  const origin = hubOrigin.replace(/\/+$/, "");
+  const ep = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+  return `${origin}/agent${ep}`;
+}
+
+/**
+ * The three triggers a def-vault needs, bare-keyed, with the webhook bearer filled.
+ * Exported for tests (asserts the bare tag + the trigger shapes without the live mints).
+ */
+export function buildDefVaultTriggers(
+  vault: string,
+  hubOrigin: string,
+  webhookBearer: string,
+): VaultTriggerInput[] {
+  const defWebhook = buildWebhook(hubOrigin, "/api/vault/agent-def");
+  const inboundWebhook = buildWebhook(hubOrigin, "/api/vault/inbound");
+  const auth = { bearer: webhookBearer };
+  return [
+    // Def-watch CREATE — a new bare `agent/definition` note instantiates its agent live.
+    {
+      name: defWatchTriggerName(vault, "create"),
+      events: ["created"],
+      when: { tags: [DEFINITION_TAG] },
+      action: { webhook: defWebhook, send: "json", auth },
+    },
+    // Def-watch EDIT — an edited bare `agent/definition` note re-instantiates its agent.
+    {
+      name: defWatchTriggerName(vault, "edit"),
+      events: ["updated"],
+      when: { tags: [DEFINITION_TAG] },
+      action: { webhook: defWebhook, send: "json", auth },
+    },
+    // INBOUND — a new bare `agent/message/inbound` note (routed by metadata.agent,
+    // not yet rendered) wakes the agent. One trigger routes every agent in the vault.
+    // `when` is the module-owned shape from AGENT_VAULT_TRIGGER_TEMPLATE (copied so
+    // the predicate matches the hub-Connections path exactly).
+    {
+      name: inboundTriggerName(vault),
+      events: ["created"],
+      when: {
+        tags: [...INBOUND_WHEN.tags],
+        has_metadata: [...INBOUND_WHEN.has_metadata],
+        missing_metadata: [...INBOUND_WHEN.missing_metadata],
+      },
+      action: { webhook: inboundWebhook, send: "json", auth },
+    },
+  ];
+}
+
+/** Dependencies for {@link registerDefVaultTriggers} (injected for tests). */
+export interface RegisterTriggersDeps {
+  /** Hub public origin (the webhook base + the mint endpoint + the JWT `iss`). */
+  hubOrigin: string;
+  /** The operator bearer the per-resource mints attenuate against. */
+  managerBearer: string;
+  /** Inject fetch for tests. Defaults to global fetch. */
+  fetchFn?: typeof fetch;
+}
+
+/** The outcome of registering one def-vault's triggers (for logging/tests). */
+export interface RegisterTriggersResult {
+  vault: string;
+  /** Trigger names that registered (HTTP 200). */
+  registered: string[];
+  /** `name: reason` for each failure (mint refusal, vault non-2xx, fetch error). */
+  failures: string[];
+}
+
+/**
+ * Register (idempotent upsert) the def-watch + inbound triggers for ONE def-vault.
+ * Mints a `vault:<v>:admin` token for the triggers API and an `agent:send` token
+ * for the webhook bearer, then POSTs each trigger. Best-effort: never throws — a
+ * mint refusal (insufficient operator authority) or an unreachable vault is logged
+ * and returned in `failures`. The poll fallback is the correctness floor.
+ */
+export async function registerDefVaultTriggers(
+  binding: DefVaultBinding,
+  deps: RegisterTriggersDeps,
+): Promise<RegisterTriggersResult> {
+  const vault = binding.vault;
+  const vaultUrl = (binding.vaultUrl ?? DEFAULT_DEF_VAULT_URL).replace(/\/+$/, "");
+  const fetchFn = deps.fetchFn ?? fetch;
+  const result: RegisterTriggersResult = { vault, registered: [], failures: [] };
+
+  const mintDeps = {
+    hubOrigin: deps.hubOrigin,
+    managerBearer: deps.managerBearer,
+    ...(deps.fetchFn ? { fetchFn: deps.fetchFn } : {}),
+  };
+
+  // 1. Mint the ADMIN token for the triggers API FIRST (the def-vault write token
+  //    can't register triggers — admin-scoped endpoint). This is the mint most
+  //    likely to be refused (a `vault:<v>:write`-only operator can't mint admin), so
+  //    minting it first short-circuits a restricted install before the second mint.
+  //    On `invalid_scope` the hub refuses here — log + skip, never crash boot.
+  let adminToken: string;
+  try {
+    const minted = await mintScopedToken(
+      { scope: vaultScope(vault, "admin"), expiresIn: ADMIN_MINT_TTL_SECONDS },
+      mintDeps,
+    );
+    adminToken = minted.token;
+  } catch (err) {
+    const detail = err instanceof MintError ? err.message : (err as Error).message;
+    result.failures.push(`mint ${vaultScope(vault, "admin")}: ${detail}`);
+    return result; // No admin token → can't POST triggers.
+  }
+
+  // 2. Mint the webhook bearer (agent:send) — the trigger fires this at the daemon.
+  //    Long-lived (the hub's default ~90d, matching the hub's own provisioning) since
+  //    it lives in the trigger's persistent `action.auth.bearer`; re-minted on each
+  //    restart's re-registration. A refusal here also skips (no bearer → no trigger).
+  let webhookBearer: string;
+  try {
+    const minted = await mintScopedToken({ scope: WEBHOOK_SCOPE }, mintDeps);
+    webhookBearer = minted.token;
+  } catch (err) {
+    const detail = err instanceof MintError ? err.message : (err as Error).message;
+    result.failures.push(`mint ${WEBHOOK_SCOPE}: ${detail}`);
+    return result; // No bearer → no trigger can be registered.
+  }
+
+  // 3. POST each trigger (upsert by name).
+  const triggers = buildDefVaultTriggers(vault, deps.hubOrigin, webhookBearer);
+  const url = `${vaultUrl}/vault/${vault}/api/triggers`;
+  for (const trigger of triggers) {
+    try {
+      const res = await fetchFn(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${adminToken}`,
+        },
+        body: JSON.stringify(trigger),
+      });
+      if (res.ok) {
+        result.registered.push(trigger.name);
+      } else {
+        const detail = await res.text().catch(() => "");
+        result.failures.push(`${trigger.name}: HTTP ${res.status} ${detail}`.trim());
+      }
+    } catch (err) {
+      result.failures.push(`${trigger.name}: ${(err as Error).message}`);
+    }
+  }
+  return result;
+}
+
+/**
+ * Register triggers for EVERY def-vault binding. Best-effort + sequential (a
+ * handful of vaults at most); a per-vault failure never blocks the others. Logs a
+ * one-line summary per vault. Returns the per-vault results (for tests).
+ */
+export async function registerAllDefVaultTriggers(
+  bindings: DefVaultBinding[],
+  deps: RegisterTriggersDeps,
+): Promise<RegisterTriggersResult[]> {
+  const results: RegisterTriggersResult[] = [];
+  for (const binding of bindings) {
+    const r = await registerDefVaultTriggers(binding, deps).catch(
+      (err): RegisterTriggersResult => ({
+        vault: binding.vault,
+        registered: [],
+        failures: [`unexpected: ${(err as Error).message}`],
+      }),
+    );
+    results.push(r);
+    if (r.failures.length === 0) {
+      console.log(
+        `parachute-agent: def-vault "${r.vault}" — auto-registered ${r.registered.length} trigger(s) ` +
+          `(def-watch create/edit + inbound, bare-keyed).`,
+      );
+    } else {
+      console.warn(
+        `parachute-agent: def-vault "${r.vault}" — registered ${r.registered.length}, ` +
+          `${r.failures.length} failed (continuing; the 60s poll is the correctness floor): ${r.failures.join("; ")}`,
+      );
+    }
+  }
+  return results;
+}

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.