pi-openappa 0.3.0 → 0.3.1

package/README.md

@@ -14,8 +14,9 @@ pi event ◀── enforce  ◀── decision  ◀─────────
 
 ## Requirements
 
-- The `appa` binary on `PATH` ([install](https://openappa.com)) — version
-  0.31.x verified; see `docs/wire-notes.md` for the recorded contract
+- The `appa` binary on `PATH`: `curl -fsSL https://openappa.com/install.sh | sh`
+  (the extension installs it automatically when missing) — version 0.31.x
+  verified; see `docs/wire-notes.md` for the recorded contract
 - An APPA runtime listening on loopback (default `127.0.0.1:8787`)
 - A policy (`appa.toml`) that declares the tools your sessions may use —
   `/appa init` writes a starter one, or copy `templates/appa.toml`
@@ -23,53 +24,84 @@ pi event ◀── enforce  ◀── decision  ◀─────────
 ## Install
 
 ```sh
-pi install npm:pi-openappa        # once published
+pi install npm:pi-openappa        # published on npm; indexed by the Pi gallery
 pi install ./pi-openappa          # from a checkout
 ```
 
+## Smoke test
+
+Ship and verify in one pass:
+
+```sh
+just deploy                        # sync the lockfile, run checks, npm publish
+just remove                        # drop a local-checkout install, if present
+pi install npm:pi-openappa         # install the published package
+pi                                 # any session: protection on, appa auto-installs
+appa --version                     # OK — the runtime is on PATH
+```
+
+`pi install` only registers the package — extension code runs when a session
+starts, so `appa` appears after that first session, not before.
+
 ## Protect sessions
 
-Protection is opt-in, in one of three ways:
+Protection is **on by default**: every Pi session is guarded unless you opt
+out. Opt-outs, most specific first:
 
-- **Project-scoped (recommended):** create `<project>/.pi/openappa` — sessions
-  started in that directory are protected, sessions elsewhere are not. The
-  marker's optional content names that project's policy (absolute or
-  cwd-relative); empty content falls back to `APPA_CONFIG` or APPA's default:
+- **Per launch:** `APPA_GATE=0 pi` (and `APPA_GATE=1 pi` to force it on).
+- **Per project:** create `<project>/.pi/no-openappa` — sessions started in
+  that directory run unguarded.
+- **Globally:** `/appa off` once (marker `~/.config/pi-openappa/off`) — every
+  session everywhere runs unguarded until `/appa on`.
+
+The project marker `<project>/.pi/openappa` names that project's policy
+(absolute or cwd-relative) and re-enables protection even when globally off;
+empty content falls back to `APPA_CONFIG` or APPA's default:
 
   ```sh
   cd your-project && mkdir -p .pi && echo "appa.toml" > .pi/openappa
   ```
 
-- **Built-in:** run `/appa on` once — every Pi session everywhere is
-  protected. `/appa off` disables.
-- **Per launch:** `APPA_GATE=1 pi` (the `clappa`-style launcher route).
-
-A gated session brings the runtime up on its own: `session_start` sends
+A protected session brings the runtime up on its own: `session_start` sends
 `appa hook --ensure-runtime` (passing `--config` when a policy is resolved),
 but **does not wait for it** — the boot runs on a serialized background lane,
-so a cold runtime, a first-run install, or a slow start never sits in Pi's
-session-start path. Ordering is preserved: the SessionStart payload always
-lands before the first `PreToolUse`, and a runtime that cannot answer fails
-that first call closed with the reason (silence never means yes). A custom
+so a cold runtime, a first-run auto-install, or a slow start never sits in
+Pi's session-start path. Ordering is preserved: the SessionStart payload
+always lands before the first `PreToolUse`, and a runtime that cannot
+answer fails that first call closed with the reason (silence never means
+yes). A custom
 `APPA_RUNTIME_URL` names a runtime that is *yours* to start — the hook
 refuses with exactly that reason instead of guessing.
 
-While gated, a runtime that cannot answer blocks the call and the reason is
-returned to the model — **silence never means yes**. If no policy exists the
-startup warning names the exact outs; `/appa off` always works, even with
-every tool call blocked. Ungated sessions never invoke the hook.
+When the default `appa` is missing from `PATH`, a protected session installs
+it itself — once, with a UI notice — by running the same official script
+(`curl -fsSL https://openappa.com/install.sh | sh`), then retries starting
+the runtime. Sessions that name a custom `APPA_HOOK_BIN` are never
+auto-installed.
+
+While protected, a runtime that cannot answer blocks the call and the reason
+is returned to the model — **silence never means yes**; `/appa off` always
+works, even with every tool call blocked. One exception: with **no policy
+anywhere** (`APPA_CONFIG`, marker content, and `~/.config/appa/appa.toml` all
+absent) and no runtime answering, the session runs **unprotected** with one
+startup warning naming the fixes — an unconfigured guard must not lock you
+out of your own machine. A named policy that fails stays fail-closed.
+Opted-out sessions never invoke the hook.
 
 ## Configuration
 
 | Source | Default | Meaning |
 |---|---|---|
-| `APPA_GATE` | unset | `1` protects this session (read once at launch) |
-| `.pi/openappa` | absent | Project marker: gates sessions started in that directory; optional content = policy path |
+| `APPA_GATE` | unset | `1` forces protection on for this launch; `0` forces it off |
+| `.pi/openappa` | absent | Project marker: names that project's policy and forces protection on |
+| `.pi/no-openappa` | absent | Project opt-out: sessions started there run unguarded |
 | `~/.config/pi-openappa/settings.json` | absent | File settings: `config`, `runtimeUrl`, `hookBin`, `hookTimeoutMs`; env always wins, project markers beat `config` |
 | `APPA_RUNTIME_URL` | `http://127.0.0.1:8787` | Runtime endpoint (loopback only) |
 | `APPA_CONFIG` | unset | `appa.toml` the session auto-starts the runtime with |
 | `APPA_HOOK_BIN` | `appa` | Hook binary to invoke |
+| `APPA_INSTALL_CMD` | `curl -fsSL https://openappa.com/install.sh \| sh` | Auto-install command for a missing default `appa` (pin a mirror or offline copy) |
 | `APPA_HOOK_TIMEOUT_MS` | `15000` | Kill the hook after this long; the call is then blocked |
+| `APPA_INSTALL_TIMEOUT_MS` | `120000` | Kill a stuck auto-install after this long |
 
 Policy resolution order: `APPA_CONFIG`, then the project marker's content,
 then `settings.json`'s `config`, then APPA's own default
@@ -123,9 +155,9 @@ JSON value per line / `}` / `expect allow|withhold|deny`); calls in one
 file share a trajectory, so taint accumulates exactly as live. All three
 gates run in `just check`.
 
-`/appa` reports protection, always-on state, and runtime health; `/appa on`
-and `/appa off` toggle always-on protection (marker:
-`~/.config/pi-openappa/always-on`), taking effect immediately including the
+`/appa` reports protection, opt-out state, and runtime health; `/appa off`
+disables protection globally (marker `~/.config/pi-openappa/off`) and
+`/appa on` re-enables it, taking effect immediately including the
 current session.
 
 ## Event mapping
@@ -156,7 +188,14 @@ policies declare them verbatim.
 - **Subagents**: spawning is mediated as a plain tool call (deny blocks the
   spawn). Child trajectories are not linked into the parent's label chain
   yet; a gated child Pi process opens its own root trajectory.
-- The adapter never starts a runtime for ungated sessions; auto-start needs
+- **On by default**: installing this extension guards every session and may
+  download and run openappa.com's install script once on first run. The
+  opt-outs above and `APPA_INSTALL_CMD` are the escapes.
+- **Auto-install is `curl \| sh`**: a protected session with the default
+  binary missing downloads and runs the script with user privileges, at most
+  once per session start. Pre-install `appa` or pin `APPA_INSTALL_CMD` to
+  avoid it.
+- The adapter never starts a runtime for opted-out sessions; auto-start needs
   either `APPA_CONFIG` or an installed APPA deployment.
 - OpenAPPA is Preview & RFC: wire surfaces may break without shims. The
   entire wire contract lives in `src/hook-client.ts` and `src/adapter.ts`

package/extensions/index.ts

@@ -3,9 +3,11 @@
  *
  * Thin by design: translate Pi events to `appa hook` invocations and enforce
  * the answer. No policy logic lives here; the APPA runtime owns every
- * decision. Protection is opt-in per session (APPA_GATE=1 at launch, a
- * project marker, or always-on) and fail-closed while gated: if the runtime
- * cannot answer, the call is blocked.
+ * decision. Protection is ON by default (opt out with APPA_GATE=0, a project
+ * `.pi/no-openappa` marker, or `/appa off`) and fail-closed while gated: if
+ * the runtime cannot answer, the call is blocked. A missing `appa` binary
+ * self-installs once on the background lane; a first run with no policy
+ * anywhere and no runtime runs the session unprotected with one warning.
  *
  * Wire facts and constraints: docs/wire-notes.md
  */
@@ -24,13 +26,15 @@ import {
   stopPayload,
   toolResponseFrom,
 } from "../src/adapter.ts";
+import { invokeAppaHook, resolveHookBin } from "../src/hook-client.ts";
 import type { InvokeOptions } from "../src/hook-client.ts";
-import { invokeAppaHook } from "../src/hook-client.ts";
+import { installAppa, type InstallOutcome } from "../src/installer.ts";
 import {
   appaDefaultConfigPath,
+  appaDefaultPolicyExists,
   captureGate,
   checkHealth,
-  setAlwaysOn,
+  setGloballyOff,
   settingsPath,
   type GateState,
 } from "../src/gate.ts";
@@ -52,6 +56,8 @@ export default function (pi: ExtensionAPI): void {
   /** Launch-fixed protection state; null until the session starts. */
   let gate: GateState | null = null;
   let sessionId = "";
+  /** No policy anywhere and nothing answered: this session runs unprotected. */
+  let unprotected = false;
   /**
    * toolCallId → the exact `input` object sent in the PreToolUse payload.
    * PostToolUse must echo it byte-identically or the runtime withholds the
@@ -64,9 +70,10 @@ export default function (pi: ExtensionAPI): void {
    * through here in order, so the SessionStart payload (with
    * `--ensure-runtime`) always lands before the first PreToolUse even though
    * session_start does not wait for it. Startup stays off the fast-start
-   * lane: the runtime boot cost is paid by whichever tool call needs the
-   * runtime first, and a runtime that cannot answer fails that call closed
-   * with the reason — never a slower session start.
+   * lane: the runtime boot — and a first run's auto-install — is paid by
+   * whichever tool call needs the runtime first, and a runtime that cannot
+   * answer fails that call closed with the reason — never a slower session
+   * start.
    */
   let lane: Promise<unknown> = Promise.resolve();
   const enqueue = <T>(run: () => Promise<T>): Promise<T> => {
@@ -78,7 +85,7 @@ export default function (pi: ExtensionAPI): void {
     return outcome;
   };
 
-  const gated = (): boolean => gate?.gated === true;
+  const gated = (): boolean => gate?.gated === true && !unprotected;
 
   const hookOptions = (state: GateState, extra: InvokeOptions = {}): InvokeOptions => {
     const options: InvokeOptions = { ...extra };
@@ -89,30 +96,88 @@ export default function (pi: ExtensionAPI): void {
   pi.on("session_start", async (event, ctx) => {
     gate = captureGate(process.env, ctx.cwd);
     sessionId = ctx.sessionManager.getSessionId();
-    if (!gated()) return;
+    if (!gate.gated) return;
+    unprotected = false;
     const state = gate;
     const options: InvokeOptions = { ensureRuntime: true };
     if (state.config !== undefined) options.config = state.config;
     if (state.hookTimeoutMs !== undefined) options.timeoutMs = state.hookTimeoutMs;
     // Backgrounded on purpose (see `lane`): a cold runtime boot — or a first
-    // run that still has to install or update the runtime — must not sit in
-    // Pi's session-start path. Failure surfaces as a warning when it settles.
+    // run that still has to install the runtime — must not sit in Pi's
+    // session-start path. Auto-install, the retry, and the first-run
+    // unprotected decision all run serialized on the lane; failure surfaces
+    // as a warning when it settles.
     void enqueue(async () => {
-      const outcome = await invokeAppaHook(
-        sessionStartPayload(sessionId, event.reason, ctx.cwd),
-        options,
-      );
-      if (outcome.exitCode !== 0 && ctx.hasUI) {
-        const remedy =
-          options.config === undefined
-            ? " Provide a policy (this project's .pi/openappa, /appa init, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
-            : "";
-        ctx.ui.notify(
-          `OpenAPPA gated but the runtime did not answer (${state.runtimeUrl}): ` +
-            `${outcome.stderr.trim() || `exit ${outcome.exitCode}`}.${remedy} ` +
-          "Tool calls will be blocked until it answers.",
-          "warning",
+      const notify = (message: string, kind: "info" | "warning"): void => {
+        if (ctx.hasUI) ctx.ui.notify(message, kind);
+      };
+      const payload = sessionStartPayload(sessionId, event.reason, ctx.cwd);
+      let outcome = await invokeAppaHook(payload, options);
+      let warnedAlready = false;
+      // A missing default `appa` is self-provisioned: run the official install
+      // script once, then retry bringing the runtime up. Custom APPA_HOOK_BINs
+      // are the user's own and never auto-installed.
+      if (outcome.binaryMissing && resolveHookBin(process.env) === "appa") {
+        notify(
+          "`appa` was not found — installing the OpenAPPA runtime " +
+            "(https://openappa.com/install.sh)…",
+          "info",
         );
+        const install = await installAppa();
+        if (install.exitCode !== 0) {
+          warnedAlready = true;
+          notify(
+            `OpenAPPA auto-install failed: ${outcomeTail(install)}. ` +
+              "Tool calls stay blocked; install `appa` manually (see the README) or run /appa off.",
+            "warning",
+          );
+        } else {
+          const retry = await invokeAppaHook(payload, options);
+          if (retry.binaryMissing) {
+            warnedAlready = true;
+            notify(
+              "OpenAPPA auto-install finished but `appa` is still not on PATH. " +
+                `Installer output: ${outcomeTail(install)} — restart the session once PATH has it.`,
+              "warning",
+            );
+          }
+          outcome = retry;
+        }
+      }
+      if (outcome.exitCode !== 0) {
+        // No policy anywhere and nothing answering: run this session
+        // unprotected with one warning instead of fail-closed (the configured
+        // default). A named policy that fails stays fail-closed below.
+        if (
+          resolveHookBin(process.env) === "appa" &&
+          state.config === undefined &&
+          !appaDefaultPolicyExists(process.env) &&
+          !(await checkHealth(state.runtimeUrl)).ok
+        ) {
+          unprotected = true;
+          if (!warnedAlready) {
+            notify(
+              "OpenAPPA is on by default, but no policy exists (run /appa init, " +
+                "or set APPA_CONFIG, .pi/openappa, or ~/.config/appa/appa.toml) and no runtime answers " +
+                `at ${state.runtimeUrl} — this session runs unprotected. ` +
+                "Write a policy, or run /appa off.",
+              "warning",
+            );
+          }
+          return;
+        }
+        if (ctx.hasUI && !warnedAlready) {
+          const remedy =
+            state.config === undefined
+              ? " Provide a policy (this project's .pi/openappa, /appa init, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
+              : "";
+          ctx.ui.notify(
+            `OpenAPPA gated but the runtime did not answer (${state.runtimeUrl}): ` +
+              `${outcome.stderr.trim() || `exit ${outcome.exitCode}`}.${remedy} ` +
+              "Tool calls will be blocked until it answers.",
+            "warning",
+          );
+        }
       }
     });
   });
@@ -182,15 +247,15 @@ export default function (pi: ExtensionAPI): void {
 
   pi.registerCommand("appa", {
     description:
-      "OpenAPPA guard: status, `appa on|off` always-on, `appa init [project]` writes a starter policy",
+      "OpenAPPA guard: status, `appa on|off` global toggle, `appa init [project]` writes a starter policy",
     getArgumentCompletions: (argumentPrefix) => {
       const items = [
         {
           value: "on",
           label: "on",
-          description: "Protect every future Pi session (always-on marker)",
+          description: "Re-enable default-on protection for every session",
         },
-        { value: "off", label: "off", description: "Disable always-on protection" },
+        { value: "off", label: "off", description: "Disable protection globally (/appa on re-enables)" },
         {
           value: "init",
           label: "init",
@@ -212,13 +277,13 @@ export default function (pi: ExtensionAPI): void {
       const arg = tokens[0] ?? "";
 
       if (arg === "on" || arg === "off") {
-        setAlwaysOn(process.env, arg === "on");
+        setGloballyOff(process.env, arg === "off");
         gate = captureGate(process.env, ctx.cwd);
         if (ctx.hasUI) {
           ctx.ui.notify(
             arg === "on"
-              ? "OpenAPPA always-on enabled: every future Pi session is protected."
-              : "OpenAPPA always-on disabled.",
+              ? "OpenAPPA protection re-enabled: on by default for every session."
+              : "OpenAPPA protection disabled globally (/appa on re-enables).",
             "info",
           );
         }
@@ -236,14 +301,21 @@ export default function (pi: ExtensionAPI): void {
       const mode =
         state.source === "project"
           ? "project (.pi/openappa)"
-          : state.source === "env"
+          : state.source === "env-on"
             ? "launch (APPA_GATE=1)"
-            : state.source === "always-on"
-              ? "always-on (/appa off to disable)"
-              : "off — /appa on enables it for every session";
+            : state.source === "env-off"
+              ? "launch opt-out (APPA_GATE=0)"
+              : state.source === "project-off"
+                ? "project opt-out (.pi/no-openappa)"
+                : state.source === "global-off"
+                  ? "global opt-out (/appa on re-enables)"
+                  : "on by default (/appa off disables)";
       const lines: string[] = [];
       lines.push(state.gated ? `Protection: ON (session ${sessionId || "not started"})` : `Protection: off — ${mode}`);
-      if (state.gated) lines.push(`Mode: ${mode}`);
+      if (unprotected) {
+        lines.push("Session: unprotected — no policy found; see the startup warning.");
+      }
+      if (state.gated && !unprotected) lines.push(`Mode: ${mode}`);
       if (state.config !== undefined) lines.push(`Policy: ${state.config}`);
       lines.push(`Runtime: ${state.runtimeUrl}`);
       const health = await checkHealth(state.runtimeUrl);
@@ -303,7 +375,7 @@ export default function (pi: ExtensionAPI): void {
         writeFileSync(settings, `${JSON.stringify({ config: policy }, null, 2)}\n`);
         lines.push(`Wrote ${settings} pointing at it.`);
       }
-      lines.push("Protect sessions with /appa on, APPA_GATE=1, or /appa init project.");
+      lines.push("Protection is on by default; /appa off disables it, /appa init project scopes a policy to one project.");
       notify(lines.join(" "));
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);
@@ -312,6 +384,13 @@ export default function (pi: ExtensionAPI): void {
   }
 }
 
+/** Last ~200 chars of installer output, whitespace-normalized, for notices. */
+function outcomeTail(outcome: InstallOutcome): string {
+  const text = `${outcome.stderr} ${outcome.stdout}`.trim().replace(/\s+/g, " ");
+  if (text === "") return "(no output)";
+  return text.length > 200 ? `…${text.slice(-200)}` : text;
+}
+
 function joinContent(content: ReadonlyArray<unknown>): string {
   const parts: string[] = [];
   for (const item of content) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openappa",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Thin OpenAPPA guard extension for Pi: gates tool calls through the APPA runtime. No policy logic lives here.",
   "keywords": [
     "pi-package",

package/src/gate.ts

@@ -1,17 +1,21 @@
 /**
- * Session gate: protection is opt-in, fixed at session start.
+ * Session gate: protection is ON by default and fixed at session start.
  *
- * Three ways a session becomes protected, most specific first for reporting:
- * - a project marker `<cwd>/.pi/openappa` (project-scoped; optional content
- *   names that project's policy, absolute or cwd-relative),
- * - launched with APPA_GATE=1 (the launcher route, mirroring `clappa`), or
- * - always-on mode, persisted by `/appa on` (marker file below).
+ * Opt-outs, most specific first:
+ * - APPA_GATE=1 / APPA_GATE=0 force on/off for one launch,
+ * - a project opt-out marker `<cwd>/.pi/no-openappa`,
+ * - a project marker `<cwd>/.pi/openappa` (which also names that project's
+ *   policy, absolute or cwd-relative),
+ * - the global `/appa off` marker below; `/appa on` clears it.
+ * Otherwise the session is protected (the default).
  *
  * An explicit APPA_CONFIG always wins as the policy source; otherwise a
  * project marker's content is used; otherwise the settings file's `config`;
  * otherwise APPA's own default. The gate is
  * captured once per session so a session cannot disable its own protection
  * mid-run; `/appa on|off` are deliberate user commands and do re-resolve.
+ * The legacy `always-on` marker from opt-in days is ignored; `/appa on`
+ * removes it.
  */
 
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -26,7 +30,13 @@ function baseConfigDir(env: NodeJS.ProcessEnv): string {
   return join(env.HOME ?? "", ".config");
 }
 
-export function alwaysOnMarkerPath(env: NodeJS.ProcessEnv): string {
+/** Global opt-out written by `/appa off`; `/appa on` removes it. */
+export function globalOffMarkerPath(env: NodeJS.ProcessEnv): string {
+  return join(baseConfigDir(env), "pi-openappa", "off");
+}
+
+/** Legacy opt-in marker from before default-on; ignored, cleared by `/appa on`. */
+export function legacyAlwaysOnMarkerPath(env: NodeJS.ProcessEnv): string {
   return join(baseConfigDir(env), "pi-openappa", "always-on");
 }
 
@@ -83,21 +93,45 @@ export function projectMarkerPath(cwd: string): string {
   return join(cwd, ".pi", "openappa");
 }
 
-export function isAlwaysOn(env: NodeJS.ProcessEnv): boolean {
-  return existsSync(alwaysOnMarkerPath(env));
+export function projectNoMarkerPath(cwd: string): string {
+  return join(cwd, ".pi", "no-openappa");
+}
+
+export function isGloballyOff(env: NodeJS.ProcessEnv): boolean {
+  return existsSync(globalOffMarkerPath(env));
 }
 
-export function setAlwaysOn(env: NodeJS.ProcessEnv, on: boolean): void {
-  const marker = alwaysOnMarkerPath(env);
-  if (on) {
+export function setGloballyOff(env: NodeJS.ProcessEnv, off: boolean): void {
+  const marker = globalOffMarkerPath(env);
+  if (off) {
     mkdirSync(dirname(marker), { recursive: true });
     writeFileSync(marker, "");
   } else {
     rmSync(marker, { force: true });
+    rmSync(legacyAlwaysOnMarkerPath(env), { force: true });
   }
 }
 
-export type GateSource = "project" | "env" | "always-on" | "off";
+/**
+ * Does APPA's own default policy exist? Heuristic mirror of the runtime's
+ * lookup: `$XDG_CONFIG_HOME/appa/appa.toml` or `~/.config/appa/appa.toml`.
+ */
+export function appaDefaultPolicyExists(env: NodeJS.ProcessEnv): boolean {
+  const xdg = env.XDG_CONFIG_HOME;
+  const candidates = [
+    ...(xdg !== undefined && xdg !== "" ? [join(xdg, "appa", "appa.toml")] : []),
+    join(env.HOME ?? "", ".config", "appa", "appa.toml"),
+  ];
+  return candidates.some((candidate) => existsSync(candidate));
+}
+
+export type GateSource =
+  | "env-on"
+  | "env-off"
+  | "project"
+  | "project-off"
+  | "global-off"
+  | "default";
 
 export interface GateState {
   /** Protection active for this session. */
@@ -137,29 +171,47 @@ export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
       ? env.APPA_CONFIG
       : undefined;
   const projectGated = cwd !== undefined && existsSync(projectMarkerPath(cwd));
+  const projectOff = cwd !== undefined && existsSync(projectNoMarkerPath(cwd));
   const projectCfg =
     projectGated && cwd !== undefined ? projectConfig(cwd) : undefined;
   // Precedence: launch env, then the project marker (per-project intent),
   // then the global settings file (see readSettings).
   const config = explicitConfig ?? projectCfg ?? settings.config;
 
-  if (env.APPA_GATE === "1" || projectGated) {
+  // An explicit launch choice beats every marker.
+  if (env.APPA_GATE === "1") {
     return {
       gated: true,
-      source: projectGated ? "project" : "env",
+      source: "env-on",
       ...base,
       ...(config !== undefined ? { config } : {}),
     };
   }
-  if (isAlwaysOn(env)) {
+  if (env.APPA_GATE === "0") {
+    return { gated: false, source: "env-off", ...base };
+  }
+  // Project level: an opt-out beats the project's own opt-in.
+  if (projectOff) {
+    return { gated: false, source: "project-off", ...base };
+  }
+  if (projectGated) {
     return {
       gated: true,
-      source: "always-on",
+      source: "project",
       ...base,
       ...(config !== undefined ? { config } : {}),
     };
   }
-  return { gated: false, source: "off", ...base };
+  // Global opt-out, then the default: protection on.
+  if (isGloballyOff(env)) {
+    return { gated: false, source: "global-off", ...base };
+  }
+  return {
+    gated: true,
+    source: "default",
+    ...base,
+    ...(config !== undefined ? { config } : {}),
+  };
 }
 
 export interface HealthResult {

package/src/hook-client.ts

@@ -18,6 +18,8 @@ export interface HookOutcome {
   stdout: string;
   stderr: string;
   timedOut: boolean;
+  /** The hook binary itself could not be spawned (ENOENT). */
+  binaryMissing: boolean;
 }
 
 export interface InvokeOptions {
@@ -94,10 +96,11 @@ export async function invokeAppaHook(
           stdout,
           stderr: `${stderr}appa hook timed out after ${timeoutMs}ms`.trim(),
           timedOut: true,
+          binaryMissing: false,
         });
         return;
       }
-      resolve({ exitCode, stdout, stderr, timedOut: false });
+      resolve({ exitCode, stdout, stderr, timedOut: false, binaryMissing: false });
     };
 
     child.on("error", (error) => {
@@ -120,11 +123,13 @@ export async function invokeAppaHook(
 
 function spawnFailure(error: unknown): HookOutcome {
   const detail = error instanceof Error ? error.message : String(error);
+  const code = (error as { code?: unknown } | null)?.code;
   return {
     exitCode: -1,
     stdout: "",
     stderr: `appa hook failed to start: ${detail}`,
     timedOut: false,
+    binaryMissing: code === "ENOENT",
   };
 }
 

package/src/installer.ts

@@ -0,0 +1,103 @@
+/**
+ * Auto-installer for the OpenAPPA runtime binary.
+ *
+ * Runs the official install pipeline through `sh -c` — nothing else. It never
+ * decides: the extension wiring owns when an install is appropriate and what
+ * to report. The command and timeout honor APPA_INSTALL_CMD and
+ * APPA_INSTALL_TIMEOUT_MS so mirrors, offline copies, and slow links work.
+ */
+
+import { spawn } from "node:child_process";
+
+export const DEFAULT_INSTALL_CMD = "curl -fsSL https://openappa.com/install.sh | sh";
+
+export interface InstallOutcome {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export function resolveInstallCmd(env: NodeJS.ProcessEnv): string {
+  const cmd = env.APPA_INSTALL_CMD;
+  return cmd !== undefined && cmd !== "" ? cmd : DEFAULT_INSTALL_CMD;
+}
+
+export function resolveInstallTimeoutMs(env: NodeJS.ProcessEnv): number {
+  const raw = Number(env.APPA_INSTALL_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+
+export async function installAppa(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<InstallOutcome> {
+  const timeoutMs = resolveInstallTimeoutMs(env);
+  return await new Promise<InstallOutcome>((resolve) => {
+    let child;
+    try {
+      child = spawn("sh", ["-c", resolveInstallCmd(env)], {
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      resolve(installFailure(error));
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+
+    const finish = (exitCode: number) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (timedOut) {
+        resolve({
+          exitCode: -1,
+          stdout,
+          stderr: `${stderr}appa install timed out after ${timeoutMs}ms`.trim(),
+          timedOut: true,
+        });
+        return;
+      }
+      resolve({ exitCode, stdout, stderr, timedOut: false });
+    };
+
+    child.on("error", (error) => {
+      resolve(mergeOutcome(installFailure(error), stderr));
+      settled = true;
+      clearTimeout(timer);
+    });
+    child.on("close", (code) => finish(code ?? -1));
+  });
+}
+
+function installFailure(error: unknown): InstallOutcome {
+  const detail = error instanceof Error ? error.message : String(error);
+  return {
+    exitCode: -1,
+    stdout: "",
+    stderr: `appa install failed to start: ${detail}`,
+    timedOut: false,
+  };
+}
+
+function mergeOutcome(base: InstallOutcome, stderrSoFar: string): InstallOutcome {
+  return { ...base, stderr: `${stderrSoFar}${base.stderr}`.trim() };
+}