@xingular/harness 1.2.0 → 1.3.1-unstable.0

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/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

@@ -16,7 +16,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 +30,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

@@ -25,7 +25,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,7 +1,7 @@
 // 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";
@@ -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',
@@ -130,7 +130,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,

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

@@ -10,11 +10,15 @@ export declare function normalizeSource(input: string): string;
 export declare function install(harness: Harness, params: PluginScope & {
     source: string;
 }): Promise<Plugin[]>;
-/** Removes an installed package. One kept as a folder beside a person's data is moved to the trash there. */
+/** Removes an installed package without consulting Hub. Hub calls this while it owns the receipt transaction. */
+export declare function removeDirect(harness: Harness, params: PluginScope & {
+    pluginId: string;
+}): Promise<Plugin[]>;
+/** Removes an installed package, delegating Hub-owned packages to their receipt owner. */
 export declare function remove(harness: Harness, params: PluginScope & {
     pluginId: string;
 }): Promise<Plugin[]>;
-/** Fetches a newer version of one installed package, or of all of them. Changed code waits for trust again. */
+/** Fetches newer versions of local packages. Hub-owned packages remain pinned to catalog versions. */
 export declare function update(harness: Harness, params: PluginScope & {
     pluginId?: string | null;
 }): Promise<Plugin[]>;

package/dist/sdk/plugins/install.js

@@ -75,8 +75,8 @@ function installed(plugins, pluginId) {
         throw invalid(`${plugin.title} was not installed as a package, so it cannot be removed or updated here.`);
     return plugin;
 }
