@henryqw/pi-subagent 26.1.2 → 26.1.3

package/CONTEXT.md

@@ -41,7 +41,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 
 ### Direct evidence
 
-- Direct mode admits declared write-capable resources for explicitly authorized scope while preserving read-only Role restrictions. Potential-writer requests serialize tasks and retain Pi checkout admission through exact completion; uncertain outcomes retain admission for manual recovery. Potential-writer answers require an explicit structured `succeeded` outcome; failed, blocked, or malformed completion stops dispatch and retains admission. This is a worker report, not proof of validation, cleanliness, rollback, or checked integration. Direct changesets require isolated mode.
+- Direct mode admits declared write-capable resources for explicitly authorized scope while preserving read-only Role restrictions. Potential-writer requests serialize tasks and retain Pi checkout admission until exact owned worker termination is proved by pane absence and two empty private process-lease scans; uncertain termination retains admission and live recovery ownership. Potential-writer answers require an explicit structured `succeeded` outcome; failed, blocked, or malformed completion stops dispatch but does not prevent release after proved termination. `/subagent` Close/cancel-and-release retries termination under session, branch, epoch and exact ownership guards without replaying work or removing checkout/session evidence. This is a worker report, not proof of validation, cleanliness, rollback, or checked integration. Direct changesets require isolated mode.
 - Checkout admission in Main serializes write-capable Pi tool calls per checkout by their model-issued root call: a `codemode` script's nested writes share the script's ownership, independent writers wait, and reads never wait.
 - Each direct worker has a recorded Herdr tab and Pi session identity. The first handle returns before completion; subsequent tab identities remain recoverable on the session branch.
 - An exact settled worker with a bounded final Pi answer produces a follow-up to Main. Blocked, unknown, idle-stalled, truncated, or ambiguous outcomes retain actionable recovery identity. Session replacement never delivers to the wrong Main session.

package/README.md

@@ -29,7 +29,7 @@ Commands are for you; tools and the packaged skill are for Main. You do not need
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `/subagent` | command | Browse work, launch isolated status inspection in a separate Herdr tab with the `fast` model, or send/edit pending instructions. Requires interactive TUI or RPC; inspection also requires a Herdr-managed pane and a read-only `scout` Role. |
+| `/subagent` | command | Browse work, Close/cancel-and-release locally owned direct workers, launch isolated status inspection in a separate Herdr tab with the `fast` model, or send/edit pending instructions. Requires interactive TUI or RPC; inspection also requires a Herdr-managed pane and a read-only `scout` Role. |
 | `/subagent recover` | command | Classify orphaned isolated work in the current canonical repository and send Main one follow-up with request IDs, blockers, and reported next actions. No UI or Herdr pane required. |
 | `delegate_task` | tool | Start authorized shared-checkout work or a durable isolated checked graph. |
 | `subagent_status` | tool | Read durable isolated state and the exact allowed continuation without replaying work. Declares an output schema, so `codemode` scripts receive the same bounded public projection as structured content. |
@@ -81,9 +81,11 @@ Chain:    { mode: "direct", chain: [{ role, name, task, ... }] }
 
 Direct tasks use the selected Role's declared tools, extensions, Skills, and MCP servers, including write-capable resources. Authorization comes from your request and Main's bounded task packet, not the Role's capabilities: name allowed paths/actions and exclusions, preserve unrelated edits and staged changes, and authorize commits or external actions explicitly. For example, a configured Git operator with `bash` can stage named pending files and commit them on the `fast` route. Read-only Roles retain their tool restrictions. Use isolated mode for a checked changeset.
 
-Direct writes affect Main's checkout immediately. No clean-checkout prerequisite, automatic checks, rollback, or isolated integration guarantee applies. Requests containing potential writers (including any extensions or MCP servers) run their tasks serially and hold checkout admission after the initial handle returns; competing Pi writes fail until exact successful completion. Pure read-only parallel requests still run concurrently. A failure in a potential-writer request stops further dispatch; an uncertain worker may still be running. Chains replace each literal `{previous}` with the preceding successful answer and stop on failure. On failure, cancellation, or uncertain launch after tab creation, admission stays held: inspect the exact tabs/session files through `/subagent`, stop any remaining owned workers, inspect and preserve their changes, then restart Pi before new writes. Never blindly retry a commit or delete work to recover.
+Direct writes affect Main's checkout immediately. No clean-checkout prerequisite, automatic checks, rollback, or isolated integration guarantee applies. Requests containing potential writers (including any extensions or MCP servers) run their tasks serially and hold checkout admission after the initial handle returns; competing Pi writes fail until all owned workers are proved stopped. Pure read-only parallel requests still run concurrently. A failure in a potential-writer request stops further dispatch; an uncertain worker may still be running. Chains replace each literal `{previous}` with the preceding successful answer and stop on failure. Task outcome and worker termination are separate: after settlement the coordinator closes exact owned writer panes and releases admission only after pane absence and two empty private process-lease scans. Native `lsof` is required for this proof; no Git files, commits, or saved sessions are removed. Failure remains failure even when admission is released. If closing fails, identity changes, a leased child survives, or inspection is uncertain, admission stays held. Open `/subagent`, select the exact direct task, and choose **Close/cancel-and-release owned workers** to cancel dispatch and retry termination. The action checks session/branch/epoch and live ownership; recorded-only tasks cannot unlock anything. Resolve the reported blocker (including any surviving owned process), then repeat the same action. Restarting Pi is not termination proof. Inspect partial changes before new writes; never blindly retry a commit or delete work to recover.
 
