@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/terminal/terminals.js

@@ -13,6 +13,8 @@ import { readAudit } from "../accounts/store.js";
 import { log } from "../core/bus.js";
 import { HarnessError, invalid } from "../core/errors.js";
 import { newId, now } from "../core/fs.js";
+import { formatBashCommandForApproval } from "../core/workspaceBashTool.js";
+import { resolveWorkspaceRoot } from "../core/workspace.js";
 import { prependSearchPath, searchPath } from "../core/path.js";
 import { dispatch } from "../tools/dispatch.js";
 import { materialise } from "../variant/materialise.js";
@@ -21,8 +23,19 @@ import * as variantStore from "../variant/store.js";
 import { compile, copyToRun, record, render, saveForSession } from "../prompt/compile.js";
 import { isActiveStatus } from "../sessions/contracts.js";
 import { findRun, loadRun, saveRun, updateRun } from "../sessions/runStore.js";
+import { combineWorkspaceScope, inspectRunWorkspaceWrite } from "../sessions/workspaceBoundary.js";
+import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
+import { harnessTools } from "../tools/harnessTools.js";
+import { HARNESS_PLUGINS } from "../plugins/builtin.js";
+import * as attachments from "../plugins/attachments.js";
+import { FIRST_PARTY_PLUGINS } from "../plugins/firstParty.js";
+import { createProfile, listProfiles, profileDirs, profileSection, removeProfile, resolveProfile } from "../agents/profiles.js";
 import { SESSION_NAME } from "../tools/sessionName.js";
 import { contributionId } from "../plugins/identity.js";
+import { setupScript } from "../worktrees/setup.js";
+import { inspectStep } from "../annotations/inspect.js";
+import * as pageNotes from "../annotations/store.js";
 import { APPS_COMMAND, WIKI_COMMAND } from "./cli.js";
 import { SOCKET_ENV, TOKEN_ENV } from "./client.js";
 import { TerminalController } from "./controller.js";
@@ -30,6 +43,7 @@ import { terminalCommandFiles } from "./launch.js";
 import { SessionSocket, socketPath } from "./socket.js";
 import { harnessLogInfo, readHarnessLogChunk } from "./logs.js";
 import { listTerminalTrajectoryRuns, readTerminalTrajectory } from "./trajectory.js";
