@xingular/harness 1.0.0 → 1.1.1

package/dist/sdk/terminal/browserControl.d.ts

@@ -0,0 +1,29 @@
+import * as path from 'node:path';
+import type { Hub } from "../hub/hub.js";
+import type { ConnectedApps } from "../mcp/service.js";
+import type { Plugin } from "../plugins/types.js";
+import type { Materialised } from "../variant/materialise.js";
+import type { BrowserSnapshot } from "./browser.js";
+type PathApi = Pick<typeof path, 'relative' | 'sep' | 'isAbsolute'>;
+export declare function isWithinBoundary(boundary: string, file: string, pathApi?: PathApi): boolean;
+export interface BrowserControlOptions {
+    root: string;
+    cwd: string;
+    pinned: Materialised | null;
+    writable: boolean;
+    plugins(): Promise<Plugin[]>;
+    hub?: Hub;
+    apps: ConnectedApps;
+}
+/** Only the protected terminal control route calls this adapter. It never loads discovered code. */
+export declare class BrowserControl {
+    private readonly options;
+    constructor(options: BrowserControlOptions);
+    snapshot(refresh?: boolean): Promise<BrowserSnapshot>;
+    read(id: string, latestVersion?: boolean): Promise<{
+        content: string;
+    }>;
+    importSkill(input: string): void;
+    connection(action: string, params: Record<string, unknown>): Promise<unknown>;
+}
+export {};

package/dist/sdk/terminal/browserControl.js

