pi-openappa 0.0.0-stage → 0.1.0

package/test/adapter.test.ts

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  mapSessionSource,
+  mapToolName,
+  parseCallDecision,
+  parseResultDecision,
+  postToolUsePayload,
+  preToolUsePayload,
+  sessionStartPayload,
+  stopPayload,
+  promptPayload,
+  renderToolOutput,
+  toolResponseFrom,
+} from "../src/adapter.ts";
+
+const SESSION = "11111111-1111-1111-1111-111111111111";
+
+describe("tool name mapping", () => {
+  it("maps pi built-ins to Claude Code policy names", () => {
+    assert.equal(mapToolName("bash"), "Bash");
+    assert.equal(mapToolName("read"), "Read");
+    assert.equal(mapToolName("edit"), "Edit");
+    assert.equal(mapToolName("write"), "Write");
+    assert.equal(mapToolName("grep"), "Grep");
+    assert.equal(mapToolName("find"), "Glob");
+    assert.equal(mapToolName("ls"), "LS");
+    assert.equal(mapToolName("powershell"), "PowerShell");
+  });
+
+  it("passes custom tool names through verbatim", () => {
+    assert.equal(mapToolName("subagent"), "subagent");
+    assert.equal(mapToolName("mcp__zoekt__search"), "mcp__zoekt__search");
+  });
+});
+
+describe("session source mapping", () => {
+  it("maps startup and new to startup", () => {
+    assert.equal(mapSessionSource("startup"), "startup");
+    assert.equal(mapSessionSource("new"), "startup");
+  });
+
+  it("maps resume, fork, and reload to resume", () => {
+    assert.equal(mapSessionSource("resume"), "resume");
+    assert.equal(mapSessionSource("fork"), "resume");
+    assert.equal(mapSessionSource("reload"), "resume");
+  });
+});
+
+describe("payload builders", () => {
+  it("session start carries source and cwd", () => {
+    assert.deepEqual(sessionStartPayload(SESSION, "startup", "/w"), {
+      session_id: SESSION,
+      hook_event_name: "SessionStart",
+      source: "startup",
+      cwd: "/w",
+    });
+  });
+
+  it("prompt carries the prompt text", () => {
+    assert.equal(promptPayload(SESSION, "list files", "/w").prompt, "list files");
+  });
+
+  it("pre and post tool use echo the same input reference", () => {
+    const input = { command: "ls", description: "list" };
+    const pre = preToolUsePayload(SESSION, "bash", input, "/w");
+    const post = postToolUsePayload(SESSION, "bash", input, { output: "x" }, "/w");
+    assert.equal(pre.tool_input, input);
+    assert.equal(post.tool_input, input);
+    assert.equal(JSON.stringify(pre.tool_input), JSON.stringify(post.tool_input));
+    assert.equal(pre.tool_name, "Bash");
+    assert.equal(post.tool_name, "Bash");
+  });
+
+  it("stop payload is minimal", () => {
+    assert.deepEqual(stopPayload(SESSION), {
+      session_id: SESSION,
+      hook_event_name: "Stop",
+    });
+  });
+});
+
+describe("tool response shaping", () => {
+  it("carries text and error flag generically", () => {
+    assert.deepEqual(toolResponseFrom({ text: "hello", isError: false }), {
+      output: "hello",
+      isError: false,
+    });
+  });
+
+  it("copies structured fields from details when present", () => {
+    const response = toolResponseFrom({
+      text: "out",
+      isError: true,
+      details: { stdout: "out", exitcode: 1, interrupted: false },
+    });
+    assert.equal(response.stdout, "out");
+    assert.equal(response.exitcode, 1);
+    assert.equal(response.interrupted, false);
+    assert.equal(response.isError, true);
+  });
+
+  it("renders updatedToolOutput with stdout/stderr preference", () => {
+    assert.equal(renderToolOutput({ stdout: "kept", exitcode: 0 }), "kept");
+    const rendered = renderToolOutput({ structured: true });
+    assert.ok(rendered.includes("structured"));
+  });
+});
+
+describe("parseCallDecision (wire fixtures from appa 0.31.1)", () => {
+  it("allows on silent exit 0", () => {
+    assert.deepEqual(parseCallDecision(0, "", ""), { type: "allow" });
+  });
+
+  it("allows on empty json object", () => {
+    assert.deepEqual(parseCallDecision(0, "{}", ""), { type: "allow" });
+  });
+
+  it("allows on structured permission allow", () => {
+    const stdout =
+      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"appa: the call is released"}}';
+    assert.deepEqual(parseCallDecision(0, stdout, ""), { type: "allow" });
+  });
+
+  it("denies with reason on exit 2 stderr (undeclared tool)", () => {
+    const decision = parseCallDecision(
+      2,
+      '{"error":"tool host/claude-code/SendWebhook is not declared"}',
+      "OpenAPPA hook blocked: tool host/claude-code/SendWebhook is not declared",
+    );
+    assert.equal(decision.type, "deny");
+    if (decision.type === "deny") {
+      assert.ok(decision.reason.includes("not declared"));
+    }
+  });
+
+  it("denies on structured permission deny with its reason", () => {
+    const stdout =
+      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"appa: this command may not run here"}}';
+    const decision = parseCallDecision(0, stdout, "");
+    assert.equal(decision.type, "deny");
+    if (decision.type === "deny") {
+      assert.equal(decision.reason, "appa: this command may not run here");
+    }
+  });
+
+  it("denies fail-closed on unrecognized exit codes", () => {
+    const decision = parseCallDecision(-1, "", "appa hook failed to start:ENOENT");
+    assert.equal(decision.type, "deny");
+  });
+
+  it("denies fail-closed on unrecognized structured decisions", () => {
+    const decision = parseCallDecision(0, '{"decision":"mystery"}', "");
+    assert.equal(decision.type, "deny");
+  });
+});
+
+describe("parseResultDecision (wire fixtures from appa 0.31.1)", () => {
+  it("passes on silent exit 0", () => {
+    assert.deepEqual(parseResultDecision(0, "", ""), { type: "pass" });
+  });
+
+  it("passes on empty json object", () => {
+    assert.deepEqual(parseResultDecision(0, "{}", ""), { type: "pass" });
+  });
+
+  it("replaces with updatedToolOutput content (withheld result)", () => {
+    const stdout = JSON.stringify({
+      decision: "block",
+      reason: "this outcome does not match the open dispatch; it is not reported",
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        updatedToolOutput: {
+          exitcode: 0,
+          stdout: "[appa] the tool result was withheld",
+        },
+      },
+    });
+    const decision = parseResultDecision(0, stdout, "");
+    assert.equal(decision.type, "replace");
+    if (decision.type === "replace") {
+      assert.equal(decision.text, "[appa] the tool result was withheld");
+      assert.equal(decision.isError, false);
+    }
+  });
+
+  it("withholds as error on exit 2", () => {
+    const decision = parseResultDecision(2, "", "OpenAPPA hook blocked: result may not cross");
+    assert.equal(decision.type, "replace");
+    if (decision.type === "replace") {
+      assert.equal(decision.isError, true);
+      assert.ok(decision.text.includes("result may not cross"));
+    }
+  });
+
+  it("withholds as error when the runtime is unreachable", () => {
+    const decision = parseResultDecision(
+      -1,
+      "",
+      "appa hook failed to start: cannot reach 127.0.0.1:8787",
+    );
+    assert.equal(decision.type, "replace");
+    if (decision.type === "replace") {
+      assert.equal(decision.isError, true);
+    }
+  });
+});

