pi-better-harness 0.1.26 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 # pi-better-harness
 
-`pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions: a default-on write sandbox, delegated subagents, durable background tasks, and goal tracking.
+`pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions: an opt-in foreground write sandbox, delegated subagents, durable background tasks, and goal tracking.
 
 ## Quick Answer
 
 Use `pi-better-harness` when you want the full working set for Pi. It manages:
 
-- `pi-better-sandbox` for a default-on write sandbox around Pi's foreground tools.
+- `pi-better-sandbox` for an opt-in write sandbox around Pi's foreground tools.
 - `pi-better-subagents` for detached, sandboxed subagent runs.
 - `pi-better-background-tasks` for durable shell tasks and watchers.
 - `pi-better-goal` for objective tracking that is aware of background work.
@@ -45,13 +45,18 @@ You keep launching Pi the way you always have:
 pi
 ```
 
-The write sandbox arms itself at every session start — startup, new session, resume, fork, and reload. There is no launcher and no settings file to create.
+The foreground write sandbox starts inactive. Use `/sandbox on` for the current
+session or `/sandbox default on` to persist opt-in across startup, new session,
+resume, fork, and reload. There is no launcher.
 
 While it is on, Pi's built-in `bash`, `write`, and `edit` tools, your own `!` / `!!` commands, local background tasks, and subagents can write only under the directory you launched Pi from, minus the packaged deny paths (`.git/hooks`, `.env`, `.env.local`).
 
 **Reads and network access are unrestricted** — this sandbox limits writes only. Writes are confined for those integrated first-party execution paths; Pi's own process, arbitrary `pi.exec` calls, and unrelated third-party extension code are **not** confined. Confinement is also **per surface**: each integrated surface denies its own control plane, not every other surface's, so with several first-party surfaces installed a confined process on one can still write another's control plane.
 
-Sandbox state is human-only: `/sandbox`, `/sandbox on`, `/sandbox off`, `/sandbox deny ...`, and `/sandbox rules` are slash commands with no tool equivalent, so the model cannot turn off its own confinement. `/sandbox off` needs an interactive confirmation and never persists past the session. Full policy: [pi-better-sandbox](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme).
+Sandbox state is human-only: `/sandbox`, `/sandbox on`, `/sandbox off`,
+`/sandbox default on|off`, `/sandbox deny ...`, and `/sandbox rules` are slash
+commands with no tool equivalent. `/sandbox off` and `/sandbox default off`
+need interactive confirmation. Full policy: [pi-better-sandbox](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme).
 
 ## When To Use
 

package/lib/cli.mjs

@@ -7,8 +7,8 @@ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const { version } = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
 
 export const componentPackages = [
-  // The sandbox is configured first so a fresh install has write protection in
-  // place before the extensions whose work it confines.
+  // The foreground policy publisher is configured before the extensions that
+  // consume its active or inactive launch decision.
   "pi-better-sandbox",
   "pi-better-subagents",
   "pi-better-background-tasks",

package/node_modules/pi-better-background-tasks/README.md

@@ -27,8 +27,10 @@ the effective foreground policy at launch and runs under the platform's write
 sandbox: reads and network stay unrestricted, writes are confined to the
 canonical project directory, and denied paths stay denied.
 
-The policy is captured once, when the task starts. A later `/sandbox on`,
-`/sandbox off`, or deny-rule change reaches tasks launched after it; a task
+The policy is captured once, when the task starts. The foreground sandbox is
+inactive by default, so local tasks ordinarily launch unconfined. A later
+`/sandbox on`, `/sandbox off`, `/sandbox default on|off`, or a deny-rule change
+reaches tasks launched after it; a task
 already running — including a watcher resumed in a later Pi session — keeps the
 policy it started with.
 
@@ -45,8 +47,8 @@ process, `pi.exec` calls, and unrelated third-party extension code stay outside
 the guarantee, and confinement is per surface: a confined process on another
 first-party surface can still write this one's task registry. Installing
 [`pi-better-harness`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-harness#readme)
-brings the sandbox in by default, so an ordinary `pi` session confines its
-foreground tools and its local background tasks under one project policy.
+installs the sandbox extension, but leaves foreground tools and local background
+tasks inactive until a human opts in.
 
 ## Remote SSH
 

package/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-background-tasks/src/sandbox.ts

@@ -12,10 +12,10 @@
  *    argv are resolved once, when the task starts, and are what the task keeps
  *    running. A later `/sandbox off` or deny-rule change therefore reaches only
  *    tasks launched after it.
- * 2. **Fail closed.** Once the foreground state says a sandbox should apply, a
- *    missing or unusable backend blocks the launch. The local command is never
- *    retried unconfined behind the operator's back. The single exception is an
- *    explicitly `disabled` state, which is a human's deliberate decision.
+ * 2. **Opt-in, then fail closed.** `inactive` and explicitly `disabled` states
+ *    launch unconfined. Once foreground policy says confinement applies, a
+ *    missing or unusable backend blocks the launch and is never retried
+ *    unconfined behind the operator's back.
  *
  * The contract is duplicated here rather than imported: `pi-better-sandbox` is
  * an optional peer that this package must keep working without. Two channel
@@ -53,12 +53,13 @@ export const FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL = "pi-better-sandbox:poli
 /**
  * What the foreground sandbox is doing right now.
  *
+ * - `inactive`    - default-off foreground policy; launch tasks as before.
  * - `enabled`     - confine locally launched tasks.
  * - `disabled`    - a human switched protection off; launch tasks as before.
  * - `unavailable` - no backend on this platform; block protected launches.
  * - `failed`      - protection cannot be applied here; block protected launches.
  */
-export type ForegroundSandboxState = "enabled" | "disabled" | "unavailable" | "failed";
+export type ForegroundSandboxState = "inactive" | "enabled" | "disabled" | "unavailable" | "failed";
 
 /** The published snapshot, narrowed to the fields a task launch needs. */
 export interface ForegroundSandboxPolicy {
@@ -101,7 +102,7 @@ export type ForegroundSandboxPlan =
 
 const UNCONFINED: ForegroundSandboxPlan = { confined: false };
 
-const VALID_STATES = new Set<string>(["enabled", "disabled", "unavailable", "failed"]);
+const VALID_STATES = new Set<string>(["inactive", "enabled", "disabled", "unavailable", "failed"]);
 
 /**
  * The latest snapshot per event bus.
@@ -183,8 +184,8 @@ export function currentForegroundSandboxPolicy(pi: unknown): ForegroundSandboxPo
  * Decide how a local launch must be confined, before the task has an id, a
  * directory, or a log.
  *
- * Throws for every state that is neither confinable nor a human's explicit
- * opt-out, which is what keeps a blocked launch from leaving task state behind.
+ * Throws for every state that is neither confinable nor intentionally
+ * unconfined, which keeps a blocked launch from leaving task state behind.
  */
 export function resolveForegroundSandboxPlan(pi: unknown): ForegroundSandboxPlan {
   return planFor(currentForegroundSandboxPolicy(pi));
@@ -195,7 +196,7 @@ export function planFor(policy: ForegroundSandboxPolicy | undefined): Foreground
   // No sandbox extension is publishing: this package is installed on its own and
   // keeps its historical unsandboxed behaviour.
   if (!policy) return UNCONFINED;
-  if (policy.state === "disabled") return UNCONFINED;
+  if (policy.state === "inactive" || policy.state === "disabled") return UNCONFINED;
   if (policy.state !== "enabled" || !policy.writableRoot) {
     throw new ForegroundSandboxBlockedError(policy);
   }

package/node_modules/pi-better-sandbox/README.md

@@ -1,6 +1,6 @@
 # pi-better-sandbox
 
-A default-on write sandbox for Pi's foreground tools.
+An opt-in write sandbox for Pi's foreground tools.
 
 It is installed by default with [`pi-better-harness`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-harness#readme), and can be installed on its own:
 
@@ -9,11 +9,12 @@ pi install npm:pi-better-sandbox
 ```
 
 Either way you keep starting Pi the way you always have — `pi`. There is
