pi-openappa 0.1.0 → 0.2.0

package/README.md

@@ -14,61 +14,92 @@ 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
 
 ## 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` invokes
+A protected session brings the runtime up on its own: `session_start` invokes
 `appa hook --ensure-runtime`, passing `--config "$APPA_CONFIG"` when set and
 otherwise letting APPA use its own default policy (`~/.config/appa/appa.toml`).
 Protected sessions therefore need zero manual server management. 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
 
 | Variable | 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 |
 | `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 |
 
-`/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
@@ -99,7 +130,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

@@ -20,8 +20,15 @@ import {
   stopPayload,
   toolResponseFrom,
 } from "../src/adapter.ts";
-import { invokeAppaHook } from "../src/hook-client.ts";
-import { captureGate, checkHealth, setAlwaysOn, type GateState } from "../src/gate.ts";
+import { invokeAppaHook, resolveHookBin, type HookOutcome } from "../src/hook-client.ts";
+import { installAppa, type InstallOutcome } from "../src/installer.ts";
+import {
+  appaDefaultPolicyExists,
+  captureGate,
+  checkHealth,
+  setGloballyOff,
+  type GateState,
+} from "../src/gate.ts";
 
 interface TextPart {
   type: "text";
@@ -32,6 +39,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
@@ -39,21 +48,77 @@ export default function (pi: ExtensionAPI): void {
    */
   const pendingInputs = new Map<string, Record<string, unknown>>();
 
-  const gated = (): boolean => gate?.gated === true;
+  const gated = (): boolean => gate?.gated === true && !unprotected;
 
   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 outcome = await invokeAppaHook(
-      sessionStartPayload(sessionId, event.reason, ctx.cwd),
-      {
-        ensureRuntime: true,
-        ...(gate.config !== undefined ? { config: gate.config } : {}),
-      },
-    );
-    if (outcome.exitCode !== 0 && ctx.hasUI) {
+    const payload = sessionStartPayload(sessionId, event.reason, ctx.cwd);
+    const options = {
+      ensureRuntime: true,
+      ...(gate.config !== undefined ? { config: gate.config } : {}),
+    };
+    const notify = (message: string, kind: "info" | "warning"): void => {
+      if (ctx.hasUI) ctx.ui.notify(message, kind);
+    };
+    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" &&
+        gate.config === undefined &&
+        !appaDefaultPolicyExists(process.env) &&
+        !(await checkHealth(gate.runtimeUrl)).ok
+      ) {
+        unprotected = true;
+        if (!warnedAlready) {
+          notify(
+            "OpenAPPA is on by default, but no policy exists (APPA_CONFIG, " +
+              ".pi/openappa, or ~/.config/appa/appa.toml) and no runtime answers " +
+              `at ${gate.runtimeUrl} — this session runs unprotected. ` +
+              "Write a policy, or run /appa off.",
+            "warning",
+          );
+        }
+        return;
+      }
+      if (ctx.hasUI && !warnedAlready) {
       const remedy =
         gate.config === undefined
           ? " Provide a policy (this project's .pi/openappa, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
@@ -64,6 +129,7 @@ export default function (pi: ExtensionAPI): void {
           "Tool calls will be blocked until it answers.",
         "warning",
       );
+      }
     }
   });
 
@@ -123,17 +189,17 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("appa", {
-    description: "Show OpenAPPA status; `appa on|off` toggles always-on protection",
+    description: "Show OpenAPPA status; `appa on|off` toggles protection globally",
     handler: async (args, ctx) => {
       const arg = args.trim();
       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",
           );
         }
@@ -143,14 +209,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);
@@ -166,6 +239,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/justfile

@@ -30,3 +30,10 @@ remove:
 # Publish to npm (requires `npm login`; the Pi gallery indexes the pi-package keyword)
 publish: check
     npm publish
+
+# Ship a version: sync the lockfile version, run every check, publish to npm
+# (run the README smoke test right after)
+deploy:
+    npm install --package-lock-only --no-audit --no-fund
+    just check
+    npm publish

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openappa",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Thin OpenAPPA guard extension for Pi: gates tool calls through the APPA runtime. No policy logic lives here.",
   "keywords": [
     "pi-package",
@@ -11,6 +11,13 @@
     "policy"
   ],
   "license": "MIT",
