@xingular/harness 1.3.1-unstable.8 → 1.4.0-unstable

package/dist/sdk/terminal/credentialStore.js

@@ -0,0 +1,33 @@
+import { controlCall } from "./control.js";
+/** Long enough to wait for another holder's lease and the lock, as the host bounds both. */
+const LEASE_CALL_MS = 60_000;
+export function terminalCredentialStore(call = controlCall) {
+    return {
+        async read(providerId, options) {
+            const result = await call('accounts.credentials.read', { provider: providerId }, undefined, options?.signal);
+            return result.credential ?? undefined;
+        },
+        async list(options) {
+            const result = await call('accounts.credentials.list', {}, undefined, options?.signal);
+            return result.credentials ?? [];
+        },
+        async modify(providerId, fn, options) {
+            // The host holds the provider's lock from the lease until the commit, so this read-modify-write
+            // (a refresh or a sign-in) is serialized with every other process on the account.
+            const lease = await call('accounts.credentials.lease', { provider: providerId }, LEASE_CALL_MS, options?.signal);
+            let next;
+            try {
+                next = await fn(lease.current ?? undefined);
+            }
+            catch (error) {
+                await call('accounts.credentials.commit', { leaseId: lease.leaseId }).catch(() => undefined);
+                throw error;
+            }
+            const result = await call('accounts.credentials.commit', { leaseId: lease.leaseId, ...(next === undefined ? {} : { credential: next }) });
+            return result.credential ?? undefined;
+        },
+        async delete(providerId, options) {
+            await call('accounts.credentials.delete', { provider: providerId }, undefined, options?.signal);
+        }
+    };
+}

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