-Potential-writer tasks must return one JSON completion object, such as `{"outcome":"succeeded","answer":"Scoped commit completed."}`. `outcome` must be `succeeded`, `failed`, or `blocked`, and `answer` must be non-empty. A normal final Pi turn is not enough: failure, blocked work, plain text, or malformed completion stops later dispatch and retains admission. Success is the worker's explicit report, not independent validation of its changes.
+If tab creation times out or returns incomplete or mismatched identity, `/subagent` retains the allocation intent: workspace, checkout, label, private lease/session paths, and any returned tab/pane IDs. No worker is started until creation identity is verified. These records are evidence, not ownership: Close is unavailable for unverified allocation, and admission remains held pending manual reconciliation against Herdr. Do not recreate a tab, guess missing IDs, or restart to bypass this blocker. A Close begun while a worker is active keeps its branch/session/epoch guards through cancellation settlement; stale dialogs cannot close panes or release admission.
+
+Potential-writer tasks must return one JSON completion object, such as `{"outcome":"succeeded","answer":"Scoped commit completed."}`. `outcome` must be `succeeded`, `failed`, or `blocked`, and `answer` must be non-empty. A normal final Pi turn is not enough: failure, blocked work, plain text, or malformed completion stops later dispatch, but admission depends on proved termination, not the reported outcome. Success is the worker's explicit report, not independent validation of its changes.
 
 The tool returns a task ID and first Herdr tab after launch, not the answer. The extension observes each worker and sends one result to Main when the workflow finishes. If Main is busy, Pi queues it after the current turn; if idle, it starts a turn. A blocked, stalled, unknown, or truncated result is not reported as success. Session switch or shutdown stops observation and preserves tab identities for recovery. Open `/subagent` on the session branch to inspect exact tabs, agents, and Pi session files, including tabs launched after the first. A recorded tab may no longer be running; locally observed work is labelled separately.
 
@@ -140,7 +142,7 @@ Completed text answers are saved independently of cleanup. Status and terminal f
 
 Isolated workers can start while Main has staged, unstaged, or untracked changes: they use only Main's pinned committed branch, HEAD, and tree. Those local edits are neither copied into worker worktrees nor stashed, staged, reset, or merged automatically. Main must remain at that committed identity while workers run; branch or HEAD drift blocks new waves. The worker produces a committed candidate without tracked or untracked changes, then runs focused preliminary checks and optional judgment. Ignored generated files do not block candidacy, but prevent automatic worktree cleanup; inspect them before deleting retained work. The runner records each ready candidate immediately but **does not integrate it automatically**. Main can inspect `subagent_status` and use `subagent_stage` to select the exact candidate in an owned integration worktree while siblings are still working; conflicts are resolved there. Stage and resolve are available during an active wave, but rejection and revision wait for the wave to settle. `subagent_integrate` can advance dependent tasks from a staged snapshot, validate the combined tip with full root checks and optional final judgment after the wave settles, and promote it to Main only after exact validation. A definitive failed combined check/review allows one committed correction in the integration checkout followed by another validation. Main must explicitly promote; promotion and cleanup never silently discard retained work.
 
-Open `/subagent` without arguments to pick work by label. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout (including requests launched in other sessions). Pick an isolated request and **Inspect status and recovery** to launch a non-focused Herdr tab with a read-only `scout` Role on the configured `fast` route. Unlike ordinary direct delegation, status inspection rejects Roles with extensions or MCP servers because their tools are not verified read-only. Its prompt contains bounded saved status (including retained paths, but not raw launch environment or session transcripts); the analysis stays in that tab and does not queue a Main turn. The tab and session file are recorded for recovery even if launch becomes uncertain. The read-only `subagent_status` tool remains Main's authority for exact identities before any stage or recovery action. If Herdr or the read-only fast route is unavailable, inspection fails without changing the request; Main can use `subagent_status`. Refresh or choose completed/history for older work. Invalid state IDs are warned about and preserved. Outside Git or when isolated inventory is unavailable, direct recovery still works. Browsing does not resume work or change resources.
+Open `/subagent` without arguments to pick work by label. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout (including requests launched in other sessions). Pick an isolated request and **Inspect status and recovery** to launch a non-focused Herdr tab with a read-only `scout` Role on the configured `fast` route. Unlike ordinary direct delegation, status inspection rejects Roles with extensions or MCP servers because their tools are not verified read-only. Its prompt contains bounded saved status (including retained paths, but not raw launch environment or session transcripts); the analysis stays in that tab and does not queue a Main turn. The tab and session file are recorded for recovery even if launch becomes uncertain. The read-only `subagent_status` tool remains Main's authority for exact identities before any stage or recovery action. If Herdr or the read-only fast route is unavailable, inspection fails without changing the request; Main can use `subagent_status`. Refresh or choose completed/history for older work. Invalid state IDs are warned about and preserved. Outside Git or when isolated inventory is unavailable, direct recovery still works. Browsing does not resume work or change resources; direct **Close/cancel-and-release** is an explicit termination action.
 
 For a locally active unsealed isolated changeset, choose **Send follow-up instructions** to open a native multiline editor; submission queues the instruction, not a completed revision. Choose **Edit queued instructions** to withdraw *all still-pending* instructions for that selected task before the editor opens. Their full text appears in FIFO order separated by blank lines. Explicit submission queues **one replacement** at the tail. Cancel leaves the withdrawn instructions removed; already-claimed instructions, initial prompts, and automatic corrections cannot be recalled. A worker may seal during editing: failed submission reopens the full submitted text for deliberate editing or copying, never automatically requeues it. Combined text above the single-instruction limit is preserved in the editor but rejected until shortened. Cancelling before withdrawal makes no change. Neither action touches Main's editor or Pi's global Option+Up queue shortcut. No-UI sessions can run `/subagent recover` or use agent tools for individual inspection and recovery.
 

package/dist/direct-herdr.d.ts