-/** Removes an installed package. One kept as a folder beside a person's data is moved to the trash there. */
-export async function remove(harness, params) {
+/** Removes an installed package without consulting Hub. Hub calls this while it owns the receipt transaction. */
+export async function removeDirect(harness, params) {
     const plugin = installed(await list(harness, params), params.pluginId);
     if (plugin.install.kind === 'folder') {
         const trash = join(harness.env.root, 'trash', 'plugins');
@@ -98,13 +98,37 @@ export async function remove(harness, params) {
     changed(harness);
     return list(harness, params);
 }
-/** Fetches a newer version of one installed package, or of all of them. Changed code waits for trust again. */
+async function hubReceiptForPackage(harness, pluginId) {
+    const receipts = (await harness.hub.list()).installed.filter((receipt) => receipt.entry.delivery.kind === 'pi-package' && receipt.resourceIds.includes(pluginId));
+    if (receipts.length > 1)
+        throw invalid('More than one Hub receipt owns this package. Review the Hub receipts before changing it.');
+    return receipts[0];
+}
+/** Removes an installed package, delegating Hub-owned packages to their receipt owner. */
+export async function remove(harness, params) {
+    const receipt = await hubReceiptForPackage(harness, params.pluginId);
+    if (receipt) {
+        await harness.hub.uninstall(receipt.entry.id, receipt.entry.version);
+        return list(harness, params);
+    }
+    return removeDirect(harness, params);
+}
+/** Fetches newer versions of local packages. Hub-owned packages remain pinned to catalog versions. */
 export async function update(harness, params) {
-    const plugin = params.pluginId ? installed(await list(harness, params), params.pluginId) : null;
+    const plugins = await list(harness, params);
+    const plugin = params.pluginId ? installed(plugins, params.pluginId) : null;
     if (plugin?.install.kind === 'folder')
         throw invalid(`${plugin.title} is a folder on this machine. Change its files to update it.`);
+    const receipts = (await harness.hub.list()).installed.filter((receipt) => receipt.entry.delivery.kind === 'pi-package');
+    const hubOwned = new Set(receipts.flatMap((receipt) => receipt.resourceIds));
+    if (plugin && hubOwned.has(plugin.id))
+        throw invalid(`${plugin.title} is managed by Hub. Uninstall its receipt before installing another exact catalog version.`);
+    const sources = plugin
+        ? [plugin.install.source]
+        : [...new Set(plugins.filter((candidate) => candidate.install && candidate.install.kind !== 'folder' && !hubOwned.has(candidate.id)).map((candidate) => candidate.install.source))];
     const { packages } = await manager(harness);
-    await withoutInstallScripts(() => packages.update(plugin?.install.source));
+    for (const source of sources)
+        await withoutInstallScripts(() => packages.update(source));
     changed(harness);
     return list(harness, params);
 }

package/dist/sdk/plugins/inventory.js

@@ -6,7 +6,7 @@ import { charCount } from "../core/text.js";
 import { allowed } from "../mcp/connections.js";
 import { BUILT_IN_DYNAMIC, compile, toolGroups } from "../prompt/compile.js";
 import { ASK_USER } from "../tools/askUser.js";
-import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { TODO_WRITE } from "../tools/todo.js";
 import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
 import { VARIANT_PLUGIN } from "./builtin.js";
 const size = (path) => {
@@ -68,7 +68,7 @@ export function inventory(input) {
     }
     const names = [...input.tools];
     const extensionToolNames = new Set(input.plugins.filter((plugin) => ['project', 'package', 'shared', 'home'].includes(plugin.source)).flatMap((plugin) => plugin.contributions.filter((entry) => entry.kind === 'tool' && entry.state === 'on').map((entry) => entry.name)));
-    for (const name of [ASK_USER, CHECKLIST_WRITE, ...DEFAULT_TOOL_NAMES, ...(input.connections ? ['mcp_list_tools', 'mcp_call_tool'] : [])])
+    for (const name of [ASK_USER, TODO_WRITE, ...DEFAULT_TOOL_NAMES, ...(input.connections ? ['mcp_list_tools', 'mcp_call_tool'] : [])])
         if (!names.includes(name))
             names.push(name);
     for (const name of names) {

package/dist/sdk/prompt/compile.d.ts

@@ -1,7 +1,7 @@
 import { type CallerContext } from "../core/caller.js";
 import type { HarnessEnv } from "../core/env.js";
 import type { Materialised } from "../variant/materialise.js";
-import type { ChecklistItem } from "../sessions/contracts.js";
+import type { TodoItem } from "../sessions/contracts.js";
 import { type StandardSession } from "./standard.js";
 export declare const REFERENCES_BUDGET = 12000;
 /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
@@ -135,7 +135,7 @@ export declare function clip(text: string, limit: number): string;
 /** A bounded, request-scoped checkpoint reintroduced after context compaction. */
 export declare function renderCompactionCheckpoint(input: {
     goal: string;
-    checklist: readonly ChecklistItem[];
+    todo: readonly TodoItem[];
     planInstructions?: string | null;
 }): string | null;
 export interface OrderedGroup extends ToolGroup {

package/dist/sdk/prompt/compile.js

@@ -13,9 +13,9 @@ import { isDir, now, readJson, safeId, writeJson } from "../core/fs.js";
 import { charCount, compareText, lines, takeChars } from "../core/text.js";
 import * as notes from "../wiki/notes.js";
 import { isWorldTool, WORLD_GUIDANCE } from "../world/untrusted.js";
-import { CHECKLIST_WRITE, describeChecklist } from "../tools/checklist.js";
+import { TODO_GUIDANCE, TODO_WRITE, describeTodo } from "../tools/todo.js";
 import { CHECKPOINT_WRITE } from "../tools/checkpoint.js";
-import { SESSION_NAME } from "../tools/sessionName.js";
+import { SESSION_GUIDANCE, SESSION_NAME } from "../tools/sessionName.js";
 import { ANNOTATIONS_GUIDANCE, STANDARD_CONNECTIONS, standardSections } from "./standard.js";
 const IDENTITY_BUDGET = 1000;
 const WIKI_BUDGET = 2500;
@@ -72,21 +72,21 @@ export function clip(text, limit) {
 }
 /** A bounded, request-scoped checkpoint reintroduced after context compaction. */
 export function renderCompactionCheckpoint(input) {
-    if (!input.checklist.length && !input.planInstructions)
+    if (!input.todo.length && !input.planInstructions)
         return null;
     const parts = [
         'This is current state from the active run after context compaction, not a new user request. Continue the same request. Do not infer that omitted details or decisions were settled.',
         input.goal.trim() ? `## Current request\n\n${clip(input.goal.trim(), 1_000)}` : '',
         input.planInstructions ? `## Active plan instructions\n\n${clip(input.planInstructions, 4_000)}` : ''
     ].filter(Boolean);
-    if (input.checklist.length) {
-        const active = input.checklist.filter((item) => item.status !== 'completed');
-        const completed = input.checklist.filter((item) => item.status === 'completed');
-        const checklist = [
-            active.length ? `### In progress and pending\n${clip(describeChecklist(active), 2_500)}` : '',
-            completed.length ? `### Completed (${completed.length})\n${clip(describeChecklist(completed), 500)}` : ''
+    if (input.todo.length) {
+        const active = input.todo.filter((item) => item.status !== 'completed');
+        const completed = input.todo.filter((item) => item.status === 'completed');
+        const todo = [
+            active.length ? `### In progress and pending\n${clip(describeTodo(active), 2_500)}` : '',
+            completed.length ? `### Completed (${completed.length})\n${clip(describeTodo(completed), 500)}` : ''
         ].filter(Boolean).join('\n\n');
-        parts.push(`## Current checklist\n\n${checklist}`);
+        parts.push(`## Current todo list\n\n${todo}`);
     }
     const body = clip(parts.join('\n\n'), 8_000);
     return `[Harness context update — not a user message]\n\n## Compaction checkpoint\n\n${body}`;
@@ -153,20 +153,18 @@ export function toolGroups(context, launch, dataRoot) {
         { group: 'World', tools: enabled.filter((name) => isWorldTool(name) && !(launch.toolGroups ?? []).some((group) => group.tools.includes(name))), order: GROUP_ORDER.World, guidance: `Web, browser and screen: ${WORLD_GUIDANCE}` },
         ...(launch.toolGroups ?? []).map((group) => ({ group: group.group, tools: group.tools, order: group.order, guidance: group.guidance }))
     ];
-    const progressTools = [CHECKLIST_WRITE, CHECKPOINT_WRITE].filter((name) => enabled.includes(name));
+    const progressTools = [TODO_WRITE, CHECKPOINT_WRITE].filter((name) => enabled.includes(name));
     if (progressTools.length) {
-        const checklist = enabled.includes(CHECKLIST_WRITE)
-            ? 'for work with several steps, write a checklist early with checklist_write and keep it current. Before your final reply, write one final update marking every fully completed step completed; leave unfinished or blocked steps accurate. The user follows your work from it, and a subagent\'s checklist shows as its progress in the user\'s list of subagents.'
-            : '';
+        const todo = enabled.includes(TODO_WRITE) ? TODO_GUIDANCE : '';
         const checkpoint = enabled.includes(CHECKPOINT_WRITE)
             ? 'a reply has a work-slice budget; when it is reached the harness asks for a handoff, and checkpoint_write records what is done, the next step, anything blocking, the files touched and the checks that matter, so the next slice starts from it instead of re-reading everything.'
             : '';
-        groups.push({ group: 'Progress', tools: progressTools, order: 87, guidance: `Progress: ${[checklist, checkpoint].filter(Boolean).join(' ')}` });
+        groups.push({ group: 'Progress', tools: progressTools, order: 87, guidance: `Progress: ${[todo, checkpoint].filter(Boolean).join(' ')}` });
     }
     if (enabled.includes(SESSION_NAME)) {
         groups.push({
             group: 'Session', tools: [SESSION_NAME], order: 88,
-            guidance: 'Session: use session_name to name meaningful work early with a short imperative sentence of at most six words. Revise when the overall objective changes, including a manually assigned name. Greetings alone need no name.'
+            guidance: `Session: ${SESSION_GUIDANCE}`
         });
     }
     const annotations = ANNOTATION_TOOLS.filter((name) => enabled.includes(name) && !(launch.toolGroups ?? []).some((group) => group.tools.includes(name)));

package/dist/sdk/server/methods.js

@@ -17,7 +17,7 @@ import { listCommands } from "../commands/list.js";
 import { selectHistory } from "../sessions/history.js";
 import { runsSince } from "../sessions/runIndex.js";
 import { findRun, listRuns, loadRun, pendingDecisions, readEvents, runFamily, snapshot } from "../sessions/runStore.js";
-import { checklistOf } from "../tools/checklist.js";
+import { todoOf } from "../tools/todo.js";
 import { dispatch } from "../tools/dispatch.js";
 import * as components from "../variant/components.js";
 import { materialise } from "../variant/materialise.js";
@@ -234,7 +234,9 @@ export function methods(harness) {
         'runs.since': (params) => runsSince(root(), { session: optional(params.filter ?? {}, 'session'), agent: optional(params.filter ?? {}, 'agent'), account: optional(params.filter ?? {}, 'account') }, optional(params, 'since')),
         'runs.events': (params) => readEvents(root(), text(params, 'runId')),
         'runs.pending': (params) => pendingDecisions(readEvents(root(), text(params, 'runId'))),
-        'runs.checklist': (params) => checklistOf(readEvents(root(), text(params, 'runId'))),
+        'runs.todo': (params) => todoOf(readEvents(root(), text(params, 'runId'))),
+        // Pre-rename name; kept for one release so existing hosts keep working.
+        'runs.checklist': (params) => todoOf(readEvents(root(), text(params, 'runId'))),
         'runs.continuation': (params) => continuationOf(root(), text(params, 'runId'), optional(params, 'sessionDir')),
         'runs.active': () => runs.activeRunIds(),
         'runs.interrupt': async (params) => {

package/dist/sdk/sessions/compactionCheckpoint.d.ts

@@ -1,9 +1,9 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { type ChecklistItem } from "./contracts.js";
+import { type TodoItem } from "./contracts.js";
 export declare const COMPACTION_CHECKPOINT_EXTENSION = "compaction-checkpoint";
 export interface CompactionCheckpointOptions {
-    /** A stopped run's persisted checklist, when the active run is a continuation. */
-    initialChecklist?: readonly ChecklistItem[];
+    /** A stopped run's persisted todo, when the active run is a continuation. */
+    initialTodo?: readonly TodoItem[];
     /** The current dynamic plan instructions, if this request is in plan mode. */
     planInstructions?: () => string | null;
 }