@xingular/harness 1.0.0 → 1.2.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,14 +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, createWriteTool } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 import { connectionFromEnv, socketCall, terminalCall } from "./client.js";
-import { runAccountsMenu } from "./accountsMenu.js";
-import { runPluginsMenu } from "./pluginMenu.js";
-import { runHubMenu } from "./hubMenu.js";
-import { claimTerminalControl, controlCall } from "./control.js";
-import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory } from "../sessions/subagents.js";
+import { controlCall } from "./control.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 { 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 { withWorkspaceWriteScope } 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;
@@ -28,8 +43,6 @@ async function withParentCancellation(signal, work) {
         signal?.removeEventListener('abort', stop);
     }
 }
-/** /hub, /plugins and /accounts are pages: the owned terminal fills the screen, and Pi's own dialogs ignore the field. */
-const PAGE = { page: true };
 export default async function (pi, planRun, getSession) {
     await terminalCall('startup', { phase: 'Pi extension loaded' });
     let context = null;
@@ -45,50 +58,13 @@ 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 {
         await terminalCall('startup', { phase: stage });
         const connection = connectionFromEnv();
-        // Claimed here, before the model has run anything, and kept in this process's memory: a
-        // command the model runs can read the session token from its environment, never this key.
-        const control = await claimTerminalControl(connection).catch(() => null);
-        pi.registerCommand('hub', {
-            description: 'Browse and install reviewed skills, plugins, and reusable documents',
-            handler: async (_args, ctx) => {
-                if (!control)
-                    return ctx.ui.notify('This session cannot install hub items.', 'warning');
-                await runHubMenu({ select: (title, options) => ctx.ui.select(title, options, PAGE), confirm: (title, message) => ctx.ui.confirm(title, message), notify: (message, level) => ctx.ui.notify(message, level) }, (method, params) => socketCall(connection, method, params ?? {}, 300_000, control));
-            }
-        });
-        pi.registerCommand('plugins', {
-            description: 'See what this session loads, and switch a plugin on or off or trust its code',
-            handler: async (_args, ctx) => {
-                if (!control)
-                    return ctx.ui.notify('This session cannot change plugins.', 'warning');
-                const { projectId } = await socketCall(connection, 'plugins.session', {}, 15_000, control).catch(() => ({ projectId: null }));
-                await runPluginsMenu({ select: (title, options) => ctx.ui.select(title, options, PAGE), confirm: (title, message) => ctx.ui.confirm(title, message), notify: (message, level) => ctx.ui.notify(message, level) }, (method, params) => socketCall(connection, method, params ?? {}, 60_000, control), projectId);
-            }
-        });
-        pi.registerCommand('accounts', {
-            description: 'Add, sign in to, check, switch, or remove the Pi accounts this harness uses',
-            handler: async (_args, ctx) => {
-                if (!control)
-                    return ctx.ui.notify('This session cannot manage accounts.', 'warning');
-                const session = await socketCall(connection, 'accounts.session', {}, 15_000, control).catch(() => null);
-                if (!session)
-                    return ctx.ui.notify('This session has no account to manage.', 'warning');
-                const outcome = await runAccountsMenu({
-                    select: (title, options) => ctx.ui.select(title, options, PAGE),
-                    confirm: (title, message) => ctx.ui.confirm(title, message),
-                    input: (title, placeholder) => ctx.ui.input(title, placeholder),
-                    notify: (message, level) => ctx.ui.notify(message, level)
-                }, (method, params) => socketCall(connection, method, params ?? {}, 120_000, control), session);
-                // The session restarts on the account it chose: Pi ends here, and the launcher starts it again.
-                if (outcome === 'relaunch')
-                    ctx.shutdown();
-            }
-        });
         const { tools } = await socketCall(connection, 'tools.list', {}, 15_000);
         stage = 'Tool registration';
         for (const tool of tools) {
@@ -104,8 +80,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),
@@ -119,6 +106,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(withWorkspaceWriteScope(createBashTool(process.cwd(), { operations: 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 })(pi);
     // Only the latest screenshots stay in what the model sees (world/images.ts).
     pi.on('context', (event) => {
         const messages = pruneToolImages(event.messages);
@@ -162,9 +189,14 @@ export default async function (pi, planRun, getSession) {
         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 : '' });
+        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.');
         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;
             subagentParent = true;
         }
         if (planRun && event.messageType === 'user') {
@@ -172,24 +204,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.';
                 }
@@ -201,7 +240,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) {
@@ -282,21 +321,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);
@@ -329,7 +408,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.');
@@ -355,6 +437,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.
+    let recorded = Promise.resolve();
+    const checklist = checklistTool({ emit: (_type, payload) => { recorded = terminalCall('checklist', payload); } });
+    pi.registerTool({
+        name: checklist.name, label: checklist.label, description: checklist.description,
+        parameters: Type.Unsafe(checklist.parameters(Type)),
+        async execute(_id, input) {
+            recorded = Promise.resolve();
+            const result = await checklist.execute(input);
+            await recorded;
+            return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
+        }
+    });
+    // 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,
@@ -364,29 +472,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. 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.',
-        parameters: Type.Object({
-            question: Type.String(),
-            options: Type.Array(Type.Object({ label: Type.String(), description: Type.Optional(Type.String()), recommended: Type.Optional(Type.Boolean()) }), {
-                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 answer = await terminalCall('question', { requestId: id, ...input });
-            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/socket.d.ts

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

package/dist/sdk/terminal/socket.js

@@ -5,8 +5,8 @@
 // reply leaves it open for the next request. Each terminal session holds a random token bound to
 // its caller, its connected-apps grant, and its controller; the token stops working when the
 // terminal ends.
-import { createHash, randomBytes } from 'node:crypto';
-import { chmodSync, mkdirSync, rmSync, statSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -17,21 +17,50 @@ const MAX_REQUEST_BYTES = 1024 * 1024;
 /** macOS refuses a socket path longer than 103 bytes. */
 const MAX_SOCKET_PATH = 100;
 /**
- * Windows has no socket files for Node's `net`: it listens on a named pipe, which lives in a
- * machine-wide namespace. A random name keeps another local process from guessing it and standing
- * in front of the session; the token still decides what a caller may do.
+ * Each Harness process listens on its own path. Windows has no socket files for Node's `net`: it
+ * listens on a named pipe in a machine-wide namespace, and a random name keeps another local process
+ * from guessing it. On Unix the file is named for this process, because several Harness processes
+ * may share one state folder: closing a server removes its socket file, so a shared name would let
+ * one process delete, and the next one take over, the path another's sessions still call. The token
+ * still decides what a caller may do.
  */
 export function socketPath(stateDir) {
     if (process.platform === 'win32')
         return `\\\\.\\pipe\\xingular-harness-${randomBytes(12).toString('hex')}`;
-    const path = join(stateDir, 'run', 'harness.sock');
+    const path = join(stateDir, 'run', `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
     if (Buffer.byteLength(path) <= MAX_SOCKET_PATH)
         return path;
-    return join(tmpdir(), `xh-${createHash('sha256').update(path).digest('hex').slice(0, 16)}.sock`);
+    return join(tmpdir(), `xh-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+}
+const OWN_SOCKET = /^harness-(\d+)-[0-9a-f]+\.sock$/;
+/** Removes socket files left in `folder` by Harness processes that are no longer running. */
+function pruneDeadSockets(folder) {
+    let names;
+    try {
+        names = readdirSync(folder);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const pid = Number(OWN_SOCKET.exec(name)?.[1]);
+        if (!pid || pid === process.pid || isRunning(pid))
+            continue;
+        rmSync(join(folder, name), { force: true });
+    }
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
 }
 function alternateSocketPath(path) {
     const candidate = join(dirname(path), `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
-    return Buffer.byteLength(candidate) <= MAX_SOCKET_PATH ? candidate : join(tmpdir(), `xh-${randomBytes(16).toString('hex')}.sock`);
+    return Buffer.byteLength(candidate) <= MAX_SOCKET_PATH ? candidate : join(tmpdir(), `xh-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
 }
 /** A named pipe has no folder, file mode, or owner to check or clean up. */
 const isPipePath = (path) => path.startsWith('\\\\.\\pipe\\');
@@ -216,8 +245,10 @@ export class SessionSocket {
     }
     /** Binds the usual path, or an instance-specific path if another Harness owns it. */
     async bindAvailablePath() {
-        if (!isPipePath(this.path))
+        if (!isPipePath(this.path)) {
             mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            pruneDeadSockets(dirname(this.path));
+        }
         try {
             await this.bind(this.path);
         }

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

@@ -1,8 +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;
@@ -11,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;