@xingular/harness 1.1.1 → 1.3.1-unstable.0

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

@@ -1,6 +1,11 @@
-import type { AgentSession, ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { type AgentSession, type ExtensionAPI } from '@earendil-works/pi-coding-agent';
 export interface TerminalPlanRunState {
     active: boolean;
     allowedTools: ReadonlySet<string>;
+    connectors?: string[];
+    subagentProfiles?: {
+        normal: string;
+        plan: string;
+    };
 }
 export default function (pi: ExtensionAPI, planRun?: TerminalPlanRunState, getSession?: () => AgentSession): Promise<void>;

package/dist/sdk/terminal/piExtension.js

@@ -1,13 +1,29 @@
+// Loaded by the `pi` command in a terminal session (`--extension`). It reports what the native
+// session does to the harness, asks before each tool call, takes instructions the harness
+// queues for it, and gives the session the harness's own tools. It runs in the `pi` process,
+// so everything it knows about the harness comes through the session socket.
+import { createBashTool, createEditTool, createPowerShellTool, createWriteTool } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
-import { QUESTION_SKETCH_MAX_LENGTH, QUESTION_SKETCH_PATTERN, questionSketchError } from "../sessions/contracts.js";
 import { connectionFromEnv, socketCall, terminalCall } from "./client.js";
 import { controlCall } from "./control.js";
-import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory } from "../sessions/subagents.js";
+import { SPAWN_SUBAGENT, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory } from "../sessions/subagents.js";
+import { PLAN_RESEARCH_TOOLS } from "../agents/planResearch.js";
 import { askUserTool } from "../tools/askUser.js";
-import { checklistTool } from "../tools/checklist.js";
+import { todoTool } from "../tools/todo.js";
+import { CHECKPOINT_WRITE, checkpointTool } from "../tools/checkpoint.js";
+import { createSliceState, parseWorkSlice, workSliceGuard } from "../sessions/workSlice.js";
+import { DEFAULT_COMMAND_TIMEOUT_SECONDS, withCommandBudget } from "../core/commandBudget.js";
 import { sessionNameTool } from "../tools/sessionName.js";
+import { CAPABILITY_DISCOVERY, describeCapabilities } from "../tools/getCapabilities.js";
 import { PLAN_INSTRUCTIONS, planRefusal } from "../sessions/planMode.js";
+import { compactionCheckpoint } from "../sessions/compactionCheckpoint.js";
 import { pruneToolImages } from "../world/images.js";