+import { BrowserControl } from "./browserControl.js";
 /** Identity of the exact resource decision that this terminal was prepared with. */
 function resourceIdentity(loading) {
     if (!loading)
@@ -63,8 +77,27 @@ export class Terminals {
     worldReadOnly = new Set();
     socket;
     assets;
-    /** A session's `/accounts` switch, taken once its Pi process has ended. */
+    /** A session's `/accounts` or `/worktree` switch, taken once its Pi process has ended. */
     relaunches = new Map();
+    /** The managed worktree each live session holds. */
+    worktreeLeases = new Map();
+    /** Each child's profile name and colour, looked up once per child run. */
+    childProfiles = new Map();
+    subagentProfile(record) {
+        if (!record.profile)
+            return null;
+        if (!this.childProfiles.has(record.id)) {
+            if (this.childProfiles.size > 500)
+                this.childProfiles.clear();
+            let color = 'blue';
+            try {
+                color = resolveProfile(this.options.env.root, record.workingDirectory, record.profile)?.color ?? color;
+            }
+            catch { }
+            this.childProfiles.set(record.id, { name: record.profile, color });
+        }
+        return this.childProfiles.get(record.id) ?? null;
+    }
     constructor(options) {
         this.options = options;
         this.assets = options.assets ?? defaultAssets();
@@ -83,6 +116,12 @@ export class Terminals {
                 const owner = this.sessions.get(parent.sessionId);
                 if (owner?.controller.activeRun?.runId === parent.id) {
                     owner.controller.observe(event, true);
+                    const settings = options.subagents?.runtimeSettings(record.id);
+                    owner.controller.observeSubagent(parent.id, record, event, this.subagentProfile(record), {
+                        accountLabel: owner.account.label,
+                        model: settings?.model ?? null,
+                        effort: settings?.effort ?? null
+                    });
                     break;
                 }
                 parentId = parent.parentRunId;
@@ -127,23 +166,48 @@ export class Terminals {
         }
         return bin;
     }
-    /** The broker's tools, then the world tools whose plugins are on for this session. */
+    /**
+     * The harness's own History, Wiki and skill tools, then the broker's, then the world tools whose
+     * plugins are on for this session: the same tools a structured session has (INV-PAR-1).
+     */
     async tools(session, listing) {
         const brokered = this.options.apps.brokerTools(session);
         const live = this.sessions.get(session.sessionId);
-        const { world } = this.options;
-        if (!world || !live)
+        if (!live)
             return brokered;
+        const own = await this.ownTools(live, listing);
+        const { world } = this.options;
+        if (!world)
+            return [...own, ...brokered];
         const context = { run: live.controller.activeRun, caller: live.caller, attended: true, subagent: false, sessionKey: session.sessionId, cwd: live.input.cwd };
         if (!listing)
-            return [...brokered, ...world.tools(context, (_plugin, tool) => this.worldNames.get(session.sessionId)?.has(tool) ?? false)];
+            return [...own, ...brokered, ...world.tools(context, (_plugin, tool) => this.worldNames.get(session.sessionId)?.has(tool) ?? false)];
         const on = await this.worldOn(live);
         const tools = world.tools(context, (plugin, tool) => on(plugin, tool));
         this.worldNames.set(session.sessionId, new Set(tools.map((tool) => tool.name)));
         for (const tool of tools)
             if (tool.readOnly)
                 this.worldReadOnly.add(tool.name);
-        return [...brokered, ...tools];
+        return [...own, ...brokered, ...tools];
+    }
+    ownNames = new Map();
+    async ownTools(live, listing) {
+        const sessionId = live.caller.sessionId;
+        const all = harnessTools(this.options.env, live.caller, { variantDir: this.variantDirs.get(sessionId) ?? null })
+            .filter((tool) => DEFAULT_TOOL_NAMES.includes(tool.name));
+        if (!listing)
+            return all.filter((tool) => this.ownNames.get(sessionId)?.has(tool.name) ?? false);
+        const on = await this.worldOn(live);
+        const owner = (tool) => HARNESS_PLUGINS.find((plugin) => plugin.tools?.some((entry) => entry.name === tool))?.id ?? null;
+        const tools = all.filter((tool) => {
+            const plugin = owner(tool.name);
+            return !plugin || on(plugin, tool.name);
+        });
+        this.ownNames.set(sessionId, new Set(tools.map((tool) => tool.name)));
+        for (const tool of tools)
+            if (tool.readOnly)
+                this.worldReadOnly.add(tool.name);
+        return tools;
     }
     /** The world tools a new session will have, named in its instructions. */
     async worldToolNames(input, account) {
@@ -155,6 +219,16 @@ export class Terminals {
         const on = plugins ? new Set(plugins.flatMap((plugin) => plugin.contributions.filter((item) => item.state === 'on').map((item) => item.id))) : null;
         return world.plugins.flatMap((plugin) => (plugin.tools ?? []).map((tool) => tool.name).filter((name) => !on || on.has(contributionId(plugin.id, 'tool', name))));
     }
+    /** The harness's own History, Wiki and skill tools a new session will have. */
+    async ownToolNames(input, account) {
+        const list = this.options.pluginControl?.list;
+        const plugins = list ? await list({ cwd: input.cwd, accountId: account.id, projectId: input.projectId ?? null }) : null;
+        const on = plugins ? new Set(plugins.flatMap((plugin) => plugin.contributions.filter((item) => item.state === 'on').map((item) => item.id))) : null;
+        return DEFAULT_TOOL_NAMES.filter((name) => {
+            const plugin = HARNESS_PLUGINS.find((entry) => entry.tools?.some((tool) => tool.name === name));
+            return !on || !plugin || on.has(contributionId(plugin.id, 'tool', name));
+        });
+    }
     /** Whether a world tool's plugin is switched on for a session's folder, account and project. */
     async worldOn(live) {
         const list = this.options.pluginControl?.list;
@@ -177,6 +251,17 @@ export class Terminals {
                 const { Type } = await import('typebox');
                 return { tools: (await this.tools(session, true)).map((tool) => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) };
             }
+            case 'firstParty.list': {
+                // The harness's own extensions switched on for this session, with their settings.
+                const live = this.sessions.get(session.sessionId);
+                const list = this.options.pluginControl?.list;
+                if (!live || !list)
+                    return { plugins: [] };
+                const plugins = await list({ cwd: live.input.cwd, accountId: live.account.id, projectId: live.input.projectId ?? null });
+                const on = new Set(plugins.flatMap((plugin) => plugin.contributions.filter((item) => item.state === 'on').map((item) => item.id)));
+                const settings = attachments.load(this.options.env.root).settings;
+                return { plugins: FIRST_PARTY_PLUGINS.filter((plugin) => plugin.code?.some((code) => on.has(`${plugin.id}/code/${code.name}`))).map((plugin) => ({ id: plugin.id, settings: settings[plugin.id] ?? {} })) };
+            }
             case 'tools.call': {
                 const tool = (await this.tools(session, false)).find((candidate) => candidate.name === params.name);
                 if (!tool)
@@ -235,6 +320,14 @@ export class Terminals {
                 const settings = params.settings && typeof params.settings === 'object' && !Array.isArray(params.settings) ? params.settings : {};
                 return api.configure({ ...scope, pluginId: text('pluginId'), settings });
             }
+            case 'plugins.install':
+                if (!api.install)
+                    throw invalid('Package installation is unavailable in this host.');
+                return api.install({ ...scope, source: text('source') });
+            case 'plugins.remove':
+                if (!api.remove)
+                    throw invalid('Package removal is unavailable in this host.');
+                return api.remove({ ...scope, pluginId: text('pluginId') });
             default:
                 throw new HarnessError('unknown_method', `Unknown call ${call}.`);
         }
@@ -324,6 +417,232 @@ export class Terminals {
                 throw new HarnessError('unknown_method', `Unknown call ${call}.`);
         }
     }
+    /** `/agents`: the agent profiles this session's folder can use (PROP-0029). */
+    agentsCall(live, call, params) {
+        const root = this.options.env.root;
+        const cwd = live.input.cwd;
+        const name = () => {
+            if (typeof params.name !== 'string' || !params.name.trim())
+                throw invalid('A profile name is required.');
+            return params.name.trim();
+        };
+        const scope = () => {
+            if (params.scope !== 'global' && params.scope !== 'project')
+                throw invalid('scope must be global or project.');
+            return params.scope;
+        };
+        switch (call.slice('terminal.agents.'.length)) {
+            case 'list': return { ...listProfiles(root, cwd, this.variantDirs.get(live.input.sessionId) ?? null), dirs: profileDirs(root, cwd) };
+            case 'create': return createProfile(root, cwd, { name: name(), scope: scope(), from: typeof params.from === 'string' && params.from ? params.from : null });
+            case 'remove':
+                removeProfile(root, cwd, { name: name(), scope: scope() });
+                return {};
+            default: throw invalid('Unknown profile operation.');
+        }
+    }
+    /** `/worktree`: the managed worktrees of the repository this session works in. */
+    async worktreesCall(live, call, params) {
+        const worktrees = this.options.worktrees;
+        if (!worktrees)
+            throw invalid('Worktrees are unavailable in this host.');
+        const sessionId = live.input.sessionId;
+        const cwd = live.input.cwd;
+        const current = this.worktreeLeases.get(sessionId) ?? null;
+        const id = () => {
+            if (typeof params.id !== 'string' || !params.id)
+                throw invalid('A worktree id is required.');
+            return params.id;
+        };
+        const action = call.slice('terminal.worktrees.'.length);
+        switch (action) {
+            case 'list': {
+                let repo;
+                try {
+                    repo = await worktrees.repositoryOf(cwd);
+                }
+                catch (error) {
+                    return { repo: null, current, worktrees: [], removed: [], reason: error instanceof Error ? error.message : String(error) };
+                }
+                const statuses = await Promise.all((await worktrees.list(repo)).map((record) => worktrees.status(record.id)));
+                return { repo, current, worktrees: statuses, removed: worktrees.removed(repo), reason: null };
+            }
+            case 'status': return worktrees.status(id());
+            case 'create': return worktrees.create({
+                repo: cwd,
+                ...(typeof params.name === 'string' && params.name ? { name: params.name } : {}),
+                ...(typeof params.branch === 'string' && params.branch ? { branch: params.branch } : {}),
+                kind: params.kind === 'permanent' ? 'permanent' : 'managed'
+            });
+            case 'branch':
+                if (typeof params.name !== 'string' || !params.name)
+                    throw invalid('A branch name is required.');
+                return worktrees.branch(id(), params.name);
+            case 'handoff': {
+                const direction = params.direction === 'toSource' || params.direction === 'toWorktree' ? params.direction : null;
+                if (!direction)
+                    throw invalid('direction is toSource or toWorktree.');
+                return worktrees.handoff(id(), direction, { move: params.move !== false });
+            }
+            case 'remove':
+                if (id() === current)
+                    throw new HarnessError('worktree_in_use', 'This session works in that worktree. Switch to another folder first.');
+                return worktrees.remove(id(), { force: params.force === true });
+            case 'restore': return worktrees.restore(id());
+            case 'prune': return worktrees.prune({ repo: cwd, ...(typeof params.keep === 'number' ? { keep: params.keep } : {}) });
+            case 'trustSetup': {
+                const repo = await worktrees.repositoryOf(cwd);
+                const script = setupScript(repo);
+                if (!script)
+                    throw invalid('This repository has no .xharness/worktree-setup.');
+                await worktrees.trustSetup(repo, script.hash);
+                return { hash: script.hash };
+            }
+            case 'switch': {
+                // A new conversation in the chosen folder: Pi keeps one history per working folder.
+                const target = params.main === true ? null : id();
+                const folder = target ? worktrees.pathOf(target) : await worktrees.repositoryOf(cwd);
+                if (!folder)
+                    throw new HarnessError('worktree_missing', 'That worktree has no folder.');
+                this.relaunches.set(sessionId, { accountId: live.account.id, nativeSessionId: null, cwd: folder, worktreeId: target });
+                return { cwd: folder, worktreeId: target };
+            }
+            default:
+                throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        }
+    }
+    /** `/usage:analysis` and `/usage:limit`: usage for this session's own account, project or session. */
+    async usageCall(live, call, params) {
+        const usage = this.options.usage;
+        const limits = this.options.usageLimits;
+        if (!usage || !limits)
+            throw invalid('Usage is unavailable in this host.');
+        if (call === 'terminal.usage.summary') {
+            const scope = params.scope === 'session' || params.scope === 'project' || params.scope === 'all' ? params.scope : 'account';
+            if (scope === 'project' && !live.input.projectId)
+                throw invalid('This session has no project to report usage for.');
+            const period = params.period === 'today' || params.period === '30d' || params.period === 'all' ? params.period : '7d';
+            return usage.summary({
+                scope,
+                sessionId: live.input.sessionId,
+                accountId: live.account.id,
+                projectId: live.input.projectId ?? null,
+                period,
+                timezoneOffsetMinutes: typeof params.timezoneOffsetMinutes === 'number' ? params.timezoneOffsetMinutes : 0
+            });
+        }
+        if (call === 'terminal.usage.limits') {
+            return params.refresh === true ? limits.refresh(live.account.id, { force: true }) : limits.read(live.account.id);
+        }
+        if (call === 'terminal.usage.headers') {
+            if (typeof params.provider !== 'string' || !params.provider)
+                throw invalid('A provider is required.');
+            if (typeof params.status !== 'number' || !Number.isFinite(params.status))
+                throw invalid('A response status is required.');
+            const headers = params.headers && typeof params.headers === 'object' && !Array.isArray(params.headers)
+                ? Object.fromEntries(Object.entries(params.headers).filter((entry) => typeof entry[1] === 'string'))
+                : {};
+            if (!Object.keys(headers).length)
+                return {};
+            limits.recordHeaders(live.account.id, params.provider, { status: params.status, headers });
+            return {};
+        }
+        throw invalid('Unknown usage operation.');
+    }
+    /** `/annotate:notes` and `/annotate:`: Web annotations and their visible capture browser. */
+    async annotationsCall(live, call, params) {
+        const root = this.options.env.root;
+        const sessionId = live.input.sessionId;
+        const capture = this.options.noteCapture;
+        const id = () => {
+            if (typeof params.id !== 'string' || !params.id)
+                throw invalid('A note id is required.');
+            return params.id;
+        };
+        const version = () => {
+            if (typeof params.expectedVersion !== 'number')
+                throw invalid('The note version you last read is required.');
+            return params.expectedVersion;
+        };
+        const needCapture = () => {
+            if (!capture)
+                throw invalid('This host has no capture browser.');
+            return capture;
+        };
+        const needNotes = () => {
+            if (!this.options.pageNotes)
+                throw invalid('This host cannot send page notes.');
+            return this.options.pageNotes;
+        };
+        const action = call.slice('terminal.annotations.'.length);
+        switch (action) {
+            case 'list': {
+                const result = pageNotes.list(root, {
+                    query: typeof params.query === 'string' ? params.query : null,
+                    url: typeof params.url === 'string' ? params.url : null,
+                    status: params.status === 'open' || params.status === 'resolved' ? params.status : null,
+                    limit: 200
+                });
+                return { ...result, sessionId };
+            }
+            case 'read': return pageNotes.read(root, id());
+            case 'create': {
+                const note = pageNotes.create(root, { source: params.source, target: params.target, body: params.body, tags: params.tags });
+                return params.share === true ? pageNotes.share(root, note.id, { sessionId }) : note;
+            }
+            case 'update': return pageNotes.update(root, id(), version(), (params.patch ?? {}));
+            case 'delete':
+                pageNotes.remove(root, id(), version());
+                return {};
+            // A terminal shares with, and withdraws from, its own session only.
+            case 'share': return pageNotes.share(root, id(), { sessionId });
+            case 'unshare': return pageNotes.unshare(root, id(), { sessionId });
+            case 'open': return needCapture().open(sessionId, typeof params.url === 'string' && params.url ? params.url : null);
+            case 'identity': return needCapture().identity(sessionId);
+            case 'begin':
+                if (params.kind !== 'text' && params.kind !== 'element')
+                    throw invalid('kind is text or element.');
+                return needCapture().begin(sessionId, params.kind);
+            case 'capture':
+                if (typeof params.captureId !== 'string')
+                    throw invalid('A capture id is required.');
+                return needCapture().capture(sessionId, params.captureId);
+            case 'cancel':
+                await needCapture().cancel(sessionId, typeof params.captureId === 'string' ? params.captureId : undefined);
+                return {};
+            case 'reveal': {
+                const note = pageNotes.read(root, id());
+                return needCapture().reveal(sessionId, note.source.url, note.target);
+            }
+            // ---- The inspector and the queue (PROP-0018); a terminal queues and sends to its own session.
+            case 'target': return { ...needCapture().describe(sessionId), windows: await needCapture().windows(sessionId).catch(() => []) };
+            case 'attach': {
+                const kind = params.kind;
+                if (kind !== 'web' && kind !== 'cdp' && kind !== 'bridge')
+                    throw invalid('kind is web, cdp or bridge.');
+                const spec = kind === 'cdp'
+                    ? { kind, endpoint: typeof params.endpoint === 'string' ? params.endpoint : '', name: typeof params.name === 'string' ? params.name : null }
+                    : kind === 'bridge' ? { kind, name: typeof params.name === 'string' ? params.name : null } : { kind };
+                return needCapture().attach(sessionId, spec);
+            }
+            case 'windows': return needCapture().windows(sessionId);
+            case 'selectWindow':
+                if (typeof params.window !== 'string')
+                    throw invalid('A window id is required.');
+                await needCapture().selectWindow(sessionId, params.window);
+                return {};
+            case 'inspect': return needCapture().inspect(sessionId);
+            case 'stopInspect':
+                await needCapture().stopInspect(sessionId);
+                return {};
+            case 'next': return inspectStep(needCapture(), needNotes(), sessionId, sessionId, 'terminal');
+            case 'queue': return needNotes().queue(id(), version(), sessionId);
+            case 'dequeue': return needNotes().dequeue(id(), version());
+            case 'confirm': return needNotes().confirm(id(), version());
+            case 'send': return needNotes().send(sessionId, { ids: Array.isArray(params.ids) ? params.ids.filter((entry) => typeof entry === 'string') : null });
+            default:
+                throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        }
+    }
     /** The account a session asked to switch to. Taken once, after its Pi process has ended and before `dispose`. */
     takeRelaunch(sessionId) {
         const request = this.relaunches.get(sessionId) ?? null;
@@ -356,6 +675,7 @@ export class Terminals {
             sessionId: input.sessionId,
             nativeSessionId: live.controller.nativeSessionId,
             workingDirectory: input.cwd,
+            workspaceRoot: resolveWorkspaceRoot(input.cwd),
             worktreeId: input.run?.worktreeId ?? null,
             goal: text,
             attachmentCount: 0,
@@ -364,7 +684,9 @@ export class Terminals {
             status: 'queued',
             exitCode: null,
             handoffId: null,
-            accountId: live.account.id
+            accountId: live.account.id,
+            variantScope: live.variant?.scope ?? null,
+            variantVersion: live.variant?.fingerprint ?? null
         };
     }
     /** The run a native turn reports into: the one reserved by `send`, or a new one for what the person typed. */
@@ -390,55 +712,151 @@ export class Terminals {
         const record = loadRun(this.options.env.root, run.runId);
         if (!isActiveStatus(record.status))
             throw invalid(`The run is no longer active (its status is ${record.status}).`);
-        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args };
+        const name = tool.toLowerCase();
+        const workspaceRoot = record.workspaceRoot ?? resolveWorkspaceRoot(record.workingDirectory ?? live.input.cwd);
+        if (live.input.readOnly && ['bash', 'edit', 'write'].includes(name))
+            return { allowed: false, reason: 'This session is read-only.', workspaceRoot };
+        let inspection;
+        try {
+            inspection = inspectRunWorkspaceWrite(record, tool, args);
+        }
+        catch (error) {
+            return { allowed: false, reason: error instanceof Error ? error.message : 'The active project workspace could not be verified.', workspaceRoot };
+        }
+        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args: inspection.input };
         const { policy } = this.options;
         if (policy.scope) {
-            const scope = await policy.scope(call);
+            const scope = combineWorkspaceScope(await policy.scope(call), inspection);
             if (!scope.allowed && (scope.automatic || !scope.requiresApproval))
-                return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.' };
+                return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.', workspaceRoot };
             try {
                 await policy.authorize?.(call);
             }
             catch (error) {
-                return { allowed: false, reason: error instanceof Error ? error.message : 'Tool unavailable in the settings.' };
+                return { allowed: false, reason: error instanceof Error ? error.message : 'Tool unavailable in the settings.', workspaceRoot };
             }
             const requiresApproval = !!scope.requiresApproval || (scope.allowed && !!scope.humanOnly);
             return {
                 allowed: scope.allowed,
                 requiresApproval,
                 reason: scope.reason ?? null,
+                workspaceRoot,
                 rememberable: scope.allowed && !scope.humanOnly,
                 ...(scope.humanOnly ? { standing: scope.allowGlobalApproval ? 'switch' : 'none' } : {})
             };
         }
-        // With no application policy: reads run, a read-only session refuses the rest, and anything else asks.
-        const name = tool.toLowerCase();
-        if (name === SESSION_NAME || name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.worldReadOnly.has(name) || this.options.apps.toolNames.includes(name))
-            return { allowed: true };
-        if (live.input.readOnly)
-            return { allowed: false, reason: 'This session is read-only.' };
-        return { allowed: false, requiresApproval: true, rememberable: true, reason: 'This native action requires approval.' };
+        if (inspection.outside)
+            return { allowed: false, requiresApproval: true, rememberable: false, standing: 'switch', reason: inspection.reason, workspaceRoot };
+        if (name === SESSION_NAME || name === CHECKLIST_WRITE || name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.worldReadOnly.has(name) || this.options.apps.toolNames.includes(name) || ['bash', 'edit', 'write'].includes(name)) {
+            return { allowed: true, workspaceRoot };
+        }
+        return { allowed: false, requiresApproval: true, rememberable: true, reason: 'This native action requires approval.', workspaceRoot };
+    }
+    async workspaceEscape(live, run, tool, args, reason) {
+        if (tool !== 'bash' || live.input.readOnly)
+            return false;
+        const record = loadRun(this.options.env.root, run.runId);
+        if (!isActiveStatus(record.status) || (record.trigger != null && record.trigger !== 'user'))
+            return false;
+        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args };
+        const scope = (await this.options.policy.scope?.(call)) ?? { allowed: true };
+        if (scope.automatic || (!scope.allowed && !scope.requiresApproval))
+            return false;
+        try {
+            await this.options.policy.authorize?.(call);
+        }
+        catch {
+            return false;
+        }
+        const operationArgs = (args && typeof args === 'object' && !Array.isArray(args) ? args : {});
+        const command = typeof operationArgs.command === 'string' ? operationArgs.command : '';
+        if (operationArgs.workspaceWriteScope !== 'outside' || !command)
+            return false;
+        const workspaceRoot = record.workspaceRoot ?? resolveWorkspaceRoot(record.workingDirectory ?? live.input.cwd);
+        const decision = await run.requestApproval({
+            target: 'workspace-write',
+            action: `${reason} Workspace: ${workspaceRoot}. This exact command will run once with broader filesystem access.\n\nCommand:\n${formatBashCommandForApproval(command)}`,
+            operation: { tool, args: operationArgs },
+            rememberable: false,
+            standing: 'none'
+        });
+        if (decision !== 'approved')
+            return false;
+        const currentRecord = loadRun(this.options.env.root, run.runId);
+        if (!isActiveStatus(currentRecord.status) || (currentRecord.trigger != null && currentRecord.trigger !== 'user'))
+            return false;
+        const currentCall = { run: currentRecord, caller: { ...live.caller, runId: run.runId }, tool, args: operationArgs };
+        const currentScope = (await this.options.policy.scope?.(currentCall)) ?? { allowed: true };
+        if (currentScope.automatic || (!currentScope.allowed && !currentScope.requiresApproval))
+            return false;
+        try {
+            await this.options.policy.authorize?.(currentCall);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async workspaceBoundaryBypass(live, run, tool, args) {
+        if (tool !== 'bash' || live.input.readOnly || !this.options.approvals.isAuto('pi'))
+            return false;
+        const record = loadRun(this.options.env.root, run.runId);
+        if (!isActiveStatus(record.status) || (record.trigger != null && record.trigger !== 'user'))
+            return false;
+        const operationArgs = (args && typeof args === 'object' && !Array.isArray(args) ? args : {});
+        if (typeof operationArgs.command !== 'string' || !operationArgs.command)
+            return false;
+        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args: operationArgs };
+        try {
+            const scope = (await this.options.policy.scope?.(call)) ?? { allowed: true };
+            if (scope.automatic || (!scope.allowed && !scope.requiresApproval) || (scope.humanOnly && !scope.allowGlobalApproval))
+                return false;
+            await this.options.policy.authorize?.(call);
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
     async subagentsCall(live, call, params) {
+        if (call === 'terminal.subagents.monitor')
+            return { children: live.controller.subagentSnapshot() };
         const service = this.options.subagents;
-        if (!service || live.input.subagents === null) {
+        if ((!service || live.input.subagents === null) && call !== 'terminal.subagents.register') {
             if (call === 'terminal.subagents.tools')
                 return { tools: [] };
             throw invalid('Subagents are disabled for this terminal.');
         }
-        if (call === 'terminal.subagents.tools')
-            return { tools: subagentTools(service, '').map(tool => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) };
+        if (call === 'terminal.subagents.tools') {
+            const variantDir = this.variantDirs.get(live.input.sessionId) ?? null;
+            return {
+                tools: subagentTools(service, '').map(tool => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })),
+                profiles: {
+                    normal: profileSection(this.options.env.root, live.input.cwd, variantDir).body,
+                    plan: profileSection(this.options.env.root, live.input.cwd, variantDir, true).body
+                }
+            };
+        }
         const run = live.controller.activeRun;
         if (!run)
             throw new HarnessError('run_not_active', 'This terminal has no active parent run.');
+        if (call === 'terminal.subagents.planSafe') {
+            const reason = service.planSpawnRefusal(run.runId, params.input);
+            return { allowed: reason === null, ...(reason ? { reason } : {}) };
+        }
         if (call === 'terminal.subagents.register') {
             if (!Array.isArray(params.tools) || params.tools.some((name) => typeof name !== 'string'))
                 throw invalid('Native tool names are required.');
+            if (params.plan !== undefined && typeof params.plan !== 'boolean')
+                throw invalid('plan must be a boolean.');
             const readOnly = live.input.readOnly === true;
-            const readTools = new Set([...READ_ONLY_TOOLS, SESSION_NAME, SPAWN_SUBAGENT, WAIT_SUBAGENTS, 'ask_user', 'mcp_list_tools', 'mcp_call_tool', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load']);
-            const tools = params.tools.filter((name) => !readOnly || readTools.has(name));
-            const capabilities = this.options.resolveCapabilities ? await this.options.resolveCapabilities(live.caller, tools, live.input.cwd) : { version: 1, tools, connectors: [], contributions: [] };
-            freezeRun(this.options.env.root, run.runId, live.caller, capabilities);
+            const readTools = new Set([...READ_ONLY_TOOLS, SESSION_NAME, CHECKLIST_WRITE, SPAWN_SUBAGENT, WAIT_SUBAGENTS, 'ask_user', 'mcp_list_tools', 'mcp_call_tool', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load']);
+            const tools = [...new Set(params.tools)].filter(name => (!readOnly || readTools.has(name)) && (params.plan === true || (name !== 'ask_user' && name !== 'ask_user_question')));
+            const caller = { ...live.caller, runId: run.runId };
+            const capabilities = this.options.resolveCapabilities ? await this.options.resolveCapabilities(caller, tools, live.input.cwd) : { version: 1, tools, connectors: [], contributions: [] };
+            freezeRun(this.options.env.root, run.runId, caller, capabilities);
+            if (!service || live.input.subagents === null)
+                return { runId: run.runId, connectors: capabilities.connectors };
             service.register({
                 run: { id: run.runId, sessionId: live.input.sessionId, mode: live.input.run?.mode ?? 'code', projectId: live.input.projectId, worktreeId: live.input.run?.worktreeId },
                 cwd: live.input.cwd, sessionDir: this.historyDir(live.input), text: '', caller: live.caller,
@@ -446,10 +864,12 @@ export class Terminals {
                 effort: typeof params.effort === 'string' ? params.effort : null,
                 launch: live.input.launch, tools: { allow: capabilities.tools, gated: capabilities.tools.filter(name => !readTools.has(name)) },
                 connections: live.input.connections === false ? false : { readOnly }, subagents: live.input.subagents,
+                plan: params.plan === true,
+                variant: live.variant ? { dir: live.variant.dir, scope: live.variant.scope } : null,
                 capabilities
             }, live.account.id, capabilities);
             service.restore(run.runId, params.history ?? { owners: [], receipts: [] });
-            return { runId: run.runId };
+            return { runId: run.runId, connectors: capabilities.connectors };
         }
         if (call === 'terminal.subagents.verify') {
             await service.verify(run.runId, params.history);
@@ -519,6 +939,43 @@ export class Terminals {
         }
         throw new HarnessError('unknown_method', `Unknown call ${call}.`);
     }
+    async sideQuestionCall(live, call, params) {
+        const service = this.options.sideQuestions;
+        if (!service)
+            throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        if (call === 'terminal.sideQuestions.start') {
+            if (typeof params.question !== 'string')
+                throw invalid('A side question is required.');
+            const context = params.context && typeof params.context === 'object' && !Array.isArray(params.context)
+                ? params.context
+                : undefined;
+            const latest = listTerminalTrajectoryRuns(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId)
+                .find(run => findRun(this.options.env.root, run.id)?.trigger !== 'side-question');
+            return service.start({
+                sessionId: live.input.sessionId,
+                parentRunId: live.controller.activeRun?.runId ?? latest?.id ?? null,
+                parentSessionId: live.input.sessionId,
+                accountId: live.account.id,
+                model: typeof params.model === 'string' ? params.model : live.input.model ?? null,
+                effort: typeof params.effort === 'string' ? params.effort : undefined,
+                cwd: live.input.cwd,
+                caller: live.caller,
+                question: params.question,
+                context
+            });
+        }
+        if (typeof params.runId !== 'string')
+            throw invalid('A side-question run id is required.');
+        if (call === 'terminal.sideQuestions.read') {
+            const afterSequence = params.afterSequence === undefined ? -1 : params.afterSequence;
+            if (typeof afterSequence !== 'number')
+                throw invalid('A side-question event sequence is required.');
+            return service.read(params.runId, live.input.sessionId, afterSequence);
+        }
+        if (call === 'terminal.sideQuestions.interrupt')
+            return service.interrupt(params.runId, live.input.sessionId);
+        throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+    }
     /** The only terminal frontend: the Bun-run OpenTUI application. */
     frontendCommand() {
         return {
@@ -538,32 +995,55 @@ export class Terminals {
         if (!input?.sessionId || !input.cwd || !input.sessionFolder)
             throw invalid('A terminal session needs an id, a working folder, and its own folder.');
         await this.dispose(input.sessionId);
-        const command = this.frontendCommand();
-        // A pinned account is used as it is; it is never exchanged for another one.
-        const account = input.accountId ? accounts.find(input.accountId) : accounts.resolve(null, null);
-        const launch = launchEnv(accounts.dir, account);
-        const loading = (await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, account), install: true, caller: { projectId: input.projectId ?? null } })) ?? null;
-        await this.socket.listen();
-        await accounts.terminalBegin(account);
         const sessionId = input.sessionId;
-        const caller = { sessionId, projectId: input.projectId ?? null, actor: 'Code', surface: 'cli' };
+        let acquiredWorktreeId = null;
+        let account = null;
+        let accountStarted = false;
         let token = null;
         try {
+            const worktreeId = input.run?.worktreeId ?? null;
+            const worktreePath = worktreeId ? this.options.worktrees?.pathOf(worktreeId) ?? null : null;
+            if (worktreeId && worktreePath) {
+                await this.options.worktrees.acquire(worktreeId, sessionId);
+                acquiredWorktreeId = worktreeId;
+                this.worktreeLeases.set(sessionId, worktreeId);
+                input.cwd = worktreePath;
+            }
+            const command = this.frontendCommand();
+            // A pinned account is used as it is; it is never exchanged for another one.
+            const preparedAccount = input.accountId ? accounts.find(input.accountId) : accounts.resolve(null, null);
+            account = preparedAccount;
+            const launch = launchEnv(accounts.dir, preparedAccount);
+            const loading = (await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, preparedAccount), install: true, caller: { projectId: input.projectId ?? null } })) ?? null;
+            await this.socket.listen();
+            await accounts.terminalBegin(preparedAccount);
+            accountStarted = true;
+            const caller = { sessionId, projectId: input.projectId ?? null, actor: 'Code', surface: 'cli' };
             const broker = input.connections === false ? null : apps.grant({ sessionId, runId: null, caller, readOnly: !!input.readOnly, depth: 0 });
             // The session keeps these instructions; each of its runs records a copy, and a memory
             // block that changes later is sent along as a note.
             const variant = input.variant ? materialise(root, input.variant, { trust: this.options.trust ?? null }) : null;
+            const browser = new BrowserControl({ root, cwd: input.cwd, pinned: variant,
+                writable: Boolean(input.variant && !('dir' in input.variant)), apps, hub: this.options.hub,
+                plugins: () => this.options.pluginControl?.list({ cwd: input.cwd, accountId: preparedAccount.id, projectId: input.projectId ?? null }) ?? Promise.resolve([]) });
             if (variant)
                 this.variantDirs.set(sessionId, variant.dir);
-            const worldTools = await this.worldToolNames(input, account);
-            const launchTools = [...new Set([...(input.launch?.tools ?? []), SESSION_NAME, ...worldTools])];
-            const pack = compile(env, caller, { ...input.launch, tools: launchTools }, variant);
+            const worldTools = await this.worldToolNames(input, preparedAccount);
+            const ownTools = await this.ownToolNames(input, preparedAccount);
+            const launchTools = [...new Set([...(input.launch?.tools ?? []), CHECKLIST_WRITE, SESSION_NAME, ...ownTools, ...(broker ? apps.toolNames : []), ...worldTools])];
+            // The profiles replace the variant's own subagent list, which they include.
+            const profiles = this.options.subagents && input.subagents !== null ? profileSection(root, input.cwd, variant?.dir ?? null) : null;
+            const launchSections = profiles ? [...(input.launch?.sections ?? []).filter((section) => section.id !== profiles.id), profiles] : input.launch?.sections;
+            // A terminal is a person's own session: the same standard sections a host's session has.
+            const standard = input.launch?.standard === null ? null : input.launch?.standard ?? { cwd: input.cwd };
+            const pack = compile(env, caller, { ...input.launch, standard, sections: launchSections, tools: launchTools }, variant && profiles ? { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) } : variant);
             record(root, pack);
             mkdirSync(this.historyDir(input), { recursive: true });
             saveForSession(input.sessionFolder, pack);
             const live = {
                 input,
-                account,
+                variant,
+                account: preparedAccount,
                 broker,
                 caller,
                 token: '',
@@ -572,6 +1052,12 @@ export class Terminals {
                     nativeSessionId: input.nativeSessionId ?? null,
                     begin: ({ reservedRunId, text }) => this.begin(live, reservedRunId, text),
                     policy: (run, tool, args) => this.decide(live, run, tool, args),
+                    workspaceRoot: run => {
+                        const record = loadRun(this.options.env.root, run.runId);
+                        return record.workspaceRoot ?? resolveWorkspaceRoot(record.workingDirectory ?? live.input.cwd);
+                    },
+                    workspaceEscape: (run, tool, args, reason) => this.workspaceEscape(live, run, tool, args, reason),
+                    workspaceBoundaryBypass: (run, tool, args) => this.workspaceBoundaryBypass(live, run, tool, args),
                     allowToolGlobally: target => { this.options.approvals.allowTool('pi', target); },
                     native: (nativeSessionId) => bus.emit({ type: 'terminal.native', sessionId, nativeSessionId }),
                     telemetry: (event) => bus.emit({ type: 'terminal.telemetry', sessionId, event }),
@@ -586,6 +1072,46 @@ export class Terminals {
                 caller: () => ({ ...caller, runId: live.controller.activeRun?.runId ?? null }),
                 broker,
                 terminal: { accept: (event, data) => live.controller.accept(event, data), disconnected: () => live.controller.disconnected(), control: async (call, params) => {
+                        if (call === 'terminal.browser.config') {
+                            const world = this.options.world;
+                            if (!world)
+                                throw invalid('Browser settings are unavailable in this host.');
+                            return { allowPrivate: world.browserConfig().allowPrivate };
+                        }
+                        if (call === 'terminal.browser.configure') {
+                            const world = this.options.world;
+                            if (!world)
+                                throw invalid('Browser settings are unavailable in this host.');
+                            if (typeof params.allowPrivate !== 'boolean')
+                                throw invalid('allowPrivate must be a boolean.');
+                            return { allowPrivate: world.configureBrowser({ allowPrivate: params.allowPrivate }).allowPrivate };
+                        }
+                        if (call === 'terminal.browser.snapshot')
+                            return browser.snapshot(params.refresh === true);
+                        if (call === 'terminal.browser.read') {
+                            if (typeof params.id !== 'string')
+                                throw invalid('A resource id is required.');
+                            return browser.read(params.id, params.latest === true);
+                        }
+                        if (call === 'terminal.browser.importSkill') {
+                            if (typeof params.path !== 'string' || !params.path.trim())
+                                throw invalid('A skill folder is required.');
+                            browser.importSkill(params.path);
+                            bus.emit({ type: 'plugins.changed' });
+                            return {};
+                        }
+                        if (call.startsWith('terminal.browser.connections.'))
+                            return browser.connection(call.slice('terminal.browser.connections.'.length), params);
+                        if (call === 'terminal.browser.hubPreview') {
+                            if (!this.options.hub || typeof params.id !== 'string' || typeof params.version !== 'string')
+                                throw invalid('A catalog entry and version are required.');
+                            return this.options.hub.preview(params.id, params.version, typeof params.offset === 'number' ? params.offset : 0);
+                        }
+                        if (call === 'terminal.browser.hubDocument') {
+                            if (!this.options.hub || typeof params.id !== 'string' || typeof params.version !== 'string')
+                                throw invalid('An installed document and version are required.');
+                            return this.options.hub.readDocument(params.id, params.version);
+                        }
                         if (call.startsWith('terminal.doctor.')) {
                             const doctor = this.options.doctor;
                             if (!doctor)
@@ -616,8 +1142,16 @@ export class Terminals {
                                 return doctor.cancel(id);
                             throw invalid('Unknown diagnostic operation.');
                         }
+                        if (call.startsWith('terminal.agents.'))
+                            return this.agentsCall(live, call, params);
                         if (call.startsWith('terminal.subagents.'))
                             return this.subagentsCall(live, call, params);
+                        if (call.startsWith('terminal.sideQuestions.'))
+                            return this.sideQuestionCall(live, call, params);
+                        if (call.startsWith('terminal.worktrees.'))
+                            return this.worktreesCall(live, call, params);
+                        if (call.startsWith('terminal.annotations.'))
+                            return this.annotationsCall(live, call, params);
                         if (call === 'terminal.logs.info')
                             return harnessLogInfo(this.options.stateDir);
                         if (call === 'terminal.logs.read') {
@@ -651,11 +1185,15 @@ export class Terminals {
                                 : this.options.approvals.revokeTool('pi', params.tool);
                             return { globalTools: policy.globalTools.pi ?? [] };
                         }
+                        if (call.startsWith('terminal.usage.'))
+                            return this.usageCall(live, call, params);
                         if (call !== 'terminal.resources')
                             return live.controller.control(call, params);
-                        const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, account), install: false, caller: { projectId: input.projectId ?? null } }) ?? null;
-                        if (resourceIdentity(current) !== resourceIdentity(loading))
+                        const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, preparedAccount), install: false, caller: { projectId: input.projectId ?? null } }) ?? null;
+                        const currentVariant = variant ? materialise(root, { dir: variant.dir, scope: variant.scope }, { trust: this.options.trust ?? null }) : null;
+                        if (resourceIdentity(current) !== resourceIdentity(loading) || (variant && (currentVariant?.fingerprint !== variant.fingerprint || JSON.stringify(currentVariant.extensionPaths) !== JSON.stringify(variant.extensionPaths)))) {
                             throw new HarnessError('terminal_resources_changed', 'Trusted resources changed since this terminal was prepared. Review /plugins and reopen the terminal to load the new selection.');
+                        }
                         return {};
                     } }
             });
@@ -664,16 +1202,17 @@ export class Terminals {
             const args = [...command.argsPrefix, '--append-system-prompt', render(env, pack)];
             if (input.model)
                 args.push('--model', input.model);
-            if (loading) {
+            {
                 // Pi's own discovery is off: the terminal loads what the harness found and nothing else.
                 args.push('--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes');
-                for (const path of [...loading.extensionPaths, ...loading.builtins, ...(variant?.extensionPaths ?? [])])
+                // The pi command's own extensions are not loaded: a host's session cannot have them (PROP-0039).
+                for (const path of [...(loading?.extensionPaths ?? []), ...(variant?.extensionPaths ?? [])])
                     args.push('--extension', path);
-                for (const path of [...(variant?.skillPaths ?? []), ...loading.skillPaths])
+                for (const path of [...(variant?.skillPaths ?? []), ...(loading?.skillPaths ?? [])])
                     args.push('--skill', path);
-                for (const path of loading.promptPaths)
+                for (const path of loading?.promptPaths ?? [])
                     args.push('--prompt-template', path);
-                for (const path of loading.themePaths)
+                for (const path of loading?.themePaths ?? [])
                     args.push('--theme', path);
             }
             // Last, so its gate sees a tool call as every other extension left it.
@@ -691,7 +1230,7 @@ export class Terminals {
                     [SOCKET_ENV]: this.socket.path,
                     [TOKEN_ENV]: token
                 },
-                accountId: account.id,
+                accountId: preparedAccount.id,
                 nativeSessionId: input.nativeSessionId ?? null
             };
         }
@@ -699,8 +1238,15 @@ export class Terminals {
             if (token)
                 this.socket.revoke(token);
             this.sessions.delete(sessionId);
+            this.variantDirs.delete(sessionId);
+            this.worldNames.delete(sessionId);
+            if (this.worktreeLeases.get(sessionId) === acquiredWorktreeId)
+                this.worktreeLeases.delete(sessionId);
             apps.revokeSession(sessionId);
-            await accounts.terminalEnd(account).catch(() => undefined);
+            if (accountStarted && account)
+                await accounts.terminalEnd(account).catch(() => undefined);
+            if (acquiredWorktreeId)
+                await this.options.worktrees?.release(acquiredWorktreeId, sessionId).catch(() => undefined);
             throw error;
         }
     }
@@ -754,6 +1300,11 @@ export class Terminals {
             }
         this.sessions.delete(sessionId);
         this.worldNames.delete(sessionId);
+        const worktreeId = this.worktreeLeases.get(sessionId);
+        this.worktreeLeases.delete(sessionId);
+        if (worktreeId)
+            await this.options.worktrees?.release(worktreeId, sessionId).catch(() => undefined);
+        void this.options.noteCapture?.release(sessionId).catch(() => undefined);
         void this.options.world?.release(sessionId).catch(() => undefined);
         live.controller.dispose();
         this.socket.revoke(live.token);