@xingular/harness 1.2.0 → 1.3.1-unstable.1

package/dist/sdk/core/workspaceSandbox.js

@@ -4,12 +4,28 @@ import { randomUUID } from 'node:crypto';
 import { accessSync, constants, existsSync, lstatSync, mkdtempSync, realpathSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { hostShell, shellArguments } from "./shell.js";
 import { isWithinWorkspace, verifyWorkspaceRoot } from "./workspace.js";
 const MARKER_PREFIX = '__XINGULAR_WORKSPACE_SANDBOX_STARTED_';
 const bashWriteScope = new AsyncLocalStorage();
 export function runWithWorkspaceWriteScope(scope, action) {
     return bashWriteScope.run(scope, action);
 }
+/** Why a Windows command asks first: Windows has no write-boundary sandbox the harness can use. */
+export const WINDOWS_UNSANDBOXED_REASON = 'Windows has no workspace write-boundary sandbox, so this command would run without one. It will not run until this one-call request is approved.';
+const SANDBOX_BACKENDS = {
+    darwin: ['/usr/bin/sandbox-exec'],
+    linux: ['/usr/bin/bwrap', '/bin/bwrap']
+};
+/**
+ * The operating system's write-boundary sandbox for this platform, or null when it is not
+ * installed. Bash cannot run without it, so readiness diagnostics report it before a command runs.
+ */
+export function workspaceSandboxBackend(platform = process.platform) {
+    const candidates = SANDBOX_BACKENDS[platform];
+    return candidates ? systemExecutable(candidates) : null;
+}
 function systemExecutable(candidates) {
     for (const candidate of candidates) {
         try {
@@ -29,6 +45,18 @@ function shellPath() {
         throw new Error('The workspace write-boundary sandbox requires Bash, but no Bash executable was found.');
     return shell;
 }
+function requireShell(resolve) {
+    const shell = resolve();
+    if (!shell) {
+        throw new Error(process.platform === 'win32'
+            ? 'No shell was found: neither Git Bash nor PowerShell is available. Bash was not run.'
+            : 'No Bash executable was found. Bash was not run.');
+    }
+    return shell;
+}
+function unconfinedCommand(shell, command) {
+    return { executable: shell.executable, args: shellArguments(shell, command), marker: '' };
+}
 function sbplString(value) {
     return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n')}"`;
 }
@@ -72,13 +100,13 @@ export function workspaceSandboxCommand(platform, workspaceRoot, cwd, command, a
         return readOnlySandboxCommand(platform, realpathSync(readOnlyTempRoot), cwd, shell, wrappedCommand, marker);
     const writeRoots = [...new Set([workspaceRoot, ...additionalWriteRoots].map((root) => realpathSync(root)))].sort((left, right) => left.length - right.length);
     if (platform === 'darwin') {
-        const executable = systemExecutable(['/usr/bin/sandbox-exec']);
+        const executable = workspaceSandboxBackend(platform);
         if (!executable)
             throw new Error('Workspace write-boundary sandbox unavailable: sandbox-exec was not found. Bash was not run.');
         return { executable, args: ['-p', macSandboxProfile(writeRoots), shell, '-c', wrappedCommand], marker };
     }
     if (platform === 'linux') {
-        const executable = systemExecutable(['/usr/bin/bwrap', '/bin/bwrap']);
+        const executable = workspaceSandboxBackend(platform);
         if (!executable)
             throw new Error('Workspace write-boundary sandbox unavailable: install bubblewrap (bwrap). Bash was not run.');
         return {
@@ -99,13 +127,13 @@ export function workspaceSandboxCommand(platform, workspaceRoot, cwd, command, a
 }
 function readOnlySandboxCommand(platform, tempRoot, cwd, shell, wrappedCommand, marker) {
     if (platform === 'darwin') {
-        const executable = systemExecutable(['/usr/bin/sandbox-exec']);
+        const executable = workspaceSandboxBackend(platform);
         if (!executable)
             throw new Error('Read-only Bash sandbox unavailable: sandbox-exec was not found. Bash was not run.');
         return { executable, args: ['-p', macReadOnlyProfile(tempRoot), shell, '-c', wrappedCommand], marker };
     }
     if (platform === 'linux') {
-        const executable = systemExecutable(['/usr/bin/bwrap', '/bin/bwrap']);
+        const executable = workspaceSandboxBackend(platform);
         if (!executable)
             throw new Error('Read-only Bash sandbox unavailable: install bubblewrap (bwrap). Bash was not run.');
         return {
@@ -127,7 +155,12 @@ function readOnlySandboxCommand(platform, tempRoot, cwd, shell, wrappedCommand,
     throw new Error(`Read-only Bash sandbox unavailable on ${platform}. Bash was not run.`);
 }
 function killProcess(child) {
-    if (child.pid && process.platform !== 'win32') {
+    if (child.pid && process.platform === 'win32') {
+        // Git Bash and PowerShell start their own children; end the whole tree.
+        spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+        return;
+    }
+    if (child.pid) {
         try {
             process.kill(-child.pid, 'SIGKILL');
             return;
@@ -270,9 +303,12 @@ export function createWorkspaceBashOperations(workspaceRoot, options = {}) {
             if (!isWithinWorkspace(root, canonicalCwd))
                 throw new Error('The Bash working directory is outside the active project workspace.');
             const scope = options.workspaceWriteScope?.() ?? bashWriteScope.getStore() ?? 'workspace';
+            const platform = options.platform ?? process.platform;
+            const shell = options.shell ?? hostShell;
             // Nothing widens a read-only scope: no Full Permission bypass, no outside request.
             if (scope === 'read-only') {
-                const platform = options.platform ?? process.platform;
+                if (platform === 'win32')
+                    throw new Error('Plan-mode Bash needs a read-only sandbox, which Windows does not have. Bash was not run.');
                 const tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'harness-read-only-bash-')));
                 try {
                     const spec = workspaceSandboxCommand(platform, root, canonicalCwd, command, [], tempRoot);
@@ -292,11 +328,15 @@ export function createWorkspaceBashOperations(workspaceRoot, options = {}) {
                 bypass = false;
             }
             if (bypass) {
-                const result = await runProcess({ executable: shellPath(), args: ['-c', command], marker: '' }, canonicalCwd, execOptions, null);
+                const result = await runProcess(unconfinedCommand(requireShell(shell), command), canonicalCwd, execOptions, null);
                 return { exitCode: result.exitCode };
             }
-            if (scope === 'outside') {
-                const reason = 'This command requests filesystem writes outside the active project workspace. It will not run until this one-call request is approved.';
+            // Without a sandbox every Windows command is an outside request: a person approves it once.
+            if (scope === 'outside' || platform === 'win32') {
+                const resolved = requireShell(shell);
+                const reason = scope === 'outside'
+                    ? 'This command requests filesystem writes outside the active project workspace. It will not run until this one-call request is approved.'
+                    : WINDOWS_UNSANDBOXED_REASON;
                 let approved = false;
                 try {
                     approved = await options.requestWorkspaceWriteScope?.({ command, cwd: canonicalCwd, workspaceRoot: root, reason }) ?? false;
@@ -306,12 +346,12 @@ export function createWorkspaceBashOperations(workspaceRoot, options = {}) {
                 }
                 if (!approved)
                     throw new Error(`${reason} Bash was not run.`);
-                execOptions.onData(Buffer.from('\n[Outside-workspace writes approved for this command; running once.]\n'));
-                const result = await runProcess({ executable: shellPath(), args: ['-c', command], marker: '' }, canonicalCwd, execOptions, null);
+                if (scope === 'outside')
+                    execOptions.onData(Buffer.from('\n[Outside-workspace writes approved for this command; running once.]\n'));
+                const result = await runProcess(unconfinedCommand(resolved, command), canonicalCwd, execOptions, null);
                 return { exitCode: result.exitCode };
             }
             assertNoExternalHardlinks(root);
-            const platform = options.platform ?? process.platform;
             const spec = workspaceSandboxCommand(platform, root, canonicalCwd, command);
             const result = await runProcess(spec, canonicalCwd, execOptions, spec.marker);
             return { exitCode: result.exitCode };

package/dist/sdk/core/workspaceWriteOperations.d.ts

@@ -7,6 +7,17 @@ export interface WorkspaceWriteAuthorization {
     expectedContentHash?: string;
     signal?: AbortSignal;
 }
+export interface AtomicWriteLaunch {
+    executable: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * How the atomic write helper starts. macOS and Linux run it inside the write-boundary sandbox.
+ * Windows has none, so Node runs the helper directly; the target was still canonicalized and
+ * authorized, and the rename replaces the directory entry rather than writing through an alias.
+ */
+export declare function atomicWriteLaunch(platform: NodeJS.Platform, root: string, additionalRoots: readonly string[]): AtomicWriteLaunch;
 declare function writeWorkspaceFile(path: string, content: string): Promise<void>;
 export declare const workspaceWriteOperations: {
     mkdir: (_directory: string) => Promise<void>;

package/dist/sdk/core/workspaceWriteOperations.js

@@ -52,6 +52,29 @@ try {
   throw error
 }
 `;
+/**
+ * How the atomic write helper starts. macOS and Linux run it inside the write-boundary sandbox.
+ * Windows has none, so Node runs the helper directly; the target was still canonicalized and
+ * authorized, and the rename replaces the directory entry rather than writing through an alias.
+ */
+export function atomicWriteLaunch(platform, root, additionalRoots) {
+    if (platform === 'win32') {
+        // Node needs SystemRoot to start on Windows; keep only what the helper requires.
+        const env = {};
+        for (const name of ['SystemRoot', 'windir', 'TEMP', 'TMP', 'USERPROFILE']) {
+            if (process.env[name])
+                env[name] = process.env[name];
+        }
+        return { executable: process.execPath, args: ['-e', atomicWriteScript], env };
+    }
+    const command = `exec ${shellQuote(process.execPath)} -e ${shellQuote(atomicWriteScript)}`;
+    const spec = workspaceSandboxCommand(platform, root, root, command, additionalRoots);
+    return {
+        executable: spec.executable,
+        args: spec.args,
+        env: { PATH: '/usr/bin:/bin', ...(process.env.HOME ? { HOME: process.env.HOME } : {}) }
+    };
+}
 function shellQuote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
@@ -96,17 +119,12 @@ async function runAtomicWrite(authorization, path, content) {
         throw new Error('The write authorization no longer matches the active workspace target.');
     }
     const additionalRoots = outside ? [nearestExistingDirectory(canonicalPath)] : [];
-    const command = `exec ${shellQuote(process.execPath)} -e ${shellQuote(atomicWriteScript)}`;
-    const spec = workspaceSandboxCommand(process.platform, root, root, command, additionalRoots);
-    const env = {
-        PATH: '/usr/bin:/bin',
-        ...(process.env.HOME ? { HOME: process.env.HOME } : {})
-    };
+    const launch = atomicWriteLaunch(process.platform, root, additionalRoots);
     await new Promise((resolvePromise, rejectPromise) => {
-        const child = spawn(spec.executable, spec.args, {
+        const child = spawn(launch.executable, launch.args, {
             cwd: root,
             detached: process.platform !== 'win32',
-            env,
+            env: launch.env,
             stdio: ['pipe', 'pipe', 'pipe'],
             windowsHide: true
         });

package/dist/sdk/doctor/checks.js

@@ -1,5 +1,9 @@
+import { randomUUID } from 'node:crypto';
 import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
-import { delimiter, isAbsolute, join } from 'node:path';
+import { basename, delimiter, isAbsolute, join } from 'node:path';
+import { hostShell, shellLabel } from "../core/shell.js";
+import { createWorkspaceBashOperations, workspaceSandboxBackend } from "../core/workspaceSandbox.js";
+import { resolveWorkspaceRoot } from "../core/workspace.js";
 import { defaultAssets } from "../terminal/terminals.js";
 import { loadPi, PINNED_PI_VERSION } from "../pi/runtime.js";
 import { list as listPlugins } from "../plugins/api.js";
@@ -12,18 +16,23 @@ import { BRAVE, TAVILY, EXA } from "../web/search.js";
 import { KEYLESS_SEARCH, WEB_PLUGIN } from "../web/tools.js";
 const pass = (evidence) => ({ status: 'pass', evidence });
 const fail = (evidence, remedy) => ({ status: 'fail', evidence, remedy });
-function executable(name) {
+function resolvedExecutable(name) {
     const paths = isAbsolute(name) ? [name] : (process.env.PATH ?? '').split(delimiter).filter(Boolean).map(dir => join(dir, name));
-    return paths.some(path => {
+    for (const path of paths) {
         try {
             accessSync(path, constants.X_OK);
-            return statSync(path).isFile();
-        }
-        catch {
-            return false;
+            if (statSync(path).isFile())
+                return path;
         }
-    });
+        catch { /* try the next PATH entry */ }
+    }
+    return null;
 }
+function executable(name) {
+    return resolvedExecutable(name) !== null;
+}
+/** One command written by the harness, not the model: it prints a fixed word and touches nothing. */
+const BASH_PROBE_COMMAND = `printf '%s\\n' harness-doctor`;
 export async function builtinChecks(harness, context, secrets, assets = defaultAssets()) {
     const check = (id, category, title, local) => ({ id, category, title, local });
     const account = () => context.accountId ? harness.accounts.find(context.accountId) : null;
@@ -96,10 +105,60 @@ export async function builtinChecks(harness, context, secrets, assets = defaultA
             }), tools: ['read', 'grep', 'find', 'ls', 'write', 'edit']
         },
         {
-            ...check('native.bash', 'tools', 'Native shell tool', async () => process.platform === 'win32'
-                ? { status: 'unverified', evidence: 'Windows shell resolution is delegated to Pi; no shell was launched.' }
-                : executable('bash') ? pass('Bash is executable on the inherited PATH. No shell command was run.') : fail('Bash was not found on the inherited PATH.', 'Verify the shell executable used by Pi.')),
-            tools: ['bash']
+            ...check('native.bash', 'tools', 'Native shell tool', async () => {
+                if (process.platform === 'win32') {
+                    const shell = hostShell();
+                    if (!shell)
+                        return fail('Neither Git Bash nor PowerShell was found.', 'Install Git for Windows, or restore Windows PowerShell.');
+                    return { status: 'warning', evidence: `Commands run in ${shellLabel(shell)} at ${shell.executable}. Windows has no workspace write-boundary sandbox, so each command asks for approval unless Full Permission is on, and plan mode cannot run commands. No shell command was run.`, remedy: 'Approve each command when asked, or turn on Full Permission for this session.' };
+                }
+                const shell = resolvedExecutable('bash');
+                if (!shell)
+                    return fail('Bash was not found on the inherited PATH.', 'Verify the shell executable used by Pi.');
+                // Bash runs inside the platform's write-boundary sandbox; without that backend every call
+                // fails before the command starts, so presence of bash alone is not readiness.
+                const backend = workspaceSandboxBackend(process.platform);
+                return backend
+                    ? pass(`Bash is executable at ${shell}, and the ${basename(backend)} workspace write-boundary sandbox it runs inside is present. No shell command was run.`)
+                    : fail(`Bash is executable at ${shell}, but the workspace write-boundary sandbox this platform needs is missing, so every Bash call fails before it runs.`, process.platform === 'linux' ? 'Install bubblewrap (bwrap) so Bash can run inside the workspace boundary.' : 'Restore the platform sandbox executable so Bash can run inside the workspace boundary.');
+            }),
+            tools: ['bash'],
+            live: {
+                notice: 'Run one fixed command written by the harness (printf) in the working folder, inside the same workspace write-boundary sandbox as a normal Bash call. No model input, no network request, no file written; only the exit status is reported.',
+                run: async (probe) => {
+                    if (process.platform === 'win32')
+                        return { status: 'unverified', evidence: 'On Windows every command needs a person to approve it, so the diagnostic does not run one.' };
+                    const refusal = await harness.sessions.diagnosticGate(probe.run, context.caller).check('bash', { command: BASH_PROBE_COMMAND });
+                    if (refusal)
+                        return { status: 'blocked', evidence: `The tool policy refused the diagnostic command: ${refusal}`, remedy: 'Review what the policy allows Bash to do in this session.' };
+                    const toolCallId = randomUUID();
+                    probe.run.emit('tool.started', { toolCallId, name: 'bash', summary: 'Synthetic diagnostic command' });
+                    let output = '';
+                    try {
+                        // The same root, boundary, hard-link scan and sandbox a real Bash call takes. A
+                        // diagnostic never widens that boundary, so Full Permission cannot change this result.
+                        const workspaceRoot = resolveWorkspaceRoot(context.cwd);
+                        const { exitCode } = await createWorkspaceBashOperations(workspaceRoot).exec(BASH_PROBE_COMMAND, workspaceRoot, {
+                            onData: chunk => { if (output.length < 400)
+                                output += chunk.toString('utf8'); },
+                            signal: probe.signal,
+                            timeout: 20
+                        });
+                        probe.run.emit('tool.completed', { toolCallId, name: 'bash', ok: exitCode === 0 });
+                        return exitCode === 0 && output.includes('harness-doctor')
+                            ? pass('A real command ran in the working folder through the workspace sandbox and returned exit status 0 with the expected output.')
+                            : fail(`The shell returned exit status ${exitCode ?? 'unknown'} for the diagnostic command.`, 'Review the shell executable, the workspace write-boundary sandbox and the working folder permissions.');
+                    }
+                    catch (error) {
+                        probe.run.emit('tool.completed', { toolCallId, name: 'bash', ok: false });
+                        return {
+                            status: 'blocked',
+                            evidence: `The command could not start in this working folder, so the shell itself was not exercised: ${error instanceof Error ? error.message : String(error)}`,
+                            remedy: 'Resolve what stops Bash before it runs (a hard-link alias in the workspace, a missing sandbox backend, or a redirected workspace root), or choose another working folder.'
+                        };
+                    }
+                }
+            }
         },
         check('runtime.storage', 'runtime', 'State and data storage', async () => {
             accessSync(harness.stateDir, constants.R_OK | constants.W_OK);

package/dist/sdk/harness.d.ts

@@ -4,6 +4,7 @@ import { Hub, type HubOptions } from "./hub/hub.js";
 import { type SecretStore } from "./accounts/secrets.js";
 import { Bus } from "./core/bus.js";
 import { type Directory, type HarnessEnv } from "./core/env.js";
+import { type LinkOpener } from "./core/links.js";
 import { ConnectedApps } from "./mcp/service.js";
 import type { AppOAuthClients } from "./mcp/types.js";
 import { Lessons } from "./history/lessons.js";
@@ -69,6 +70,8 @@ export interface HarnessOptions {
     hookImporter?: (address: string) => Promise<unknown>;
     /** Where managed worktrees are made, the prefix of branches they get, and how many `prune` keeps. */
     worktrees?: WorktreesOptions;
+    /** How a link a person clicked reaches the operating system. Defaults to the system's own opener. */
+    linkOpener?: LinkOpener;
 }
 /** What starting on a data root found and repaired. */
 export interface Recovery {
@@ -99,6 +102,8 @@ export declare class Harness {
     readonly env: Env;
     readonly stateDir: string;
     readonly policy: ToolPolicy;
+    /** How a link a person clicked reaches the operating system (page 10, `links.open`). */
+    readonly linkOpener: LinkOpener;
     readonly accounts: Accounts;
     readonly approvals: Approvals;
     readonly runs: RunRegistry;

package/dist/sdk/harness.js

@@ -15,6 +15,7 @@ import { DEFAULT_PRODUCT_NAME, EMPTY_DIRECTORY } from "./core/env.js";
 import { HarnessError } from "./core/errors.js";
 import { readJsonOr } from "./core/fs.js";
 import { closeIndex } from "./core/index.js";
+import { openWithSystem } from "./core/links.js";
 import { ConnectedApps } from "./mcp/service.js";
 import { migrateConnectionScopes } from "./mcp/scopeMigration.js";
 import { Lessons } from "./history/lessons.js";
@@ -26,6 +27,7 @@ import { VariantTrust } from "./variant/trust.js";
 import * as notes from "./wiki/notes.js";
 import * as pluginApi from "./plugins/api.js";
 import * as pluginInstall from "./plugins/install.js";
+import * as pluginProposals from "./plugins/proposals.js";
 import * as attachments from "./plugins/attachments.js";
 import { HARNESS_PLUGINS } from "./plugins/builtin.js";
 import { World } from "./world/world.js";
@@ -72,6 +74,8 @@ export class Harness {
     env;
     stateDir;
     policy;
+    /** How a link a person clicked reaches the operating system (page 10, `links.open`). */
+    linkOpener;
     accounts;
     approvals;
     runs;
@@ -118,6 +122,7 @@ export class Harness {
         this.env = new Env(options.dataRoot || null, options.directory ?? EMPTY_DIRECTORY, options.productName ?? DEFAULT_PRODUCT_NAME, this.bus);
         this.hub = new Hub(this, options.hub);
         this.policy = options.policy ?? {};
+        this.linkOpener = options.linkOpener ?? openWithSystem;
         configureBuiltins(options.builtins ?? []);
         this.trust = new VariantTrust(this.stateDir);
         this.refineHost = options.refineHost ?? null;
@@ -189,7 +194,7 @@ export class Harness {
             worktrees: this.worktrees
         });
         this.sideQuestions = new SideQuestions({ env: this.env, sessions: this.sessions, runs: this.runs });
-        this.world = new World({ root: () => this.env.root, stateDir: this.stateDir, secrets, browser: this.browserEnabled ? undefined : false, notesChanged: (sessionId, ids) => this.bus.emit({ type: 'annotations.changed', sessionId, ids }) });
+        this.world = new World({ root: () => this.env.root, stateDir: this.stateDir, secrets, browser: this.browserEnabled ? undefined : false });
         // The harness's own world tools come first; a tool an application provides under the same name is not added again.
         this.sessions.provide(this.world.provider());
         this.doctor = new Doctor({
@@ -200,7 +205,7 @@ export class Harness {
         this.refine = new Refinements({ root: () => this.env.root, bus: this.bus, trust: this.trust, host: () => this.refineHost, runtime: refineRuntime });
         this.lessons = new Lessons({ root: () => this.env.root, runtime: refineRuntime });
         this.pageNotes = new NoteDeliveries({ root: () => this.env.root, bus: this.bus, terminals: () => this.terminals ?? null });
-        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params) }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes });
+        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params), proposals: { list: () => pluginProposals.list(this.env.root), preview: id => pluginProposals.preview(this.env.root, id), accept: (id, hash) => pluginProposals.accept(this, id, hash), reject: (id, hash) => pluginProposals.reject(this.env.root, id, hash) } }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes });
         this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)));
         this.runs.listen((event, run) => {
             this.accounts.onRunEvent(event, run);
@@ -215,9 +220,9 @@ export class Harness {
             if (runEnded)
                 indexRunUsage(this.env.root, event.runId);
             if (runEnded && run?.sessionId) {
-                // Notes sent with "Proceed now" while this session was working go out now; the terminal
-                // needs a moment to see its run as ended.
-                setTimeout(() => void this.pageNotes.runEnded(run.sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error))), 250).unref?.();
+                // Notes sent while this session was working go out now (runEnded waits for the terminal to
+                // see its run as ended, and tries again while it is still busy).
+                void this.pageNotes.runEnded(run.sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error)));
             }
             if ((event.type === 'completed' || event.type === 'failed') && run) {
                 if (event.type === 'completed')
@@ -294,7 +299,7 @@ export class Harness {
                     if (!sessionId || recoveredSessions.has(sessionId))
                         continue;
                     recoveredSessions.add(sessionId);
-                    setTimeout(() => void this.pageNotes.runEnded(sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error))), 250).unref?.();
+                    void this.pageNotes.runEnded(sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error)));
                 }
                 catch {
                     // A malformed run record does not prevent the rest of recovery.

package/dist/sdk/hub/hub.js

@@ -316,7 +316,7 @@ export class Hub {
                     attachments.save(root, choicesBefore);
                 if (entry.delivery.kind === 'pi-package')
                     for (const pluginId of receipt.resourceIds)
-                        await packages.remove(this.harness, { pluginId });
+                        await packages.removeDirect(this.harness, { pluginId });
                 throw error;
             }
             this.harness.bus.emit({ type: 'hub.changed' });
@@ -404,8 +404,10 @@ export class Hub {
                     }
                 }
                 if (receipt.entry.delivery.kind === 'pi-package')
-                    for (const pluginId of receipt.resourceIds)
-                        await packages.remove(this.harness, { pluginId });
+                    for (const pluginId of receipt.resourceIds) {
+                        if ((await pluginApi.list(this.harness, {})).some((plugin) => plugin.id === pluginId && plugin.install))
+                            await packages.removeDirect(this.harness, { pluginId });
+                    }
                 writeJson(join(root, 'hub', 'installed.json'), records.filter((item) => item !== receipt));
                 committed = true;
                 try {

package/dist/sdk/index.d.ts

@@ -6,6 +6,7 @@ export { hubCatalogSchema, hubEntrySchema, hubOverviewSchema, hubReceiptSchema,
 export { Bus, log, type Notice } from "./core/bus.js";
 export { EMPTY_DIRECTORY, type Directory, type HarnessEnv } from "./core/env.js";
 export { HarnessError, invalid, notFound, toErrorShape, type ErrorShape } from "./core/errors.js";
+export { linkOpenCommand, linkTarget, openableTarget, openLink, openLinkTarget, openWithSystem, type LinkOpener, type LinkTarget, type OpenedTarget } from "./core/links.js";
 export { findBinary, searchPath } from "./core/path.js";
 export { fileSecretStore, memorySecretStore, secretKey, type SecretStore } from "./accounts/secrets.js";
 export type { Account, AccountsOverview, Pool } from "./accounts/store.js";
@@ -16,7 +17,7 @@ export type { RunCapabilitySnapshot } from "./capabilities/runSnapshot.js";
 export type { CallerContext } from "./core/caller.js";
 export { dispatch as harnessCall } from "./tools/dispatch.js";
 export { compile, render, SECTION_ORDER, CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY, type ContextPack, type HostSection, type HostToolGroup, type Launch, type Reference, type Section } from "./prompt/compile.js";
-export { runEventSchema, runRecordSchema, isActiveStatus, type ChecklistItem, type RunEvent, type RunEventType, type RunRecord } from "./sessions/contracts.js";
+export { runEventSchema, runRecordSchema, isActiveStatus, type TodoItem, type RunEvent, type RunEventType, type RunRecord } from "./sessions/contracts.js";
 export type { ApprovalFacts, ApprovalPolicy, AutomaticReason } from "./sessions/approvals.js";
 export type { ScopeDecision, ToolCall, ToolPolicy } from "./sessions/policy.js";
 export type { ActiveRun, ApprovalDecision, ApprovalInput, QuestionAnswer, QuestionInput } from "./sessions/registry.js";
@@ -30,7 +31,7 @@ export type { Effort } from "./sessions/runner.js";
 export { describeTool, HARNESS_TOOLS, DEFAULT_TOOL_NAMES, WIKI_WRITE, type HarnessCall, type HarnessToolDefinition } from "./tools/definitions.js";
 export type { ToolProvider, ToolResult, ToolSession, ToolSpec } from "./tools/types.js";
 export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from "./tools/spawnSubagent.js";
-export { CHECKLIST_WRITE, checklistOf } from "./tools/checklist.js";
+export { TODO_WRITE, todoOf, CHECKLIST_WRITE, checklistOf } from "./tools/todo.js";
 export { BUILTIN_PROFILES } from "./agents/builtin.js";
 export { PROFILE_COLORS, createProfile, listProfiles, parseProfile, profileDirs, removeProfile, resolveProfile, type AgentProfile, type ProfileColor, type ProfileListing, type ProfileProblem, type ProfileScope, type ProfileSource, type ProfileVariant } from "./agents/profiles.js";
 export { continuationOf, type Continuation, type ContinuationBlock } from "./sessions/continuation.js";

package/dist/sdk/index.js

@@ -15,6 +15,7 @@ export { hubCatalogSchema, hubEntrySchema, hubOverviewSchema, hubReceiptSchema }
 export { Bus, log } from "./core/bus.js";
 export { EMPTY_DIRECTORY } from "./core/env.js";
 export { HarnessError, invalid, notFound, toErrorShape } from "./core/errors.js";
+export { linkOpenCommand, linkTarget, openableTarget, openLink, openLinkTarget, openWithSystem } from "./core/links.js";
 export { findBinary, searchPath } from "./core/path.js";
 export { fileSecretStore, memorySecretStore, secretKey } from "./accounts/secrets.js";
 export { dispatch as harnessCall } from "./tools/dispatch.js";
@@ -25,7 +26,7 @@ export { STANDARD_CONNECTIONS } from "./prompt/standard.js";
 export { SideQuestions, SIDE_QUESTION_INSTRUCTION, buildSideQuestionText } from "./sessions/sideQuestions.js";
 export { describeTool, HARNESS_TOOLS, DEFAULT_TOOL_NAMES, WIKI_WRITE } from "./tools/definitions.js";
 export { SPAWN_SUBAGENT, SUBAGENT_RELATION } from "./tools/spawnSubagent.js";
-export { CHECKLIST_WRITE, checklistOf } from "./tools/checklist.js";
+export { TODO_WRITE, todoOf, CHECKLIST_WRITE, checklistOf } from "./tools/todo.js";
 export { BUILTIN_PROFILES } from "./agents/builtin.js";
 export { PROFILE_COLORS, createProfile, listProfiles, parseProfile, profileDirs, removeProfile, resolveProfile } from "./agents/profiles.js";
 export { continuationOf } from "./sessions/continuation.js";

package/dist/sdk/plugins/builtin.js

@@ -1,13 +1,13 @@
 // Built-in feature modules register their contributions here; this registry never loads Pi code.
 import { CONNECTION_TOOLS, NATIVE_GROUP } from "../prompt/compile.js";
 import { ASK_USER, askUserTool } from "../tools/askUser.js";
-import { CHECKLIST_WRITE, checklistTool } from "../tools/checklist.js";
+import { TODO_WRITE, todoTool } from "../tools/todo.js";
 import { CHECKPOINT_WRITE, checkpointTool } from "../tools/checkpoint.js";
 import { sliceOf } from "../sessions/workSlice.js";
 import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
 import { subagentTools } from "../tools/spawnSubagent.js";
 import { SESSION_NAME } from "../tools/sessionName.js";
-import { RECALL_TOOLS, SKILL_TOOLS, TRAJECTORY_TOOLS, WIKI_READ_TOOLS, WIKI_WRITE_TOOLS } from "../tools/definitions.js";
+import { PLUGIN_PROPOSAL_TOOLS, RECALL_TOOLS, SKILL_TOOLS, TRAJECTORY_TOOLS, WIKI_READ_TOOLS, WIKI_WRITE_TOOLS } from "../tools/definitions.js";
 import { FIRST_PARTY_PLUGINS } from "./firstParty.js";
 import { WEB_PLUGIN } from "../web/tools.js";
 import { KEYLESS_SEARCH, webPart } from "../web/part.js";
@@ -79,7 +79,7 @@ const WIKI_PLUGIN = {
 };
 const HISTORY_PLUGIN = { id: 'history', title: 'History', description: 'Search earlier conversations and inspect recorded run trajectories.', required: 'Earlier runs are how an agent picks up where work stopped.', tools: tools([...RECALL_TOOLS, ...TRAJECTORY_TOOLS]), toolGroups: ['History'] };
 const ASK_USER_PLUGIN = { id: 'ask-user', title: 'Ask the user', description: 'Lets the agent stop and ask a question with choices.', required: 'An agent must be able to stop and ask you.', tools: [{ name: ASK_USER }] };
-const CHECKLIST_PLUGIN = { id: 'checklist', title: 'Checklist', description: 'Lets the agent keep a checklist of the steps of its work, recorded with the run so progress can be shown and picked up again.', required: 'Progress of longer work is kept through it.', tools: [{ name: CHECKLIST_WRITE, description: 'Write the checklist' }] };
+const TODO_PLUGIN = { id: 'todo', title: 'Todo', description: 'Lets the agent keep a todo list of the steps of its work, recorded with the run so progress can be shown and picked up again.', required: 'Progress of longer work is kept through it.', tools: [{ name: TODO_WRITE, description: 'Write the todo list' }] };
 const CHECKPOINT_PLUGIN = { id: 'checkpoint', title: 'Checkpoint', description: 'Lets a bounded reply record a handoff at a work-slice boundary so the next slice starts from it.', required: 'A reply that stops at its budget leaves the state the next one resumes from.', tools: [{ name: CHECKPOINT_WRITE, description: 'Write the handoff checkpoint' }] };
 const CONNECTED_APPS_PLUGIN = {
     id: 'connected-apps',
@@ -93,6 +93,7 @@ const CONNECTED_APPS_PLUGIN = {
 const DOCTOR_PLUGIN = { id: 'doctor', title: 'Doctor', description: 'Local readiness checks and explicitly confirmed live probes for accounts, models and tools.', required: 'Every local terminal has readiness diagnostics.' };
 const WORKTREES_PLUGIN = { id: 'worktrees', title: 'Worktrees', description: 'Create and manage isolated git worktrees, move changes between them, and restore removed worktrees.', required: 'Managed worktrees are available to every local terminal.' };
 const HUB_PLUGIN = { id: 'hub', title: 'Hub', description: 'Browse and install reviewed skills, plugins and documents from configured registries.', required: 'Reviewed Harness resources are available to every host.' };
+const PLUGIN_AUTHORING = { id: 'plugin-authoring', title: 'Plugin authoring', description: 'Propose plugins for a person to review.', required: 'Plugin proposals are reviewed before installation.', tools: tools(PLUGIN_PROPOSAL_TOOLS) };
 const REFINEMENT_PLUGIN = { id: 'refinement', title: 'Refinement', description: 'Improve variants from recorded evidence through isolated refinement runs and reviewed candidates.', required: 'Variant refinement is available to every host.' };
 const CAPABILITIES_PLUGIN = { id: 'capabilities', title: 'Capability discovery', description: 'Inspect the callable tools of the current run, including their input schemas. Discovery never grants access.', required: 'Every interactive session can inspect its own registered capabilities.', tools: [{ name: GET_CAPABILITIES, description: 'Inspect current capabilities' }] };
 const USAGE_PLUGIN = {
@@ -130,7 +131,7 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
         serverMethods: historyServerMethods
     },
     { descriptor: ASK_USER_PLUGIN, toolOrder: 40, tools: context => context.harnessTools && context.allowedTools.includes(ASK_USER) ? [askUserTool(context.run)] : [] },
-    { descriptor: CHECKLIST_PLUGIN, toolOrder: 50, tools: context => context.harnessTools ? [checklistTool(context.run)] : [] },
+    { descriptor: TODO_PLUGIN, toolOrder: 50, tools: context => context.harnessTools ? [todoTool(context.run)] : [] },
     { descriptor: CHECKPOINT_PLUGIN, toolOrder: 51, tools: context => context.harnessTools && context.allowedTools.includes(CHECKPOINT_WRITE) ? [checkpointTool(context.run, () => sliceOf(context.env.root, context.runId))] : [] },
     {
         descriptor: CONNECTED_APPS_PLUGIN,
@@ -139,6 +140,7 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
         serverMethods: connectedAppServerMethods
     },
     { descriptor: HUB_PLUGIN, serverMethods: hubServerMethods },
+    { descriptor: PLUGIN_AUTHORING, ...toolContribution(PLUGIN_PROPOSAL_TOOLS, 31) },
     { descriptor: REFINEMENT_PLUGIN, serverMethods: refinementServerMethods },
     { descriptor: SIDE_QUESTIONS_PLUGIN, serverMethods: sideQuestionServerMethods },
     {
@@ -154,12 +156,14 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
     {
         descriptor: ANNOTATIONS_PLUGIN,
         commandPrefix: 'annotate',
-        defaultCommand: 'annotate',
+        defaultCommand: 'open',
         commands: [
-            { name: 'notes', description: 'Review web annotations saved from pages and apps' },
-            { name: 'annotate', description: 'Inspect a page or app, comment on components, and send fixes: /annotate:annotate [url | --app <devtools address> | --bridge]' }
+            { name: 'open', rootOnly: true, description: 'Annotate a page or app and send it to the agent: /annotate: [url | --app <port> | --bridge]' },
+            { name: 'notes', description: 'Every saved web annotation, searchable' },
+            { name: 'submit', description: 'Send this session\'s unsent annotations with your request: /annotate:submit <request>' },
+            { name: 'clear', description: 'Resolve this session\'s unsent annotations and stop sharing them' }
         ],
-        createWorldPart: ({ options }) => annotationsPart({ root: options.root, changed: options.notesChanged }),
+        createWorldPart: ({ options }) => annotationsPart({ root: options.root }),
         serverMethods: annotationServerMethods
     },
     { descriptor: CAPABILITIES_PLUGIN },
@@ -169,7 +173,8 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
         defaultCommand: 'analysis',
         commands: [
             { name: 'analysis', description: 'Token, cost and latency totals: /usage:analysis [today | 7d | 30d | all]' },
-            { name: 'limit', description: 'Provider plan windows, balances and rate limits: /usage:limit' }
+            { name: 'limit', description: 'Provider plan windows, balances and rate limits: /usage:limit' },
+            { name: 'accounts', description: 'Provider limits across all accounts: /usage:accounts' }
         ],
         serverMethods: usageServerMethods
     },

package/dist/sdk/plugins/builtinRegistry.d.ts

@@ -14,6 +14,8 @@ export interface BuiltinPluginCommand {
     name: string;
     description: string;
     legacyBare: boolean;
+    /** Reached only as the namespace root (`/annotate:`); it has no `/<prefix>:<name>` route and is not listed by name. */
+    rootOnly?: boolean;
 }
 export interface BuiltinWorldContext {
     options: WorldOptions;
@@ -36,7 +38,7 @@ export interface BuiltinPluginModule {
     descriptor: PluginDescriptor;
     /** Stable terminal command namespace; defaults to the plugin id. */
     commandPrefix?: string;
-    /** Command invoked by the namespace root, such as `/annotate:`. */
+    /** Command invoked by the namespace root, such as `/annotate:`. Mark it `rootOnly` to give it no named route. */
     defaultCommand?: string;
     /** Stable order for model tools, independent of descriptor display order. */
     toolOrder?: number;

package/dist/sdk/plugins/builtinRegistry.js

@@ -27,6 +27,10 @@ export function createBuiltinPluginRegistry(modules) {
         if (module.defaultCommand && !module.commands?.some(command => command.name === module.defaultCommand)) {
             throw new Error(`Unknown default command for built-in plugin ${id}: ${module.defaultCommand}`);
         }
+        for (const command of module.commands ?? []) {
+            if (command.rootOnly && command.name !== module.defaultCommand)
+                throw new Error(`Root-only command ${prefix}:${command.name} must be the default command of built-in plugin ${id}.`);
+        }
     }
     const commands = modules.flatMap(module => (module.commands ?? []).map(command => ({
         pluginId: module.descriptor.id,
@@ -34,12 +38,14 @@ export function createBuiltinPluginRegistry(modules) {
         ...command,
         legacyBare: !!module.descriptor.required
     })));
-    const byRoute = new Map(commands.map(command => [`${command.prefix}:${command.name}`, command]));
+    const allRoutes = new Map(commands.map(command => [`${command.prefix}:${command.name}`, command]));
+    const routed = commands.filter(command => !command.rootOnly);
+    const byRoute = new Map(routed.map(command => [`${command.prefix}:${command.name}`, command]));
     const byName = new Map();
-    for (const command of commands)
+    for (const command of routed)
         byName.set(command.name, [...(byName.get(command.name) ?? []), command]);
     const defaults = new Map(modules.flatMap(module => module.defaultCommand
-        ? [[module.commandPrefix ?? module.descriptor.id, byRoute.get(`${module.commandPrefix ?? module.descriptor.id}:${module.defaultCommand}`)]]
+        ? [[module.commandPrefix ?? module.descriptor.id, allRoutes.get(`${module.commandPrefix ?? module.descriptor.id}:${module.defaultCommand}`)]]
         : []));
     const toolModules = modules.map((module, index) => ({ module, index })).filter(({ module }) => module.tools)
         .sort((left, right) => (left.module.toolOrder ?? left.index) - (right.module.toolOrder ?? right.index));