localpi 0.5.2 → 0.6.1

package/dist/src/pi/extension-sources/tool-approval.js

@@ -1,45 +1,186 @@
-export function approvalExtensionSource() {
-    return `import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { settingsFileSource } from "./settings-file.js";
+export function approvalExtensionSource(config) {
+    const initialEnabledSource = JSON.stringify(config.enabled);
+    const approveReadToolsSource = JSON.stringify(config.approveReadTools);
+    return `import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type PermissionMode = "ask" | "allow";
+
+type CommandContext = {
+  readonly hasUI: boolean;
+  readonly ui: {
+    setStatus(key: string, text: string | undefined): void;
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+    select(title: string, options: string[]): Promise<string | undefined>;
+  };
+};
+
+const approvalRule =
+  "\\n\\nTool approval rule: if any tool result says the tool was blocked, denied, or requires approval, the tool did not run. Do not claim blocked tools ran.";
+const modes: readonly PermissionMode[] = ["ask", "allow"];
+const aliases: readonly string[] = ["on", "off"];
+// Read-only Pi tools cannot change the workspace, so the gate lets them run. bash is not in this
+// list, because a bash command can write. An unknown tool also stays behind the gate.
+const readOnlyTools: readonly string[] = ["read", "grep", "find", "ls"];
+const statusKey = "localpi-approval";
+const allowOnce = "Allow once";
+const allowSession = "Allow all tools for this session";
+const deny = "Deny and stop";
+const blockedReason = "Tool call was blocked by the user and did not run.";
+const noUiReason = " was blocked and did not run because interactive approval is required.";
+// A deny stops the turn instead of letting the model try again. Pi terminates the turn when every
+// blocked result in the tool batch asks for it, and a cancelled dialog counts as a deny.
+// The permission setting is the launch default for new sessions. The /approval command writes it;
+// the session-only choice in the tool call dialog never writes it.
+${settingsFileSource(config.settingsPath)}
+const initialEnabled: boolean = ${initialEnabledSource};
+const gateReadTools: boolean = ${approveReadToolsSource};
 
 export default function localpiToolApproval(pi: ExtensionAPI): void {
+  let enabled = initialEnabled;
+
   pi.on("before_agent_start", (event) => ({
-    systemPrompt:
-      event.systemPrompt +
-      "\\n\\nTool approval rule: if any tool result says the tool was blocked, denied, or requires approval, the tool did not run. Do not claim blocked tools ran."
+    systemPrompt: event.systemPrompt + approvalRule
   }));
 
+  pi.on("session_start", (_event, ctx) => {
+    showStatus(ctx);
+  });
+
+  pi.registerCommand("approval", {
+    description: "Choose whether tool calls ask for approval",
+    getArgumentCompletions: (prefix: string) => {
+      const trimmed = prefix.trim().toLowerCase();
+      const names = [...modes, ...aliases];
+      const matches = names.filter((name) => name.startsWith(trimmed));
+      return matches.length === 0 ? null : matches.map((name) => ({ value: name, label: name }));
+    },
+    handler: async (args: string, ctx: CommandContext) => {
+      const requested = parseMode(args);
+      if (requested !== undefined) {
+        await apply(requested, ctx, true);
+        return;
+      }
+      if (!ctx.hasUI) {
+        ctx.ui.notify(
+          "permission: " + label(enabled) + "; run localpi in a terminal to change it",
+          "info"
+        );
+        return;
+      }
+      const selected = await promptMode(enabled, ctx);
+      if (selected === undefined) {
+        return;
+      }
+      await apply(selected, ctx, true);
+    }
+  });
+
   pi.on("tool_call", async (event, ctx) => {
-    const input = formatInput(event.input);
+    if (!enabled) {
+      return undefined;
+    }
+
+    if (!gateReadTools && readOnlyTools.includes(event.toolName)) {
+      return undefined;
+    }
 
     if (!ctx.hasUI) {
       return {
         block: true,
-        reason: \`Tool call "\${event.toolName}" was blocked and did not run because interactive approval is required.\`
+        reason: 'Tool call "' + event.toolName + '"' + noUiReason,
+        terminate: true
       };
     }
 
-    const ok = await ctx.ui.confirm(\`Allow tool call: \${event.toolName}?\`, input);
-    if (!ok) {
-      return { block: true, reason: "Tool call was blocked by the user and did not run." };
+    const choice = await ctx.ui.select(
+      "Allow tool call: " + event.toolName + "?\\n" + previewInput(event.input),
+      [allowOnce, allowSession, deny]
+    );
+
+    if (choice === allowSession) {
+      await apply("allow", ctx, false);
+      return undefined;
+    }
+
+    if (choice !== allowOnce) {
+      return { block: true, reason: blockedReason, terminate: true };
     }
 
     return undefined;
   });
+
+  function showStatus(ctx: CommandContext): void {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus(statusKey, enabled ? undefined : "permission: allow");
+    }
+  }
+
+  async function apply(mode: PermissionMode, ctx: CommandContext, save: boolean): Promise<void> {
+    enabled = mode === "ask";
+    showStatus(ctx);
+    ctx.ui.notify(notification(mode, save), enabled ? "info" : "warning");
+    if (save) {
+      await persist(mode);
+    }
+  }
+}
+
+function notification(mode: PermissionMode, save: boolean): string {
+  const scope = save ? ", saved for new sessions" : " for this session";
+  return mode === "ask"
+    ? "permission: ask" + scope + "; tool calls ask before they run"
+    : "permission: allow" + scope + "; tool calls run without asking";
+}
+
+async function persist(mode: PermissionMode): Promise<void> {
+  const settings = await readSettings();
+  settings["permission"] = mode;
+  await writeSettings(settings);
+}
+
+function label(enabled: boolean): PermissionMode {
+  return enabled ? "ask" : "allow";
+}
+
+function parseMode(value: string): PermissionMode | undefined {
+  const normalized = value.trim().split(/\\s+/u)[0]?.toLowerCase();
+  if (normalized === "on") {
+    return "ask";
+  }
+  if (normalized === "off") {
+    return "allow";
+  }
+  return modes.find((mode) => mode === normalized);
+}
+
+async function promptMode(
+  current: boolean,
+  ctx: CommandContext
+): Promise<PermissionMode | undefined> {
+  const currentMode = label(current);
+  const selected = await ctx.ui.select(
+    "Tool approval",
+    modes.map((mode) => (mode === currentMode ? mode + " (current)" : mode))
+  );
+  return selected === undefined ? undefined : parseMode(selected);
 }
 
-function formatInput(input: unknown): string {
+function previewInput(input: unknown): string {
   let text: string;
   try {
-    text = JSON.stringify(input, null, 2);
+    text = JSON.stringify(input, null, 2) ?? String(input);
   } catch {
     text = String(input);
   }
 
-  const maxLength = 4000;
+  const maxLength = 1200;
   if (text.length <= maxLength) {
     return text;
   }
-  return \`\${text.slice(0, maxLength)}\\n... truncated ...\`;
+  return text.slice(0, maxLength) + "\\n... truncated ...";
 }
 `;
 }

package/dist/src/pi/extensions.js

@@ -3,7 +3,9 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { localpiSettingsPath } from "../localpi/settings-state.js";
 import { resolveDemoPrompts } from "./demo.js";
+import { continueOnTruncationExtensionSource } from "./extension-sources/continue-on-truncation.js";
 import { startupModelSelectorExtensionSource } from "./extension-sources/startup-model-selector.js";
+import { statusLineExtensionSource } from "./extension-sources/status-line.js";
 import { thinkingControlExtensionSource } from "./extension-sources/thinking-control.js";
 import { tokenStatusExtensionSource } from "./extension-sources/token-status.js";
 import { approvalExtensionSource } from "./extension-sources/tool-approval.js";
@@ -26,16 +28,22 @@ export async function writeDefaultExtensions(options, extensionOptions = {}) {
         };
     }
     paths.push(await writeExtension(extensionDir, "thinking-control.ts", thinkingControlExtensionSource(localpiSettingsPath(options))));
-    if (options.approval) {
-        paths.push(await writeExtension(extensionDir, "tool-approval.ts", approvalExtensionSource()));
+    paths.push(await writeExtension(extensionDir, "tool-approval.ts", approvalExtensionSource({
+        enabled: options.approval,
+        settingsPath: localpiSettingsPath(options),
+        approveReadTools: options.approveReadTools
+    })));
+    if (options.continueOnTruncation > 0) {
+        paths.push(await writeExtension(extensionDir, "continue-on-truncation.ts", continueOnTruncationExtensionSource(options.continueOnTruncation)));
     }
-    if (options.tokenStatus) {
-        paths.push(await writeExtension(extensionDir, "token-status.ts", tokenStatusExtensionSource({ includeContext: !options.demo })));
+    if (options.stats !== "off") {
+        paths.push(await writeExtension(extensionDir, "token-status.ts", tokenStatusExtensionSource(tokenStatusConfig(options, extensionOptions.runtime))));
+        paths.push(await writeExtension(extensionDir, "status-line.ts", statusLineExtensionSource({ engines: extensionOptions.engines ?? [] })));
     }
     return {
         paths,
         env,
-        systemPrompt: localpiSystemPrompt(options.approval)
+        systemPrompt: localpiSystemPrompt()
     };
 }
 // Demo mode is the shared pi-demo-mode package (a git dependency), loaded
@@ -50,13 +58,32 @@ async function writeExtension(extensionDir, name, source) {
     await writeFile(extensionPath, source, "utf8");
     return extensionPath;
 }
-function localpiSystemPrompt(approval) {
+function tokenStatusConfig(options, runtime) {
+    return {
+        settingsPath: localpiSettingsPath(options),
+        mode: options.stats,
+        ...runtimeConfig(runtime)
+    };
+}
+// The managed llama-server and the built-in llama.cpp provider are both llama.cpp, and both
+// expose live prefill progress on /slots. Other engines fall back to elapsed-time prefill display.
+function runtimeConfig(runtime) {
+    if (runtime === undefined) {
+        return {};
+    }
+    const llamaCpp = runtime.providerId === "llama-cpp" || runtime.providerId === "llama-server";
+    return {
+        ...(llamaCpp ? { engine: "llama-cpp" } : {}),
+        baseUrl: runtime.baseUrl,
+        modelId: runtime.model
+    };
+}
+// The tool approval gate appends its own detailed rule. This base prompt keeps the same warning
+// when a user disables localpi extensions, and stays true whether approval is on or off.
+function localpiSystemPrompt() {
     return [
         "You are running through localpi, a local Pi launcher for local models.",
-        approval
-            ? "Tool calls require user approval. If a tool result says it was blocked, denied, or requires approval, the tool did not run."
-            : "Tool approval is disabled for this session.",
-        "Do not claim that a blocked tool call ran.",
+        "Tool calls may require user approval. Never claim that a tool call ran when its result says it was blocked or denied.",
         "Prefer answering directly when tools are not needed."
     ].join("\n");
 }

package/dist/src/pi/skills.js

@@ -0,0 +1,24 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+// Pi loads skills from shared directories such as ~/.agents/skills. A localpi session keeps its own
+// skills instead, so a small local model does not carry skill lists it cannot use.
+export function localpiSkillsDir(stateDir) {
+    return path.join(stateDir, "pi-skills");
+}
+export async function ensureLocalpiSkillsDir(options) {
+    const dir = localpiSkillsDir(options.stateDir);
+    if (options.skills === "own") {
+        await mkdir(dir, { recursive: true });
+    }
+    return dir;
+}
+export function localpiSkillsArgs(mode, stateDir) {
+    switch (mode) {
+        case "ambient":
+            return [];
+        case "off":
+            return ["--no-skills"];
+        case "own":
+            return ["--no-skills", "--skill", localpiSkillsDir(stateDir)];
+    }
+}

package/dist/src/pi/theme.js

@@ -0,0 +1,107 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { catppuccinMocha } from "../localpi/catppuccin.js";
+export const localpiThemeName = "catppuccin-mocha";
+const themeSchema = "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json";
+// Tool status cards need a dark surface with a visible success or failure cast. Both values are the
+// Catppuccin base surface tinted with green and red.
+const toolSuccessSurface = "#24352f";
+const toolErrorSurface = "#3b2633";
+export function localpiThemePath(stateDir) {
+    return path.join(stateDir, "pi-themes", `${localpiThemeName}.json`);
+}
+export function localpiThemeArgs(themePath, forwardedArgs) {
+    if (themePath === undefined) {
+        return [];
+    }
+    // The theme file is always loaded, so /settings can offer it. Catppuccin is only selected when
+    // the user did not ask for another theme in the same command line.
+    return hasForwardedFlag(forwardedArgs, "--use-theme")
+        ? ["--theme", themePath]
+        : ["--theme", themePath, "--use-theme", localpiThemeName];
+}
+export async function writeLocalpiTheme(stateDir, forwardedArgs) {
+    if (hasForwardedFlag(forwardedArgs, "--no-themes")) {
+        return undefined;
+    }
+    const themePath = localpiThemePath(stateDir);
+    await mkdir(path.dirname(themePath), { recursive: true });
+    await writeFile(themePath, catppuccinThemeSource(), "utf8");
+    return themePath;
+}
+export function catppuccinThemeSource() {
+    return `${JSON.stringify(catppuccinTheme(), null, 2)}\n`;
+}
+export function catppuccinTheme() {
+    return {
+        $schema: themeSchema,
+        name: localpiThemeName,
+        vars: { ...catppuccinMocha },
+        colors: {
+            accent: "lavender",
+            border: "surface2",
+            borderAccent: "blue",
+            borderMuted: "surface1",
+            success: "green",
+            error: "red",
+            warning: "peach",
+            muted: "subtext0",
+            dim: "overlay1",
+            text: "text",
+            thinkingText: "overlay2",
+            scrollbarTrack: "surface0",
+            scrollbarThumb: "overlay1",
+            selectedBg: "surface1",
+            searchMatchBg: "surface2",
+            searchMatchText: "text",
+            userMessageBg: "surface0",
+            userMessageText: "text",
+            customMessageBg: "mantle",
+            customMessageText: "text",
+            customMessageLabel: "mauve",
+            toolPendingBg: "mantle",
+            toolSuccessBg: toolSuccessSurface,
+            toolErrorBg: toolErrorSurface,
+            toolTitle: "blue",
+            toolOutput: "subtext0",
+            mdHeading: "peach",
+            mdLink: "blue",
+            mdLinkUrl: "overlay1",
+            mdCode: "teal",
+            mdCodeBlock: "green",
+            mdCodeBlockBorder: "surface2",
+            mdQuote: "subtext0",
+            mdQuoteBorder: "mauve",
+            mdHr: "surface2",
+            mdListBullet: "peach",
+            toolDiffAdded: "green",
+            toolDiffRemoved: "red",
+            toolDiffContext: "overlay2",
+            syntaxComment: "overlay1",
+            syntaxKeyword: "mauve",
+            syntaxFunction: "blue",
+            syntaxVariable: "lavender",
+            syntaxString: "green",
+            syntaxNumber: "peach",
+            syntaxType: "yellow",
+            syntaxOperator: "sky",
+            syntaxPunctuation: "overlay2",
+            thinkingOff: "overlay0",
+            thinkingMinimal: "overlay1",
+            thinkingLow: "sapphire",
+            thinkingMedium: "blue",
+            thinkingHigh: "mauve",
+            thinkingXhigh: "pink",
+            thinkingMax: "red",
+            bashMode: "green"
+        },
+        export: {
+            pageBg: "#11111b",
+            cardBg: "#1e1e2e",
+            infoBg: "#313244"
+        }
+    };
+}
+function hasForwardedFlag(args, flag) {
+    return args.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+}

package/docs/2026-06-16-startup-model-and-thinking-control-plan.md

@@ -93,16 +93,39 @@ Startup defaults:
 
 In-session control:
 
-- Localpi provides a Pi extension command named `/thinking`.
-- `/thinking` opens Pi's selector UI.
-- `/thinking high` sets the level directly.
-- The extension calls Pi's thinking API, so Pi owns runtime mutation.
-- The extension saves the actual Pi thinking level to localpi state for the next launch.
-
-Managed `llama-server` caveat:
-
-- Server-side reasoning budget is still chosen at startup.
-- Changing the server-side budget later would require restarting the local server process.
+- Pi provides the `/thinking` command. Pi owns runtime mutation of the thinking level.
+- The localpi extension saves the actual Pi thinking level to localpi state for the next launch.
+
+Superseded: localpi first registered its own `/thinking` extension command. Pi already owns that
+name, so Pi skipped the localpi command in autocomplete. Localpi now keeps only the persistence
+hooks (`thinking_level_select` and `session_shutdown`) and leaves the command to Pi.
+
+Managed `llama-server` thinking budget:
+
+A reasoning model can loop in its thinking and never answer. The managed server bounds that by
+cutting the thinking at a token budget and forcing the end-of-thinking tag, so the turn still
+produces an answer.
+
+- Server-side reasoning budget is still chosen at startup. Changing it later restarts the
+  localpi-owned server process.
+- Thinking levels map to token budgets: `off` passes `--reasoning off` and no budget, `minimal` 32,
+  `low` 128, `medium` 512, `high` 2048, and `xhigh` 16384.
+- `--thinking-budget <n>` and `LOCALPI_THINKING_BUDGET` set the budget directly. `-1` means
+  unrestricted, and a positive value replaces the budget of the level table. Any other value fails
+  with a clear message.
+- When the budget is finite, localpi passes a default message that the server injects before the
+  end-of-thinking tag, so the model knows why the thinking stopped. `--thinking-budget-message
+<text>` and `LOCALPI_THINKING_BUDGET_MESSAGE` reword that default, and an empty value passes no
+  message flag at all.
+- The message override is optional text with no validation, so the default still has its escape
+  hatch and a model that needs different wording can get it.
+- The engine detects the thinking tags from the model template. Localpi does not hardcode a tag, and
+  it does not pass reasoning effort levels that the template rejects.
+- The managed server metadata records the reasoning mode, the budget, and the message. A changed
+  value restarts the owned server, as the budget check already does.
+- The reasoning translation stays in the `llama-server` adapter. There is no engine-agnostic
+  reasoning layer, because localpi starts only the managed `llama-server`; LM Studio and vLLM are
+  external servers that localpi only connects to.
 
 ## Implementation Checklist
 
@@ -112,10 +135,15 @@ Managed `llama-server` caveat:
 - [x] Pass the launch-time catalog into generated Pi model config.
 - [x] Keep `/model` owned by Pi.
 - [x] Add reasoning and thinking-format metadata for known local reasoning models.
-- [x] Add `/thinking` as a Pi extension command.
+- [x] Add `/thinking` as a Pi extension command. Superseded: Pi owns the name, so the extension now only remembers the level.
 - [x] Keep startup thinking non-interactive.
 - [x] Keep `--thinking` and `LOCALPI_THINKING` as automation-safe startup controls.
 - [x] Remember the last Pi thinking level for future localpi launches.
+- [x] Add `--thinking-budget` and `LOCALPI_THINKING_BUDGET` for the managed `llama-server`.
+- [x] Inject a default message before the end-of-thinking tag when the budget is finite.
+- [x] Add `--thinking-budget-message` and `LOCALPI_THINKING_BUDGET_MESSAGE` to reword the message, or to pass none.
+- [x] Record the reasoning mode, the budget, and the message in the managed server metadata.
+- [x] Test the level table, the budget override, an invalid value, and the restart trigger.
 - [ ] Manually verify model picker behavior in an interactive terminal with multiple loaded providers.
 - [ ] Manually verify Pi `/model` can switch among generated catalog entries.
 - [ ] Manually verify Pi `/thinking` picker and direct `/thinking <level>` command.

package/docs/2026-09-23-acp-mode-plan.md

@@ -0,0 +1,111 @@
+# Plan: ACP mode for localpi
+
+Date: 2026-09-23
+Status: selected for implementation
+
+## Goal
+
+Make localpi able to act as an ACP agent. Add `localpi --acp` (and
+`LOCALPI_ACP=1`) that resolves and writes the same Pi configuration a normal
+launch writes, then starts the ACP server on stdio and gets out of the way. Pin
+`pi-acp` as a dependency instead of vendoring its source.
+
+## Why
+
+`pi-acp` is the maintained ACP adapter for Pi (owner `svkozak`, MIT, npm
+`pi-acp@0.0.33`, published with provenance). localpi already owns model
+resolution, Pi configuration, and launching. Adding ACP on top of that turns
+localpi into an agent that ACP clients can drive, including the Harbor harness,
+so a benchmark can measure this launcher instead of a purpose-built adapter.
+
+## Verified facts
+
+These were read from the pinned sources, not assumed.
+
+- `pi-acp` spawns Pi as `pi --mode rpc --no-themes`, plus `--session <path>`
+  when a session path exists, and passes the current environment to the child.
+- `pi-acp` uses `PI_ACP_PI_COMMAND` as the executable name, so localpi can point
+  it at the Pi it resolved.
+- `pi-acp` reads settings from `$PI_CODING_AGENT_DIR/settings.json` and from
+  `<cwd>/.pi/settings.json`, and it does not pass `--no-extensions`, so Pi
+  extension discovery stays enabled.
+- localpi is at version 0.5.2, is a strict TypeScript CLI, and declares
+  `@osolmaz/pi-factory` and `pi-demo-mode` as its only dependencies. Its bin is
+  `localpi` mapped to `dist/src/cli/main.js`.
+- localpi has no ACP support today. A search for ACP over its source, docs,
+  README, and manifest returns only `llamaCpp` substrings.
+- localpi already forwards `--mode` to Pi and only rejects it together with
+  `--demo`.
+- Pi has no ACP mode of its own, so the ACP server must be a separate process.
+
+## Design
+
+1. Pin, do not vendor. Add `pi-acp` to `dependencies` at a fixed version with a
+   lockfile entry. Do not copy its source into this repository.
+2. One new entry path. `localpi --acp` and `LOCALPI_ACP=1` start the ACP server.
+   Follow the existing precedence: flag, environment, saved setting, default.
+   The default stays a normal launch, so nothing changes for current users.
+3. Configure first, then hand off. Run the existing resolution and Pi config
+   writing, then start the pinned `pi-acp` with inherited stdio. Reuse the
+   existing resolution path. Do not duplicate discovery or config writing.
+4. No interactive selection in ACP mode. There is no TTY, so require an explicit
+   model from the flag, environment, or model profile, and fail with a clear
+   message when none is given. Never print a picker.
+5. Keep stdout pure. In ACP mode, stdout carries protocol bytes only. Send
+   diagnostics, warnings, and startup notes to stderr. Add a test that fails if
+   anything else reaches stdout.
+6. Point the adapter at the resolved Pi. Set `PI_ACP_PI_COMMAND` to the Pi
+   executable localpi would launch, and pass the same environment the normal
+   launch uses: the Pi config directory, provider base URL, the API key name,
+   the thinking level, and the session directory.
+7. Do not select ACP again inside the child. The ACP path must set the adapter
+   command to Pi itself, never back to localpi, so a spawned child cannot
+   re-enter ACP mode. Add a test for that.
+8. Keep the existing rules. Settings stay in `<state-dir>/settings.json`. Model
+   profile limits (`client.context_window`, `client.max_tokens`) and the managed
+   llama-server thinking budget keep their current meaning. Never invent a
+   smaller reply cap than the declared one.
+
+## Deliverables
+
+- `localpi --acp` and `LOCALPI_ACP=1`, implemented in the existing launcher
+  structure with the ACP start kept in its own module.
+- `pi-acp` pinned in `package.json` and the lockfile.
+- Unit tests with a fake ACP child: correct command and environment, pure
+  stdout, a clear failure when no explicit model is given, exit-code
+  propagation, and no re-entry into ACP mode.
+- A README section for ACP mode and an entry in
+  `docs/runtime-specification.md`.
+
+## Acceptance checks
+
+1. `npm run check` passes, including the generated-extension typecheck test.
+2. `localpi --acp` with a fake adapter child starts it with the expected
+   environment, and stdout carries only protocol bytes.
+3. `localpi --acp` without an explicit model fails fast with one clear message
+   and no picker.
+4. A normal launch, without the ACP flag, behaves exactly as before.
+5. No new state file appears; every new setting lives in the settings object.
+
+## Out of scope
+
+- Harbor manifests, harness wheels, and benchmark arms. Those belong to
+  `osolmaz/harbor-custom-harnesses`.
+- Vendoring `pi-acp` source, or building anything from source.
+- Publishing to npm, merging, or any release. Those need a separate instruction.
+- Real model inference in tests.
+
+## Authority
+
+- Repository: `osolmaz/localpi` only.
+- Allowed: edit, test, commit, push, open a pull request.
+- Not allowed: merge without an explicit instruction, publish a package or a
+  release, install or copy credentials, run paid remote work, or push to another
+  repository.
+
+## Risks
+
+- Two Pi processes could blink in and out if the adapter command ever points
+  back at localpi. The re-entry test covers this.
+- Any startup chatter on stdout breaks the protocol handshake, so the purity
+  test is part of the gate, not an afterthought.