-no launcher, no wrapper command, and nothing to configure. From the first
-session start, Pi's built-in `bash` tool and the `!` / `!!` commands you type
-yourself run inside an OS sandbox that lets them write only under the directory
-you launched Pi from, and the built-in `write` and `edit` tools are held to the
-same policy.
+no launcher or wrapper command. The sandbox starts inactive. Use `/sandbox on`
+for the current session or `/sandbox default on` to persist opt-in. While
+enabled, Pi's built-in `bash` tool and the `!` / `!!` commands you type yourself
+run inside an OS sandbox that lets them write only under the directory you
+launched Pi from, and the built-in `write` and `edit` tools are held to the same
+policy.
 
 ```
 Read:       every filesystem path
@@ -71,8 +72,10 @@ operations underneath them are replaced.
 
 ```text
 /sandbox                     show the effective status
-/sandbox on                  re-arm protection for operations started from now on
+/sandbox on                  enable protection for operations started from now on
 /sandbox off                 turn protection off for this session (interactive confirmation)
+/sandbox default on          persist opt-in and enable it now
+/sandbox default off         persist opt-out (interactive confirmation)
 /sandbox deny list           show the write-denied paths
 /sandbox deny add <path>     stop allowing writes to a path
 /sandbox deny remove <path>  allow writes to a path again