+  "author": "aemonge",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aemonge-dev/pi-openappa.git"
+  },
+  "homepage": "https://github.com/aemonge-dev/pi-openappa#readme",
+  "bugs": "https://github.com/aemonge-dev/pi-openappa/issues",
   "type": "module",
   "pi": {
     "extensions": ["./extensions/index.ts"]

package/src/gate.ts

@@ -1,16 +1,20 @@
 /**
- * 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 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";
@@ -25,7 +29,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");
 }
 
@@ -33,21 +43,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. */
@@ -83,27 +117,46 @@ 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;
-  const config = explicitConfig ?? projectCfg;
 
-  if (env.APPA_GATE === "1" || projectGated) {
+  // An explicit launch choice beats every marker.
+  if (env.APPA_GATE === "1") {
+    const config = explicitConfig ?? projectCfg;
     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) {
+    const config = explicitConfig ?? projectCfg;
     return {
       gated: true,
-      source: "always-on",
+      source: "project",
       ...base,
-      ...(explicitConfig !== undefined ? { config: explicitConfig } : {}),
+      ...(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,
+    ...(explicitConfig !== undefined ? { config: explicitConfig } : {}),
+  };
 }
 
 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() };
+}

package/test/auto-install.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { after, describe, it } from "node:test";
+import { sessionStartPayload } from "../src/adapter.ts";
+import { invokeAppaHook } from "../src/hook-client.ts";
+import {
+  DEFAULT_INSTALL_CMD,
+  installAppa,
+  resolveInstallCmd,
+  resolveInstallTimeoutMs,
+} from "../src/installer.ts";
+
+/** Environment keys this suite mutates; restored after every test. */
+const KEYS = ["APPA_INSTALL_CMD", "APPA_INSTALL_TIMEOUT_MS"];
+const saved: Record<string, string | undefined> = {};
+for (const key of KEYS) saved[key] = process.env[key];
+
+after(() => {
+  for (const key of KEYS) {
+    const value = saved[key];
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+describe("installer resolution", () => {
+  it("defaults to the official install pipeline", () => {
+    delete process.env.APPA_INSTALL_CMD;
+    assert.equal(resolveInstallCmd(process.env), DEFAULT_INSTALL_CMD);
+    assert.equal(DEFAULT_INSTALL_CMD, "curl -fsSL https://openappa.com/install.sh | sh");
+  });
+
+  it("honors APPA_INSTALL_CMD", () => {
+    process.env.APPA_INSTALL_CMD = "./offline-install.sh";
+    assert.equal(resolveInstallCmd(process.env), "./offline-install.sh");
+  });
+
+  it("honors APPA_INSTALL_TIMEOUT_MS with a sane default", () => {
+    delete process.env.APPA_INSTALL_TIMEOUT_MS;
+    assert.equal(resolveInstallTimeoutMs(process.env), 120_000);
+    process.env.APPA_INSTALL_TIMEOUT_MS = "2500";
+    assert.equal(resolveInstallTimeoutMs(process.env), 2500);
+    process.env.APPA_INSTALL_TIMEOUT_MS = "garbage";
+    assert.equal(resolveInstallTimeoutMs(process.env), 120_000);
+  });
+});
+
+describe("installer run", () => {
+  it("captures a successful install", async () => {
+    process.env.APPA_INSTALL_CMD = "echo installed-ok";
+    const outcome = await installAppa();
+    assert.equal(outcome.exitCode, 0);
+    assert.ok(outcome.stdout.includes("installed-ok"));
+    assert.equal(outcome.timedOut, false);
+  });
+
+  it("captures a failed install with its output", async () => {
+    process.env.APPA_INSTALL_CMD = "echo boom >&2; exit 3";
+    const outcome = await installAppa();
+    assert.equal(outcome.exitCode, 3);
+    assert.ok(outcome.stderr.includes("boom"));
+    assert.equal(outcome.timedOut, false);
+  });
+
+  it("kills a stuck install", async () => {
+    process.env.APPA_INSTALL_CMD = "sleep 5";
+    process.env.APPA_INSTALL_TIMEOUT_MS = "150";
+    const started = Date.now();
+    const outcome = await installAppa();
+    assert.equal(outcome.timedOut, true);
+    assert.equal(outcome.exitCode, -1);
+    assert.ok(outcome.stderr.includes("timed out"));
+    assert.ok(Date.now() - started < 4000, "killed promptly, not after sleep 5");
+  });
+});
+
+describe("hook-client binary detection", () => {
+  it("flags a missing hook binary (ENOENT)", async () => {
+    const outcome = await invokeAppaHook(sessionStartPayload("s1", "startup", "/tmp"), {
+      bin: "/nonexistent-dir/appa",
+    });
+    assert.equal(outcome.binaryMissing, true);
+    assert.equal(outcome.exitCode, -1);
+    assert.ok(outcome.stderr.includes("failed to start"));
+  });
+});

package/test/extension.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import { after, beforeEach, describe, it } from "node:test";
-import { mkdtempSync, rmSync, existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync, existsSync, readFileSync, mkdirSync, writeFileSync, copyFileSync, chmodSync } from "node:fs";
+import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -10,7 +11,7 @@ const MOCK_BIN = join(here, "fixtures", "mock-appa.mjs");
 const SESSION = "22222222-2222-2222-2222-222222222222";
 
 /** Environment keys this suite mutates; restored after every test. */
-const KEYS = ["APPA_GATE", "APPA_HOOK_BIN", "MOCK_MODE", "MOCK_RECORD", "APPA_HOOK_TIMEOUT_MS", "APPA_CONFIG", "XDG_CONFIG_HOME"];
+const KEYS = ["APPA_GATE", "APPA_HOOK_BIN", "MOCK_MODE", "MOCK_RECORD", "APPA_HOOK_TIMEOUT_MS", "APPA_CONFIG", "XDG_CONFIG_HOME", "APPA_INSTALL_CMD", "APPA_INSTALL_TIMEOUT_MS", "PATH", "HOME", "APPA_RUNTIME_URL"];
 const saved: Record<string, string | undefined> = {};
 for (const key of KEYS) saved[key] = process.env[key];
 
@@ -78,6 +79,20 @@ function withMock(dir: string, mode: string): void {
   process.env.MOCK_RECORD = join(dir, "record.jsonl");
 }
 
+/** PATH with `appa` absent: extra dirs first, then only node/curl/sh system dirs. */
+function hermeticPath(...extraDirs: string[]): string {
+  return [...extraDirs, dirname(process.execPath), "/usr/bin", "/bin"].join(":");
+}
+
+/** Give the fake ctx a recording UI; returns [kind, message] pairs. */
+function enableUiSpy(harness: Harness): Array<[string, string]> {
+  const notices: Array<[string, string]> = [];
+  const ctx = harness.ctx as { hasUI?: boolean; ui?: { notify: (m: string, k: string) => void } };
+  ctx.hasUI = true;
+  ctx.ui = { notify: (message, kind) => notices.push([kind, message]) };
+  return notices;
+}
+
 const bashCall = { type: "tool_call", toolCallId: "call-1", toolName: "bash", input: { command: "ls", description: "list" } };
 const bashResult = {
   type: "tool_result",
@@ -90,16 +105,19 @@ const bashResult = {
 };
 
 beforeEach(() => {
-  // Isolate gate resolution from real machine state: clean config dir per
-  // test, no gate env. Tests that need gating set it up inside themselves.
+  // Isolate gate resolution from real machine state: clean config dir and
+  // HOME per test (no off markers, no APPA default policy), no gate env.
+  // Tests that want to opt out set APPA_GATE=0 or a marker themselves.
   process.env.XDG_CONFIG_HOME = join(workDir(), "xdg");
+  process.env.HOME = join(workDir(), "home");
   delete process.env.APPA_GATE;
   delete process.env.APPA_CONFIG;
+  delete process.env.APPA_RUNTIME_URL;
 });
 
-describe("gate off: extension is inert", () => {
+describe("opted-out session (APPA_GATE=0): extension is inert", () => {
   beforeEach(() => {
-    delete process.env.APPA_GATE;
+    process.env.APPA_GATE = "0";
   });
 
   it("never invokes the hook and passes everything through", async () => {
@@ -191,6 +209,10 @@ describe("gated session through the scripted mock", () => {
   it("fails closed when the hook binary cannot start", async () => {
     const dir = workDir();
     withMock(dir, "allow");
+    // A named config keeps this fail-closed: with none, a failed start with
+    // nothing answering downgrades the session to unprotected instead.
+    process.env.APPA_CONFIG = "/tmp/policy.toml";
+    process.env.APPA_RUNTIME_URL = "http://127.0.0.1:8799";
     process.env.APPA_HOOK_BIN = join(dir, "does-not-exist");
     const harness = await loadExtension();
     await startSession(harness);
@@ -202,6 +224,8 @@ describe("gated session through the scripted mock", () => {
   it("fails closed on hook timeout", async () => {
     const dir = workDir();
     withMock(dir, "sleep");
+    process.env.APPA_CONFIG = "/tmp/policy.toml"; // no no-policy downgrade
+    process.env.APPA_RUNTIME_URL = "http://127.0.0.1:8799";
     process.env.APPA_HOOK_TIMEOUT_MS = "150";
     const harness = await loadExtension();
     await startSession(harness);
@@ -315,10 +339,10 @@ describe("auto-start on gated session start", () => {
     assert.ok(!first?.includes("--config"));
   });
 
-  it("starts nothing when ungated", async () => {
+  it("starts nothing when opted out (APPA_GATE=0)", async () => {
     const dir = workDir();
     withMock(dir, "allow");
-    delete process.env.APPA_GATE;
+    process.env.APPA_GATE = "0";
     delete process.env.APPA_CONFIG;
     const harness = await loadExtension();
     await startSession(harness);
@@ -327,6 +351,95 @@ describe("auto-start on gated session start", () => {
   });
 });
 
+describe("auto-install on gated session start (default-on)", () => {
+  it("installs the default appa and retries ensure-runtime", async () => {
+    const dir = workDir();
+    const binDir = join(dir, "bin");
+    mkdirSync(binDir);
+    // No APPA_GATE: protection is on by default now.
+    delete process.env.APPA_HOOK_BIN;
+    delete process.env.APPA_CONFIG;
+    process.env.MOCK_MODE = "allow";
+    process.env.MOCK_RECORD = join(dir, "record.jsonl");
+    const installed = join(binDir, "appa");
+    process.env.APPA_INSTALL_CMD = `cp ${MOCK_BIN} ${installed} && chmod +x ${installed}`;
+    process.env.PATH = hermeticPath(binDir);
+    const harness = await loadExtension();
+    const notices = enableUiSpy(harness);
+    await startSession(harness);
+    assert.ok(existsSync(installed), "installer ran and placed appa");
+    const first = recordedArgv(dir)[0];
+    assert.ok(first?.includes("--ensure-runtime"), `argv: ${JSON.stringify(first)}`);
+    assert.ok(!first?.includes("--config"));
+    assert.ok(notices.some(([kind]) => kind === "info"), "install notice shown");
+    assert.deepEqual(
+      notices.filter(([kind]) => kind === "warning"),
+      [],
+      `no warnings on success: ${JSON.stringify(notices)}`,
+    );
+  });
+
+  it("reports a failed install once and never retries the hook", async () => {
+    const dir = workDir();
+    process.env.APPA_GATE = "1";
+    delete process.env.APPA_HOOK_BIN;
+    delete process.env.APPA_CONFIG;
+    process.env.MOCK_MODE = "allow";
+    process.env.MOCK_RECORD = join(dir, "record.jsonl");
+    process.env.APPA_INSTALL_CMD = "echo boom >&2; exit 3";
+    process.env.APPA_RUNTIME_URL = "http://127.0.0.1:8799";
+    process.env.PATH = hermeticPath(join(dir, "bin"));
+    const harness = await loadExtension();
+    const notices = enableUiSpy(harness);
+    await startSession(harness);
+    assert.deepEqual(recordedArgv(dir), []);
+    assert.deepEqual(recordedLines(dir), []);
+    const warnings = notices.filter(([kind]) => kind === "warning");
+    assert.equal(warnings.length, 1, JSON.stringify(notices));
+    assert.ok(warnings[0]?.[1].includes("auto-install failed"));
+    assert.ok(warnings[0]?.[1].includes("boom"));
+    assert.ok(warnings[0]?.[1].includes("blocked"));
+  });
+
+  it("warns once when the install succeeds but appa is still missing", async () => {
+    const dir = workDir();
+    process.env.APPA_GATE = "1";
+    delete process.env.APPA_HOOK_BIN;
+    delete process.env.APPA_CONFIG;
+    process.env.MOCK_MODE = "allow";
+    process.env.MOCK_RECORD = join(dir, "record.jsonl");
+    process.env.APPA_INSTALL_CMD = "true";
+    process.env.APPA_RUNTIME_URL = "http://127.0.0.1:8799";
+    process.env.PATH = hermeticPath(join(dir, "bin"));
+    const harness = await loadExtension();
+    const notices = enableUiSpy(harness);
+    await startSession(harness);
+    assert.deepEqual(recordedArgv(dir), []);
+    const warnings = notices.filter(([kind]) => kind === "warning");
+    assert.equal(warnings.length, 1, JSON.stringify(notices));
+    assert.ok(warnings[0]?.[1].includes("still not on PATH"));
+  });
+
+  it("never auto-installs a custom APPA_HOOK_BIN", async () => {
+    const dir = workDir();
+    process.env.APPA_GATE = "1";
+    process.env.APPA_HOOK_BIN = join(dir, "missing-bin");
+    delete process.env.APPA_CONFIG;
+    process.env.MOCK_MODE = "allow";
+    process.env.MOCK_RECORD = join(dir, "record.jsonl");
+    const marker = join(dir, "install-ran");
+    process.env.APPA_INSTALL_CMD = `touch ${marker}`;
+    process.env.PATH = hermeticPath();
+    const harness = await loadExtension();
+    const notices = enableUiSpy(harness);
+    await startSession(harness);
+    assert.ok(!existsSync(marker), "installer must not run for custom binaries");
+    const warnings = notices.filter(([kind]) => kind === "warning");
+    assert.equal(warnings.length, 1, JSON.stringify(notices));
+    assert.ok(warnings[0]?.[1].includes("did not answer"), "generic fail-closed warning");
+  });
+});
+
 describe("project-scoped protection (.pi/openappa)", () => {
   it("gates the project and passes the marker's policy as --config", async () => {
     const dir = workDir();
@@ -378,14 +491,11 @@ describe("project-scoped protection (.pi/openappa)", () => {
   });
 });
 
-describe("always-on mode (marker file)", () => {
-  it("gates every session once the marker exists", async () => {
+describe("global opt-out (/appa off marker)", () => {
+  it("gates every session by default, with no markers or env", async () => {
     const dir = workDir();
     withMock(dir, "allow");
     delete process.env.APPA_GATE;
-    process.env.XDG_CONFIG_HOME = join(dir, "xdg");
-    mkdirSync(join(dir, "xdg", "pi-openappa"), { recursive: true });
-    writeFileSync(join(dir, "xdg", "pi-openappa", "always-on"), "");
     const harness = await loadExtension();
     await startSession(harness);
     const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
@@ -393,11 +503,13 @@ describe("always-on mode (marker file)", () => {
     assert.ok(recordedArgv(dir).length > 0, "hook was invoked without APPA_GATE");
   });
 
-  it("inert when the marker is absent", async () => {
+  it("is inert once the global off marker exists", async () => {
     const dir = workDir();
     withMock(dir, "allow");
     delete process.env.APPA_GATE;
-    process.env.XDG_CONFIG_HOME = join(dir, "xdg-clean");
+    process.env.XDG_CONFIG_HOME = join(dir, "xdg");
+    mkdirSync(join(dir, "xdg", "pi-openappa"), { recursive: true });
+    writeFileSync(join(dir, "xdg", "pi-openappa", "off"), "");
     const harness = await loadExtension();
     await startSession(harness);
     const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
@@ -407,18 +519,38 @@ describe("always-on mode (marker file)", () => {
 });
 
 describe("/appa on|off", () => {
-  it("on creates the marker and gates immediately; off removes it", async () => {
+  it("off writes the global marker and ungates; on clears it and re-gates", async () => {
     const dir = workDir();
-    process.env.XDG_CONFIG_HOME = join(dir, "xdg");
+    withMock(dir, "allow");
     delete process.env.APPA_GATE;
+    process.env.XDG_CONFIG_HOME = join(dir, "xdg");
     const harness = await loadExtension();
     const command = harness.commands.get("appa");
     assert.ok(command);
-    await command.handler("on", harness.ctx);
-    assert.ok(existsSync(join(dir, "xdg", "pi-openappa", "always-on")));
-    const gated = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
-    assert.equal(gated, undefined); // gated now: would invoke hook (mock unset -> inert record empty ok)
     await command.handler("off", harness.ctx);
+    const marker = join(dir, "xdg", "pi-openappa", "off");
+    assert.ok(existsSync(marker));
+    const argvAfterOff = recordedArgv(dir).length;
+    await startSession(harness);
+    const optedOut = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(optedOut, undefined);
+    assert.equal(recordedArgv(dir).length, argvAfterOff, "no hook while opted out");
+    await command.handler("on", harness.ctx);
+    assert.ok(!existsSync(marker));
+    await startSession(harness);
+    const reGated = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(reGated, undefined);
+    assert.ok(recordedArgv(dir).length > argvAfterOff, "hook invoked again after /appa on");
+  });
+
+  it("on also clears the legacy always-on marker", async () => {
+    const dir = workDir();
+    process.env.XDG_CONFIG_HOME = join(dir, "xdg");
+    mkdirSync(join(dir, "xdg", "pi-openappa"), { recursive: true });
+    writeFileSync(join(dir, "xdg", "pi-openappa", "always-on"), "");
+    delete process.env.APPA_GATE;
+    const harness = await loadExtension();
+    await harness.commands.get("appa")!.handler("on", harness.ctx);
     assert.ok(!existsSync(join(dir, "xdg", "pi-openappa", "always-on")));
   });
 
@@ -445,3 +577,91 @@ describe("/appa command", () => {
     await command.handler("", harness.ctx);
   });
 });
+
+describe("no-policy downgrade (runs unprotected)", () => {
+  function noPolicySetup(dir: string): void {
+    delete process.env.APPA_GATE;
+    delete process.env.APPA_CONFIG;
+    delete process.env.APPA_HOOK_BIN;
+    // The mock stands in for the default `appa` binary: present on PATH (so
+    // no auto-install triggers), crashing on ensure-runtime (spawn works).
+    const binDir = join(dir, "bin");
+    mkdirSync(binDir, { recursive: true });
+    const asAppa = join(binDir, "appa");
+    copyFileSync(MOCK_BIN, asAppa);
+    chmodSync(asAppa, 0o755);
+    process.env.MOCK_MODE = "crash";
+    process.env.MOCK_RECORD = join(dir, "record.jsonl");
+    process.env.APPA_RUNTIME_URL = "http://127.0.0.1:8799"; // nothing answers
+    process.env.APPA_INSTALL_CMD = "exit 1"; // tripwire: must never run
+    process.env.PATH = hermeticPath(binDir);
+  }
+
+  it("runs the session unprotected with one warning when no policy exists", async () => {
+    const dir = workDir();
+    noPolicySetup(dir);
+    const harness = await loadExtension();
+    const notices = enableUiSpy(harness);
+    await startSession(harness);
+    const warnings = notices.filter(([kind]) => kind === "warning");
+    assert.equal(warnings.length, 1, JSON.stringify(notices));
+    assert.ok(warnings[0]?.[1].includes("runs unprotected"));
+    // The initial SessionStart went out; tool calls afterwards do not.
+    assert.equal(recordedLines(dir).length, 1);
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(call, undefined);
+    assert.equal(recordedLines(dir).length, 1, "no hook while unprotected");
+  });
+
+  it("stays fail-closed when APPA's default policy exists", async () => {
+    const dir = workDir();
+    noPolicySetup(dir);
+    mkdirSync(join(process.env.XDG_CONFIG_HOME!, "appa"), { recursive: true });
+    writeFileSync(join(process.env.XDG_CONFIG_HOME!, "appa", "appa.toml"), "");
+    const harness = await loadExtension();
+    const notices = enableUiSpy(harness);
+    await startSession(harness);
+    const warnings = notices.filter(([kind]) => kind === "warning");
+    assert.equal(warnings.length, 1, JSON.stringify(notices));
+    assert.ok(warnings[0]?.[1].includes("did not answer"));
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(call.block, true);
+  });
+
+  it("stays fail-closed with a named APPA_CONFIG", async () => {
+    const dir = workDir();
+    noPolicySetup(dir);
+    process.env.APPA_CONFIG = "/tmp/named-but-broken.toml";
+    const harness = await loadExtension();
+    const notices = enableUiSpy(harness);
+    await startSession(harness);
+    const warnings = notices.filter(([kind]) => kind === "warning");
+    assert.equal(warnings.length, 1, JSON.stringify(notices));
+    assert.ok(warnings[0]?.[1].includes("did not answer"));
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(call.block, true);
+  });
+
+  it("stays fail-closed when a runtime is already answering", async () => {
+    const dir = workDir();
+    noPolicySetup(dir);
+    const server = createServer((req, res) => {
+      res.end(req.url?.includes("health") ? "ok" : "");
+    });
+    await new Promise<void>((ready) => server.listen(0, "127.0.0.1", ready));
+    const address = server.address() as { port: number };
+    process.env.APPA_RUNTIME_URL = `http://127.0.0.1:${address.port}`;
+    try {
+      const harness = await loadExtension();
+      const notices = enableUiSpy(harness);
+      await startSession(harness);
+      const warnings = notices.filter(([kind]) => kind === "warning");
+      assert.equal(warnings.length, 1, JSON.stringify(notices));
+      assert.ok(warnings[0]?.[1].includes("did not answer"));
+      const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+      assert.equal(call.block, true);
+    } finally {
+      server.close();
+    }
+  });
+});

package/test/gate.test.ts

@@ -0,0 +1,131 @@
+import assert from "node:assert/strict";
+import { after, describe, it } from "node:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  appaDefaultPolicyExists,
+  captureGate,
+  globalOffMarkerPath,
+  legacyAlwaysOnMarkerPath,
+} from "../src/gate.ts";
+
+/** Environment keys this suite mutates; restored after every test. */
+const KEYS = ["APPA_GATE", "APPA_CONFIG", "XDG_CONFIG_HOME", "HOME"];
+const saved: Record<string, string | undefined> = {};
+for (const key of KEYS) saved[key] = process.env[key];
+
+after(() => {
+  for (const key of KEYS) {
+    const value = saved[key];
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+const workDirs: string[] = [];
+after(() => {
+  for (const dir of workDirs) rmSync(dir, { recursive: true, force: true });
+});
+
+/** Fresh env with isolated HOME/XDG (no markers, no default policy) + project dir. */
+function fresh(): { env: Record<string, string>; proj: string } {
+  const dir = mkdtempSync(join(tmpdir(), "pi-openappa-gate-"));
+  workDirs.push(dir);
+  return {
+    env: { HOME: join(dir, "home"), XDG_CONFIG_HOME: join(dir, "xdg") },
+    proj: join(dir, "proj"),
+  };
+}
+
+function projectMarker(env: Record<string, string>, proj: string, content = ""): void {
+  mkdirSync(join(proj, ".pi"), { recursive: true });
+  writeFileSync(join(proj, ".pi", "openappa"), content);
+}
+
+describe("default-on gate resolution", () => {
+  it("is gated by default with no markers or env", () => {
+    const { env, proj } = fresh();
+    const state = captureGate(env, proj);
+    assert.equal(state.gated, true);
+    assert.equal(state.source, "default");
+    assert.equal(state.config, undefined);
+  });
+
+  it("APPA_GATE=0 opts out for one launch; APPA_GATE=1 forces on", () => {
+    const { env, proj } = fresh();
+    env.APPA_GATE = "0";
+    assert.equal(captureGate(env, proj).source, "env-off");
+    env.APPA_GATE = "1";
+    const on = captureGate(env, proj);
+    assert.equal(on.gated, true);
+    assert.equal(on.source, "env-on");
+  });
+
+  it("an explicit launch choice beats every project marker", () => {
+    const { env, proj } = fresh();
+    projectMarker(env, proj, "appa.toml");
+    mkdirSync(join(proj, ".pi"), { recursive: true });
+    writeFileSync(join(proj, ".pi", "no-openappa"), "");
+    env.APPA_GATE = "1";
+    assert.equal(captureGate(env, proj).source, "env-on");
+    env.APPA_GATE = "0";
+    assert.equal(captureGate(env, proj).source, "env-off");
+  });
+
+  it(".pi/openappa gates the project and names its policy", () => {
+    const { env, proj } = fresh();
+    projectMarker(env, proj, "appa.toml\n");
+    const state = captureGate(env, proj);
+    assert.equal(state.gated, true);
+    assert.equal(state.source, "project");
+    assert.equal(state.config, join(proj, "appa.toml"));
+  });
+
+  it(".pi/no-openappa opts the project out, beating .pi/openappa", () => {
+    const { env, proj } = fresh();
+    projectMarker(env, proj, "appa.toml");
+    writeFileSync(join(proj, ".pi", "no-openappa"), "");
+    const state = captureGate(env, proj);
+    assert.equal(state.gated, false);
+    assert.equal(state.source, "project-off");
+  });
+
+  it("the /appa off marker opts out globally; APPA_CONFIG still names a policy", () => {
+    const { env, proj } = fresh();
+    mkdirSync(join(env.XDG_CONFIG_HOME!, "pi-openappa"), { recursive: true });
+    writeFileSync(globalOffMarkerPath(env), "");
+    const state = captureGate(env, proj);
+    assert.equal(state.gated, false);
+    assert.equal(state.source, "global-off");
+    env.APPA_CONFIG = "/tmp/policy.toml";
+    env.APPA_GATE = "1";
+    assert.equal(captureGate(env, proj).config, "/tmp/policy.toml");
+  });
+
+  it("ignores the legacy always-on marker (default is already on)", () => {
+    const { env, proj } = fresh();
+    mkdirSync(join(env.XDG_CONFIG_HOME!, "pi-openappa"), { recursive: true });
+    writeFileSync(legacyAlwaysOnMarkerPath(env), "");
+    assert.equal(captureGate(env, proj).source, "default");
+  });
+});
+
+describe("appaDefaultPolicyExists heuristic", () => {
+  it("finds nothing in a clean environment", () => {
+    const { env } = fresh();
+    assert.equal(appaDefaultPolicyExists(env), false);
+  });
+
+  it("finds ~/.config/appa/appa.toml and the XDG equivalent", () => {
+    const home = fresh();
+    mkdirSync(join(home.env.HOME!, ".config", "appa"), { recursive: true });
+    writeFileSync(join(home.env.HOME!, ".config", "appa", "appa.toml"), "");
+    assert.equal(appaDefaultPolicyExists(home.env), true);
+
+    const xdg = fresh();
+    mkdirSync(join(xdg.env.XDG_CONFIG_HOME!, "appa"), { recursive: true });
+    writeFileSync(join(xdg.env.XDG_CONFIG_HOME!, "appa", "appa.toml"), "");
+    assert.equal(appaDefaultPolicyExists(xdg.env), true);
+  });
+});