@@ -1,4 +1,5 @@
 import { type AgentSession, type ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { type GoalController } from "../sessions/goal.js";
 export interface TerminalPlanRunState {
     active: boolean;
     allowedTools: ReadonlySet<string>;
@@ -8,4 +9,4 @@ export interface TerminalPlanRunState {
         plan: string;
     };
 }
-export default function (pi: ExtensionAPI, planRun?: TerminalPlanRunState, getSession?: () => AgentSession): Promise<void>;
+export default function (pi: ExtensionAPI, planRun?: TerminalPlanRunState, getSession?: () => AgentSession, goal?: GoalController): Promise<void>;

package/dist/sdk/terminal/piExtension.js

@@ -3,7 +3,7 @@
 // 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 { readFileSync } from 'node:fs';
-import { createBashTool, createEditTool, createPowerShellTool, createWriteTool } from '@earendil-works/pi-coding-agent';
+import { createBashTool, createEditTool, createEditToolDefinition, createPowerShellTool, createWriteTool, createWriteToolDefinition } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 import { bodyOf } from "../core/frontmatter.js";
 import { connectionFromEnv, socketCall, terminalCall } from "./client.js";
@@ -12,8 +12,11 @@ import { SPAWN_SUBAGENT, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, sub
 import { PLAN_RESEARCH_TOOLS } from "../agents/planResearch.js";
 import { askUserTool } from "../tools/askUser.js";
 import { TODO_WRITE, todoTool } from "../tools/todo.js";
-import { CHECKPOINT_WRITE, checkpointTool } from "../tools/checkpoint.js";
-import { createSliceState, parseWorkSlice, workSliceGuard } from "../sessions/workSlice.js";
+import { createStopGateState, handoffFields, sessionCheckModel, stopCheckpointReason, stopGate, stopGateNotice, stopOutcome, stopSummary, STOP_GATE_EXTENSION } from "../sessions/stopGate.js";
+import { launchSwitchOff } from "../sessions/completionCheck.js";
+import { GOAL_STATE_ENTRY, GOAL_TOOLS, goalTools } from "../sessions/goal.js";
+import { GOAL_EXTENSION, goalLoop, goalNotice } from "../sessions/goalLoop.js";
+import { createSliceState, DEFAULT_SLICE_POLICY, parseWorkSlice, sliceContinuation, workSliceGuard } from "../sessions/workSlice.js";
 import { DEFAULT_COMMAND_TIMEOUT_SECONDS, withCommandBudget } from "../core/commandBudget.js";
 import { SESSION_NAME, deriveSessionName, sessionNameTool } from "../tools/sessionName.js";
 import { CAPABILITY_DISCOVERY, describeCapabilities } from "../tools/getCapabilities.js";
@@ -26,7 +29,7 @@ import { skillInvocations } from "./tui/skillInvocation.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 { createWorkspaceFileTools } from "../core/workspaceWriteOperations.js";
 import { BUDGET_GUARD, OUTPUT_TRIM, budgetGuard, outputTrim } from "../plugins/firstParty.js";
 /** How long reply text gathers before it is sent on to a paired phone. */
 const STREAM_FLUSH_MS = 150;
@@ -49,7 +52,7 @@ async function withParentCancellation(signal, work) {
         signal?.removeEventListener('abort', stop);
     }
 }
-export default async function (pi, planRun, getSession) {
+export default async function (pi, planRun, getSession, goal) {
     await terminalCall('startup', { phase: 'Pi extension loaded' });
     let context = null;
     let nativeSubagents = false;
@@ -156,8 +159,9 @@ export default async function (pi, planRun, getSession) {
         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));
+    const nativeFileTools = createWorkspaceFileTools({ createWriteTool, createWriteToolDefinition, createEditTool, createEditToolDefinition }, process.cwd(), writeAuthorizations);
+    pi.registerTool(nativeFileTools.write);
+    pi.registerTool(nativeFileTools.edit);
     // The current name and this run's todo ride with each request; they never change the stable prefix.
     pi.on('context', (event) => {
         if (!sessionState || stateDelivered)
@@ -174,16 +178,64 @@ export default async function (pi, planRun, getSession) {
         };
     });
     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);
+    // A terminal reply is bounded like any other (PROP-0041): a checkpoint at each boundary, and the
+    // reply continues in place up to the policy's slice cap (ADR-0070) before the person decides.
+    let slicePolicy;
+    try {
+        slicePolicy = parseWorkSlice(undefined);
+    }
+    catch (error) {
+        slicePolicy = { ...DEFAULT_SLICE_POLICY };
+        console.error(`${error instanceof Error ? error.message : String(error)} Using the default work slices.`);
+    }
     const sliceState = createSliceState(slicePolicy);
     // `XINGULAR_WORK_SLICE=off` at launch leaves terminal replies unbounded, as before PROP-0041.
+    // One stop-gate state per terminal session; each reply resets it.
+    const gateState = createStopGateState();
+    // A goal-claim check's model request counts with the reply's usage, like any other request.
+    const recordCheckUsage = (raw) => {
+        const message = raw;
+        const reported = message.usage;
+        if (!reported)
+            return;
+        usage.inputTokens += reported.input ?? 0;
+        usage.outputTokens += reported.output ?? 0;
+        usage.cacheReadTokens += reported.cacheRead ?? 0;
+        usage.cacheWriteTokens += reported.cacheWrite ?? 0;
+        usage.requests += 1;
+        if (typeof reported.reasoning === 'number')
+            reasoningTokens = (reasoningTokens ?? 0) + reported.reasoning;
+        const cost = reported.cost?.total;
+        if (typeof cost === 'number') {
+            usage.costUsd += cost;
+            costReported = true;
+        }
+        const identity = { model: message.model, provider: message.provider };
+        const { costUsd, ...tokens } = usage;
+        void terminalCall('usage', {
+            ...tokens,
+            ...(costReported ? { costUsd, costSource: 'harness' } : {}),
+            ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
+            ...identity,
+            request: {
+                index: usage.requests,
+                ...identity,
+                responseId: message.responseId,
+                inputTokens: reported.input ?? 0,
+                cacheReadTokens: reported.cacheRead ?? 0,
+                cacheWriteTokens: reported.cacheWrite ?? 0,
+                outputTokens: reported.output ?? 0,
+                ...(typeof reported.reasoning === 'number' ? { reasoningTokens: reported.reasoning } : {}),
+                ...(typeof cost === 'number' ? { costUsd: cost, costSource: 'harness' } : {}),
+                ...(typeof message.durationMs === 'number' ? { durationMs: message.durationMs } : {}),
+                stopReason: message.stopReason
+            }
+        }).catch(() => undefined);
+    };
     if (slicePolicy.enabled)
         workSliceGuard({
             policy: slicePolicy,
             state: sliceState,
-            checkpointAvailable: () => !planRun?.active || planRun.allowedTools.has(CHECKPOINT_WRITE),
             onRefuse: (event, reason) => { pendingRefusals.push(terminalCall('refusal', { toolCallId: event.toolCallId, name: event.toolName, code: 'work_slice', reason: reason.slice(0, 2_000) }).catch(() => { })); }
         })(pi);
     // Only the latest screenshots stay in what the model sees (world/images.ts).
@@ -438,6 +490,89 @@ export default async function (pi, planRun, getSession) {
             continue: true
         };
     });