@@ -80,15 +83,17 @@ operations underneath them are replaced.
 /sandbox rules               open the write-denied paths editor
 ```
 
-The footer shows `sandbox · on · <project>` while protection is active, and a
-prominent `sandbox · OFF`, `sandbox · UNAVAILABLE`, or `sandbox · FAILED`
-otherwise. Both surfaces report what the runtime actually resolved — which
-backend, which executable — never what was merely configured.
+The footer shows `sandbox · available` when a backend is available but inactive,
+`sandbox · inactive` when inactive without a backend, and
+`sandbox · on · <project>` while protection is active. Explicitly enabled
+sessions report `UNAVAILABLE` or `FAILED` when protection cannot be applied.
+Both surfaces report what the runtime actually resolved — which backend, which
+executable — never what was merely configured.
 
-`/sandbox off` needs an interactive confirmation and is refused outright when
-there is no interactive UI. There is no tool for changing sandbox state or its
-rules, so the model can neither disable its own confinement nor edit the paths
-it is confined away from.
+`/sandbox off` and `/sandbox default off` need interactive confirmation and are
+refused outright when there is no interactive UI. There is no tool for changing
+sandbox state or its rules, so the model cannot change confinement or edit the
+paths it is confined away from.
 
 ## Write-denied paths
 
@@ -158,17 +163,19 @@ in your rule set but is held out in that project, with a message saying so.
 
 ## Lifecycle
 
-The sandbox is enabled again at every session start: startup, new session,
-resume, fork, and reload. An off state is never written anywhere, so it cannot
-outlive the session you switched it off in.
+The foreground sandbox is inactive by default. Session overrides do not survive
+startup, new session, resume, fork, or reload. `/sandbox default on|off` stores
+the default for those future sessions in
+`~/.pi/agent/extensions/pi-better-sandbox-preferences.json`.
 
 Toggles apply to operations launched after the change. A command already running
 keeps the policy it launched with.
 
 ## Fail-closed behaviour
 
-While the sandbox is enabled and a backend cannot be applied, protected commands
-and file mutations are **blocked** rather than run unprotected:
+While the sandbox is explicitly or persistently enabled and a backend cannot be
+applied, protected commands and file mutations are **blocked** rather than run
+unprotected:
 
 - No backend on this platform (`unavailable`).
 - A launch directory too broad to confine — `/` or your home directory

package/node_modules/pi-better-sandbox/commands.ts

@@ -26,13 +26,15 @@ import type { ForegroundSandboxController, ForegroundSandboxStatus } from "./sta
 export const SANDBOX_COMMAND_NAME = "sandbox";
 
 export const SANDBOX_COMMAND_DESCRIPTION =
-    "Show the foreground write sandbox, turn it on or off for this session, or manage write-denied paths";
+    "Show the foreground write sandbox, change session or persistent activation, or manage write-denied paths";
 
 const USAGE = [
     "Usage:",
     "  /sandbox",
     "  /sandbox on",
     "  /sandbox off",
+    "  /sandbox default on",
+    "  /sandbox default off",
     "  /sandbox deny list",
     "  /sandbox deny add <path>",
     "  /sandbox deny remove <path>",
@@ -52,12 +54,20 @@ const DISABLE_TITLE = "Disable the foreground write sandbox?";
 
 const DISABLE_MESSAGE = [
     "The built-in bash, write, and edit tools and user-entered ! / !! commands",
-    "will run with normal host write access for the rest of this session. New,",
-    "resumed, forked, and reloaded sessions start protected again.",
+    "will run with normal host write access for the rest of this session. The",
+    "next session applies your persisted foreground sandbox default.",
 ].join("\n");
 
 const NO_UI_REJECTION =
-    "/sandbox off needs an interactive confirmation and there is no interactive UI here, so the sandbox stays on.";
+    "/sandbox off needs an interactive confirmation and there is no interactive UI here, so the sandbox state is unchanged.";
+
+const DEFAULT_OFF_TITLE = "Keep the foreground write sandbox off by default?";
+
+const DEFAULT_OFF_MESSAGE = [
+    "This session and future sessions will run foreground tools and local background",
+    "tasks with normal host write access until you run /sandbox on or change the",
+    "persistent default.",
+].join("\n");
 
 const RESET_TITLE = "Restore the packaged write-deny defaults?";
 
@@ -67,6 +77,8 @@ export type SandboxCommandDeps = {
     denyRules: DenyRuleManager;
     /** Called after any state change so the footer and consumers stay truthful. */
     onStateChange: (status: ForegroundSandboxStatus) => void;
+    /** Persist a default and apply it to the current session. */
+    setDefault: (enabled: boolean) => ForegroundSandboxStatus;
 };
 
 /** Build the `/sandbox` handler. Exported so its behaviour is directly testable. */
@@ -74,6 +86,7 @@ export function createSandboxCommandHandler({
     controller,
     denyRules,
     onStateChange,
+    setDefault,
 }: SandboxCommandDeps) {
     return async function handleSandboxCommand(
         args: string,
@@ -97,13 +110,20 @@ export function createSandboxCommandHandler({
             ctx.ui.notify(
                 status.state === "enabled"
                     ? `Foreground sandbox on. ${status.reason}`
-                    : `Foreground sandbox re-armed but not active: ${status.reason}`,
+                    : `Foreground sandbox requested but not active: ${status.reason}`,
                 status.state === "enabled" ? "info" : "warning",
             );
             return;
         }
 
         if (subcommand === "off") {
+            if (controller.status().state === "inactive") {
+                ctx.ui.notify(
+                    "Foreground sandbox is already inactive by default. Use /sandbox default on to opt in persistently.",
+                    "info",
+                );
+                return;
+            }
             if (!ctx.hasUI) {
                 ctx.ui.notify(NO_UI_REJECTION, "error");
                 return;
@@ -122,6 +142,44 @@ export function createSandboxCommandHandler({
             return;
         }
 
+        if (subcommand === "default") {
+            const mode = tail[0]?.toLowerCase();
+            if (mode !== "on" && mode !== "off") {
+                ctx.ui.notify("/sandbox default needs on or off.\n\n" + USAGE, "error");
+                return;
+            }
+            if (mode === "off") {
+                if (!ctx.hasUI) {
+                    ctx.ui.notify(
+                        "/sandbox default off needs an interactive confirmation and there is no interactive UI here.",
+                        "error",
+                    );
+                    return;
+                }
+                const confirmed = await ctx.ui.confirm(DEFAULT_OFF_TITLE, DEFAULT_OFF_MESSAGE);
+                if (!confirmed) {
+                    ctx.ui.notify("The sandbox default was left unchanged.", "info");
+                    return;
+                }
+            }
+            try {
+                const status = setDefault(mode === "on");
+                onStateChange(status);
+                ctx.ui.notify(
+                    mode === "on"
+                        ? `Foreground sandbox default is ON. ${status.reason}`
+                        : "Foreground sandbox default is off. Foreground tools and local background tasks are unconfined.",
+                    mode === "on" && status.state !== "enabled" ? "warning" : "info",
+                );
+            } catch (error) {
+                ctx.ui.notify(
+                    `Could not save the sandbox default: ${error instanceof Error ? error.message : String(error)}`,
+                    "error",
+                );
+            }
+            return;
+        }
+
         if (subcommand === "deny") {
             await handleDeny(denyRules, ctx, tail[0]?.toLowerCase() ?? "list", rest);
             return;
@@ -195,20 +253,27 @@ function announce(ctx: ExtensionCommandContext, change: () => DenyRuleReport): v
     }
 }
 
-const SUBCOMMANDS = ["on", "off", "deny", "rules"] as const;
+const SUBCOMMANDS = ["on", "off", "default", "deny", "rules"] as const;
 const DENY_ACTIONS = ["list", "add", "remove", "reset"] as const;
 
 /** Argument completions for `/sandbox`, including the `deny` actions. */
 export function sandboxArgumentCompletions(argumentPrefix: string) {
     const prefix = argumentPrefix.trimStart().toLowerCase();
     const denyPrefix = /^deny(\s|$)/.test(prefix) ? prefix.replace(/^deny\s*/, "") : undefined;
+    const defaultPrefix = /^default(\s|$)/.test(prefix)
+        ? prefix.replace(/^default\s*/, "")
+        : undefined;
 
     const values =
-        denyPrefix === undefined
-            ? SUBCOMMANDS.filter((value) => value.startsWith(prefix))
-            : DENY_ACTIONS.filter((value) => value.startsWith(denyPrefix)).map(
+        denyPrefix !== undefined
+            ? DENY_ACTIONS.filter((value) => value.startsWith(denyPrefix)).map(
                   (value) => `deny ${value}`,
-              );
+              )
+            : defaultPrefix !== undefined
+              ? ["on", "off"]
+                    .filter((value) => value.startsWith(defaultPrefix))
+                    .map((value) => `default ${value}`)
+              : SUBCOMMANDS.filter((value) => value.startsWith(prefix));
 
     return values.map((value) => ({ value, label: value }));
 }

package/node_modules/pi-better-sandbox/events.ts

@@ -21,12 +21,24 @@ export const FOREGROUND_SANDBOX_POLICY_CHANNEL = "pi-better-sandbox:policy";
 /** Channel a late-loading consumer emits on to ask for the current policy. */
 export const FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL = "pi-better-sandbox:policy-request";
 
-/** The immutable payload published on the policy channel. */
-export type ForegroundSandboxPolicyEvent = ForegroundSandboxStatus;
+/**
+ * The immutable payload published on the policy channel.
+ *
+ * `inactive` is a foreground presentation state. Consumers only need the
+ * enforcement decision, so it is published as the existing `disabled` state.
+ * This keeps older background-task versions fail-safe during package skew.
+ */
+export type ForegroundSandboxPolicyEvent = Omit<ForegroundSandboxStatus, "state"> & {
+    readonly state: Exclude<ForegroundSandboxStatus["state"], "inactive">;
+};
 
 /** Deep-freeze a status so a consumer cannot mutate another consumer's copy. */
 export function freezePolicy(status: ForegroundSandboxStatus): ForegroundSandboxPolicyEvent {
-    return Object.freeze({ ...status, denyWrite: Object.freeze([...status.denyWrite]) });
+    return Object.freeze({
+        ...status,
+        state: status.state === "inactive" ? "disabled" : status.state,
+        denyWrite: Object.freeze([...status.denyWrite]),
+    });
 }
 
 /** Publish the current effective policy to every subscribed extension. */

package/node_modules/pi-better-sandbox/index.ts

@@ -1,5 +1,5 @@
 /**
- * pi-better-sandbox - a default-on write sandbox for foreground tool execution.
+ * pi-better-sandbox - an opt-in write sandbox for foreground tool execution.
  *
  * Installing this package loads an extension; it ships no launcher, so users
  * keep starting Pi with plain `pi`. While enabled, the built-in `bash` tool and
@@ -38,6 +38,7 @@ import {
     createSandboxedEditOperations,
     createSandboxedWriteOperations,
 } from "./files.ts";
+import { readSandboxDefault, writeSandboxDefault } from "./preferences.ts";
 import { createSandboxedBashOperations } from "./shell.ts";
 import { footerTone, formatFooterStatus } from "./status.ts";
 import { ForegroundSandboxController, type ForegroundSandboxStatus } from "./state.ts";
@@ -109,10 +110,19 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
             );
         };
 
-        // Every session start re-captures the project root and re-arms
-        // protection, so an earlier /sandbox off never survives into a new,
-        // resumed, forked, or reloaded session.
-        controller.beginSession(ctx.cwd);
+        // Every session re-reads the persistent activation preference. Missing
+        // or malformed state resolves to the product default (off), never to an
+        // unexpected fail-closed session.
+        let defaultEnabled = false;
+        try {
+            defaultEnabled = readSandboxDefault() === "on";
+        } catch (error) {
+            ctx.ui.notify(
+                `Foreground sandbox preference ignored; defaulting off: ${error instanceof Error ? error.message : String(error)}`,
+                "warning",
+            );
+        }
+        controller.beginSession(ctx.cwd, defaultEnabled);
 
         // Then the rules are re-read and re-resolved, because the same global
         // template set means different absolute paths in a different project.
@@ -130,7 +140,7 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
                 "warning",
             );
         }
-        if (status.state !== "enabled") {
+        if (status.state !== "enabled" && status.state !== "inactive") {
             ctx.ui.notify(
                 `Foreground sandbox ${status.state}: ${status.reason}`,
                 status.state === "disabled" ? "info" : "warning",
@@ -145,7 +155,15 @@ export default function piBetterSandbox(pi: ExtensionAPI): void {
     pi.registerCommand(SANDBOX_COMMAND_NAME, {
         description: SANDBOX_COMMAND_DESCRIPTION,
         getArgumentCompletions: sandboxArgumentCompletions,
-        handler: createSandboxCommandHandler({ controller, denyRules, onStateChange: announce }),
+        handler: createSandboxCommandHandler({
+            controller,
+            denyRules,
+            onStateChange: announce,
+            setDefault: (enabled) => {
+                writeSandboxDefault(enabled ? "on" : "off");
+                return controller.applyDefault(enabled);
+            },
+        }),
     });
 }
 
@@ -201,6 +219,16 @@ export {
     readDenyRuleOverride,
     writeDenyRuleOverride,
 } from "./deny-rules.ts";
+export {
+    readSandboxDefault,
+    SANDBOX_PREFERENCES_FILE_NAME,
+    SANDBOX_PREFERENCES_FORMAT_VERSION,
+    SandboxPreferenceError,
+    sandboxPreferencesPath,
+    type SandboxDefaultMode,
+    type SandboxPreferenceSeams,
+    writeSandboxDefault,
+} from "./preferences.ts";
 export { openSandboxRulesPage, RULES_PAGE_NO_UI_REJECTION } from "./rules-page.ts";
 export {
     describeUnsafeProjectRoot,

package/node_modules/pi-better-sandbox/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-sandbox",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi extension that confines foreground shell execution to the project directory with a kernel-enforced write sandbox.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-sandbox/preferences.ts

@@ -0,0 +1,93 @@
+/** Persisted foreground-sandbox activation preference. */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const SANDBOX_PREFERENCES_FILE_NAME = "pi-better-sandbox-preferences.json";
+export const SANDBOX_PREFERENCES_FORMAT_VERSION = 1;
+
+export type SandboxDefaultMode = "off" | "on";
+
+export type SandboxPreferenceSeams = {
+    agentDir?: () => string;
+};
+
+type SandboxPreferencesFile = {
+    version: number;
+    default: SandboxDefaultMode;
+};
+
+export class SandboxPreferenceError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "SandboxPreferenceError";
+    }
+}
+
+export function sandboxPreferencesPath(seams: SandboxPreferenceSeams = {}): string {
+    return join((seams.agentDir ?? getAgentDir)(), "extensions", SANDBOX_PREFERENCES_FILE_NAME);
+}
+
+/** Read the persisted default. No file means the product default: off. */
+export function readSandboxDefault(seams: SandboxPreferenceSeams = {}): SandboxDefaultMode {
+    const path = sandboxPreferencesPath(seams);
+    let raw: string;
+    try {
+        raw = readFileSync(path, "utf8");
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return "off";
+        throw new SandboxPreferenceError(
+            `The sandbox preference at ${path} could not be read: ${messageOf(error)}`,
+        );
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (error) {
+        throw new SandboxPreferenceError(
+            `The sandbox preference at ${path} is not valid JSON: ${messageOf(error)}`,
+        );
+    }
+
+    const value = parsed as Partial<SandboxPreferencesFile> | null;
+    if (
+        value?.version !== SANDBOX_PREFERENCES_FORMAT_VERSION ||
+        (value.default !== "off" && value.default !== "on")
+    ) {
+        throw new SandboxPreferenceError(
+            `The sandbox preference at ${path} must contain version ${SANDBOX_PREFERENCES_FORMAT_VERSION} and default "off" or "on".`,
+        );
+    }
+    return value.default;
+}
+
+/** Atomically persist the default used by future sessions. */
+export function writeSandboxDefault(
+    mode: SandboxDefaultMode,
+    seams: SandboxPreferenceSeams = {},
+): string {
+    const path = sandboxPreferencesPath(seams);
+    mkdirSync(dirname(path), { recursive: true });
+    const contents = `${JSON.stringify(
+        { version: SANDBOX_PREFERENCES_FORMAT_VERSION, default: mode } satisfies SandboxPreferencesFile,
+        undefined,
+        2,
+    )}\n`;
+    const pending = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(pending, contents, "utf8");
+        renameSync(pending, path);
+    } catch (error) {
+        throw new SandboxPreferenceError(
+            `The sandbox preference at ${path} could not be written: ${messageOf(error)}`,
+        );
+    }
+    return path;
+}
+
+function messageOf(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}

package/node_modules/pi-better-sandbox/state.ts

@@ -2,13 +2,13 @@
  * Session-local foreground sandbox state.
  *
  * One controller per Pi session owns three things: the canonical project root
- * captured at session start, whether a human has switched protection off, and
+ * captured at session start, the persisted default plus session override, and
  * the *effective* status derived from live runtime evidence (which backend this
  * platform actually resolves, not what the package intended).
  *
- * The enabled state is deliberately in-memory only. Every session start —
- * startup, new, resume, fork, reload — calls `beginSession` and lands back on
- * enabled, which is what "an off state is never persisted" means in practice.
+ * Session overrides are deliberately in-memory only. Every session start —
+ * startup, new, resume, fork, reload — calls `beginSession` with the persisted
+ * default and clears the previous override.
  */
 
 import { createHash } from "node:crypto";
@@ -32,13 +32,14 @@ import {
 /**
  * What the foreground sandbox is actually doing right now.
  *
+ * - `inactive`  - default-off; protected operations run unconfined.
  * - `enabled`   - a backend is resolved and protected operations are wrapped.
  * - `disabled`  - a human turned it off for this session.
  * - `unavailable` - this platform resolves no backend; protected operations are blocked.
  * - `failed`    - protection cannot be applied here (no session yet, or an
  *                 unsafe launch root); protected operations are blocked.
  */
-export type ForegroundSandboxState = "enabled" | "disabled" | "unavailable" | "failed";
+export type ForegroundSandboxState = "inactive" | "enabled" | "disabled" | "unavailable" | "failed";
 
 /**
  * The immutable effective-policy snapshot published to first-party consumers
@@ -109,7 +110,8 @@ export class ForegroundSandboxController {
     #unsafeRootReason: string | undefined;
     #denyWrite: readonly string[] = [];
     #denyTemplates: readonly string[] = PACKAGED_DENY_WRITE_TEMPLATES;
-    #userEnabled = true;
+    #defaultEnabled = false;
+    #sessionOverride: boolean | undefined;
     #profileDir: string | undefined;
 
     constructor(seams: ForegroundSandboxSeams = {}) {
@@ -117,12 +119,10 @@ export class ForegroundSandboxController {
     }
 
     /**
-     * Capture the canonical launch directory and re-arm protection.
-     *
-     * Called for every session start reason, which is what keeps a previous
-     * `/sandbox off` from surviving a new, resumed, forked, or reloaded session.
+     * Capture the canonical launch directory and apply the persisted default.
+     * A session override never survives a new, resumed, forked, or reloaded session.
      */
-    beginSession(cwd: string): ForegroundSandboxStatus {
+    beginSession(cwd: string, defaultEnabled = false): ForegroundSandboxStatus {
         const projectRoot = canonicalizePath(cwd, this.#seams);
         this.#projectRoot = projectRoot;
         this.#unsafeRootReason = describeUnsafeProjectRoot(projectRoot, this.#seams);
@@ -131,25 +131,33 @@ export class ForegroundSandboxController {
                 ? []
                 : resolveDenyWriteTemplates(this.#denyTemplates, projectRoot, this.#seams),
         );
-        this.#userEnabled = true;
+        this.#defaultEnabled = defaultEnabled;
+        this.#sessionOverride = undefined;
         return this.status();
     }
 
     /** Re-enable protection for operations launched from now on. */
     enable(): ForegroundSandboxStatus {
-        this.#userEnabled = true;
+        this.#sessionOverride = true;
         return this.status();
     }
 
     /** Turn protection off for this session only. Never persisted. */
     disable(): ForegroundSandboxStatus {
-        this.#userEnabled = false;
+        this.#sessionOverride = false;
+        return this.status();
+    }
+
+    /** Apply a newly persisted default immediately and clear the session override. */
+    applyDefault(defaultEnabled: boolean): ForegroundSandboxStatus {
+        this.#defaultEnabled = defaultEnabled;
+        this.#sessionOverride = undefined;
         return this.status();
     }
 
     /** Whether a human has left protection switched on. */
     isUserEnabled(): boolean {
-        return this.#userEnabled;
+        return this.#sessionOverride ?? this.#defaultEnabled;
     }
 
     /** The deny-write templates currently in force (packaged defaults for now). */
@@ -194,14 +202,19 @@ export class ForegroundSandboxController {
             });
         }
 
-        if (!this.#userEnabled) {
+        if (!this.isUserEnabled()) {
+            const explicitlyDisabled = this.#sessionOverride === false;
             return Object.freeze({
                 ...base,
-                state: "disabled",
+                state: explicitlyDisabled ? "disabled" : "inactive",
                 writableRoot: undefined,
                 backend: support.supported ? support.backend : undefined,
                 executable: support.supported ? support.executable : undefined,
-                reason: "A human turned the foreground sandbox off for this session with /sandbox off.",
+                reason: explicitlyDisabled
+                    ? "A human turned the foreground sandbox off for this session with /sandbox off."
+                    : support.supported
+                      ? "The foreground sandbox is available but inactive by default. Use /sandbox on for this session or /sandbox default on to persist opt-in."
+                      : `The foreground sandbox is inactive by default, and no backend is available: ${support.reason}`,
             });
         }
 
@@ -240,13 +253,12 @@ export class ForegroundSandboxController {
     /**
      * Decide how to launch one protected operation.
      *
-     * Returns an unconfined plan only when a human explicitly disabled the
-     * sandbox. Every other non-enabled state throws, so a missing or unusable
-     * backend blocks the operation rather than silently degrading it.
+     * Returns an unconfined plan while the sandbox is inactive or explicitly
+     * disabled. Once enabled, missing or unusable backends fail closed.
      */
     requireLaunchPlan(): ForegroundSandboxLaunchPlan {
         const status = this.status();
-        if (status.state === "disabled") return { confined: false };
+        if (status.state === "inactive" || status.state === "disabled") return { confined: false };
         if (status.state !== "enabled" || status.writableRoot === undefined) {
             throw new ForegroundSandboxBlockedError(status);
         }

package/node_modules/pi-better-sandbox/status.ts

@@ -22,6 +22,7 @@ const plain: StatusPainter = (_tone, text) => text;
 /** The tone the footer uses for a given state. */
 export function footerTone(status: ForegroundSandboxStatus): StatusTone {
     if (status.state === "enabled") return "accent";
+    if (status.state === "inactive") return status.backend === undefined ? "warning" : "accent";
     if (status.state === "unavailable") return "warning";
     return "error";
 }
@@ -40,6 +41,9 @@ export function formatFooterStatus(
     if (status.state === "enabled" && status.writableRoot !== undefined) {
         return paint(tone, `sandbox · on · ${basename(status.writableRoot)}`);
     }
+    if (status.state === "inactive") {
+        return paint(tone, status.backend === undefined ? "sandbox · inactive" : "sandbox · available");
+    }
     if (status.state === "disabled") return paint(tone, "sandbox · OFF");
     if (status.state === "unavailable") return paint(tone, "sandbox · UNAVAILABLE");
     return paint(tone, "sandbox · FAILED");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-better-harness",
-  "version": "0.1.26",
-  "description": "Pi extension bundle for a default write sandbox, subagents, durable background tasks, and goal tracking.",
+  "version": "0.2.0",
+  "description": "Pi extension bundle for an opt-in foreground write sandbox, subagents, durable background tasks, and goal tracking.",
   "license": "MIT",
   "type": "module",
   "keywords": [
@@ -45,9 +45,9 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "pi-better-background-tasks": "0.2.6",
+    "pi-better-background-tasks": "0.2.7",
     "pi-better-goal": "0.1.22",
-    "pi-better-sandbox": "0.1.0",
+    "pi-better-sandbox": "0.2.0",
     "pi-better-subagents": "0.1.22"
   },
   "bundledDependencies": [