+import { parseInitialBashCommand } from "../sessions/initialBash.js";
+import { inspectWorkspaceWrite } from "../sessions/workspaceBoundary.js";
+import { createWorkspaceShellTool } from "../core/workspaceBashTool.js";
+import { createWorkspaceBashOperations, runWithWorkspaceWriteScope } from "../core/workspaceSandbox.js";
+import { withWorkspaceWriteAuthorization, workspaceEditOperations, workspaceWriteOperations } from "../core/workspaceWriteOperations.js";
+import { BUDGET_GUARD, OUTPUT_TRIM, budgetGuard, outputTrim } from "../plugins/firstParty.js";
 /** How much text a tool handed back to the model. */
 function resultSize(result) {
     const content = result?.content;
@@ -32,6 +48,7 @@ export default async function (pi, planRun, getSession) {
     let context = null;
     let nativeSubagents = false;
     let subagentParent = false;
+    let stoppedChildren = null;
     let timer = null;
     let polling = false;
     let failure;
@@ -42,6 +59,8 @@ export default async function (pi, planRun, getSession) {
     let requestStartedAt = null;
     const toolStartedAt = new Map();
     const fileTools = new Map();
+    const writeAuthorizations = new Map();
+    let workspaceRoot = null;
     // The harness's own tools for this session (connected apps and what the application offers).
     let stage = 'Tool discovery';
     try {
@@ -62,8 +81,19 @@ export default async function (pi, planRun, getSession) {
                 }
             });
         }
+        // The harness's own extensions a person switched on, as a structured session loads them inline.
+        const own = await socketCall(connection, 'firstParty.list', {}, 15_000)
+            .then((reply) => reply?.plugins ?? [], () => []);
+        for (const plugin of own) {
+            if (plugin.id === OUTPUT_TRIM)
+                outputTrim(plugin.settings)(pi);
+            if (plugin.id === BUDGET_GUARD)
+                budgetGuard(plugin.settings)(pi);
+        }
         const native = await controlCall('terminal.subagents.tools');
         nativeSubagents = native.tools.length > 0;
+        if (planRun && native.profiles)
+            planRun.subagentProfiles = native.profiles;
         for (const tool of native.tools)
             pi.registerTool({
                 name: tool.name, label: tool.label, description: tool.description, parameters: Type.Unsafe(tool.parameters),
@@ -77,6 +107,46 @@ export default async function (pi, planRun, getSession) {
         await terminalCall('startupFailed', { reason: `${stage} failed: ${error instanceof Error ? error.message : 'Unavailable'}` }).catch(() => { });
         throw error;
     }
+    pi.registerTool({
+        ...CAPABILITY_DISCOVERY,
+        parameters: Type.Unsafe(CAPABILITY_DISCOVERY.parameters),
+        async execute(_id, input) {
+            const active = pi.getActiveTools();
+            const tools = pi.getAllTools();
+            const selected = planRun?.active ? [...planRun.allowedTools] : active;
+            const name = input && typeof input === 'object' && typeof input.tool === 'string'
+                ? input.tool
+                : undefined;
+            const text = JSON.stringify(describeCapabilities({
+                capabilities: { version: 1, tools: selected, connectors: planRun?.connectors ?? [], contributions: [] },
+                active,
+                registered: tools
+            }, name));
+            return { content: [{ type: 'text', text }], details: undefined };
+        }
+    });
+    const workspaceBash = createWorkspaceBashOperations(() => workspaceRoot, {
+        bypassWorkspaceBoundary: async (request) => {
+            const result = await controlCall('terminal.workspaceBoundaryBypass', { tool: 'bash', args: { command: request.command, cwd: request.cwd, workspaceRoot: request.workspaceRoot } });
+            return result.bypass;
+        },
+        requestWorkspaceWriteScope: async (request) => {
+            const result = await controlCall('terminal.workspaceEscape', { tool: 'bash', args: { command: request.command, workspaceWriteScope: 'outside' }, reason: request.reason });
+            return result.approved;
+        },
+        workspaceWriteScope: () => planRun?.active ? 'read-only' : undefined
+    });
+    pi.registerTool(createWorkspaceShellTool({ createBashTool, createPowerShellTool }, process.cwd(), workspaceBash));
+    pi.registerTool(withWorkspaceWriteAuthorization(createWriteTool(process.cwd(), { operations: workspaceWriteOperations }), writeAuthorizations));
+    pi.registerTool(withWorkspaceWriteAuthorization(createEditTool(process.cwd(), { operations: workspaceEditOperations }), writeAuthorizations));
+    compactionCheckpoint({ planInstructions: () => planRun?.active ? PLAN_INSTRUCTIONS : null })(pi);
+    // A terminal reply is bounded like any other (PROP-0041): a checkpoint at the boundary, then the
+    // person decides whether to continue.
+    const slicePolicy = parseWorkSlice(undefined);
+    const sliceState = createSliceState(slicePolicy);
+    // `XINGULAR_WORK_SLICE=off` at launch leaves terminal replies unbounded, as before PROP-0041.
+    if (slicePolicy.enabled)
+        workSliceGuard({ policy: slicePolicy, state: sliceState, checkpointAvailable: () => !planRun?.active || planRun.allowedTools.has(CHECKPOINT_WRITE) })(pi);
     // Only the latest screenshots stay in what the model sees (world/images.ts).
     pi.on('context', (event) => {
         const messages = pruneToolImages(event.messages);
@@ -86,7 +156,8 @@ export default async function (pi, planRun, getSession) {
         context = ctx;
         if (timer)
             clearInterval(timer);
-        await terminalCall('ready', { nativeSessionId: ctx.sessionManager.getSessionFile() });
+        // The branch's parent runs let the controller show the latest one's rows again on reopen.
+        await terminalCall('ready', { nativeSessionId: ctx.sessionManager.getSessionFile(), owners: subagentHistory(ctx.sessionManager.getBranch?.() ?? []).owners });
         timer = setInterval(() => {
             if (polling || !context)
                 return;
@@ -119,10 +190,20 @@ export default async function (pi, planRun, getSession) {
         reasoningTokens = undefined;
         costReported = false;
         // A run a plugin starts with a custom message has no user prompt to record; it still begins a turn.
-        const begun = await terminalCall('begin', { text: event.messageType === 'user' ? event.prompt : '' });
+        const begun = await terminalCall('begin', { text: event.messageType === 'user' ? event.prompt : '', model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel?.() ?? null });
+        workspaceRoot = typeof begun.workspaceRoot === 'string' ? begun.workspaceRoot : null;
+        if (!workspaceRoot)
+            throw new Error('The active project workspace could not be resolved; the turn was not started.');
+        // Every turn marks its run on the branch, so a reopened conversation finds its latest one.
+        pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId });
+        stoppedChildren = null;
         if (nativeSubagents) {
-            pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId });
-            await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) });
+            const snapshot = await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), plan: planRun?.active === true, history: subagentHistory(ctx.sessionManager.getBranch()) });
+            if (planRun && Array.isArray(snapshot.connectors))
+                planRun.connectors = snapshot.connectors;
+            if (planRun && snapshot.subagentProfiles)
+                planRun.subagentProfiles = snapshot.subagentProfiles;
+            stoppedChildren = snapshot.notice ?? null;
             subagentParent = true;
         }
         if (planRun && event.messageType === 'user') {
@@ -130,24 +211,31 @@ export default async function (pi, planRun, getSession) {
                 event.systemPromptOptions.sections.plan = PLAN_INSTRUCTIONS;
             else
                 delete event.systemPromptOptions.sections.plan;
+            if (planRun.subagentProfiles)
+                event.systemPromptOptions.sections.subagents = planRun.active ? planRun.subagentProfiles.plan : planRun.subagentProfiles.normal;
         }
         const bang = event.messageType === 'user' ? /^\s*!\s*([\s\S]+)$/u.exec(event.prompt) : null;
         if (!bang)
             return;
-        const command = bang[1];
+        const initial = parseInitialBashCommand(bang[1]);
+        const command = initial.command;
+        const args = { command, ...(initial.workspaceWriteScope === 'outside' ? { workspaceWriteScope: 'outside' } : {}) };
         const id = `initial-bash:${begun.runId}`;
         const started = Date.now();
-        await terminalCall('tool', { phase: 'start', id, name: 'bash', summary: command.slice(0, 200), input: JSON.stringify({ command }) });
+        await terminalCall('tool', { phase: 'start', id, name: 'bash', summary: command.slice(0, 200), input: JSON.stringify(args) });
         let refusal;
         let result;
-        if (planRun?.active) {
+        if (!command) {
+            refusal = 'Enter a Bash command after !outside.';
+        }
+        else if (planRun?.active) {
             refusal = 'Bash commands are disabled while a plan request is running.';
         }
         else {
             try {
-                const policy = await terminalCall('policy', { tool: 'bash', args: { command } });
+                const policy = await terminalCall('policy', { tool: 'bash', args });
                 if (policy.requiresApproval) {
-                    const approval = await terminalCall('approval', { requestId: id, tool: 'bash', args: { command } });
+                    const approval = await terminalCall('approval', { requestId: id, tool: 'bash', args });
                     if (approval.decision !== 'approved')
                         refusal = 'The user denied this Bash command.';
                 }
@@ -159,7 +247,7 @@ export default async function (pi, planRun, getSession) {
                     if (!session)
                         refusal = 'The native session is unavailable.';
                     else
-                        result = await session.executeBash(command, undefined, { id });
+                        result = await runWithWorkspaceWriteScope(initial.workspaceWriteScope, () => withCommandBudget(() => session.executeBash(command, undefined, { id, operations: workspaceBash }), () => session.abortBash(), DEFAULT_COMMAND_TIMEOUT_SECONDS));
                 }
             }
             catch (error) {
@@ -179,6 +267,13 @@ export default async function (pi, planRun, getSession) {
             : 'The user’s initial Bash command has already run. Read its native Bash result and explain what it shows. Do not run the same command again unless the user explicitly asks.';
         return { message: { customType: 'xingular-initial-bash', content: instruction, display: false, details: {} } };
     });
+    // A second handler, so the notice joins any initial-Bash message rather than replacing it.
+    pi.on('before_agent_start', async () => {
+        const notice = stoppedChildren;
+        stoppedChildren = null;
+        if (notice)
+            return { message: { customType: SUBAGENT_RESULTS, content: notice.text, display: false, details: { [SUBAGENT_RECEIPT]: notice.receipt } } };
+    });
     const deliverChildren = async (event, ctx, settle) => {
         if (!nativeSubagents || (settle && event.outcome !== 'completed') || ctx.signal?.aborted)
             return;
@@ -240,21 +335,61 @@ export default async function (pi, planRun, getSession) {
     pi.on('turn_start', async () => {
         requestStartedAt = Date.now();
     });
-    pi.on('tool_call', async (event) => {
+    pi.on('tool_call', async (event, ctx) => {
         if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
-            const reason = planRefusal(event.toolName, new Set()) ?? `Plan mode is research-only: ${event.toolName} is not available in this session.`;
+            const reason = planRefusal(event.toolName, new Set(), event.input) ?? `Plan mode is research-only: ${event.toolName} is not available in this session.`;
             return { block: true, reason };
         }
+        if (planRun?.active && event.toolName === SPAWN_SUBAGENT) {
+            try {
+                const eligibility = await controlCall('terminal.subagents.planSafe', { input: event.input });
+                if (!eligibility.allowed)
+                    return { block: true, reason: eligibility.reason ?? 'This profile is not eligible for plan-mode research.' };
+            }
+            catch (error) {
+                return { block: true, reason: `Plan-mode research eligibility could not be verified: ${error instanceof Error ? error.message : 'controller unavailable'}` };
+            }
+        }
+        else if (planRun?.active) {
+            const reason = planRefusal(event.toolName, new Set(PLAN_RESEARCH_TOOLS), event.input);
+            if (reason)
+                return { block: true, reason };
+        }
+        let authorization;
+        if ((event.toolName === 'edit' || event.toolName === 'write') && typeof event.input.path === 'string') {
+            try {
+                if (!workspaceRoot)
+                    throw new Error('The active project workspace is unavailable.');
+                const inspection = inspectWorkspaceWrite(workspaceRoot, ctx.cwd, event.toolName, event.input);
+                Object.assign(event.input, inspection.input);
+                if (!inspection.path)
+                    throw new Error('The native file-write target could not be verified.');
+                authorization = {
+                    workspaceRoot,
+                    cwd: ctx.cwd,
+                    path: inspection.path,
+                    outside: inspection.outside,
+                    authorized: false
+                };
+            }
+            catch (error) {
+                return { block: true, reason: error instanceof Error ? error.message : 'The active project workspace could not be verified.' };
+            }
+        }
         try {
             const policy = await controlCall('terminal.policy', { tool: event.toolName, args: event.input });
             if (policy.requiresApproval) {
                 const approval = await controlCall('terminal.approval', { requestId: event.toolCallId, tool: event.toolName, args: event.input });
-                if (approval.decision === 'approved')
-                    return;
-                return { block: true, reason: 'The user denied this action. Ask how they would like to proceed.' };
+                if (approval.decision !== 'approved')
+                    return { block: true, reason: 'The user denied this action. Ask how they would like to proceed.' };
             }
-            if (!policy.allowed)
+            else if (!policy.allowed) {
                 return { block: true, reason: policy.reason ?? 'Outside what this session may do.' };
+            }
+            if (authorization) {
+                authorization.authorized = true;
+                writeAuthorizations.set(event.toolCallId, authorization);
+            }
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
@@ -287,7 +422,10 @@ export default async function (pi, planRun, getSession) {
             }
         }
         subagentParent = false;
-        await terminalCall('settled', { error: failure, aborted: event.aborted });
+        // A reply that stopped at its work-slice boundary is not a completed task: the record says so,
+        // so a host can offer the continuation instead of treating it as done (PROP-0041).
+        const reason = sliceState.endedBy ? sliceState.endedBy === 'stuck' ? 'stalled' : 'slice_complete' : undefined;
+        await terminalCall('settled', { error: failure, aborted: event.aborted, ...(reason ? { reason } : {}) });
     });
     pi.on('user_bash', async () => {
         throw new Error('Use the ! command composer so this action can be checked.');
@@ -313,19 +451,32 @@ export default async function (pi, planRun, getSession) {
             return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
         }
     });
-    // The checklist is recorded on the harness run; the shared tool validates and the socket carries the event.
+    // The todo list is recorded on the harness run; the shared tool validates and the socket carries the event.
     let recorded = Promise.resolve();
-    const checklist = checklistTool({ emit: (_type, payload) => { recorded = terminalCall('checklist', payload); } });
+    const todo = todoTool({ emit: (_type, payload) => { recorded = terminalCall('todo', payload); } });
     pi.registerTool({
-        name: checklist.name, label: checklist.label, description: checklist.description,
-        parameters: Type.Unsafe(checklist.parameters(Type)),
+        name: todo.name, label: todo.label, description: todo.description,
+        parameters: Type.Unsafe(todo.parameters(Type)),
         async execute(_id, input) {
             recorded = Promise.resolve();
-            const result = await checklist.execute(input);
+            const result = await todo.execute(input);
             await recorded;
             return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
         }
     });
+    // A bounded reply records its handoff here; the terminal reply is its own slice.
+    let checkpointRecorded = Promise.resolve();
+    const checkpoint = checkpointTool({ emit: (_type, payload) => { checkpointRecorded = terminalCall('checkpoint', payload); } }, 1);
+    pi.registerTool({
+        name: checkpoint.name, label: checkpoint.label, description: checkpoint.description,
+        parameters: Type.Unsafe(checkpoint.parameters(Type)),
+        async execute(_id, input) {
+            checkpointRecorded = Promise.resolve();
+            const result = await checkpoint.execute(input);
+            await checkpointRecorded;
+            return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
+        }
+    });
     const ask = askUserTool({ requestAnswers: questions => terminalCall('questions', { questions }, 1_230_000) });
     pi.registerTool({
         name: ask.name, label: ask.label, description: ask.description,
@@ -335,43 +486,6 @@ export default async function (pi, planRun, getSession) {
             return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
         }
     });
-    pi.registerTool({
-        name: 'ask_user_question',
-        label: 'Ask a question',
-        description: 'Ask the user a question and wait for their answer. Include a concise 1–2 word summary label; if omitted, the terminal derives one from the question. Every question must include at least one choice and at least one choice must be recommended. Recommendations are visual only and never preselect answers; submitted choices keep their labels. Mark at most one choice recommended for single-choice questions or several when multiSelect is true. When a UI diagram helps compare choices, set uiSketch: true and include a detailed, bounded ASCII wireframe for every choice. Use ASCII tables and panel borders to show the affected element alongside relevant neighboring UI, with readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes, not a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels.',
-        parameters: Type.Object({
-            summary: Type.Optional(Type.String({ description: 'A concise label of one or two words' })),
-            question: Type.String(),
-            uiSketch: Type.Optional(Type.Literal(true, { description: 'Enable an ASCII sketch preview; when true, every choice must include a sketch.' })),
-            options: Type.Array(Type.Object({
-                label: Type.String(),
-                description: Type.Optional(Type.String()),
-                recommended: Type.Optional(Type.Boolean()),
-                sketch: Type.Optional(Type.String({ minLength: 1, maxLength: QUESTION_SKETCH_MAX_LENGTH, pattern: QUESTION_SKETCH_PATTERN, description: 'Literal ASCII UI wireframe: 1–24 LF-separated lines, at most 80 printable ASCII characters per line. Include the affected element and neighboring UI using structured table/panel borders with fixed, matching outer-edge columns on every row. Required for every choice when uiSketch is true.' }))
-            }), {
-                minItems: 1,
-                contains: Type.Object({ recommended: Type.Literal(true) })
-            }),
-            multiSelect: Type.Optional(Type.Boolean())
-        }),
-        async execute(id, input) {
-            if (!Array.isArray(input.options) || input.options.length === 0)
-                throw new Error('Every question needs at least one choice.');
-            const recommendedCount = input.options.filter(option => option.recommended).length;
-            if (recommendedCount === 0)
-                throw new Error('Every question needs at least one recommended choice.');
-            if (!input.multiSelect && recommendedCount > 1)
-                throw new Error('A single-choice question may recommend at most one option.');
-            const sketchError = questionSketchError(input.uiSketch, input.options);
-            if (sketchError)
-                throw new Error(sketchError);
-            const summary = typeof input.summary === 'string' ? input.summary.trim() : '';
-            if (summary && (summary.length > 100 || summary.split(/\s+/u).filter(Boolean).length > 2)) {
-                throw new Error('The question summary must be a concise 1–2 word label of no more than 100 characters.');
-            }
-            const answer = await terminalCall('question', { requestId: id, ...input, ...(summary ? { summary } : {}) });
-            return { content: [{ type: 'text', text: JSON.stringify(answer) }], details: undefined };
-        }
-    });
+    // One question tool, as in every structured session: the terminal has no ask_user_question alias (PROP-0039).
     await terminalCall('startup', { phase: 'Pi hooks registered' });
 }

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

@@ -1,10 +1,14 @@
 import { spawn as nodeSpawn } from 'node:child_process';
+import type { SecretStore } from "../accounts/secrets.js";
+import { type SecretBackendDescriptor } from "../core/interactiveProfile.js";
 import { type Harness, type HarnessOptions } from "../harness.js";
 export interface StandalonePaths {
     dataRoot: string;
     stateDir: string;
     /** `--worktree [name]`: start in a new managed worktree (true) or the named one. */
     worktree?: string | true | null;
+    /** `--variant <scope>`: run on that scope's head, as a host's agent of that scope does. */
+    variant?: string | null;
 }
 export interface StandaloneDependencies {
     home?: string;
@@ -13,6 +17,9 @@ export interface StandaloneDependencies {
     stdoutIsTTY?: boolean;
     createSessionId?: () => string;
     createHarness?: (options: HarnessOptions) => Harness;
+    hostSecretStore?: (descriptor: Extract<SecretBackendDescriptor, {
+        kind: 'host';
+    }>) => SecretStore | Promise<SecretStore>;
     spawn?: typeof nodeSpawn;
 }
 export declare function standaloneArguments(argv: string[]): string[] | null;

package/dist/sdk/terminal/standalone.js

@@ -6,30 +6,39 @@ import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { setLogSink } from "../core/bus.js";
 import { DEFAULT_PRODUCT_NAME } from "../core/env.js";
+import { interactiveProfileSecretStore, resolveInteractiveProfile } from "../core/interactiveProfile.js";
 import { createHarness } from "../harness.js";
+import { seedVariant } from "../variant/seed.js";
+import * as variantStore from "../variant/store.js";
 export function standaloneArguments(argv) {
     const command = argv[0];
     if (!command || command.startsWith('-'))
         return argv;
     return command === 'terminal' ? argv.slice(1) : null;
 }
-export function parseStandaloneOptions(argv, home = homedir(), cwd = process.cwd()) {
-    const root = join(home, '.xingular-harness');
-    const paths = {
-        dataRoot: join(root, 'data'),
-        stateDir: join(root, 'state')
-    };
+function resolveStandaloneOptions(argv, home = homedir(), cwd = process.cwd()) {
+    const overrides = {};
     const given = new Set();
+    let worktree;
+    let variant;
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         if (argument === '--worktree' || argument === '-w') {
             const name = argv[index + 1];
             if (name && !name.startsWith('-')) {
-                paths.worktree = name;
+                worktree = name;
                 index += 1;
             }
             else
-                paths.worktree = true;
+                worktree = true;
+            continue;
+        }
+        if (argument === '--variant') {
+            const scope = argv[index + 1];
+            if (!scope || scope.startsWith('-'))
+                throw new Error('--variant needs a variant scope.');
+            variant = scope;
+            index += 1;
             continue;
         }
         if (argument !== '--data' && argument !== '--state')
@@ -37,7 +46,10 @@ export function parseStandaloneOptions(argv, home = homedir(), cwd = process.cwd
         const value = argv[index + 1];
         if (!value || value.startsWith('--'))
             throw new Error(`${argument} needs a directory path.`);
-        paths[argument === '--data' ? 'dataRoot' : 'stateDir'] = resolve(cwd, value);
+        if (argument === '--data')
+            overrides.dataRoot = resolve(cwd, value);
+        else
+            overrides.stateDir = resolve(cwd, value);
         given.add(argument);
         index += 1;
     }
@@ -46,7 +58,49 @@ export function parseStandaloneOptions(argv, home = homedir(), cwd = process.cwd
     if (!isAbsolute(home) && !(given.has('--data') && given.has('--state'))) {
         throw new Error(`The home folder "${home}" is not an absolute path, so the default data and state folders cannot be placed. Set HOME to your home folder, or pass --data and --state with absolute folders.`);
     }
-    return paths;
+    // `npm run dev` passes these roots explicitly. Keep its profile and credentials separate from
+    // the installed interactive profile, even when that production profile selects a host store.
+    const devRoot = isAbsolute(home) ? join(home, '.xingular-harness-dev') : null;
+    const devData = devRoot ? join(devRoot, 'data') : null;
+    const devState = devRoot ? join(devRoot, 'state') : null;
+    const development = !!devRoot && (overrides.dataRoot === devData || overrides.stateDir === devState);
+    const resolvedProfile = isAbsolute(home)
+        ? resolveInteractiveProfile({
+            home,
+            ...(development ? {
+                configPath: join(devRoot, 'profile.json'),
+                legacyDefaults: {
+                    dataRoot: devData,
+                    stateDir: devState,
+                    defaultVariantScope: 'default',
+                    secretBackend: { kind: 'file', path: join(devState, 'secrets.json') }
+                }
+            } : {}),
+            overrides
+        })
+        : {
+            version: 1,
+            dataRoot: overrides.dataRoot,
+            stateDir: overrides.stateDir,
+            defaultVariantScope: 'default',
+            secretBackend: { kind: 'file', path: join(overrides.stateDir, 'secrets.json') }
+        };
+    // The standalone development launch has no host adapter and must not use the App's Keychain.
+    const profile = development
+        ? { ...resolvedProfile, secretBackend: { kind: 'file', path: join(resolvedProfile.stateDir, 'secrets.json') } }
+        : resolvedProfile;
+    return {
+        profile,
+        paths: {
+            dataRoot: profile.dataRoot,
+            stateDir: profile.stateDir,
+            ...(worktree !== undefined ? { worktree } : {}),
+            ...(variant !== undefined ? { variant } : {})
+        }
+    };
+}
+export function parseStandaloneOptions(argv, home = homedir(), cwd = process.cwd()) {
+    return resolveStandaloneOptions(argv, home, cwd).paths;
 }
 function processEnvironment(overrides) {
     const environment = { ...process.env };
@@ -133,9 +187,10 @@ export async function runStandaloneTerminal(argv, dependencies = {}) {
         throw new Error('The interactive Harness terminal needs a TTY. Run it from a terminal, or use `xagent serve` for a host process.');
     }
     let cwd = resolve(dependencies.cwd ?? process.cwd());
-    const paths = parseStandaloneOptions(argv, dependencies.home, cwd);
+    const { paths, profile } = resolveStandaloneOptions(argv, dependencies.home, cwd);
+    const secrets = await interactiveProfileSecretStore(profile, dependencies.hostSecretStore);
     const makeHarness = dependencies.createHarness ?? createHarness;
-    const harness = makeHarness({ dataRoot: paths.dataRoot, stateDir: paths.stateDir, productName: DEFAULT_PRODUCT_NAME });
+    const harness = makeHarness({ dataRoot: paths.dataRoot, stateDir: paths.stateDir, productName: DEFAULT_PRODUCT_NAME, secrets });
     const newSessionId = dependencies.createSessionId ?? randomUUID;
     let current = { sessionId: newSessionId(), accountId: null, nativeSessionId: null };
     // The frontend draws on this terminal, so the host's diagnostics go to a file the person can read instead.
@@ -150,6 +205,10 @@ export async function runStandaloneTerminal(argv, dependencies = {}) {
     });
     try {
         await harness.ready;
+        const variantScope = paths.variant ?? profile.defaultVariantScope;
+        if (variantScope === profile.defaultVariantScope && !variantStore.head(paths.dataRoot, variantScope)) {
+            variantStore.seed(paths.dataRoot, variantScope, seedVariant(paths.dataRoot, {}), 'interactive profile default');
+        }
         if (harness.accounts.overview().accounts.length === 0)
             harness.accounts.create('Default', 'subscription');
         let worktreeId = null;
@@ -160,7 +219,7 @@ export async function runStandaloneTerminal(argv, dependencies = {}) {
         }
         for (;;) {
             const sessionFolder = join(paths.dataRoot, 'sessions', 'terminal', createHash('sha256').update(cwd).digest('hex'));
-            const launch = await harness.terminals.prepare({ ...current, cwd, sessionFolder, ...(worktreeId ? { run: { worktreeId } } : {}) });
+            const launch = await harness.terminals.prepare({ ...current, cwd, sessionFolder, variant: { scope: variantScope }, ...(worktreeId ? { run: { worktreeId } } : {}) });
             const code = await spawnFrontend(launch, cwd, dependencies.spawn);
             // `/accounts` and `/worktree` ask for a switch and end the frontend. An account switch resumes
             // the conversation; a folder switch starts a new one there.

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

@@ -1,13 +1,17 @@
-import type { RunEvent, RunStatus } from "../sessions/contracts.js";
+import { type RunEvent, type RunStatus, type UsagePayload } from "../sessions/contracts.js";
+import type { Effort } from "../sessions/runner.js";
 /** The agent profile a child started from, as the roster shows it (PROP-0029). */
 export interface TerminalSubagentProfile {
     name: string;
     color: string;
 }
+/** The main agent's row: the parent run itself, shown by name rather than by a profile. */
+export declare const MAIN_PROFILE: TerminalSubagentProfile;
 export interface TerminalSubagentRun {
     id: string;
     parentRunId: string | null;
-    relation: 'subagent';
+    /** `main` is the parent run itself; every other row is a child or nested child. */
+    relation: 'main' | 'subagent';
     /** The short name the parent gave the child (PROP-0030). */
     title: string;
     goal: string | null;
@@ -15,11 +19,19 @@ export interface TerminalSubagentRun {
     startedAt: string;
     endedAt: string | null;
     profile?: TerminalSubagentProfile | null;
+    /** The pinned account's display label; subagents never switch accounts. */
+    accountLabel?: string | null;
+    /** Effective launch selection, superseded by provider-reported usage when available. */
+    model?: string | null;
+    effort?: Effort | null;
 }
+export type TerminalSubagentUsage = Partial<Pick<UsagePayload, 'provider' | 'model' | 'inputTokens' | 'outputTokens' | 'cacheReadTokens' | 'cacheWriteTokens' | 'reasoningTokens' | 'costUsd' | 'costSource' | 'requests' | 'contextTokens' | 'contextWindow'>>;
 export interface TerminalSubagentActivity extends TerminalSubagentRun {
     activity: string;
-    /** How far the child's own checklist is: counts only, never the items. */
-    checklist: {
+    /** Cumulative run usage only; provider reasoning summaries and request details stay private. */
+    usage: TerminalSubagentUsage | null;
+    /** How far the child's own todo is: counts only, never the items. */
+    todo: {
         done: number;
         total: number;
     } | null;
@@ -27,12 +39,22 @@ export interface TerminalSubagentActivity extends TerminalSubagentRun {
 export declare const ACTIVE_SUBAGENT_STATUSES: Set<"queued" | "running" | "waiting_for_approval" | "waiting_for_input" | "interrupted" | "completed" | "failed">;
 export declare function terminalSubagentDuration(activity: TerminalSubagentRun, now?: number): string;
 export declare function terminalSubagentTone(status: RunStatus): 'success' | 'warning' | 'error' | 'muted';
-/** Volatile, read-only activity projection for the active terminal parent run. */
+/** Volatile, read-only activity projection for the latest terminal parent run. */
 export declare class SubagentMonitor {
     private parentRunId;
     private readonly activities;
     begin(parentRunId: string): void;
-    observe(parentRunId: string, run: TerminalSubagentRun, event: RunEvent): void;
+    /** Folds one event of the tracked parent (`main`) or one of its descendants; `null` seeds the row. */
+    observe(parentRunId: string, run: TerminalSubagentRun, event: RunEvent | null): void;
+    /**
+     * Rebuilds the rows of a parent run that is no longer live, such as the latest one of a reopened
+     * conversation, by folding each run's saved events. Rows keep their final status.
+     */
+    restore(parentRunId: string, runs: readonly {
+        run: TerminalSubagentRun;
+        events: readonly RunEvent[];
+    }[]): void;
+    /** The main row first, then children in start order. */
     snapshot(parentRunId: string): TerminalSubagentActivity[];
     clear(parentRunId?: string): void;
 }