+    // The stop gate (ADR-0069), after subagent delivery and plan repair so it sees their
+    // continuations: a terminal reply that ends with open todo items is sent back up to its cap.
+    // Plan replies are not gated.
+    if (!launchSwitchOff('XINGULAR_STOP_GATE'))
+        stopGate({
+            state: gateState,
+            active: () => !planRun?.active,
+            sliceEnded: () => sliceState.endedBy !== null,
+            failed: () => Boolean(failure),
+            onEvent: (event) => {
+                void terminalCall('notice', { kind: 'notify', level: 'info', extension: STOP_GATE_EXTENSION, text: stopGateNotice(event) }).catch(() => undefined);
+            }
+        })(pi);
+    // A /goal (ADR-0072): while one is active, a reply that would end continues in place. After the
+    // stop gate, so open todo items are nudged first; its claim check is the only completion check.
+    if (goal) {
+        for (const spec of goalTools(() => goal))
+            pi.registerTool({
+                name: spec.name,
+                label: spec.label,
+                description: spec.description,
+                parameters: spec.parameters(Type),
+                async execute(_id, input) {
+                    const result = await spec.execute(input);
+                    return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
+                }
+            });
+        // The goal's tools are offered to the model only while a goal exists.
+        const syncGoalTools = (state) => {
+            const active = pi.getActiveTools();
+            const wanted = state !== null && state.status !== 'complete';
+            const has = GOAL_TOOLS.some((name) => active.includes(name));
+            if (wanted && !GOAL_TOOLS.every((name) => active.includes(name)))
+                pi.setActiveTools([...active, ...GOAL_TOOLS.filter((name) => !active.includes(name))]);
+            else if (!wanted && has)
+                pi.setActiveTools(active.filter((name) => !GOAL_TOOLS.includes(name)));
+        };
+        const unsubscribe = goal.subscribe((state) => {
+            try {
+                pi.appendEntry(GOAL_STATE_ENTRY, { goal: state });
+                syncGoalTools(state);
+            }
+            catch {
+                // The session is closing; the next one restores from its own branch.
+            }
+        });
+        pi.on('session_shutdown', () => { unsubscribe(); });
+        pi.on('session_start', (_event, ctx) => {
+            // A goal is restored from the branch, and waits for the person: nothing resumes by itself.
+            const entries = (ctx.sessionManager.getBranch?.() ?? []);
+            const saved = [...entries].reverse().find((entry) => entry.type === 'custom' && entry.customType === GOAL_STATE_ENTRY)?.data?.goal ?? null;
+            goal.restore(saved && (saved.status === 'active') ? { ...saved, status: 'paused', claimed: false } : saved);
+            syncGoalTools(goal.get());
+        });
+        goalLoop({
+            controller: goal,
+            check: launchSwitchOff('XINGULAR_COMPLETION_CHECK') ? null : sessionCheckModel,
+            active: () => !planRun?.active,
+            sliceEnded: () => sliceState.endedBy !== null,
+            failed: () => Boolean(failure),
+            recordUsage: recordCheckUsage,
+            onEvent: (event) => {
+                void terminalCall('notice', { kind: 'notify', level: 'info', extension: GOAL_EXTENSION, text: goalNotice(event) }).catch(() => undefined);
+            }
+        })(pi);
+    }
+    // After the stop gate, which stays silent at a slice boundary: a reply that did work and reached
+    // its budget continues as the next slice of the same run (ADR-0070).
+    if (slicePolicy.enabled)
+        sliceContinuation({
+            policy: slicePolicy,
+            state: sliceState,
+            active: () => !planRun?.active,
+            failed: () => Boolean(failure),
+            blocked: () => goal?.get()?.status === 'blocked',
+            goalActive: () => goal?.active() === true,
+            todo: () => gateState.todo,
+            next: () => handoffFields(gateState, goal?.get() ?? null).next,
+            onContinue: (ended) => {
+                void terminalCall('checkpoint', { summary: `Work slice ${ended.slice} reached its limit after ${ended.steps} steps; the reply continues.`, ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: ended.slice, reason: 'budget' }).catch(() => undefined);
+                void terminalCall('notice', { kind: 'notify', level: 'info', extension: STOP_GATE_EXTENSION, text: `Work slice ${ended.slice} reached ${ended.limit ?? 'its limit'}; continuing with slice ${ended.slice + 1} of up to ${slicePolicy.maxSlices}.` }).catch(() => undefined);
+            }
+        })(pi);
     // Reply text as it streams, batched, for a paired phone (remote control). The completed message
     // carries the same id and replaces whatever streamed.
     let streamId = null;