@@ -14,7 +14,24 @@ export interface DirectHandle {
 export declare function exactDirectTerminalTurn(jsonl: string, prompt: string): boolean;
 export declare function exactDirectAnswer(jsonl: string, prompt: string, maxBytes?: number, requireSuccess?: boolean): string;
 export declare function directSessionTokens(jsonl: string, prompt: string): number | undefined;
-export type DirectTab = Pick<DirectHandle, "name" | "tabId" | "paneId" | "sessionFile">;
+export type DirectTab = Pick<DirectHandle, "name" | "tabId" | "paneId" | "sessionFile"> & {
+    leasePath: string;
+};
+/** Allocation evidence is not ownership and must never authorize pane mutation. */
+export type DirectAllocation = Omit<DirectTab, "tabId" | "paneId"> & {
+    workspaceId: string;
+    cwd: string;
+    label: string;
+    tabId?: string;
+    paneId?: string;
+};
+export declare class DirectAllocationError extends Error {
+    readonly allocation: DirectAllocation;
+    constructor(allocation: DirectAllocation, cause: unknown);
+}
 export declare function createDirectHerdr(pi: Pick<ExtensionAPI, "exec">, cwd: string, idleMs: number): {
+    /** Close only an exact owned pane, then prove it and its leased children stopped.
+     * A task result or Ctrl-C acknowledgement is not termination evidence. */
+    stop(tab: DirectTab, current?: () => boolean): Promise<void>;
     start(launch: ResolvedRoleLaunch, name: string, label: string, task: string, signal: AbortSignal, onTab: (tab: DirectTab) => void, requireSuccess?: boolean): Promise<DirectHandle>;
 };

package/dist/direct-herdr.js

@@ -1,9 +1,11 @@
 import { randomBytes } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { readFile, mkdtemp, stat } from "node:fs/promises";
+import { readFile, mkdtemp, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import { createHerdrClient, hasHerdrErrorCode, herdrCommandFailure, startPiAgent } from "@henryqw/pi-herdr";
+import { assertPrivateLease, scanProcessLease } from "./process-lease.js";
 const OPERATION_MS = 30_000;
 const SESSION_LIMIT = 16 * 1024 * 1024;
 const ANSWER_LIMIT = 50 * 1024;
@@ -132,6 +134,13 @@ export function directSessionTokens(jsonl, prompt) {
     }
     return observed ? total : undefined;
 }
+export class DirectAllocationError extends Error {
+    allocation;
+    constructor(allocation, cause) {
+        super(`Direct tab allocation is unverified: ${cause instanceof Error ? cause.message : String(cause)}. No agent start was dispatched. Inspect /subagent allocation evidence: workspace ${allocation.workspaceId}, cwd ${allocation.cwd}, label ${JSON.stringify(allocation.label)}, tab ${allocation.tabId ?? "unknown"}, pane ${allocation.paneId ?? "unknown"}, agent ${allocation.name}, session ${allocation.sessionFile}, lease ${allocation.leasePath}. Manual allocation reconciliation is required; do not replay creation or unlock admission.`, { cause });
+        this.allocation = allocation;
+    }
+}
 export function createDirectHerdr(pi, cwd, idleMs) {
     if (process.env.HERDR_ENV !== "1")
         throw new Error("Direct delegation requires a Herdr-managed Pi pane (HERDR_ENV=1).");
@@ -149,6 +158,56 @@ export function createDirectHerdr(pi, cwd, idleMs) {
         return field(agent.agent_status, "agent state");
     };
     return {
+        /** Close only an exact owned pane, then prove it and its leased children stopped.
+         * A task result or Ctrl-C acknowledgement is not termination evidence. */
+        async stop(tab, current = () => true) {
+            const requireCurrent = () => { if (!current())
+                throw new Error("Direct task scope changed; reopen /subagent."); };
+            requireCurrent();
+            await assertPrivateLease(tab.leasePath, false);
+            const listed = result(await herdr.json(["agent", "list"], options()), "agent_list");
+            if (!Array.isArray(listed.agents))
+                throw new Error("Malformed Herdr agent list.");
+            const related = listed.agents.map((value) => {
+                const agent = object(value, "listed agent");
+                for (const key of ["pane_id", "tab_id"])
+                    field(agent[key], `listed agent ${key}`);
+                return agent;
+            }).filter((agent) => agent.name === tab.name || agent.pane_id === tab.paneId || agent.tab_id === tab.tabId);
+            const panes = async () => {
+                const list = result(await herdr.json(["pane", "list", "--workspace", workspaceId], options()), "pane_list");
+                if (!Array.isArray(list.panes))
+                    throw new Error("Malformed Herdr pane list.");
+                return list.panes.map((value) => {
+                    const pane = object(value, "listed pane");
+                    for (const key of ["pane_id", "tab_id"])
+                        field(pane[key], `listed pane ${key}`);
+                    if (pane.workspace_id !== workspaceId)
+                        throw new Error("Herdr pane list escaped the owned workspace.");
+                    return pane;
+                });
+            };
+            if (related.length) {
+                const agent = related[0];
+                if (related.length !== 1 || agent.name !== tab.name || agent.pane_id !== tab.paneId
+                    || agent.tab_id !== tab.tabId || agent.workspace_id !== workspaceId || agent.cwd !== workingDir
+                    || tab.paneId === callerPane)
+                    throw new Error("Worker termination requires one exact owned agent, workspace, checkout, tab and pane match.");
+                requireCurrent();
+                result(await herdr.json(["pane", "close", tab.paneId], options()), "ok");
+            }
+            if ((await panes()).some((pane) => pane.pane_id === tab.paneId || pane.tab_id === tab.tabId)) {
+                throw new Error(`Owned pane ${tab.paneId} is still present; termination is unproved.`);
+            }
+            for (let scan = 0; scan < 2; scan++) {
+                const holders = await scanProcessLease(tab.leasePath, (args) => pi.exec("lsof", args, { cwd: workingDir, timeout: 3_000 }));
+                if (holders.length)
+                    throw new Error(`Owned process lease ${tab.leasePath} still has holders: ${holders.join(", ")}. Stop those owned processes, then retry Close/cancel-and-release.`);
+                if (scan === 0)
+                    await sleep(50);
+            }
+            requireCurrent();
+        },
         async start(launch, name, label, task, signal, onTab, requireSuccess = false) {
             const caller = result(await herdr.json(["pane", "current", "--current"], options(signal)), "pane_current");
             const pane = object(caller.pane, "calling pane");
@@ -158,6 +217,8 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                 throw new Error("Direct Herdr launch cannot transfer Role environment overrides.");
             const sessionDir = await mkdtemp(join(tmpdir(), "pi-subagent-direct-"));
             const sessionFile = join(sessionDir, "session.jsonl");
+            const leasePath = join(sessionDir, "process.lease");
+            await writeFile(leasePath, "", { flag: "wx", mode: 0o600 });
             // Pi's native session is the exact answer channel. Herdr screen output is diagnostic only.
             const sessionArgs = launch.args.filter((arg) => arg !== "--no-session");
             if (sessionArgs.length !== launch.args.length - 1)
@@ -165,18 +226,34 @@ export function createDirectHerdr(pi, cwd, idleMs) {
             signal.throwIfAborted();
             // Tab creation is bounded but not session-cancellable: Herdr may create it
             // before the CLI responds, and aborting the CLI loses the exact tab ID.
-            const created = result(await herdr.json(["tab", "create", "--workspace", workspaceId, "--cwd", workingDir, "--label", label, "--no-focus"], options()), "tab_created");
-            const tab = object(created.tab, "created tab");
-            const workerPane = object(created.root_pane, "created pane");
-            const tabId = field(tab.tab_id, "tab id");
-            const paneId = field(workerPane.pane_id, "pane id");
-            if (tab.workspace_id !== workspaceId || workerPane.workspace_id !== workspaceId || workerPane.tab_id !== tabId
-                || workerPane.cwd !== workingDir || tab.focused !== false || workerPane.focused !== false || paneId === callerPane) {
-                throw new Error(`Herdr tab ${tabId} has unverified identity, cwd or focus; inspect it before retrying.`);
+            const allocation = { name, workspaceId, cwd: workingDir, label, sessionFile, leasePath };
+            let tabId;
+            let paneId;
+            try {
+                const response = await herdr.json(["tab", "create", "--workspace", workspaceId, "--cwd", workingDir, "--label", label, "--env", `PI_SUBAGENT_PROCESS_LEASE=${leasePath}`, "--no-focus"], options());
+                const created = object(response.result, "tab allocation result");
+                // Capture every returned ID before validation can fail. These are evidence,
+                // not owned tabs; the caller retains this intent even without either ID.
+                for (const [source, key, target] of [[created.tab, "tab_id", "tabId"], [created.root_pane, "pane_id", "paneId"]]) {
+                    if (source && typeof source === "object" && typeof source[key] === "string")
+                        allocation[target] = source[key];
+                }
+                result(response, "tab_created");
+                const tab = object(created.tab, "created tab");
+                const workerPane = object(created.root_pane, "created pane");
+                tabId = field(tab.tab_id, "tab id");
+                paneId = field(workerPane.pane_id, "pane id");
+                if (tab.workspace_id !== workspaceId || workerPane.workspace_id !== workspaceId || workerPane.tab_id !== tabId
+                    || workerPane.cwd !== workingDir || tab.focused !== false || workerPane.focused !== false || paneId === callerPane) {
+                    throw new Error(`Herdr tab ${tabId} has unverified identity, cwd or focus; inspect it before retrying.`);
+                }
+            }
+            catch (error) {
+                throw new DirectAllocationError(allocation, error);
             }
             try {
                 // Record the tab before the agent start can outlive an aborted launch.
-                onTab({ name, tabId, paneId, sessionFile });
+                onTab({ name, tabId, paneId, sessionFile, leasePath });
                 signal.throwIfAborted();
                 const started = await startPiAgent(herdr, { name, pane: paneId,
                     args: [...sessionArgs, "--session", sessionFile], options: options(signal), shouldRetry: () => false });

package/dist/herdr-runtime.js

@@ -9,6 +9,7 @@ import { isCleanCommitted, } from "./schema.js";
 import { buildChangesetTaskPrompt, withTransientLaunch, } from "./runner.js";
 import { runProcess as defaultRunProcess } from "./process.js";
 import { EXECUTION_BUDGET_ENV } from "./ephemeral.js";
+import { assertPrivateLease, scanProcessLease } from "./process-lease.js";
 import { exactDirectTerminalTurn } from "./direct-herdr.js";
 const MIN_HERDR_VERSION = [0, 9, 0];
 const MIN_HERDR_PROTOCOL = 22;
@@ -1193,42 +1194,10 @@ export class HerdrHostRuntime {
         }
     }
     async assertPrivateLease(path, allowMissing) {
-        let info;
-        try {
-            info = await lstat(path);
-        }
-        catch (error) {
-            if (allowMissing && error.code === "ENOENT")
-                return false;
-            throw new Error(`Exact process lease cannot be inspected: ${path}`, { cause: error });
-        }
-        const uid = process.getuid?.();
-        if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o777) !== LEASE_MODE || (uid !== undefined && info.uid !== uid)) {
-            throw new Error("Exact process lease must be a current-user regular non-symlink mode-0600 file.");
-        }
-        return true;
+        return assertPrivateLease(path, allowMissing);
     }
     async scanLease(path, cwd, context, pid, allowMissing = false) {
-        if (!await this.assertPrivateLease(path, allowMissing))
-            return [];
-        const args = ["-nP", "-a", ...(pid === undefined ? [] : ["-p", String(pid)]), "-F", "p", "--", path];
-        const result = await this.execute(this.lsofCommand, args, this.processOptions(cwd, context, LSOF_OPERATION_CAP_MS));
-        if (result.killed || ![0, 1].includes(result.code) || (result.code === 1 && (result.stdout.trim() || result.stderr.trim()))) {
-            throw new Error("Exact process lease lsof scan failed or was ambiguous.");
-        }
-        if (result.code === 1)
-            return [];
-        if (result.stderr.trim())
-            throw new Error("Exact process lease lsof scan returned unexpected diagnostics.");
-        const lines = result.stdout.trim().split(/\r?\n/).filter(Boolean);
-        if (!lines.length || lines.some((line) => !/^p[1-9]\d*$/.test(line))) {
-            throw new Error("Exact process lease lsof scan returned malformed PID fields.");
-        }
-        const holders = [...new Set(lines.map((line) => Number(line.slice(1))))];
-        if (holders.some((holder) => !Number.isSafeInteger(holder) || holder <= 0) || (pid !== undefined && holders.some((holder) => holder !== pid))) {
-            throw new Error("Exact process lease lsof scan returned an unexpected PID.");
-        }
-        return holders;
+        return scanProcessLease(path, (args) => this.execute(this.lsofCommand, args, this.processOptions(cwd, context, LSOF_OPERATION_CAP_MS)), pid, allowMissing);
     }
     async signalExactHolders(holders, allocation, signal, context) {
         for (const pid of holders) {

package/dist/process-lease.d.ts

@@ -0,0 +1,4 @@
+import type { HerdrExecResult } from "@henryqw/pi-herdr";
+export declare function assertPrivateLease(path: string, allowMissing: boolean): Promise<boolean>;
+/** Shared exact process-lease evidence for direct and isolated workers. */
+export declare function scanProcessLease(path: string, execute: (args: string[]) => Promise<HerdrExecResult>, pid?: number, allowMissing?: boolean): Promise<number[]>;

package/dist/process-lease.js

@@ -0,0 +1,40 @@
+import { lstat } from "node:fs/promises";
+export async function assertPrivateLease(path, allowMissing) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (allowMissing && error.code === "ENOENT")
+            return false;
+        throw new Error(`Exact process lease cannot be inspected: ${path}`, { cause: error });
+    }
+    const uid = process.getuid?.();
+    if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o777) !== 0o600 || (uid !== undefined && info.uid !== uid)) {
+        throw new Error("Exact process lease must be a current-user regular non-symlink mode-0600 file.");
+    }
+    return true;
+}
+/** Shared exact process-lease evidence for direct and isolated workers. */
+export async function scanProcessLease(path, execute, pid, allowMissing = false) {
+    if (!await assertPrivateLease(path, allowMissing))
+        return [];
+    const args = ["-nP", "-a", ...(pid === undefined ? [] : ["-p", String(pid)]), "-F", "p", "--", path];
+    const result = await execute(args);
+    if (result.killed || ![0, 1].includes(result.code) || (result.code === 1 && (result.stdout.trim() || result.stderr.trim()))) {
+        throw new Error("Exact process lease lsof scan failed or was ambiguous.");
+    }
+    if (result.code === 1)
+        return [];
+    if (result.stderr.trim())
+        throw new Error("Exact process lease lsof scan returned unexpected diagnostics.");
+    const lines = result.stdout.trim().split(/\r?\n/).filter(Boolean);
+    if (!lines.length || lines.some((line) => !/^p[1-9]\d*$/.test(line))) {
+        throw new Error("Exact process lease lsof scan returned malformed PID fields.");
+    }
+    const holders = [...new Set(lines.map((line) => Number(line.slice(1))))];
+    if (holders.some((holder) => !Number.isSafeInteger(holder) || holder <= 0) || (pid !== undefined && holders.some((holder) => holder !== pid))) {
+        throw new Error("Exact process lease lsof scan returned an unexpected PID.");
+    }
+    return holders;
+}

package/extensions/admission.ts

@@ -83,14 +83,11 @@ export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (inp
 	pi.on("tool_result", (event) => release(event.toolCallId));
 	pi.on("tool_execution_end", (event) => release(event.toolCallId));
 	pi.on("session_shutdown", () => {
-		ownerByCheckout.clear();
-		checkoutByRoot.clear();
-		writersByRoot.clear();
-		rootByCall.clear();
-		heldCalls.clear();
+		// Session replacement is not proof that a held direct worker stopped.
+		for (const call of rootByCall.keys()) release(call);
 	});
 	// A direct handle settles the tool call before the worker settles. Keep its
-	// admission until exact completion; uncertain workers require manual recovery.
+	// admission until proved termination; uncertain workers require guarded recovery.
 	return (toolCallId) => {
 		const root = rootByCall.get(toolCallId);
 		if (root === undefined || !writersByRoot.get(root)?.has(toolCallId)) {

package/extensions/subagent-command.ts

@@ -5,6 +5,8 @@ export interface DirectTask {
 	id: string;
 	name: string;
 	status: string;
+	canClose?: boolean;
+	recovery?: string;
 	tabs: readonly { entryId: string; name: string; tabId: string; paneId: string; sessionFile: string }[];
 }
 
@@ -30,6 +32,7 @@ export interface IsolatedInventory {
  * validation and queue operation. They must not await between those operations. */
 export interface SubagentCommandAdapter {
 	direct(ctx: ExtensionContext): readonly DirectTask[];
+	closeDirect(task: DirectTask, current: () => boolean): Promise<string>;
 	isolated(cwd: string, current: () => boolean): Promise<IsolatedInventory>;
 	recover(cwd: string): Promise<string>;
 	inspectInTab(root: string, requestId: string, ctx: ExtensionContext, current: () => boolean): Promise<{ tabId: string; name: string; sessionFile: string }>;
@@ -119,9 +122,23 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				if (selected.kind === "history") { history = !history; continue; }
 				if (selected.kind === "direct") {
 					ctx.ui.notify(`Direct workflow ${clean(selected.task.name)} (${JSON.stringify(selected.task.id)}) · ${clean(selected.task.status)}`, "info");
+					if (selected.task.recovery) ctx.ui.notify(clean(selected.task.recovery, 4000), "warning");
 					for (const tab of selected.task.tabs) {
 						ctx.ui.notify(`Task ${JSON.stringify(tab.entryId)} · agent ${JSON.stringify(tab.name)} · tab ${JSON.stringify(tab.tabId)} · pane ${JSON.stringify(tab.paneId)} · session ${JSON.stringify(tab.sessionFile)}`, "info");
 					}
+					if (selected.task.canClose) {
+						const action = await choose(ctx, `Direct · ${clean(selected.task.name)} · ${selected.task.id}`, [
+							{ label: "Close/cancel-and-release owned workers (preserve files and commits)", value: "close" },
+							{ label: "Back / refresh", value: "back" },
+						]);
+						if (!valid()) return;
+						if (action === "close") {
+							try {
+								const report = await adapter.closeDirect(selected.task, current);
+								if (valid()) ctx.ui.notify(report, "info");
+							} catch (error) { if (valid()) ctx.ui.notify(`Admission retained: ${errorText(error)}. Inspect the exact tab/session; retry Close/cancel-and-release after resolving termination.`, "error"); }
+						}
+					}
 					continue;
 				}
 				const { root, request } = selected;

package/extensions/subagent.ts

@@ -10,7 +10,7 @@ import { registerSubagentCommand, type DirectTask } from "./subagent-command.ts"
 import { MODEL_CLASS_GUIDANCE } from "./model-class-policy.ts";
 import { ENTRY_STATUS_PRESENTATION, formatWorkflowResult, type BackgroundWorkflowTransportDetails, type WorkflowTransportEntry } from "./result-transport.ts";
 import { DelegateTaskParameters, identifyWorkflowEntries, parseDelegateTask, runForegroundWorkflow, type Delegation, type ParsedWorkflow, type WorkflowEntry } from "./workflow.ts";
-import { createDirectHerdr, type DirectHandle, type DirectTab } from "../dist/direct-herdr.js";
+import { createDirectHerdr, DirectAllocationError, type DirectAllocation, type DirectHandle, type DirectTab } from "../dist/direct-herdr.js";
 import { materializeTransientLaunch } from "../dist/launch-runtime.js";
 const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 1_000;
@@ -110,6 +110,8 @@ function replaceRouteModel(ctx: ExtensionContext, reference: string, route: Reso
 
 const DIRECT_RESULT_TYPE = "subagent-direct-result";
 const DIRECT_TAB_TYPE = "subagent-direct-tab";
+const DIRECT_ALLOCATION_TYPE = "subagent-direct-allocation";
+type DirectAllocationRecord = DirectAllocation & { taskId: string; entryId: string; failure: string };
 type DirectTabRecord = DirectTab & { taskId: string; entryId: string };
 
 function boundedError(error: unknown): Error {
@@ -136,7 +138,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		if (!details?.entries) return new Text(content, outputPad, 0);
 		const count = details.entries.length;
 		const subject = count === 1 ? "Direct subagent" : `${count} direct subagents`;
-		const state = details.recovery ? "stopped; recovery needed" : details.outcome;
+		const state = details.recovery ? "termination unverified; recovery needed" : details.outcome;
 		const glyph = details.recovery ? "■" : details.outcome === "completed" ? "✓" : "✗";
 		const color = details.recovery ? "warning" : details.outcome === "completed" ? "success" : "error";
 		const rows = details.entries.map(({ name, role, status, summary }) => {
@@ -188,24 +190,48 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		currentPolicy,
 	});
 	let directSequence = 0;
-	const directTasks = new Map<string, { controller: AbortController; settled: Promise<void>; handles: DirectHandle[]; tabs: DirectTabRecord[] }>();
+	const directTasks = new Map<string, { controller: AbortController; settled: Promise<void>; handles: DirectHandle[]; tabs: DirectTabRecord[]; close?: (current: () => boolean) => Promise<void>; closeScope?: () => boolean; allocation?: DirectAllocationRecord; recovery?: string }>();
 	let latestCtx: ExtensionContext | undefined;
 	let sessionEpoch = 0;
 	registerSubagentCommand(pi, {
 		direct(ctx): DirectTask[] {
 			const grouped = new Map<string, DirectTask & { tabs: Array<DirectTask["tabs"][number]> }>();
 			for (const entry of ctx.sessionManager.getBranch()) {
+				if (entry.type === "custom" && entry.customType === DIRECT_ALLOCATION_TYPE && entry.data) {
+					const allocation = entry.data as DirectAllocationRecord;
+					grouped.set(allocation.taskId, { id: allocation.taskId, name: allocation.name,
+						status: "allocation unverified; admission retained", recovery: allocation.failure,
+						tabs: grouped.get(allocation.taskId)?.tabs ?? [] });
+				}
 				if (entry.type !== "custom" || entry.customType !== DIRECT_TAB_TYPE || !entry.data) continue;
 				const tab = entry.data as DirectTabRecord;
-				const observed = directTasks.has(tab.taskId);
+				const local = directTasks.get(tab.taskId);
 				const existing = grouped.get(tab.taskId);
 				const record = { entryId: tab.entryId, name: tab.name, tabId: tab.tabId, paneId: tab.paneId, sessionFile: tab.sessionFile };
 				if (existing) {
 					if (!existing.tabs.some((item) => item.tabId === tab.tabId)) existing.tabs.push(record);
-				} else grouped.set(tab.taskId, { id: tab.taskId, name: tab.name, status: observed ? "observed locally" : "recorded (not observed)", tabs: [record] });
+				} else grouped.set(tab.taskId, { id: tab.taskId, name: tab.name, status: local?.recovery ? `admission retained: ${local.recovery}` : local ? "observed locally" : "recorded (not observed)", canClose: Boolean(local?.close), tabs: [record] });
 			}
 			return [...grouped.values()];
 		},
+		async closeDirect(task, current) {
+			const local = directTasks.get(task.id);
+			const owned = () => current() && directTasks.get(task.id) === local;
+			if (!owned() || !local?.close || task.tabs.length !== local.tabs.length || task.tabs.some((tab, index) => {
+				const saved = local.tabs[index]!;
+				return tab.entryId !== saved.entryId || tab.name !== saved.name || tab.tabId !== saved.tabId
+					|| tab.paneId !== saved.paneId || tab.sessionFile !== saved.sessionFile;
+			})) throw new Error("Direct task ownership changed; reopen /subagent. Recorded-only tasks cannot release admission.");
+			// Cancellation settles through the background finalizer; it must retain this
+			// command's authority across every awaited identity/termination lookup too.
+			local.closeScope = owned;
+			local.controller.abort();
+			await local.settled;
+			// Automatic settlement may already have proved termination and released it.
+			if (!current()) throw new Error("Direct task scope changed; reopen /subagent.");
+			if (directTasks.has(task.id)) await local.close(owned);
+			return "Owned workers stopped; checkout admission released. Dirty files, commits and session evidence preserved. Inspect changes before retrying work.";
+		},
 		isolated: isolatedSurface.inventory,
 		recover: (cwd) => isolatedSurface.recover(cwd),
 		async inspectInTab(root, id, ctx, current) {
@@ -359,6 +385,10 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			const recorded = new Set(ctx.sessionManager.getBranch().flatMap((entry) =>
 				entry.type === "custom" && entry.customType === DIRECT_TAB_TYPE && entry.data
 					? [(entry.data as DirectTabRecord).tabId] : []));
+			for (const { allocation } of previous) if (allocation && !ctx.sessionManager.getBranch().some((entry) =>
+				entry.type === "custom" && entry.customType === DIRECT_ALLOCATION_TYPE && (entry.data as DirectAllocationRecord)?.taskId === allocation.taskId)) {
+				pi.appendEntry(DIRECT_ALLOCATION_TYPE, allocation);
+			}
 			for (const { tabs } of previous) for (const tab of tabs) {
 				if (!recorded.has(tab.tabId)) {
 					pi.appendEntry(DIRECT_TAB_TYPE, tab);
@@ -394,7 +424,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			await Promise.allSettled(handles.map((handle) => handle.cancel()));
 		}
 		await Promise.allSettled(tasks.map(({ settled }) => settled));
-		directTasks.clear();
+		// Unproved workers keep their local ownership and admission across a session switch.
 	});
 	// btw-style context refresh: model_select carries the new model on the event,
 	// agent_settled delivers the freshest full context after each turn.
@@ -418,17 +448,19 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		mode: ParsedWorkflow["mode"],
 		entries: readonly WorkflowTransportEntry[],
 		tabs: readonly DirectTabRecord[],
+		recovery?: string,
 	): void => {
 		const stale = launchEpoch !== sessionEpoch;
 		if (stale) return;
 		const transport = formatWorkflowResult(mode, entries);
 		const outcome: BackgroundWorkflowTransportDetails["outcome"] = transport.failed ? "failed" : "completed";
-		const content = [transport.text, ...(tabs.length ? ["Recovery (also available via /subagent):", ...tabs.map(({ taskId, entryId, name, tabId, paneId, sessionFile }) =>
+		const content = [transport.text, ...(recovery ? [`Checkout admission retained: ${recovery}. Open /subagent, select ${taskId}, and follow its recovery guidance (Close/cancel-and-release only when offered); never blindly retry work.`] : []), ...(tabs.length ? ["Recovery (also available via /subagent):", ...tabs.map(({ taskId, entryId, name, tabId, paneId, sessionFile }) =>
 			`- ${taskId} · ${entryId} · tab ${tabId} · pane ${paneId} · agent ${name} · session ${sessionFile}`)] : [])].join("\n");
 		const details: BackgroundWorkflowTransportDetails & { tabs: readonly DirectTabRecord[] } = {
 			...transport.details,
 			taskId,
 			outcome,
+			...(recovery ? { recovery: true as const } : {}),
 			tabs: [...tabs],
 		};
 		try {
@@ -501,7 +533,21 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			// Register before Herdr can create a tab: session switches must await this
 			// launch, including its identity callback, before copying recovery records.
 			const releaseAdmission = writes ? holdAdmission(toolCallId) : () => {};
-			directTasks.set(taskId, { controller, settled, handles, tabs });
+			const local: NonNullable<ReturnType<typeof directTasks.get>> = { controller, settled, handles, tabs };
+			local.close = async (current) => {
+				const inScope = () => current() && (local.closeScope?.() ?? true);
+				try {
+					if (local.allocation) throw new Error(local.allocation.failure);
+					for (const tab of tabs) await herdr.stop(tab, inScope);
+					if (!inScope()) throw new Error("Direct task scope changed; reopen /subagent.");
+					releaseAdmission();
+					directTasks.delete(taskId);
+				} catch (error) {
+					local.recovery = boundedError(error).message;
+					throw error;
+				}
+			};
+			directTasks.set(taskId, local);
 			const launch = async (entry: WorkflowEntry, activeSignal: AbortSignal) => {
 				activeSignal.throwIfAborted();
 				const role = loadRoles().find((candidate) => candidate.name === entry.delegation.role);
@@ -534,6 +580,10 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 							tabByEntry.set(entry.id, record);
 						}, writes);
 				} catch (error) {
+					if (error instanceof DirectAllocationError) {
+						local.allocation = { taskId, entryId: entry.id, ...error.allocation, failure: error.message };
+						pi.appendEntry(DIRECT_ALLOCATION_TYPE, local.allocation);
+					}
 					// A failed start can still be in flight. Keep its private prompt for recovery.
 					throw new Error(`${error instanceof Error ? error.message : String(error)}. Direct Role prompt retained at ${transient.launch.args[prepared.promptArgIndex + 1]} after uncertain start.`, { cause: error });
 				}
@@ -558,9 +608,9 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			} catch (error) {
 				controller.abort();
 				finishWidgetItem(entries[0]!.id, "failure");
-				directTasks.delete(taskId);
+				if (!tabs.length && !local.allocation) { releaseAdmission(); directTasks.delete(taskId); }
+				else local.recovery = local.allocation?.failure ?? "Launch outcome uncertain; inspect the exact recorded tab before Close/cancel-and-release";
 				resolveSettled();
-				if (!tabs.length) releaseAdmission();
 				throw boundedError(error);
 			} finally { signal?.removeEventListener("abort", abortLaunch); }
 			void (async () => {
@@ -608,14 +658,16 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 							status: "skipped",
 						});
 					}
-					if ([...states.values()].every(({ status }) => status === "succeeded")) releaseAdmission();
-					if (!controller.signal.aborted) reportDirect(launchEpoch, taskId, workflow.mode, [...states.values()], tabs);
-					directTasks.delete(taskId);
+					if (writes || controller.signal.aborted) {
+						try { await local.close!(() => directTasks.get(taskId) === local); }
+						catch { /* Retain ownership and admission for an explicit guarded retry. */ }
+					} else directTasks.delete(taskId);
+					if (!controller.signal.aborted) reportDirect(launchEpoch, taskId, workflow.mode, [...states.values()], tabs, local.recovery);
 					resolveSettled();
 				}
 			})();
 			return {
-				content: [{ type: "text" as const, text: capOutput(`Direct delegation started · ${taskId}\nHerdr tab: ${first.tabId} · pane: ${first.paneId} · agent: ${first.name}\nExact session: ${first.sessionFile}\nAll launched tabs: /subagent (on this session branch).\n${entries.length} task(s); result will arrive in one follow-up message. Direct work shares this checkout; completion is an exact answer, not checked integration. ${writes ? "Potential writers run serially; competing Pi writes stay blocked until exact completion. On failure or cancellation, inspect owned tabs before restarting Pi; changes are not rolled back." : "Concurrent changes may make reads stale."}`) }],
+				content: [{ type: "text" as const, text: capOutput(`Direct delegation started · ${taskId}\nHerdr tab: ${first.tabId} · pane: ${first.paneId} · agent: ${first.name}\nExact session: ${first.sessionFile}\nAll launched tabs: /subagent (on this session branch).\n${entries.length} task(s); result will arrive in one follow-up message. Direct work shares this checkout; completion is an exact answer, not checked integration. ${writes ? "Potential writers run serially; competing Pi writes stay blocked until owned workers are proved stopped. If termination is uncertain, use /subagent Close/cancel-and-release; changes are not rolled back." : "Concurrent changes may make reads stale."}`) }],
 				details: { taskId, mode: workflow.mode, tabId: first.tabId, sessionFile: first.sessionFile,
 					entries: entries.map(({ id, index, delegation }) => ({ id, index, name: delegation.name, role: delegation.role })) },
 			};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "26.1.2",
+  "version": "26.1.3",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",

package/skills/pi-subagent/SKILL.md

@@ -24,7 +24,7 @@ After delegation acknowledges a handle or durable request, do other work or end
 
 # Direct requests
 
-Use one compact `role`/`name`/`task` packet, `tasks` for independent packets, or `chain` for dependent packets. Only answer-returning tasks (`kind: text`) are accepted; writes and commits are allowed within explicit task authorization, but `kind: changeset`, structured checks, and judgment require isolated mode. State scope, exclusions, commit policy, and external-action permission; preserve unrelated files and staged changes. Direct writes take effect immediately with no automatic validation, rollback, or isolated integration guarantees. Requests with potential writers run serially and block competing Pi writes until exact completion. Main may read or do work elsewhere while waiting, not mutate the reserved checkout. On failure/cancellation or an uncertain launched tab, inspect `/subagent` identities, stop remaining owned workers, preserve and inspect changes, then restart Pi before writing or retrying. A failed commit may already have happened; never replay it blindly. The tool returns a handle after launching Herdr tabs in the current workspace. Main receives the verified result as a follow-up after the workflow finishes, without interrupting an active turn. If observation stops, open `/subagent` to inspect exact recorded tabs and session files on this session branch; recorded does not prove still running.
+Use one compact `role`/`name`/`task` packet, `tasks` for independent packets, or `chain` for dependent packets. Only answer-returning tasks (`kind: text`) are accepted; writes and commits are allowed within explicit task authorization, but `kind: changeset`, structured checks, and judgment require isolated mode. State scope, exclusions, commit policy, and external-action permission; preserve unrelated files and staged changes. Direct writes take effect immediately with no automatic validation, rollback, or isolated integration guarantees. Requests with potential writers run serially and block competing Pi writes until owned workers are proved stopped. Main may read or do work elsewhere while waiting, not mutate the reserved checkout. Task failure is not proof a worker stopped. The coordinator closes exact owned writer panes and releases admission only after pane absence and two empty private process-lease scans. If termination remains uncertain, inspect `/subagent` identities and choose **Close/cancel-and-release owned workers** for the exact locally owned task. Resolve the reported blocker, then retry that guarded action; it never replays the prompt or removes dirty files, commits, or sessions. Recorded-only tasks have no live release authority; restarting Pi is not termination proof. An unverified tab allocation retains its workspace, checkout, label, lease/session paths and any returned IDs for manual reconciliation; it cannot authorize Close, guessed identities or replayed creation. Close keeps its branch/session/epoch guards while an active task cancels and settles. Preserve and inspect changes before writing or retrying. A failed commit may already have happened; never replay it blindly. The tool returns a handle after launching Herdr tabs in the current workspace. Main receives the verified result as a follow-up after the workflow finishes, without interrupting an active turn. If observation stops, open `/subagent` to inspect exact recorded tabs and session files on this session branch; recorded does not prove still running.
 
 # Isolated requests