@@ -0,0 +1,186 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import * as path from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { invalid } from "../core/errors.js";
+import { connectionInputSchema } from "../mcp/types.js";
+import * as library from "../variant/components.js";
+import { PI_SURFACE, componentOf } from "../variant/surface.js";
+import { headVariant } from "../variant/store.js";
+const MAX_CONTENT = 256 * 1024;
+export function isWithinBoundary(boundary, file, pathApi = path) {
+    const within = pathApi.relative(boundary, file);
+    return within !== '..' && !within.startsWith(`..${pathApi.sep}`) && !pathApi.isAbsolute(within);
+}
+function readText(path) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_CONTENT)
+            throw invalid('Preview requires a regular text file smaller than 256 KiB.');
+        return readFileSync(fd, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Only the protected terminal control route calls this adapter. It never loads discovered code. */
+export class BrowserControl {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async snapshot(refresh = false) {
+        const { root, pinned, apps } = this.options;
+        const plugins = await this.options.plugins();
+        const scope = pinned?.scope ?? null;
+        const latest = scope ? headVariant(root, scope) : null;
+        const items = [];
+        const add = (item) => items.push(item);
+        for (const [id, name, description] of [
+            ['runtime', 'Runtime and recording', 'The foundation runs sessions and records their events. Changes require a release.'],
+            ['prompt', 'Prompt compiler', 'Assembles the stable prompt and context updates. Variant c1–c4 supply configurable instructions.'],
+            ['loader', 'Resource loader', 'Selects plugins and their contributions. Discovered code waits for exact-code trust.'],
+            ['gate', 'Tool approval gate', 'Checks capabilities, policy and approvals for every tool call. Availability never grants authorization.'],
+            ['accounts', 'Accounts and secrets', 'Keeps account identities isolated and credentials in the secret store.'],
+            ['surface', 'Variant surface', 'Defines c1–c8, validation and immutable versions. Only a validated variant version may change.']
+        ])
+            add({ id: `foundation:${id}`, section: 'foundation', name: name, description: description, owner: 'Foundation', origin: 'Built-in', status: 'Read-only' });
+        for (const plugin of plugins) {
+            add({ id: `plugin:${plugin.id}`, section: 'plugins', name: plugin.title, description: plugin.description,
+                owner: plugin.title, origin: plugin.source, status: plugin.required ? 'Required' : plugin.trust === 'untrusted' ? 'Needs trust' : 'Saved configuration',
+                pluginId: plugin.id, path: plugin.path ?? undefined, required: plugin.required });
+            for (const entry of plugin.contributions) {
+                if (!['skill', 'tool', 'command', 'instruction'].includes(entry.kind))
+                    continue;
+                if ((entry.kind === 'command' || entry.kind === 'instruction') && !entry.path)
+                    continue;
+                const section = entry.kind === 'skill' ? 'skills' : entry.kind === 'tool' ? 'tools' : 'library';
+                add({ id: `contribution:${entry.id}`, section, name: entry.name, description: entry.description,
+                    owner: plugin.title, origin: plugin.source, pluginId: plugin.id, contributionId: entry.id,
+                    path: entry.path ?? undefined, scope: entry.scope, status: entry.state === 'off' ? 'Disabled' : entry.state === 'untrusted' ? 'Needs trust' : 'Enabled for future sessions',
+                    read: Boolean(entry.path && ['skill', 'command', 'instruction'].includes(entry.kind)) });
+            }
+        }
+        for (const item of library.list(root)) {
+            const added = Boolean(latest && library.isInVariant(root, latest.variant, item.id));
+            const existing = items.find(existing => existing.path === item.path);
+            if (existing) {
+                existing.componentId = item.id;
+                existing.added = added;
+                continue;
+            }
+            add({ id: `library:${item.id}`, section: item.kind === 'skills' ? 'skills' : 'library', name: item.name,
+                description: item.description, owner: 'Reusable library', origin: item.builtin ? 'Built-in library' : 'Local library', path: item.path,
+                componentId: item.id, added, status: added ? 'Saved in latest variant' : 'Library only', read: true });
+        }
+        const paths = new Set([...Object.keys(pinned?.files ?? {}), ...Object.keys(latest?.variant ?? {})]);
+        for (const path of [...paths].sort()) {
+            const component = PI_SURFACE.components.find(entry => entry.id === componentOf(PI_SURFACE, path));
+            if (!component)
+                continue;
+            const current = pinned?.files[path];
+            const future = latest?.variant[path];
+            const status = !latest || current === future ? 'Pinned version' : current === undefined ? 'Added in latest' : future === undefined ? 'Removed in latest' : 'Changed in latest';
+            add({ id: `variant:${path}`, section: 'variant', name: path, description: `c${component.index} · ${component.title}: ${component.description}`,
+                owner: 'Variant', origin: 'Variant', status, read: true });
+            if (/^skills\/[^/]+\/SKILL\.md$/.test(path) && current !== undefined) {
+                const name = path.split('/')[1];
+                const fullPath = join(pinned.dir, path);
+                if (!items.some(item => item.section === 'skills' && item.path === fullPath))
+                    add({ id: `variant-skill:${path}`, section: 'skills', name,
+                        description: /^description:\s*(.+)$/m.exec(current)?.[1] ?? '', owner: 'Variant', origin: 'Variant', status: 'Prepared for this session',
+                        path: fullPath, read: true });
+            }
+        }
+        const connections = apps.connections.list().map(connection => ({ ...connection,
+            error: connection.error ? String(apps.connections.scrub(connection.error, connection.id)) : null,
+            tools: apps.connections.scrub(connection.tools, connection.id) }));
+        for (const connection of connections)
+            add({ id: `connection:${connection.id}`, section: 'connections', name: connection.name || connection.id,
+                description: `${connection.kind === 'remote' ? 'Remote HTTP' : 'Local stdio'} MCP · ${connection.tools.length} tools${connection.checkedAt ? ` · last checked ${connection.checkedAt}` : ' · never tested'}`,
+                owner: 'Connected apps', origin: connection.kind === 'remote' ? 'Remote' : 'Local', connectionId: connection.id,
+                scope: connection.global ? 'Everywhere' : connection.projectIds.join(', ') || 'No project scope',
+                status: !connection.enabled ? 'Disabled' : connection.auth === 'oauth' && connection.authState !== 'signed_in' ? 'Sign in required' : connection.error ? 'Last check failed' : connection.checkedAt ? 'Last check passed' : 'Not tested' });
+        return { items, plugins, connections, variant: { scope, pinned: pinned?.fingerprint ?? null, latest: latest?.fingerprint ?? null,
+                writable: this.options.writable && Boolean(scope && latest) }, hub: this.options.hub ? await this.options.hub.list(refresh) : null };
+    }
+    async read(id, latestVersion = false) {
+        const { root, pinned } = this.options;
+        const snapshot = await this.snapshot();
+        const item = snapshot.items.find(entry => entry.id === id);
+        if (!item?.read)
+            throw invalid('This resource has no inspectable content.');
+        if (id.startsWith('variant:') || id.startsWith('variant-skill:')) {
+            const path = id.slice(id.indexOf(':') + 1);
+            const files = latestVersion && pinned?.scope ? headVariant(root, pinned.scope)?.variant : pinned?.files;
+            const content = files?.[path] ?? '(File absent in this version.)';
+            return { content: content.length > MAX_CONTENT ? content.slice(0, MAX_CONTENT) + '\n[Preview truncated.]' : content };
+        }
+        if (!item.path)
+            throw invalid('This resource has no file.');
+        const plugin = snapshot.plugins.find(plugin => plugin.id === item.pluginId);
+        const registryItem = item.componentId ? library.list(root).find(entry => entry.id === item.componentId) : undefined;
+        const boundary = realpathSync(registryItem && !registryItem.builtin ? join(root, 'registry') : plugin?.path ?? dirname(item.path));
+        const file = realpathSync(item.path);
+        if (!isWithinBoundary(boundary, file))
+            throw invalid('Resource is outside its owner folder.');
+        return { content: readText(file) };
+    }
+    importSkill(input) {
+        const start = resolve(this.options.cwd, input);
+        const folder = lstatSync(start).isDirectory() ? start : dirname(start);
+        if (start !== folder && basename(start) !== 'SKILL.md')
+            throw invalid('Choose a skill folder or its SKILL.md.');
+        const files = [];
+        let bytes = 0;
+        let directories = 0;
+        const visit = (directory, depth = 0) => {
+            if (++directories > 100 || depth > 16)
+                throw invalid('Skill import exceeds its directory limit.');
+            for (const name of readdirSync(directory)) {
+                if (name.startsWith('.'))
+                    continue;
+                const path = join(directory, name);
+                const stat = lstatSync(path);
+                if (stat.isSymbolicLink())
+                    throw invalid('Skill imports cannot contain symbolic links.');
+                if (stat.isDirectory()) {
+                    visit(path, depth + 1);
+                    continue;
+                }
+                if (!stat.isFile() || files.length >= 100 || stat.size > 10 * 1024 * 1024)
+                    throw invalid('Skill import exceeds its file limit.');
+                bytes += stat.size;
+                if (bytes > 10 * 1024 * 1024)
+                    throw invalid('Skill import exceeds 10 MiB.');
+                files.push({ path: relative(folder, path), content: readFileSync(path).toString('base64'), encoding: 'base64' });
+            }
+        };
+        if (lstatSync(folder).isSymbolicLink())
+            throw invalid('Choose a regular skill folder.');
+        visit(folder);
+        library.importItems(this.options.root, 'skills', [{ name: basename(folder), files }]);
+    }
+    async connection(action, params) {
+        const apps = this.options.apps;
+        if (action === 'appClients')
+            return apps.appClients();
+        if (action === 'save')
+            return apps.save(connectionInputSchema.parse(params.input));
+        const id = typeof params.id === 'string' ? params.id : '';
+        if (!apps.connections.list().some(connection => connection.id === id))
+            throw invalid('Unknown connection.');
+        if (action === 'test') {
+            const result = await apps.test(id);
+            return { ...result, error: result.error ? String(apps.connections.scrub(result.error, id)) : null,
+                tools: apps.connections.scrub(result.tools, id) };
+        }
+        if (action === 'signIn')
+            return apps.signIn(id);
+        if (action === 'signOut')
+            return apps.signOut(id);
+        if (action === 'remove')
+            return apps.remove(id);
+        throw invalid('Unknown connection action.');
+    }
+}

package/dist/sdk/terminal/commandHelp.d.ts

@@ -0,0 +1,17 @@
+export interface TerminalCommandCompletion {
+    name: string;
+    aliases?: string[];
+    description?: string;
+    group: string;
+}
+export interface TerminalCommandHelpEntry {
+    name: string;
+    aliases?: string[];
+    description?: string;
+}
+export declare function formatTerminalCommandLabel(name: string, aliases?: readonly string[]): string;
+export interface TerminalCommandHelpGroup {
+    name: string;
+    commands: TerminalCommandHelpEntry[];
+}
+export declare function groupTerminalCommands(commands: readonly TerminalCommandCompletion[]): TerminalCommandHelpGroup[];

package/dist/sdk/terminal/commandHelp.js

@@ -0,0 +1,20 @@
+export function formatTerminalCommandLabel(name, aliases) {
+    return aliases?.length ? `${name} (${aliases.join(', ')})` : name;
+}
+const GROUP_ORDER = ['Core', 'Run', 'Model', 'Session', 'Inspect', 'Harness', 'Plugins', 'Extensions', 'Prompts'];
+export function groupTerminalCommands(commands) {
+    const groups = new Map();
+    for (const command of commands) {
+        const group = groups.get(command.group) ?? [];
+        group.push({
+            name: command.name,
+            ...(command.aliases?.length ? { aliases: command.aliases } : {}),
+            description: command.description
+        });
+        groups.set(command.group, group);
+    }
+    const order = new Map(GROUP_ORDER.map((name, index) => [name, index]));
+    return [...groups]
+        .sort(([left], [right]) => (order.get(left) ?? GROUP_ORDER.length) - (order.get(right) ?? GROUP_ORDER.length))
+        .map(([name, entries]) => ({ name, commands: entries }));
+}

package/dist/sdk/terminal/controller.d.ts

@@ -1,5 +1,6 @@
-import type { RunEvent } from "../sessions/contracts.js";
+import { type RunEvent, type RunRecord } from "../sessions/contracts.js";
 import type { ActiveRun, ApprovalDecision, QuestionAnswer } from "../sessions/registry.js";
+import { type TerminalSubagentActivity, type TerminalSubagentProfile } from "./subagentMonitor.js";
 export interface PolicyReply {
     allowed: boolean;
     reason?: string | null;
@@ -35,6 +36,7 @@ export declare class TerminalController {
     private readonly hooks;
     private run;
     private readonly pending;
+    private readonly subagents;
     private ready;
     private disposed;
     private dirty;
@@ -64,6 +66,10 @@ export declare class TerminalController {
     disconnected(): void;
     /** Project registry-owned questions, including grouped requests, into the terminal inbox. */
     observe(event: RunEvent, descendant?: boolean): void;
+    /** A child event that belongs to the active terminal parent run. */
+    observeSubagent(parentRunId: string, run: RunRecord, event: RunEvent, profile?: TerminalSubagentProfile | null): void;
+    /** Read-only child activity for the active run. */
+    subagentSnapshot(): TerminalSubagentActivity[];
     /** The socket grants this interface only to the process that owns terminal input. */
     control(call: string, data: Record<string, any>): Promise<unknown>;
     private requestNativeApproval;

package/dist/sdk/terminal/controller.js

@@ -4,12 +4,16 @@
 // extension's questions about policy, approvals, and what to do next.
 import { createHash, randomUUID } from 'node:crypto';
 import { HarnessError } from "../core/errors.js";
+import { runStatusSchema } from "../sessions/contracts.js";
+import { briefTitle } from "../sessions/subagents.js";
+import { SubagentMonitor } from "./subagentMonitor.js";
 const READY_TIMEOUT_MS = 90_000;
 const ACK_TIMEOUT_MS = 25_000;
 export class TerminalController {
     hooks;
     run = null;
     pending = new Map();
+    subagents = new SubagentMonitor();
     ready = false;
     disposed = false;
     dirty = false;
@@ -48,6 +52,7 @@ export class TerminalController {
             throw new Error('The native prompt did not match the reserved delivery. Inspect the terminal before continuing.');
         const run = this.hooks.begin({ reservedRunId: delivery?.runId ?? null, nativeTurnId, text });
         this.run = run;
+        this.subagents.begin(run.runId);
         run.onInterrupt(() => void this.commands.push({ type: 'interrupt' }));
         if (text)
             run.emit('message.completed', { messageId: nativeTurnId, role: 'user', text });
@@ -56,7 +61,9 @@ export class TerminalController {
         return run;
     }
     finish(outcome, message) {
+        const runId = this.run?.runId;
         this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined);
+        this.subagents.clear(runId);
         this.run = null;
         this.seen.clear();
         this.pending.clear();
@@ -138,6 +145,27 @@ export class TerminalController {
             this.pending.delete(String(event.payload.questionId));
         }
     }
+    /** A child event that belongs to the active terminal parent run. */
+    observeSubagent(parentRunId, run, event, profile = null) {
+        if (this.disposed || this.activeRun?.runId !== parentRunId || run.relation !== 'subagent')
+            return;
+        this.subagents.observe(parentRunId, {
+            id: run.id,
+            parentRunId: run.parentRunId,
+            relation: 'subagent',
+            title: run.title ?? briefTitle(run.goal),
+            goal: run.goal,
+            status: runStatusSchema.parse(run.status),
+            startedAt: run.startedAt,
+            endedAt: run.endedAt,
+            profile
+        }, event);
+    }
+    /** Read-only child activity for the active run. */
+    subagentSnapshot() {
+        const run = this.activeRun;
+        return run ? this.subagents.snapshot(run.runId) : [];
+    }
     /** The socket grants this interface only to the process that owns terminal input. */
     async control(call, data) {
         if (this.disposed)
@@ -301,8 +329,10 @@ export class TerminalController {
             if (existing)
                 return event === 'approval' ? { decision: await existing } : existing;
             if (event === 'question') {
-                const response = run.requestAnswer({ requestId: key, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect, allowText: true });
-                this.pending.set(key, { type: 'question', requestId: key, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect });
+                const summary = typeof data.summary === 'string' && data.summary.trim() ? data.summary.trim() : undefined;
+                const sketchMode = data.uiSketch === undefined ? {} : { uiSketch: data.uiSketch };
+                const response = run.requestAnswer({ requestId: key, ...(summary ? { summary } : {}), ...sketchMode, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect, allowText: true });
+                this.pending.set(key, { type: 'question', requestId: key, ...(summary ? { summary } : {}), ...sketchMode, question: String(data.question ?? ''), options: data.options ?? [], multiSelect: !!data.multiSelect });
                 this.seen.set(key, response);
                 return response.finally(() => this.pending.delete(key));
             }
@@ -324,6 +354,8 @@ export class TerminalController {
         }
         if (event === 'usage')
             run.emit('usage.updated', data);
+        else if (event === 'checklist')
+            run.emit('checklist.updated', { items: data.items });
         else if (event === 'file')
             run.emit('file.changed', data);
         else if (event === 'message')

package/dist/sdk/terminal/opentui/subagentsWidget.d.ts

@@ -0,0 +1,28 @@
+import { type TerminalSubagentActivity } from "../subagentMonitor.js";
+export type SubagentTone = 'success' | 'warning' | 'error' | 'muted' | 'accent';
+/** One roster row: status mark, profile, session name, checklist progress, in that order. */
+export interface SubagentRowView {
+    id: string;
+    mark: string;
+    tone: SubagentTone;
+    /** The profile name, or `subagent` for a copy of the parent. */
+    profile: string;
+    /** The profile's colour name (PROP-0029); null for a copy of the parent. */
+    color: string | null;
+    title: string;
+    /** `n of m tasks`, or null when the child wrote no checklist. */
+    tasks: string | null;
+}
+export interface SubagentRosterView {
+    rows: SubagentRowView[];
+    /** `+N more · /subagents` when rows were left out. */
+    overflow: string | null;
+}
+export declare function subagentTasks(checklist: TerminalSubagentActivity['checklist']): string | null;
+/**
+ * The compact live roster shown under the status line: active children first, at most three
+ * rows. The session name is cut first when the terminal is narrow.
+ */
+export declare function subagentRoster(items: readonly TerminalSubagentActivity[], width: number, frame?: string): SubagentRosterView | null;
+/** A row as plain text, the way it reads on screen. */
+export declare function subagentRowText(row: SubagentRowView): string;

package/dist/sdk/terminal/opentui/subagentsWidget.js

@@ -0,0 +1,52 @@
+import { stripTerminalSequences, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { ACTIVE_SUBAGENT_STATUSES } from "../subagentMonitor.js";
+import { getWorkingSpinnerFrames } from "../tui/workingStatus.js";
+const MAX_VISIBLE_ROWS = 3;
+const GAP = '  ';
+/** Cuts plain text to a width; the cut adds no styling codes. */
+function cut(text, width) {
+    return stripTerminalSequences(truncateToWidth(text, width, '…'));
+}
+function safe(text) {
+    return stripTerminalSequences(text).replace(/[\x00-\x1f\x7f]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function mark(status, frame) {
+    switch (status) {
+        case 'completed': return { mark: '✓', tone: 'success' };
+        case 'failed': return { mark: '✕', tone: 'error' };
+        case 'interrupted': return { mark: '!', tone: 'muted' };
+        case 'queued': return { mark: '○', tone: 'muted' };
+        case 'waiting_for_approval':
+        case 'waiting_for_input': return { mark: '●', tone: 'accent' };
+        case 'running': return { mark: frame, tone: 'warning' };
+    }
+}
+export function subagentTasks(checklist) {
+    return checklist && checklist.total > 0 ? `${checklist.done} of ${checklist.total} tasks` : null;
+}
+/**
+ * The compact live roster shown under the status line: active children first, at most three
+ * rows. The session name is cut first when the terminal is narrow.
+ */
+export function subagentRoster(items, width, frame = getWorkingSpinnerFrames()[0] ?? '') {
+    if (!items.length || width < 1)
+        return null;
+    const ordered = [...items].sort((left, right) => {
+        const active = Number(ACTIVE_SUBAGENT_STATUSES.has(right.status)) - Number(ACTIVE_SUBAGENT_STATUSES.has(left.status));
+        return active || left.startedAt.localeCompare(right.startedAt) || left.id.localeCompare(right.id);
+    });
+    const rows = ordered.slice(0, MAX_VISIBLE_ROWS).map((item) => {
+        const status = mark(item.status, frame);
+        const profile = cut(safe(item.profile?.name ?? '') || 'subagent', Math.max(1, Math.min(24, width - 2)));
+        const tasks = subagentTasks(item.checklist);
+        const used = 2 + visibleWidth(profile) + GAP.length + (tasks ? GAP.length + tasks.length : 0);
+        const title = cut(safe(item.title) || 'Subagent', Math.max(1, width - used));
+        return { id: item.id, mark: status.mark, tone: status.tone, profile, color: item.profile?.color ?? null, title, tasks };
+    });
+    const overflow = ordered.length - rows.length;
+    return { rows, overflow: overflow > 0 ? cut(`+${overflow} more · /subagents`, width) : null };
+}
+/** A row as plain text, the way it reads on screen. */
+export function subagentRowText(row) {
+    return [`${row.mark} ${row.profile}`, row.title, row.tasks].filter(Boolean).join(GAP);
+}

package/dist/sdk/terminal/piExtension.js

@@ -1,11 +1,10 @@
 import { Type } from 'typebox';
+import { QUESTION_SKETCH_MAX_LENGTH, QUESTION_SKETCH_PATTERN, questionSketchError } from "../sessions/contracts.js";
 import { connectionFromEnv, socketCall, terminalCall } from "./client.js";
-import { runAccountsMenu } from "./accountsMenu.js";
-import { runPluginsMenu } from "./pluginMenu.js";
-import { runHubMenu } from "./hubMenu.js";
-import { claimTerminalControl, controlCall } from "./control.js";
+import { controlCall } from "./control.js";
 import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory } from "../sessions/subagents.js";
 import { askUserTool } from "../tools/askUser.js";
+import { checklistTool } from "../tools/checklist.js";
 import { sessionNameTool } from "../tools/sessionName.js";
 import { PLAN_INSTRUCTIONS, planRefusal } from "../sessions/planMode.js";
 import { pruneToolImages } from "../world/images.js";
@@ -28,8 +27,6 @@ async function withParentCancellation(signal, work) {
         signal?.removeEventListener('abort', stop);
     }
 }
-/** /hub, /plugins and /accounts are pages: the owned terminal fills the screen, and Pi's own dialogs ignore the field. */
-const PAGE = { page: true };
 export default async function (pi, planRun, getSession) {
     await terminalCall('startup', { phase: 'Pi extension loaded' });
     let context = null;
@@ -50,45 +47,6 @@ export default async function (pi, planRun, getSession) {
     try {
         await terminalCall('startup', { phase: stage });
         const connection = connectionFromEnv();
-        // Claimed here, before the model has run anything, and kept in this process's memory: a
-        // command the model runs can read the session token from its environment, never this key.
-        const control = await claimTerminalControl(connection).catch(() => null);
-        pi.registerCommand('hub', {
-            description: 'Browse and install reviewed skills, plugins, and reusable documents',
-            handler: async (_args, ctx) => {
-                if (!control)
-                    return ctx.ui.notify('This session cannot install hub items.', 'warning');
-                await runHubMenu({ select: (title, options) => ctx.ui.select(title, options, PAGE), confirm: (title, message) => ctx.ui.confirm(title, message), notify: (message, level) => ctx.ui.notify(message, level) }, (method, params) => socketCall(connection, method, params ?? {}, 300_000, control));
-            }
-        });
-        pi.registerCommand('plugins', {
-            description: 'See what this session loads, and switch a plugin on or off or trust its code',
-            handler: async (_args, ctx) => {
-                if (!control)
-                    return ctx.ui.notify('This session cannot change plugins.', 'warning');
-                const { projectId } = await socketCall(connection, 'plugins.session', {}, 15_000, control).catch(() => ({ projectId: null }));
-                await runPluginsMenu({ select: (title, options) => ctx.ui.select(title, options, PAGE), confirm: (title, message) => ctx.ui.confirm(title, message), notify: (message, level) => ctx.ui.notify(message, level) }, (method, params) => socketCall(connection, method, params ?? {}, 60_000, control), projectId);
-            }
-        });
-        pi.registerCommand('accounts', {
-            description: 'Add, sign in to, check, switch, or remove the Pi accounts this harness uses',
-            handler: async (_args, ctx) => {
-                if (!control)
-                    return ctx.ui.notify('This session cannot manage accounts.', 'warning');
-                const session = await socketCall(connection, 'accounts.session', {}, 15_000, control).catch(() => null);
-                if (!session)
-                    return ctx.ui.notify('This session has no account to manage.', 'warning');
-                const outcome = await runAccountsMenu({
-                    select: (title, options) => ctx.ui.select(title, options, PAGE),
-                    confirm: (title, message) => ctx.ui.confirm(title, message),
-                    input: (title, placeholder) => ctx.ui.input(title, placeholder),
-                    notify: (message, level) => ctx.ui.notify(message, level)
-                }, (method, params) => socketCall(connection, method, params ?? {}, 120_000, control), session);
-                // The session restarts on the account it chose: Pi ends here, and the launcher starts it again.
-                if (outcome === 'relaunch')
-                    ctx.shutdown();
-            }
-        });
         const { tools } = await socketCall(connection, 'tools.list', {}, 15_000);
         stage = 'Tool registration';
         for (const tool of tools) {
@@ -355,6 +313,19 @@ export default async function (pi, planRun, getSession) {
             return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
         }
     });
+    // The checklist is recorded on the harness run; the shared tool validates and the socket carries the event.
+    let recorded = Promise.resolve();
+    const checklist = checklistTool({ emit: (_type, payload) => { recorded = terminalCall('checklist', payload); } });
+    pi.registerTool({
+        name: checklist.name, label: checklist.label, description: checklist.description,
+        parameters: Type.Unsafe(checklist.parameters(Type)),
+        async execute(_id, input) {
+            recorded = Promise.resolve();
+            const result = await checklist.execute(input);
+            await recorded;
+            return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
+        }
+    });
     const ask = askUserTool({ requestAnswers: questions => terminalCall('questions', { questions }, 1_230_000) });
     pi.registerTool({
         name: ask.name, label: ask.label, description: ask.description,
@@ -367,10 +338,17 @@ export default async function (pi, planRun, getSession) {
     pi.registerTool({
         name: 'ask_user_question',
         label: 'Ask a question',
-        description: 'Ask the user a question and wait for their answer. Every question must include at least one choice and at least one choice must be recommended. Recommendations are visual only and never preselect answers; submitted choices keep their labels. Mark at most one choice recommended for single-choice questions or several when multiSelect is true.',
+        description: 'Ask the user a question and wait for their answer. Include a concise 1–2 word summary label; if omitted, the terminal derives one from the question. Every question must include at least one choice and at least one choice must be recommended. Recommendations are visual only and never preselect answers; submitted choices keep their labels. Mark at most one choice recommended for single-choice questions or several when multiSelect is true. When a UI diagram helps compare choices, set uiSketch: true and include a detailed, bounded ASCII wireframe for every choice. Use ASCII tables and panel borders to show the affected element alongside relevant neighboring UI, with readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes, not a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels.',
         parameters: Type.Object({
+            summary: Type.Optional(Type.String({ description: 'A concise label of one or two words' })),
             question: Type.String(),
-            options: Type.Array(Type.Object({ label: Type.String(), description: Type.Optional(Type.String()), recommended: Type.Optional(Type.Boolean()) }), {
+            uiSketch: Type.Optional(Type.Literal(true, { description: 'Enable an ASCII sketch preview; when true, every choice must include a sketch.' })),
+            options: Type.Array(Type.Object({
+                label: Type.String(),
+                description: Type.Optional(Type.String()),
+                recommended: Type.Optional(Type.Boolean()),
+                sketch: Type.Optional(Type.String({ minLength: 1, maxLength: QUESTION_SKETCH_MAX_LENGTH, pattern: QUESTION_SKETCH_PATTERN, description: 'Literal ASCII UI wireframe: 1–24 LF-separated lines, at most 80 printable ASCII characters per line. Include the affected element and neighboring UI using structured table/panel borders with fixed, matching outer-edge columns on every row. Required for every choice when uiSketch is true.' }))
+            }), {
                 minItems: 1,
                 contains: Type.Object({ recommended: Type.Literal(true) })
             }),
@@ -384,7 +362,14 @@ export default async function (pi, planRun, getSession) {
                 throw new Error('Every question needs at least one recommended choice.');
             if (!input.multiSelect && recommendedCount > 1)
                 throw new Error('A single-choice question may recommend at most one option.');
-            const answer = await terminalCall('question', { requestId: id, ...input });
+            const sketchError = questionSketchError(input.uiSketch, input.options);
+            if (sketchError)
+                throw new Error(sketchError);
+            const summary = typeof input.summary === 'string' ? input.summary.trim() : '';
+            if (summary && (summary.length > 100 || summary.split(/\s+/u).filter(Boolean).length > 2)) {
+                throw new Error('The question summary must be a concise 1–2 word label of no more than 100 characters.');
+            }
+            const answer = await terminalCall('question', { requestId: id, ...input, ...(summary ? { summary } : {}) });
             return { content: [{ type: 'text', text: JSON.stringify(answer) }], details: undefined };
         }
     });

package/dist/sdk/terminal/socket.d.ts

@@ -28,9 +28,12 @@ export interface SocketHandlers {
     accounts?(grant: SocketGrant, call: string, params: Record<string, unknown>, control: boolean): Promise<unknown>;
 }
 /**
- * Windows has no socket files for Node's `net`: it listens on a named pipe, which lives in a
- * machine-wide namespace. A random name keeps another local process from guessing it and standing
- * in front of the session; the token still decides what a caller may do.
+ * Each Harness process listens on its own path. Windows has no socket files for Node's `net`: it
+ * listens on a named pipe in a machine-wide namespace, and a random name keeps another local process
+ * from guessing it. On Unix the file is named for this process, because several Harness processes
+ * may share one state folder: closing a server removes its socket file, so a shared name would let
+ * one process delete, and the next one take over, the path another's sessions still call. The token
+ * still decides what a caller may do.
  */
 export declare function socketPath(stateDir: string): string;
 export declare class SessionSocket {