@@ -642,9 +777,20 @@ export default async function (pi, planRun, getSession) {
         subagentParent = false;
         // 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 ? 'slice_complete' : undefined;
-        const code = sliceState.endedBy === 'compaction-thrash' ? 'compaction_thrash' : sliceState.endedBy === 'budget' ? 'slice_budget' : undefined;
-        await terminalCall('settled', { error: failure, ...(failureCode ? { errorCode: failureCode } : {}), aborted: event.aborted || messageAborted, ...(reason ? { reason } : {}), ...(code ? { code } : {}) });
+        // A reply that ended with open todo items is not completed either (ADR-0069): it stopped for the
+        // person, or the stop gate's nudges ran out. The harness writes its checkpoint from the todo list.
+        const aborted = event.aborted || messageAborted;
+        const stop = !sliceState.endedBy && !failure && !aborted && !planRun?.active ? stopOutcome(gateState, goal?.get() ?? null) : null;
+        if (stop) {
+            await terminalCall('checkpoint', { summary: stopSummary(stop), ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: stopCheckpointReason(stop) }).catch(() => undefined);
+        }
+        else if (sliceState.endedBy && !failure && !aborted) {
+            // The guard ended the reply and promised the model the harness would keep its state.
+            await terminalCall('checkpoint', { summary: `The reply stopped after ${sliceState.steps} steps at its work-slice boundary.`, ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: sliceState.endedBy }).catch(() => undefined);
+        }
+        const reason = sliceState.endedBy ? 'slice_complete' : stop?.code;
+        const code = sliceState.endedBy === 'compaction-thrash' ? 'compaction_thrash' : sliceState.endedBy === 'budget' ? 'slice_budget' : stop?.code;
+        await terminalCall('settled', { error: failure, ...(failureCode ? { errorCode: failureCode } : {}), aborted, ...(reason ? { reason } : {}), ...(code ? { code } : {}) });
         turnActive = false;
     });
     pi.on('user_bash', async () => {
@@ -695,19 +841,6 @@ export default async function (pi, planRun, getSession) {
             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,

package/dist/sdk/terminal/terminals.js

@@ -28,6 +28,7 @@ import { isActiveStatus } from "../sessions/contracts.js";
 import { findRun, listRuns, loadRun, readEvents, recordedSubagents, saveRun, updateRun } from "../sessions/runStore.js";
 import { combineWorkspaceScope, inspectRunWorkspaceWrite } from "../sessions/workspaceBoundary.js";
 import { TODO_WRITE } from "../tools/todo.js";
+import { GOAL_TOOLS } from "../sessions/goal.js";
 import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
 import { harnessTools } from "../tools/harnessTools.js";
 import { HARNESS_PLUGINS } from "../plugins/builtin.js";
@@ -431,6 +432,24 @@ export class Terminals {
                 return accounts.overview();
             case 'accounts.session':
                 return { accountId: live.account.id, label: live.account.label };
+            // The terminal's Pi keeps no credential file: it reads and writes its own account's credentials
+            // here, under the store's cross-process lock, never an account the caller names.
+            case 'accounts.credentials.read':
+                return { credential: (await accounts.readCredential(live.account.id, text('provider'))) ?? null };
+            case 'accounts.credentials.list':
+                return { credentials: await accounts.listCredentials(live.account.id) };
+            case 'accounts.credentials.lease': {
+                const lease = await accounts.leaseCredential(live.account.id, text('provider'));
+                return { leaseId: lease.leaseId, current: lease.current ?? null };
+            }
+            case 'accounts.credentials.commit': {
+                const credential = params.credential && typeof params.credential === 'object' ? params.credential : undefined;
+                return { credential: (await accounts.commitCredentialLease(live.account.id, text('leaseId'), credential)) ?? null };
+            }
+            case 'accounts.credentials.delete':
+                await accounts.writeCredential(live.account.id, text('provider'), null);
+                accounts.invalidate(live.account.id);
+                return {};
             case 'accounts.create':
                 return accounts.create(text('label'), optional('authKind') ?? 'subscription');
             case 'accounts.rename':
@@ -862,7 +881,7 @@ export class Terminals {
         }
         if (inspection.outside)
             return { allowed: false, requiresApproval: true, rememberable: false, standing: 'switch', reason: inspection.reason, workspaceRoot };
-        if (name === SESSION_NAME || name === TODO_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)) {
+        if (name === SESSION_NAME || name === TODO_WRITE || GOAL_TOOLS.includes(name) || 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 };
@@ -1006,8 +1025,12 @@ export class Terminals {
             await service.verify(run.runId, params.history);
             return {};
         }
-        if (call === 'terminal.subagents.delivery')
-            return service.delivery(run.runId, params.history, params.settle === true);
+        if (call === 'terminal.subagents.delivery') {
+            // Waiting for children to settle ends when the parent is interrupted, a stall included.
+            const stop = new AbortController();
+            run.onInterrupt(() => stop.abort());
+            return service.delivery(run.runId, params.history, params.settle === true, stop.signal);
+        }
         if (call === 'terminal.subagents.call') {
             const tool = subagentTools(service, run.runId).find(tool => tool.name === params.name);
             if (!tool)
@@ -1221,7 +1244,7 @@ export class Terminals {
                     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 }),
-                    interrupt: runId => this.options.runs.interrupt(runId),
+                    interrupt: (runId, stop) => this.options.runs.interrupt(runId, stop),
                     resolveApproval: (runId, id, decision) => this.options.runs.resolveApproval(runId, id, decision),
                     answerQuestion: (runId, id, answer) => this.options.runs.answerQuestion(runId, id, answer),
                     answerQuestions: (runId, batchId, answers) => this.options.runs.answerQuestions(runId, batchId, answers)

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

@@ -25,6 +25,8 @@ export interface TerminalCommandHost {
     todo(): Promise<readonly TodoEntry[]>;
     showTodo(items: readonly TodoEntry[]): void;
     plan(brief: string): void;
+    /** Runs `/goal` and returns the text to show (ADR-0072). */
+    goal(argument: string): Promise<string>;
     /** Asks a side question in its own tool-free session; empty text dismisses the one showing. */
     btw(question: string): Promise<void>;
     shutdown(): void;

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

@@ -227,6 +227,9 @@ export function createTerminalCommands(host) {
                     host.plan(argument);
                     break;
                 }
+                case 'goal':
+                    host.ui.notify(await host.goal(argument), 'info');
+                    break;
                 case 'quit':
                     host.shutdown();
                     break;

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

@@ -0,0 +1,19 @@
+import { GOAL_CUSTOM_TYPE, type GoalController } from "../../sessions/goal.js";
+export interface GoalCommandDeps {
+    controller: GoalController;
+    /** True when no reply is running. */
+    idle(): boolean;
+    /** Sends a hidden message and starts a reply with it. */
+    start(content: string): Promise<void>;
+    /** Sends a hidden message into the running reply. */
+    steer(content: string): Promise<void>;
+    /** Records a hidden message without starting a reply. */
+    note(content: string): Promise<void>;
+    /** Stops the running reply. */
+    interrupt(): Promise<void>;
+    confirm(title: string, message: string): Promise<boolean>;
+    input(title: string, value: string): Promise<string | undefined>;
+}
+export { GOAL_CUSTOM_TYPE };
+/** Runs one `/goal` and returns the text to show the person. */
+export declare function runGoalCommand(argument: string, deps: GoalCommandDeps): Promise<string>;

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

@@ -0,0 +1,83 @@
+// `/goal` in the terminal (ADR-0072): set, view, edit, pause, resume and clear a goal. Adapted from
+// OpenAI Codex (Apache-2.0; see NOTICE.md): codex-rs/tui/src/chatwidget/slash_dispatch.rs and
+// goal_menu.rs. The model never creates a goal: the person does, here.
+import { GOAL_CUSTOM_TYPE, GoalError, continuationPrompt, goalSummary, objectiveUpdatedPrompt, parseGoalCommand, provenanceText } from "../../sessions/goal.js";
+export { GOAL_CUSTOM_TYPE };
+/** Runs one `/goal` and returns the text to show the person. */
+export async function runGoalCommand(argument, deps) {
+    const { controller } = deps;
+    const command = parseGoalCommand(argument);
+    try {
+        switch (command.kind) {
+            case 'error': return command.message;
+            case 'show': return goalSummary(controller.get());
+            case 'set': {
+                const existing = controller.get();
+                if (existing && existing.status !== 'complete') {
+                    const replace = await deps.confirm('Replace goal?', `The current goal is not finished:\n${existing.objective}\n\nReplace it with the new one and start it now?`);
+                    if (!replace)
+                        return 'Kept the current goal.';
+                }
+                // A reply that is running stops first: the new goal starts from a clean boundary.
+                if (!deps.idle())
+                    await deps.interrupt();
+                const goal = controller.set(command.objective, command.limits);
+                await deps.start(`${provenanceText('set', goal)}\n\n${continuationPrompt(goal)}`);
+                return `Goal active\nObjective: ${goal.objective}`;
+            }
+            case 'edit': {
+                const existing = controller.get();
+                if (!existing)
+                    return 'No goal to edit. Use /goal <objective>.';
+                const objective = command.objective ?? await deps.input('Edit goal', existing.objective);
+                if (!objective?.trim())
+                    return 'Goal unchanged.';
+                const goal = controller.edit(objective);
+                const content = `${provenanceText('edited', goal)}\n\n${objectiveUpdatedPrompt(goal)}`;
+                if (deps.idle())
+                    await deps.start(`${provenanceText('edited', goal)}\n\n${continuationPrompt(goal)}`);
+                else
+                    await deps.steer(content);
+                return `Goal updated\nObjective: ${goal.objective}`;
+            }
+            case 'pause': {
+                const goal = controller.get();
+                if (!goal)
+                    return 'No goal to pause.';
+                if (!deps.idle())
+                    await deps.interrupt();
+                const paused = controller.pause();
+                await deps.note(provenanceText('paused', paused));
+                return `Goal ${paused?.status === 'paused' ? 'paused' : `is ${paused?.status.replace('_', ' ')}`}. Use /goal resume to continue.`;
+            }
+            case 'resume': {
+                const goal = controller.get();
+                if (!goal)
+                    return 'No goal to resume.';
+                if (goal.status === 'complete')
+                    return 'The goal is complete. Set a new one with /goal <objective>.';
+                const resumed = controller.resume();
+                const content = `${provenanceText('resumed', resumed)}\n\n${continuationPrompt(resumed)}`;
+                if (deps.idle())
+                    await deps.start(content);
+                else
+                    await deps.steer(content);
+                return 'Goal active';
+            }
+            case 'clear': {
+                if (!controller.get())
+                    return 'No goal to clear.';
+                if (!deps.idle() && controller.active())
+                    await deps.interrupt();
+                controller.clear();
+                await deps.note(provenanceText('cleared', null));
+                return 'Goal cleared';
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof GoalError)
+            return error.message;
+        throw error;
+    }
+}

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

@@ -1,2 +1,2 @@
-export { normalModeTools, parseProposedPlan, planModeTools, QUESTION_TOOL_NAMES } from "../../sessions/planMode.js";
+export { normalModeTools, normalToolsForBranch, parseProposedPlan, planModeTools, PLAN_TOOLS_ENTRY, QUESTION_TOOL_NAMES } from "../../sessions/planMode.js";
 export type { ProposedPlan } from "../../sessions/planMode.js";

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

@@ -1,2 +1,2 @@
 // The terminal's plan mode uses the session's read-only tool set.
-export { normalModeTools, parseProposedPlan, planModeTools, QUESTION_TOOL_NAMES } from "../../sessions/planMode.js";
+export { normalModeTools, normalToolsForBranch, parseProposedPlan, planModeTools, PLAN_TOOLS_ENTRY, QUESTION_TOOL_NAMES } from "../../sessions/planMode.js";

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

@@ -1,4 +1,5 @@
 import { type AgentSession, type AgentSessionEventListener, type AgentSessionRuntime, type AgentSessionServices, type ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import { GoalController } from "../../sessions/goal.js";
 import type { SessionAccount } from "../accountsMenu.js";
 import type { QuestionAnswer } from "../../sessions/registry.js";
 import type { TerminalQuestion } from "./questions.js";
@@ -104,6 +105,8 @@ export interface TerminalRuntime {
     installationDeviceId(): Promise<string>;
     reload(): Promise<void>;
     interrupt(): Promise<void>;
+    /** This session's /goal (ADR-0072). */
+    readonly goal: GoalController;
     dispose(): Promise<void>;
 }
 /** Saved native history stays in the prepared project folder, including symlink targets. */

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

@@ -2,7 +2,9 @@ import { createAgentSession, createAgentSessionRuntime, DefaultResourceLoader, M
 import { closeSync, existsSync, openSync, readSync, realpathSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import terminalExtension from "../piExtension.js";
-import { normalModeTools, planModeTools, QUESTION_TOOL_NAMES } from "./planMode.js";
+import { GoalController } from "../../sessions/goal.js";
+import { terminalCredentialStore } from "../credentialStore.js";
+import { normalModeTools, normalToolsForBranch, planModeTools, PLAN_TOOLS_ENTRY, QUESTION_TOOL_NAMES } from "./planMode.js";
 import { claimTerminalControl, controlCall } from "../control.js";
 import { observeProviderResponses } from "../../usage/limits/capture.js";
 import { limitHeaders } from "../../usage/limits/normalize.js";
@@ -126,7 +128,8 @@ export async function createTerminalRuntime(args, host) {
     const account = identity && typeof identity.accountId === 'string' && typeof identity.label === 'string'
         ? Object.freeze({ accountId: identity.accountId, label: identity.label }) : null;
     await loadPiAdapter();
-    const modelRuntime = await ModelRuntime.create({ authPath: join(agentDir, 'auth.json'), modelsPath: join(agentDir, 'models.json') });
+    // Credentials live in the host's store, read and refreshed under its lock (`terminalCredentialStore`).
+    const modelRuntime = await ModelRuntime.create({ credentials: terminalCredentialStore(), modelsPath: join(agentDir, 'models.json') });
     // This process makes the model requests, so it is where response headers are seen. Only the
     // limit-bearing headers cross the socket, and the parent throttles what it stores.
     observeProviderResponses(modelRuntime, (provider, response) => {
@@ -157,6 +160,7 @@ export async function createTerminalRuntime(args, host) {
         return sessionUiContext(host.ui, () => !disposed && generation === uiGeneration);
     };
     const planRun = { active: false, allowedTools: new Set() };
+    const goal = new GoalController();
     let currentMode = 'normal';
     let pendingApply = false;
     const choiceStore = {
@@ -179,6 +183,11 @@ export async function createTerminalRuntime(args, host) {
             ?? session.settingsManager.getDefaultThinkingLevel() ?? 'medium');
     };
     const applyMode = () => modeChoices.apply(native.session, currentMode, modelFor, defaultEffort(native.session));
+    // Pi rebuilds the active tools from the transcript, where the last recorded set may be a plan's.
+    const restoreNormalTools = (session) => {
+        const recorded = normalToolsForBranch(session.sessionManager.getBranch());
+        session.setActiveToolsByName(normalModeTools(recorded ?? session.getActiveToolNames()));
+    };
     const restoreChoice = async (session, previous) => {
         if (previous.model && (session.model?.provider !== previous.model.provider || session.model?.id !== previous.model.id)) {
             await session.setModel(previous.model, { persist: false }).catch(() => undefined);
@@ -216,7 +225,7 @@ export async function createTerminalRuntime(args, host) {
             additionalSkillPaths: prepared.skills, additionalPromptTemplatePaths: prepared.prompts,
             additionalThemePaths: prepared.themes,
             extensionFactories: [
-                { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun, () => native.session), hidden: true },
+                { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun, () => native.session, goal), hidden: true },
                 // A model picked in the terminal reaches Pi as this event. A restore is not a pick.
                 { name: 'harness-mode-choices', factory: pi => { pi.on('model_select', event => { if (event.source !== 'restore')
                         void modeChoices.record(recordingMode(), { model: `${event.model.provider}/${event.model.id}` }); }); }, hidden: true },
@@ -275,7 +284,7 @@ export async function createTerminalRuntime(args, host) {
             ...(thinkingLevel ? { thinkingLevel } : {})
         });
         installPluginCommandRouter(created.session, resourceOwners, barePrompts);
-        created.session.setActiveToolsByName(normalModeTools(created.session.getActiveToolNames()));
+        restoreNormalTools(created.session);
         const services = { cwd, agentDir, modelRuntime, settingsManager, resourceLoader, diagnostics: [] };
         host.resources?.(services);
         return { ...created, services, diagnostics: services.diagnostics };
@@ -382,6 +391,7 @@ export async function createTerminalRuntime(args, host) {
             planRun.allowedTools = new Set(allowedTools);
             planRun.active = true;
             try {
+                session.sessionManager.appendCustomEntry(PLAN_TOOLS_ENTRY, { phase: 'begin', normal: originalTools });
                 session.setActiveToolsByName(allowedTools);
                 await modeChoices.apply(session, 'plan', modelFor, defaultEffort(session));
                 await session.prompt(text, { expandPromptTemplates: false, ...(images?.length ? { images } : {}) });
@@ -391,6 +401,7 @@ export async function createTerminalRuntime(args, host) {
                 planRun.allowedTools = new Set();
                 if (!disposed && native.session === session) {
                     session.setActiveToolsByName(originalTools);
+                    session.sessionManager.appendCustomEntry(PLAN_TOOLS_ENTRY, { phase: 'end' });
                     await modeChoices.quietly(() => restoreChoice(session, previous));
                     if (pendingApply) {
                         pendingApply = false;
@@ -429,6 +440,8 @@ export async function createTerminalRuntime(args, host) {
         fork: (entryId, options) => exclusive(() => native.fork(entryId, options)),
         navigateTree: (targetId, options) => exclusive(async () => {
             const result = await native.session.navigateTree(targetId, options);
+            if (!result.cancelled && !planRun.active)
+                restoreNormalTools(native.session);
             if (!result.cancelled)
                 await announce();
             return result;
@@ -451,7 +464,11 @@ export async function createTerminalRuntime(args, host) {
                 } });
             host.changed();
         }),
+        goal,
         async interrupt() {
+            // The person stopping a running goal pauses it, as in Codex; /goal resume continues.
+            if (goal.active() && !native.session.isIdle)
+                goal.pause();
             // Bash executions use their own abort controllers, outside Pi's agent tool loop.
             native.session.abortBash();
             // Socket-backed questions and approvals must settle before Pi can finish aborting tools.

package/dist/sdk/tools/askUser.js

@@ -19,7 +19,7 @@ export function askUserTool(run) {
         name: ASK_USER,
         label: 'Ask the user',
         description: 'Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 1–2 word label and aim to keep each question to 25 words or fewer. ' +
-            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. When a UI diagram helps compare choices, set uiSketch: true and give every choice a detailed, bounded ASCII wireframe. Use ASCII tables and panel borders to show the affected element with relevant neighboring UI, 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. Do not substitute a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels. Use it when you need a decision, not for small talk.',
+            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. When a UI diagram helps compare choices, set uiSketch: true and give every choice a detailed, bounded ASCII wireframe. Use ASCII tables and panel borders to show the affected element with relevant neighboring UI, 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. Do not substitute a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels. Use it when you need a decision the request and the files do not answer, not for small talk and never to ask permission for work inside the request. If no answer arrives, continue with your best judgment instead of asking again or treating the turn as blocked.',
         parameters: (Type) => Type.Object({
             questions: Type.Array(Type.Object({
                 summary: Type.String({ description: 'A concise label of one or two words' }),