@xingular/harness 1.0.0 → 1.1.1

package/dist/sdk/terminal/terminals.js

@@ -21,8 +21,13 @@ 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 { CHECKLIST_WRITE } from "../tools/checklist.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 +35,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 +69,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 +108,7 @@ export class Terminals {
                 const owner = this.sessions.get(parent.sessionId);
                 if (owner?.controller.activeRun?.runId === parent.id) {
                     owner.controller.observe(event, true);
+                    owner.controller.observeSubagent(parent.id, record, event, this.subagentProfile(record));
                     break;
                 }
                 parentId = parent.parentRunId;
@@ -235,6 +261,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 +358,194 @@ 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}.`);
+        }
+    }
+    /** `/plugin:notes` and `/plugin:annotate`: the page notes a person keeps, and the visible browser they capture them in. */
+    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;
@@ -413,13 +635,15 @@ export class Terminals {
         }
         // 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))
+        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))
             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.' };
     }
     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 (call === 'terminal.subagents.tools')
@@ -435,7 +659,7 @@ export class Terminals {
             if (!Array.isArray(params.tools) || params.tools.some((name) => typeof name !== 'string'))
                 throw invalid('Native tool names are required.');
             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 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 = 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);
@@ -446,6 +670,7 @@ 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,
+                variant: this.variantDirs.has(live.input.sessionId) ? { dir: this.variantDirs.get(live.input.sessionId), scope: live.input.variant && 'scope' in live.input.variant ? live.input.variant.scope ?? null : null } : null,
                 capabilities
             }, live.account.id, capabilities);
             service.restore(run.runId, params.history ?? { owners: [], receipts: [] });
@@ -519,6 +744,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 +800,51 @@ 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 launchTools = [...new Set([...(input.launch?.tools ?? []), CHECKLIST_WRITE, SESSION_NAME, ...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;
+            const pack = compile(env, caller, { ...input.launch, 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,
+                account: preparedAccount,
                 broker,
                 caller,
                 token: '',
@@ -586,6 +867,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 +937,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') {
@@ -653,7 +982,7 @@ export class Terminals {
                         }
                         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;
+                        const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, preparedAccount), install: false, caller: { projectId: input.projectId ?? null } }) ?? null;
                         if (resourceIdentity(current) !== resourceIdentity(loading))
                             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 {};
@@ -691,7 +1020,7 @@ export class Terminals {
                     [SOCKET_ENV]: this.socket.path,
                     [TOKEN_ENV]: token
                 },
-                accountId: account.id,
+                accountId: preparedAccount.id,
                 nativeSessionId: input.nativeSessionId ?? null
             };
         }
@@ -699,8 +1028,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 +1090,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);

package/dist/sdk/terminal/trajectory.js

@@ -15,7 +15,7 @@ export function listTerminalTrajectoryRuns(root, sessionId, nativeSessionId) {
     if (!nativeSessionId)
         return [];
     return listRuns(root, { sessionId })
-        .filter(run => run.nativeSessionId === nativeSessionId)
+        .filter(run => run.nativeSessionId === nativeSessionId || run.trigger === 'side-question' && run.sessionId === sessionId)
         .map(summary);
 }
 /** Read a run only when it belongs to both this terminal and its current native conversation. */
@@ -23,7 +23,7 @@ export function readTerminalTrajectory(root, sessionId, nativeSessionId, runId,
     if (!nativeSessionId || !Number.isSafeInteger(afterSequence ?? 0) || (afterSequence ?? 0) < 0)
         throw notFound('Run');
     const run = findRun(root, runId);
-    if (!run || run.sessionId !== sessionId || run.nativeSessionId !== nativeSessionId)
+    if (!run || run.sessionId !== sessionId || (run.nativeSessionId !== nativeSessionId && run.trigger !== 'side-question'))
         throw notFound('Run');
     const events = readEvents(root, runId).filter(event => afterSequence === undefined || event.sequence > afterSequence);
     return { run: summary(run), events };

package/dist/sdk/terminal/tui/annotateCommand.d.ts

@@ -0,0 +1,3 @@
+import type { AnnotateStart } from "./pages/annotatePage.js";
+/** `/plugin:annotate` accepts a page address, DevTools target, or page-bridge target. */
+export declare function parseAnnotate(argument: string): AnnotateStart | string;

package/dist/sdk/terminal/tui/annotateCommand.js

@@ -0,0 +1,22 @@
+/** `/plugin:annotate` accepts a page address, DevTools target, or page-bridge target. */
+export function parseAnnotate(argument) {
+    const words = argument.trim().split(/\s+/).filter(Boolean);
+    if (!words.length)
+        return { kind: 'web' };
+    if (words[0] === '--app') {
+        const endpoint = words[1];
+        if (!endpoint)
+            return 'Give the app\'s DevTools address: /plugin:annotate --app http://127.0.0.1:9229';
+        const address = /^\d+$/.test(endpoint) ? `http://127.0.0.1:${endpoint}` : endpoint;
+        const name = words.slice(2).join(' ');
+        return { kind: 'cdp', endpoint: address, ...(name ? { name } : {}) };
+    }
+    if (words[0] === '--bridge') {
+        const name = words.slice(1).join(' ');
+        return { kind: 'bridge', ...(name ? { name } : {}) };
+    }
+    if (words.length > 1 || words[0].startsWith('--'))
+        return 'Use /plugin:annotate [url], /plugin:annotate --app <DevTools address>, or /plugin:annotate --bridge.';
+    const url = /^[a-z][a-z0-9+.-]*:\/\//i.test(words[0]) ? words[0] : /^(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/.test(words[0]) ? `http://${words[0]}` : `https://${words[0]}`;
+    return { kind: 'web', url };
+}

package/dist/sdk/terminal/tui/commandPages.d.ts

@@ -1,7 +1,11 @@
 import type { TerminalPage } from "./page.js";
 import type { TerminalCommandHost } from "./commands.js";
-export type CommandPageId = 'doctor' | 'accounts' | 'permissions' | 'plugins' | 'hub' | 'components' | 'settings' | 'trajectory' | 'log';
+import { type AnnotateStart } from "./pages/annotatePage.js";
+export type CommandPageId = 'doctor' | 'accounts' | 'permissions' | 'plugins' | 'hub' | 'components' | 'settings' | 'trajectory' | 'log' | 'harness' | 'skills' | 'connections' | 'tools' | 'worktree' | 'notes' | 'annotate' | 'subagents' | 'agents';
 /** Construct one independent full-screen page for a slash command. */
 export declare function createCommandPage(host: TerminalCommandHost, id: CommandPageId, options?: {
     runId?: string;
+    url?: string;
+    annotate?: AnnotateStart;
+    close?(): void;
 }): TerminalPage;