package/test/extension.test.ts

@@ -0,0 +1,447 @@
+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 { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+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 saved: Record<string, string | undefined> = {};
+for (const key of KEYS) saved[key] = process.env[key];
+
+const workDirs: string[] = [];
+function workDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-openappa-test-"));
+  workDirs.push(dir);
+  return dir;
+}
+
+after(() => {
+  for (const dir of workDirs) rmSync(dir, { recursive: true, force: true });
+  for (const key of KEYS) {
+    const value = saved[key];
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+type Handler = (event: any, ctx: any) => Promise<any>;
+
+interface Harness {
+  handlers: Map<string, Handler>;
+  commands: Map<string, { handler: Handler }>;
+  ctx: unknown;
+}
+
+async function loadExtension(cwd?: string): Promise<Harness> {
+  const mod = await import(pathToFileURL(join(here, "..", "extensions", "index.ts")).href);
+  const handlers = new Map<string, Handler>();
+  const commands = new Map<string, { handler: Handler }>();
+  const fakePi = {
+    on: (name: string, handler: Handler) => handlers.set(name, handler),
+    registerCommand: (name: string, options: { handler: Handler }) =>
+      commands.set(name, options),
+  };
+  mod.default(fakePi);
+  const ctx = {
+    cwd: cwd ?? "/home/aemonge/projects/pi-openappa",
+    hasUI: false,
+    sessionManager: { getSessionId: () => SESSION },
+    ui: { notify: () => {} },
+  };
+  return { handlers, commands, ctx };
+}
+
+async function startSession(harness: Harness, reason = "startup"): Promise<void> {
+  const handler = harness.handlers.get("session_start");
+  assert.ok(handler, "session_start handler registered");
+  await handler({ type: "session_start", reason }, harness.ctx);
+}
+
+function recordedLines(dir: string): string[] {
+  const file = join(dir, "record.jsonl");
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((line) => line !== "");
+}
+
+function withMock(dir: string, mode: string): void {
+  process.env.APPA_GATE = "1";
+  process.env.APPA_HOOK_BIN = MOCK_BIN;
+  process.env.MOCK_MODE = mode;
+  process.env.MOCK_RECORD = join(dir, "record.jsonl");
+}
+
+const bashCall = { type: "tool_call", toolCallId: "call-1", toolName: "bash", input: { command: "ls", description: "list" } };
+const bashResult = {
+  type: "tool_result",
+  toolCallId: "call-1",
+  toolName: "bash",
+  input: { command: "ls", description: "list" },
+  content: [{ type: "text", text: "file1 file2" }],
+  details: { stdout: "file1 file2", exitcode: 0 },
+  isError: false,
+};
+
+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.
+  process.env.XDG_CONFIG_HOME = join(workDir(), "xdg");
+  delete process.env.APPA_GATE;
+  delete process.env.APPA_CONFIG;
+});
+
+describe("gate off: extension is inert", () => {
+  beforeEach(() => {
+    delete process.env.APPA_GATE;
+  });
+
+  it("never invokes the hook and passes everything through", async () => {
+    const dir = workDir();
+    process.env.APPA_HOOK_BIN = MOCK_BIN;
+    process.env.MOCK_RECORD = join(dir, "record.jsonl");
+    const harness = await loadExtension();
+    await startSession(harness);
+    const prompt = await harness.handlers.get("before_agent_start")!(
+      { type: "before_agent_start", prompt: "hello", systemPrompt: "", systemPromptOptions: {} },
+      harness.ctx,
+    );
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    const result = await harness.handlers.get("tool_result")!(bashResult, harness.ctx);
+    const turnEnd = await harness.handlers.get("turn_end")!({ type: "turn_end" }, harness.ctx);
+    assert.equal(prompt, undefined);
+    assert.equal(call, undefined);
+    assert.equal(result, undefined);
+    assert.equal(turnEnd, undefined);
+    assert.deepEqual(recordedLines(dir), []);
+  });
+});
+
+describe("gated session through the scripted mock", () => {
+  it("allows a released call and passes its result", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    const harness = await loadExtension();
+    await startSession(harness);
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(call, undefined);
+    const result = await harness.handlers.get("tool_result")!(bashResult, harness.ctx);
+    assert.equal(result, undefined);
+    const events = recordedLines(dir).map((line) => JSON.parse(line));
+    assert.deepEqual(
+      events.map((e) => e.hook_event_name),
+      ["SessionStart", "PreToolUse", "PostToolUse"],
+    );
+  });
+
+  it("denies with the runtime's reason on exit 2", async () => {
+    const dir = workDir();
+    withMock(dir, "deny-stderr");
+    const harness = await loadExtension();
+    await startSession(harness);
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.deepEqual(call, {
+      block: true,
+      reason: "appa: not declared in this policy",
+    });
+  });
+
+  it("denies with a structured permission reason", async () => {
+    const dir = workDir();
+    withMock(dir, "deny-permission");
+    const harness = await loadExtension();
+    await startSession(harness);
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.deepEqual(call, {
+      block: true,
+      reason: "appa: appa: this command may not run here",
+    });
+  });
+
+  it("replaces a withheld result with the runtime's output", async () => {
+    const dir = workDir();
+    withMock(dir, "replace-result");
+    const harness = await loadExtension();
+    await startSession(harness);
+    await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    const result = await harness.handlers.get("tool_result")!(bashResult, harness.ctx);
+    assert.deepEqual(result, {
+      content: [{ type: "text", text: "[appa] the tool result was withheld by policy" }],
+      isError: false,
+    });
+  });
+
+  it("withholds a result as an error when the runtime blocks it", async () => {
+    const dir = workDir();
+    withMock(dir, "deny-result");
+    const harness = await loadExtension();
+    await startSession(harness);
+    await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    const result = await harness.handlers.get("tool_result")!(bashResult, harness.ctx);
+    assert.equal(result.isError, true);
+    assert.ok(result.content[0].text.includes("result may not cross"));
+  });
+
+  it("fails closed when the hook binary cannot start", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    process.env.APPA_HOOK_BIN = join(dir, "does-not-exist");
+    const harness = await loadExtension();
+    await startSession(harness);
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(call.block, true);
+    assert.ok(call.reason.includes("failed to start"));
+  });
+
+  it("fails closed on hook timeout", async () => {
+    const dir = workDir();
+    withMock(dir, "sleep");
+    process.env.APPA_HOOK_TIMEOUT_MS = "150";
+    const harness = await loadExtension();
+    await startSession(harness);
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(call.block, true);
+    assert.ok(call.reason.includes("timed out"));
+  });
+
+  it("treats a subagent spawn as a plain tool call", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    const harness = await loadExtension();
+    await startSession(harness);
+    const spawn = await harness.handlers.get("tool_call")!(
+      {
+        type: "tool_call",
+        toolCallId: "call-2",
+        toolName: "subagent",
+        input: { agent: "scout", prompt: "look around" },
+      },
+      harness.ctx,
+    );
+    assert.equal(spawn, undefined);
+    const events = recordedLines(dir).map((line) => JSON.parse(line));
+    const pre = events.find((e) => e.hook_event_name === "PreToolUse");
+    assert.equal(pre.tool_name, "subagent");
+    assert.deepEqual(pre.tool_input, { agent: "scout", prompt: "look around" });
+  });
+
+  it("echoes the exact tool_input bytes between Pre and PostToolUse", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    const harness = await loadExtension();
+    await startSession(harness);
+    await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    // The executed input mutates afterwards (another handler rewrote it);
+    // the result event sees different bytes than what was checked.
+    const mutatedResult = {
+      ...bashResult,
+      input: { command: "ls -la", description: "list" },
+    };
+    await harness.handlers.get("tool_result")!(mutatedResult, harness.ctx);
+    const lines = recordedLines(dir).map((line) => JSON.parse(line));
+    const pre = lines.find((e) => e.hook_event_name === "PreToolUse");
+    const post = lines.find((e) => e.hook_event_name === "PostToolUse");
+    assert.equal(
+      JSON.stringify(pre.tool_input),
+      JSON.stringify({ command: "ls", description: "list" }),
+    );
+    assert.equal(JSON.stringify(post.tool_input), JSON.stringify(pre.tool_input));
+  });
+
+  it("reports turn end with --turn-end semantics (non-blocking)", async () => {
+    const dir = workDir();
+    withMock(dir, "crash");
+    const harness = await loadExtension();
+    await startSession(harness);
+    const outcome = await harness.handlers.get("turn_end")!({ type: "turn_end" }, harness.ctx);
+    assert.equal(outcome, undefined);
+  });
+
+  it("sends the prompt as the turn boundary and stop at turn end", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    const harness = await loadExtension();
+    await startSession(harness);
+    await harness.handlers.get("before_agent_start")!(
+      { type: "before_agent_start", prompt: "list the files", systemPrompt: "", systemPromptOptions: {} },
+      harness.ctx,
+    );
+    await harness.handlers.get("turn_end")!({ type: "turn_end" }, harness.ctx);
+    const events = recordedLines(dir).map((line) => JSON.parse(line));
+    const prompt = events.find((e) => e.hook_event_name === "UserPromptSubmit");
+    const stop = events.find((e) => e.hook_event_name === "Stop");
+    assert.equal(prompt.prompt, "list the files");
+    assert.ok(stop);
+  });
+});
+
+function recordedArgv(dir: string): string[][] {
+  const file = `${join(dir, "record.jsonl")}.argv`;
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((line) => line !== "")
+    .map((line) => JSON.parse(line) as string[]);
+}
+
+describe("auto-start on gated session start", () => {
+  it("passes --ensure-runtime and --config from APPA_CONFIG", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    process.env.APPA_CONFIG = "/tmp/playground/appa.toml";
+    const harness = await loadExtension();
+    await startSession(harness);
+    const first = recordedArgv(dir)[0];
+    assert.ok(first?.includes("--ensure-runtime"), `argv: ${JSON.stringify(first)}`);
+    const configIndex = first?.indexOf("--config");
+    assert.notEqual(configIndex, -1);
+    assert.equal(first?.[Number(configIndex) + 1], "/tmp/playground/appa.toml");
+  });
+
+  it("omits --config when APPA_CONFIG is unset", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    delete process.env.APPA_CONFIG;
+    const harness = await loadExtension();
+    await startSession(harness);
+    const first = recordedArgv(dir)[0];
+    assert.ok(first?.includes("--ensure-runtime"));
+    assert.ok(!first?.includes("--config"));
+  });
+
+  it("starts nothing when ungated", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    delete process.env.APPA_GATE;
+    delete process.env.APPA_CONFIG;
+    const harness = await loadExtension();
+    await startSession(harness);
+    assert.deepEqual(recordedArgv(dir), []);
+    assert.deepEqual(recordedLines(dir), []);
+  });
+});
+
+describe("project-scoped protection (.pi/openappa)", () => {
+  it("gates the project and passes the marker's policy as --config", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    delete process.env.APPA_GATE;
+    delete process.env.APPA_CONFIG;
+    const proj = join(dir, "proj");
+    mkdirSync(join(proj, ".pi"), { recursive: true });
+    writeFileSync(join(proj, ".pi", "openappa"), "appa.toml\n");
+    const harness = await loadExtension(proj);
+    await startSession(harness);
+    const first = recordedArgv(dir)[0];
+    assert.ok(first?.includes("--ensure-runtime"), `argv: ${JSON.stringify(first)}`);
+    const index = first?.indexOf("--config");
+    assert.notEqual(index, -1);
+    assert.equal(first?.[Number(index) + 1], join(proj, "appa.toml"));
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(call, undefined);
+  });
+
+  it("empty marker content passes no --config", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    delete process.env.APPA_GATE;
+    delete process.env.APPA_CONFIG;
+    const proj = join(dir, "proj2");
+    mkdirSync(join(proj, ".pi"), { recursive: true });
+    writeFileSync(join(proj, ".pi", "openappa"), "");
+    const harness = await loadExtension(proj);
+    await startSession(harness);
+    const first = recordedArgv(dir)[0];
+    assert.ok(first?.includes("--ensure-runtime"));
+    assert.ok(!first?.includes("--config"));
+  });
+
+  it("explicit APPA_CONFIG wins over marker content", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    delete process.env.APPA_GATE;
+    process.env.APPA_CONFIG = "/tmp/env-policy.toml";
+    const proj = join(dir, "proj3");
+    mkdirSync(join(proj, ".pi"), { recursive: true });
+    writeFileSync(join(proj, ".pi", "openappa"), "appa.toml\n");
+    const harness = await loadExtension(proj);
+    await startSession(harness);
+    const first = recordedArgv(dir)[0];
+    const index = first?.indexOf("--config");
+    assert.equal(first?.[Number(index) + 1], "/tmp/env-policy.toml");
+  });
+});
+
+describe("always-on mode (marker file)", () => {
+  it("gates every session once the marker exists", 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);
+    assert.equal(call, undefined);
+    assert.ok(recordedArgv(dir).length > 0, "hook was invoked without APPA_GATE");
+  });
+
+  it("inert when the marker is absent", async () => {
+    const dir = workDir();
+    withMock(dir, "allow");
+    delete process.env.APPA_GATE;
+    process.env.XDG_CONFIG_HOME = join(dir, "xdg-clean");
+    const harness = await loadExtension();
+    await startSession(harness);
+    const call = await harness.handlers.get("tool_call")!(bashCall, harness.ctx);
+    assert.equal(call, undefined);
+    assert.deepEqual(recordedArgv(dir), []);
+  });
+});
+
+describe("/appa on|off", () => {
+  it("on creates the marker and gates immediately; off removes it", async () => {
+    const dir = workDir();
+    process.env.XDG_CONFIG_HOME = join(dir, "xdg");
+    delete process.env.APPA_GATE;
+    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);
+    assert.ok(!existsSync(join(dir, "xdg", "pi-openappa", "always-on")));
+  });
+
+  it("status completes without a runtime", async () => {
+    const dir = workDir();
+    process.env.XDG_CONFIG_HOME = join(dir, "xdg2");
+    process.env.APPA_RUNTIME_URL = "http://127.0.0.1:8799";
+    const harness = await loadExtension();
+    await startSession(harness);
+    await harness.commands.get("appa")!.handler("status", harness.ctx);
+  });
+});
+
+describe("/appa command", () => {
+  it("reports protection state without a runtime", async () => {
+    const dir = workDir();
+    delete process.env.APPA_GATE;
+    process.env.APPA_RUNTIME_URL = "http://127.0.0.1:8799";
+    const harness = await loadExtension();
+    await startSession(harness);
+    const command = harness.commands.get("appa");
+    assert.ok(command, "/appa registered");
+    // No UI in this harness; the handler must still complete without throwing.
+    await command.handler("", harness.ctx);
+  });
+});