@youweichen/pi-harness 0.0.0-stage → 1.1.0

package/dist/server/origin-policy.js

@@ -0,0 +1,50 @@
+/**
+ * Origin / Host admission policy for HTTP and WebSocket requests.
+ *
+ * Pure (no env, no I/O) so it can be unit-tested; server/index.ts builds one
+ * instance from the environment.
+ */
+const LOOPBACK_BIND_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+/** URL#hostname spelling of the loopback names a local browser can use. */
+const LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "[::1]"];
+/** "host" or "host:port" → { hostname, port }. */
+export function parseAuthority(a) {
+    try {
+        const u = new URL(`http://${a}`);
+        return { hostname: u.hostname.toLowerCase(), port: u.port || "80" };
+    }
+    catch {
+        return { hostname: "", port: "" };
+    }
+}
+/**
+ * Effective Host allowlist. An explicit list always wins. When the server is
+ * bound to loopback only, default to loopback hostnames: otherwise a DNS
+ * rebinding page (evil.com → 127.0.0.1) passes the same-authority Origin/Host
+ * check and gets full control of the agent. Non-loopback binds (LAN, Docker,
+ * reverse proxy) have no safe default and keep the old behavior.
+ */
+export function effectiveAllowHosts(bindHost, allowHosts) {
+    if (allowHosts.length > 0)
+        return allowHosts;
+    return LOOPBACK_BIND_HOSTS.has(bindHost.toLowerCase()) ? LOOPBACK_HOSTNAMES : [];
+}
+export function createOriginPolicy(options) {
+    const allowHosts = effectiveAllowHosts(options.bindHost, options.allowHosts);
+    return (headers) => {
+        const host = parseAuthority((headers.host ?? "").toLowerCase());
+        if (allowHosts.length > 0 && !allowHosts.includes(host.hostname))
+            return false;
+        const origin = headers.origin;
+        if (!origin)
+            return true; // non-browser client
+        const o = origin.toLowerCase();
+        if (options.allowOrigins.includes(o))
+            return true;
+        if (o === "null")
+            return false; // file:// pages etc. are not trusted
+        const ori = parseAuthority(o.replace(/^[a-z]+:\/\//, ""));
+        // Same host:port only; other ports on the same host are different origins.
+        return ori.hostname === host.hostname && ori.port === host.port;
+    };
+}

package/dist/server/patch-node-pty.js

@@ -0,0 +1,96 @@
+/**
+ * node-pty compatibility patches for Node `--watch` and Windows ConPTY.
+ *
+ * Node's `--watch` mode (the dev script runs `node --watch --import tsx`)
+ * pushes `watch:require` / `watch:import` messages over the IPC channels of
+ * spawned worker threads AND forked child processes to track module
+ * dependencies. node-pty 1.1.0 does not recognize these and mishandles them in
+ * two places:
+ *
+ *  · windowsConoutConnection.js — logs every unknown worker message via
+ *    `console.warn`, producing hundreds of "Unexpected ConoutWorkerMessage"
+ *    lines per terminal (the SCM panel's hidden query PTY triggers it on every
+ *    git-view open).
+ *  · windowsPtyAgent.js — the kill path's `_getConsoleProcessList()` treats ANY
+ *    message from the forked console-list agent as its reply; a watch message
+ *    has no `consoleProcessList` property, so `message.consoleProcessList` is
+ *    undefined and the `.forEach` on it crashes the server.
+ *
+ * Both are benign protocol noise: the ConPTY worker only ever sends its READY
+ * sentinel and the agent only sends `{ consoleProcessList }` — both of which
+ * node-pty handles. These patches make node-pty ignore unrelated IPC traffic.
+ * The console-list helper also needs to report an empty list when a shell has
+ * already exited: node-pty 1.1.0 lets AttachConsole throw at module scope,
+ * producing an uncaught stack trace and making its parent wait five seconds.
+ *
+ * IMPORTANT: this module MUST be imported before node-pty (see terminals.ts) —
+ * it rewrites the installed copies on disk so the subsequently-compiled
+ * node-pty modules contain the fixed handlers. Best-effort and idempotent
+ * (checks before rewriting), mirroring the spawn-helper chmod self-heal; a
+ * read-only node_modules or a different node-pty version just skips the patch
+ * (the runtime console.warn filter in terminals.ts still guards the flood).
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+const require = createRequire(import.meta.url);
+/** Absolute path of the installed node-pty package root, or null. */
+function ptyPackageDir() {
+    try {
+        // require.resolve("node-pty") → <pkg>/lib/index.js → package root is two up.
+        return dirname(dirname(require.resolve("node-pty")));
+    }
+    catch {
+        return null;
+    }
+}
+/** Idempotently replace one code fragment in a node-pty source file. */
+function patchFile(pkgDir, rel, find, replace) {
+    try {
+        const file = join(pkgDir, rel);
+        if (!existsSync(file))
+            return;
+        const src = readFileSync(file, "utf8");
+        if (src.includes(replace))
+            return; // already patched
+        if (!src.includes(find))
+            return; // unexpected content — leave alone
+        writeFileSync(file, src.replace(find, replace), "utf8");
+    }
+    catch {
+        // best-effort — the runtime console.warn filter still guards the flood
+    }
+}
+function applyPatches() {
+    const pkgDir = ptyPackageDir();
+    if (!pkgDir)
+        return;
+    // 1. ConoutConnection: ignore unknown worker messages instead of warning.
+    patchFile(pkgDir, "lib/windowsConoutConnection.js", "console.warn('Unexpected ConoutWorkerMessage', message);", "break; // pi-harness: ignore Node --watch worker messages");
+    // 2. windowsPtyAgent kill path: only accept a real console-list reply
+    //    (watch messages arrive first on the fork channel and carry no
+    //    consoleProcessList — previously resolved undefined and crashed).
+    patchFile(pkgDir, "lib/windowsPtyAgent.js", "agent.on('message', function (message) {\n                clearTimeout(timeout);\n                resolve(message.consoleProcessList);\n            });", [
+        "            agent.on('message', function (message) {",
+        "                // pi-harness: ignore Node --watch messages on the fork channel",
+        "                if (message && Array.isArray(message.consoleProcessList)) {",
+        "                    clearTimeout(timeout);",
+        "                    resolve(message.consoleProcessList);",
+        "                }",
+        "            });",
+    ].join("\n"));
+    // 3. A shell may exit before the console-list helper attaches. Always reply
+    //    to the parent so a normal terminal close cannot print an uncaught error
+    //    or hold its cleanup path for the full five-second fallback timeout.
+    patchFile(pkgDir, "lib/conpty_console_list_agent.js", "var consoleProcessList = getConsoleProcessList(shellPid);\nprocess.send({ consoleProcessList: consoleProcessList });", [
+        "try {",
+        "    var consoleProcessList = getConsoleProcessList(shellPid);",
+        "    process.send({ consoleProcessList: consoleProcessList });",
+        "} catch (error) {",
+        "    if (!error || error.message !== 'AttachConsole failed') throw error;",
+        "    // pi-harness: the console may already be gone during ConPTY teardown",
+        "    process.send({ consoleProcessList: [] });",
+        "}",
+    ].join("\n"));
+}
+applyPatches();

package/dist/server/pi-environment.js

@@ -0,0 +1,203 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { appVersion } from "./app-version.js";
+/**
+ * Whether the pi agent config looks ready: the agent dir exists and
+ * auth.json has at least one provider credential. Cached for 2s.
+ */
+export class PiConfigProbe {
+    agentDir;
+    cache = null;
+    constructor(agentDir) {
+        this.agentDir = agentDir;
+    }
+    isConfigured() {
+        const now = Date.now();
+        const cached = this.cache;
+        if (cached && now - cached.at < 2000)
+            return cached.configured;
+        let configured = false;
+        try {
+            const authPath = join(this.agentDir, "auth.json");
+            if (existsSync(authPath)) {
+                const data = JSON.parse(readFileSync(authPath, "utf8"));
+                configured =
+                    typeof data === "object" &&
+                        data !== null &&
+                        Object.keys(data).length > 0;
+            }
+        }
+        catch {
+            configured = false;
+        }
+        this.cache = { at: now, configured };
+        return configured;
+    }
+    invalidate() {
+        this.cache = null;
+    }
+}
+/**
+ * Whether the pi CLI binary is installed and runnable (`pi --version`
+ * probe). Cached machine-wide (same binary for every client) for 10s —
+ * the check is only rerun after install or when the cache expires.
+ */
+let piCliProbe = null;
+const PI_CLI_PROBE_TTL_MS = 10_000;
+export function isPiCliInstalled() {
+    const now = Date.now();
+    const cached = piCliProbe;
+    if (cached && now - cached.at < PI_CLI_PROBE_TTL_MS)
+        return cached.installed;
+    let installed = false;
+    try {
+        const res = spawnSync("pi", ["--version"], {
+            timeout: 5000,
+            stdio: "ignore",
+            // Windows: `pi` resolves to a pi.cmd shim — spawnSync can only
+            // exec those through a shell (else ENOENT).
+            shell: process.platform === "win32",
+        });
+        installed = !res.error && res.status === 0;
+    }
+    catch {
+        installed = false;
+    }
+    piCliProbe = { at: now, installed };
+    return installed;
+}
+function invalidatePiCliProbe() {
+    piCliProbe = null;
+}
+/**
+ * Run a command async, collecting stdout+stderr; kills on timeout.
+ * Never throws / never crashes the server: spawn errors (ENOENT etc.)
+ * resolve with code -1 so callers can report them as notices.
+ */
+function runAsync(cmd, args, timeoutMs, cwd) {
+    return new Promise((resolve) => {
+        let p;
+        try {
+            p = spawn(cmd, args, {
+                ...(cwd ? { cwd } : {}),
+                stdio: ["ignore", "pipe", "pipe"],
+                // Windows: npm and friends are .cmd shims — Node can only exec
+                // them through the shell (otherwise spawn npm → ENOENT).
+                shell: process.platform === "win32",
+            });
+        }
+        catch (err) {
+            resolve({ code: -1, out: String(err) });
+            return;
+        }
+        let out = "";
+        let settled = false;
+        const done = (code, text) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(t);
+            resolve({ code, out: text ?? out });
+        };
+        const t = setTimeout(() => p.kill(), timeoutMs);
+        p.stdout?.on("data", (d) => (out += d.toString()));
+        p.stderr?.on("data", (d) => (out += d.toString()));
+        p.on("error", (err) => done(-1, String(err)));
+        p.on("close", (code) => done(code));
+    });
+}
+/** Simple numeric semver compare: >0 means a newer than b. */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x - y;
+    }
+    return 0;
+}
+/** Ask the npm registry for the latest pi-harness version and report it. */
+export async function checkUpdate(emit) {
+    const current = appVersion();
+    try {
+        // Fetch the full package doc (not /latest): it carries the per-version
+        // publish timestamps so the UI can hint when a version was JUST
+        // published and the registry/CDN caches may not have caught up yet.
+        const res = await fetch("https://registry.npmjs.org/@youweichen%2fpi-harness", {
+            signal: AbortSignal.timeout(8_000),
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const data = (await res.json());
+        const latest = data["dist-tags"]?.latest ?? null;
+        const latestPublishedAt = latest && data.time ? (data.time[latest] ?? null) : null;
+        const upToDate = latest === null || compareVersions(current, latest) >= 0;
+        emit({
+            type: "update_status",
+            current,
+            latest,
+            latestPublishedAt,
+            upToDate,
+        });
+    }
+    catch (err) {
+        emit({
+            type: "update_status",
+            current,
+            latest: null,
+            latestPublishedAt: null,
+            upToDate: false,
+            error: `检查更新失败：${err.message}`,
+        });
+    }
+}
+/**
+ * Auto-install the pi agent: ensure the config dir exists and install the
+ * pi CLI globally (npm i -g). Auth is configured afterwards via the API key
+ * form or by running `pi` in a terminal. Callers should re-send a snapshot
+ * afterwards so the UI re-probes the CLI.
+ */
+export async function installPiAgent(agentDir, emit) {
+    try {
+        mkdirSync(agentDir, { recursive: true });
+        emit({
+            type: "notice",
+            level: "info",
+            text: "正在安装 pi agent CLI（npm i -g @earendil-works/pi-coding-agent）…",
+        });
+        const { code, out } = await runAsync("npm", ["i", "-g", "@earendil-works/pi-coding-agent"], 180_000);
+        if (code === 0) {
+            emit({
+                type: "notice",
+                level: "info",
+                text: "✅ pi agent CLI 安装完成。填入 API 密钥即可开始，或在终端运行 pi 完成登录。",
+            });
+            emit({ type: "install_result", ok: true, detail: "" });
+        }
+        else {
+            emit({
+                type: "notice",
+                level: "error",
+                text: `pi agent 安装失败（${code ?? "timeout"}）：${out.slice(0, 400)}`,
+            });
+            emit({
+                type: "install_result",
+                ok: false,
+                detail: out.slice(0, 600),
+            });
+        }
+    }
+    catch (err) {
+        emit({
+            type: "notice",
+            level: "error",
+            text: `pi agent 安装失败：${err.message}`,
+        });
+    }
+    // The CLI may just have landed on PATH (or the install may have failed) —
+    // drop the probe cache so the next snapshot re-checks.
+    invalidatePiCliProbe();
+}

package/dist/server/plan/extension.js

@@ -0,0 +1,74 @@
+import { Type } from "typebox";
+import { editableState, latestPlan, snapshotFromDetails, transition } from "./state.js";
+const string = (maxLength) => Type.String({ minLength: 1, maxLength });
+export const planParameters = Type.Object({
+    action: Type.Union([Type.Literal("create"), Type.Literal("update")]),
+    planId: Type.Optional(string(128)), expectedRevision: Type.Optional(Type.Integer({ minimum: 1 })),
+    title: string(80), status: Type.Union([Type.Literal("active"), Type.Literal("completed"), Type.Literal("cancelled"), Type.Literal("failed")]),
+    steps: Type.Array(Type.Object({ id: string(64), title: string(80), detail: Type.Optional(string(500)) }), { minItems: 1, maxItems: 16, description: "Required for BOTH create and update, including completion. Send every step with its id, title and detail; never omit unchanged steps." }),
+    currentStepId: Type.Union([string(64), Type.Null()], { description: "Current step for active plans; terminal statuses clear it automatically." }), completedStepIds: Type.Array(string(64), { maxItems: 16, uniqueItems: true, description: "Completed step IDs. Explicit status completed completes all submitted steps; cancelled/failed preserve this list." }),
+    completionCriteria: string(240), changeSummary: Type.Optional(string(240)),
+});
+export function restorePlanContext(messages, branch) {
+    const latest = latestPlan(branch);
+    if (!latest || latest.snapshot.status !== "active")
+        return messages;
+    const { snapshot, toolCallId } = latest;
+    const visibleResult = messages.some(message => message.role === "toolResult" && message.toolName === "plan" && message.toolCallId === toolCallId && !message.isError && JSON.stringify(snapshotFromDetails(message.details)) === JSON.stringify(snapshot));
+    const visibleCall = messages.some(message => message.role === "assistant" && message.content.some(block => {
+        if (block.type !== "toolCall" || block.name !== "plan" || block.id !== toolCallId)
+            return false;
+        try {
+            const args = block.arguments;
+            const identity = args.action === "create" ? snapshot.revision === 1 : args.action === "update" && args.planId === snapshot.planId && args.expectedRevision === snapshot.revision - 1;
+            return identity && JSON.stringify(editableState(args)) === JSON.stringify(editableState(snapshot));
+        }
+        catch {
+            return false;
+        }
+    }));
+    const lastUser = messages.findLastIndex(message => message.role === "user");
+    const lastPlanResult = messages.slice(lastUser + 1).findLast(message => message.role === "toolResult" && message.toolName === "plan");
+    const failedCall = lastPlanResult?.role === "toolResult" && lastPlanResult.isError;
+    if (visibleResult && visibleCall && !failedCall)
+        return messages;
+    const content = `${failedCall ? "Plan call failed; the saved plan below is unchanged. To correct the call, submit the full state including steps, even if unchanged or marking completion. Use the saved planId and expectedRevision. This reminder does not authorize continuing work.\n" : ""}Historical plan background, not authorization to continue. Judge relevance to the current request yourself. For related, already authorized implementation, update this plan with its current identity and revision and continue without requesting separate plan approval. For unrelated multi-step work, create a new plan. Ordinary questions do not require a plan. Follow user/skill instructions and waiting requirements; this tool grants no extra permissions.\n${JSON.stringify({ action: "update", planId: snapshot.planId, expectedRevision: snapshot.revision, ...editableState(snapshot) })}`;
+    const reminder = { role: "custom", customType: "pi-harness:plan-background", content, display: false, timestamp: 0 };
+    const summary = messages.findLastIndex(message => message.role === "compactionSummary");
+    const user = messages.findLastIndex(message => message.role === "user");
+    let at = summary >= 0 ? summary + 1 : user >= 0 ? user : 0;
+    // A user interruption may occur inside an outstanding call/result group.
+    // Keep that entire group together when selecting the insertion boundary.
+    const open = new Map();
+    for (let index = 0; index < at; index++) {
+        const message = messages[index];
+        if (message.role === "assistant")
+            for (const block of message.content)
+                if (block.type === "toolCall")
+                    open.set(block.id, index);
+        if (message.role === "toolResult")
+            open.delete(message.toolCallId);
+    }
+    if (open.size)
+        at = Math.min(at, ...open.values());
+    return [...messages.slice(0, at), reminder, ...messages.slice(at)];
+}
+export const createPlanExtension = () => pi => {
+    pi.registerTool({
+        name: "plan", label: "Plan", description: "Create or update a complete, versioned implementation plan on this session branch. Every call requires title, status, steps, currentStepId, completedStepIds and completionCriteria, even when completing or only changing status. Updates also require the latest planId and expectedRevision. This is full replacement, not a partial patch. Explicit completed status completes all submitted steps and clears currentStepId; cancelled/failed only clear currentStepId. Ended plans require create.",
+        exposure: "model-only", executionMode: "sequential", defaultActive: false,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        promptSnippet: "Record and update a multi-step implementation plan.",
+        promptGuidelines: ["For multi-step implementation, create or update a relevant plan before execution and update the current step before starting it. For already authorized work, proceed without requesting separate plan approval. Submit the full state each time. Wait for create to return its identity before updating. Follow user and skill instructions, including waiting; a plan does not grant authorization. Ordinary questions need no plan. When work is merged into another step or becomes unnecessary, update or remove the superseded step and explain the change instead of leaving a stale pending item. Never mark unfinished work completed. Mark completion explicitly; never infer it from a stopped run."],
+        parameters: planParameters,
+        async execute(_id, args, _signal, _update, ctx) {
+            const snapshot = transition(args, latestPlan(ctx.sessionManager.getBranch())?.snapshot);
+            return { content: [{ type: "text", text: `Plan ${snapshot.planId}, revision ${snapshot.revision}: ${snapshot.status}.` }], details: { planSnapshot: snapshot } };
+        },
+    });
+    pi.on("context", (event, ctx) => {
+        if (!pi.getActiveTools().includes("plan") || !["builtin:pi-harness-plan", "<inline:pi-harness-plan>"].includes(pi.getAllTools().find(tool => tool.name === "plan")?.sourceInfo.path ?? ""))
+            return;
+        return { messages: restorePlanContext(event.messages, ctx.sessionManager.getBranch()) };
+    });
+};

package/dist/server/plan/progress.js

@@ -0,0 +1,90 @@
+import { isToolTextContinuation } from "../tool-text.js";
+import { latestPlan } from "./state.js";
+const histories = new WeakMap();
+export function taskHistoryFromSession(manager, serialize) {
+    const leaf = manager.getLeafId();
+    const previous = histories.get(manager);
+    if (previous?.leaf === leaf)
+        return previous.messages;
+    const branch = manager.getBranch();
+    const messages = latestPlan(branch) ? branch.flatMap(entry => {
+        if (entry.type !== "message")
+            return [];
+        const message = serialize(entry.message, entry.id);
+        return message ? [{ ...message, entryId: entry.id }] : [];
+    }) : undefined;
+    histories.set(manager, { leaf, messages });
+    return messages;
+}
+/** Replay assistant call order, pairing results before the following call. */
+export function planFromTranscript(messages) {
+    const results = new Map(messages.filter(message => message.role === "toolResult" && message.toolCallId).map(message => [message.toolCallId, message]));
+    let latest;
+    let confirmed = false;
+    let changes = [];
+    let changeSummary;
+    const tools = new Map();
+    const removed = new Map();
+    const times = new Map();
+    for (const [index, message] of messages.entries()) {
+        if (message.role === "user") {
+            if (!isToolTextContinuation(messages, index))
+                confirmed = false;
+            continue;
+        }
+        if (message.role !== "assistant")
+            continue;
+        for (const part of message.content) {
+            if (part.type !== "toolCall")
+                continue;
+            const call = part;
+            if (call.name !== "plan") {
+                if (confirmed && latest?.status === "active" && latest.currentStepId)
+                    tools.set(latest.currentStepId, [...(tools.get(latest.currentStepId) ?? []), call.id]);
+                continue;
+            }
+            const result = results.get(call.id);
+            const next = !result?.isError ? result?.planSnapshot : undefined;
+            if (!next)
+                continue;
+            if (next.planId !== latest?.planId) {
+                tools.clear();
+                removed.clear();
+                times.clear();
+                changes = [];
+                changeSummary = undefined;
+            }
+            else
+                for (const step of latest.steps)
+                    if (!next.steps.some(item => item.id === step.id))
+                        removed.set(step.id, step);
+            for (const step of next.steps) {
+                removed.delete(step.id);
+                const time = times.get(step.id) ?? {};
+                if (next.currentStepId === step.id && time.startedAt === undefined)
+                    time.startedAt = result?.timestamp;
+                if (next.completedStepIds.includes(step.id) && time.endedAt === undefined)
+                    time.endedAt = result?.timestamp;
+                times.set(step.id, time);
+            }
+            const structuralChanges = next.changes.flatMap(change => ["added", "removed", "updated"].includes(change.kind) && "title" in change ? [{ kind: change.kind, title: change.title, position: change.position }] : []);
+            if (structuralChanges.length)
+                changes = structuralChanges;
+            if (next.changeSummary)
+                changeSummary = next.changeSummary;
+            latest = next;
+            confirmed = true;
+        }
+    }
+    if (!latest)
+        return { known: false };
+    if (!confirmed && latest.status !== "active")
+        return { known: true };
+    return { known: true, plan: {
+            source: "plan", origin: latest.planId, revision: latest.revision, status: latest.status, awaitingConfirmation: !confirmed,
+            title: latest.title, completionCriteria: latest.completionCriteria, changeSummary,
+            added: latest.changes.filter(change => change.kind === "added").length, removed: removed.size,
+            changes,
+            items: [...latest.steps.map(step => ({ ...step, status: latest.completedStepIds.includes(step.id) ? "done" : confirmed && step.id === latest.currentStepId ? "running" : "pending", toolCallIds: tools.get(step.id) ?? [], ...times.get(step.id) })), ...[...removed.values()].map(step => ({ ...step, status: "removed", toolCallIds: tools.get(step.id) ?? [], ...times.get(step.id) }))],
+        } };
+}

package/dist/server/plan/settings.js

@@ -0,0 +1,41 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+/** One service instance preference. Sessions only hold their effective loadout. */
+export class PlanSettings {
+    path;
+    enabled = true;
+    constructor(dataDir = resolve(process.env.PI_WEB_DATA_DIR ?? join(homedir(), ".pi-web"))) {
+        this.path = join(dataDir, "plan-settings.json");
+        try {
+            const saved = JSON.parse(readFileSync(this.path, "utf8"));
+            if (typeof saved.enabled === "boolean")
+                this.enabled = saved.enabled;
+        }
+        catch { /* Missing or invalid preference: default on. */ }
+    }
+    set(enabled) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const temporary = `${this.path}.${process.pid}.tmp`;
+        writeFileSync(temporary, JSON.stringify({ enabled }) + "\n", { mode: 0o600 });
+        renameSync(temporary, this.path);
+        this.enabled = enabled;
+    }
+    state(session) {
+        const tool = session.getAllTools().find(tool => tool.name === "plan");
+        const available = !!tool && ["builtin:pi-harness-plan", "<inline:pi-harness-plan>"].includes(tool.sourceInfo.path);
+        const effective = available && session.getActiveToolNames().includes("plan");
+        return { enabled: this.enabled, available, effective, pending: available && effective !== this.enabled, ...(!available ? { reason: tool ? "conflict" : "missing" } : {}) };
+    }
+    coordinate(session, writable) {
+        const state = this.state(session);
+        if (!state.available || !state.pending || !session.isIdle || !writable)
+            return;
+        const active = session.getActiveToolNames().filter(name => name !== "plan");
+        if (this.enabled)
+            active.push("plan");
+        session.setActiveToolsByName(active);
+    }
+}
+let shared;
+export const planSettings = () => shared ??= new PlanSettings();