@henryqw/pi-subagent 26.5.1 → 27.1.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { readFileSync, readdirSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { basename, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DefaultPackageManager, getAgentDir, parseFrontmatter, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { extensionConfigDir } from "@henryqw/pi-config-store";
+import { extensionConfigDir, extensionConfigPath } from "@henryqw/pi-config-store";
 import { hasDisplayControlCharacters } from "./display-text.js";
 import { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
 import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
@@ -155,6 +155,54 @@ function rejectRetiredRoleIsolation(value, source) {
         return;
     throw new Error(`${source}: Role isolation is retired; select mode \"isolated\" on delegate_task instead.`);
 }
+const ROLE_FRONTMATTER_KEYS = ["name", "description", "modelClass", "tools", "extensions", "skills", "mcps"];
+const ROLE_DEFAULT_KEYS = ["extensions", "tools", "skills"];
+/** Validate `config.json` `roleDefaults` with the same rules as Role fields; `label` prefixes errors. */
+export function parseRoleDefaults(value, label = "roleDefaults") {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be a JSON object.`);
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (!ROLE_DEFAULT_KEYS.includes(key))
+            throw new Error(`${label}: unknown key ${JSON.stringify(key)}; expected ${ROLE_DEFAULT_KEYS.join(", ")}.`);
+    }
+    return {
+        ...(record.extensions === undefined ? {} : { extensions: extensionList(record.extensions, label) }),
+        ...(record.tools === undefined ? {} : { tools: stringList(record.tools, "tools", label) }),
+        ...(record.skills === undefined ? {} : { skills: stringList(record.skills, "skills", label) }),
+    };
+}
+function readRoleDefaults(agentDir) {
+    const path = extensionConfigPath("pi-subagent", agentDir);
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    // Whole-file validation belongs to the execution policy reader, which blocks delegation.
+    const value = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.roleDefaults : undefined;
+    return value === undefined ? {} : parseRoleDefaults(value, `${path}: roleDefaults`);
+}
+const withDefaults = (defaults, values) => [...new Set([...(defaults ?? []), ...values])];
+function applyRoleDefaults(role, defaults) {
+    return {
+        ...role,
+        tools: withDefaults(defaults.tools, role.tools),
+        extensions: withDefaults(defaults.extensions, role.extensions),
+        skills: withDefaults(defaults.skills, role.skills),
+    };
+}
 // Built-in Roles resolved from the package-shipped Markdown relative to this module.
 const BUILTIN_ROLE_NAMES = ["implementer", "reviewer", "scout"];
 /** Single-file Role parser shared by built-in and user roles. */
@@ -168,6 +216,11 @@ function parseRoleFile(file, raw) {
     }
     const frontmatter = parsed.frontmatter;
     rejectRetiredRoleIsolation(frontmatter.isolation, file);
+    for (const key of Object.keys(frontmatter)) {
+        if (!ROLE_FRONTMATTER_KEYS.includes(key)) {
+            throw new Error(`${file}: unknown Role frontmatter key ${JSON.stringify(key)}; expected ${ROLE_FRONTMATTER_KEYS.join(", ")}.`);
+        }
+    }
     const modelClass = roleModelClass(frontmatter.modelClass, file);
     return {
         name: parseRoleName(frontmatter.name, file),
@@ -196,35 +249,81 @@ export function loadBuiltinRole(name) {
 function builtinRoles() {
     return BUILTIN_ROLE_NAMES.map(loadBuiltinRole);
 }
+function claimedRoleName(file) {
+    try {
+        const { name } = parseFrontmatter(readFileSync(file, "utf8")).frontmatter;
+        if (typeof name === "string" && name.trim())
+            return name.trim();
+    }
+    catch { /* The file's own error is reported; fall back to its stem. */ }
+    return basename(file, ".md");
+}
 /**
- * Validated package-shipped Roles plus valid user roles from `config/pi-subagent`.
- * A user role with a built-in name overrides the default; duplicate names among
- * user files are an error. Missing user directory returns the built-ins.
+ * Package-shipped Roles plus user Roles from `config/pi-subagent`, with
+ * `roleDefaults` merged in. A user Role overrides a same-named built-in. Each
+ * invalid or duplicate user file is reported and makes its claimed name
+ * unavailable without hiding valid Roles. Malformed `roleDefaults` throws.
  */
-export function loadRoles(agentDir = getAgentDir()) {
-    const byName = new Map(builtinRoles().map((role) => [role.name, role]));
+export function loadRoleCatalog(agentDir = getAgentDir()) {
+    const defaults = readRoleDefaults(agentDir);
+    const builtins = new Map(builtinRoles().map((role) => [role.name, role]));
     const dir = extensionConfigDir("pi-subagent", agentDir);
-    let entries;
+    let entries = [];
     try {
         entries = readdirSync(dir, { withFileTypes: true });
     }
     catch (error) {
-        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
-            return [...byName.values()];
-        throw error;
+        if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    const user = new Map();
+    const errors = [];
+    for (const entry of entries
+        .filter((candidate) => candidate.name.endsWith(".md") && (candidate.isFile() || candidate.isSymbolicLink()))
+        .sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = join(dir, entry.name);
+        try {
+            const role = readRoleFile(file);
+            user.set(role.name, [...(user.get(role.name) ?? []), { file, role }]);
+        }
+        catch (error) {
+            errors.push({ file, name: claimedRoleName(file), message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    for (const [name, files] of user) {
+        if (files.length < 2)
+            continue;
+        for (const { file } of files)
+            errors.push({ file, name, message: `${file}: Duplicate Subagent role: ${name} (${files.map((item) => item.file).join(", ")}).` });
+    }
+    const blocked = new Set(errors.map(({ name }) => name));
+    const sources = new Map();
+    const byName = new Map();
+    for (const [name, role] of builtins) {
+        byName.set(name, user.get(name)?.[0]?.role ?? role);
+        sources.set(name, user.has(name) ? "user override" : "built-in");
+    }
+    for (const [name, files] of user) {
+        if (builtins.has(name))
+            continue;
+        byName.set(name, files[0].role);
+        sources.set(name, "user");
     }
-    const userRoles = entries
-        .filter((entry) => entry.name.endsWith(".md") && (entry.isFile() || entry.isSymbolicLink()))
-        .sort((a, b) => a.name.localeCompare(b.name))
-        .map((entry) => readRoleFile(join(dir, entry.name)));
-    const names = new Set();
-    for (const role of userRoles) {
-        if (names.has(role.name))
-            throw new Error(`Duplicate Subagent role: ${role.name}.`);
-        names.add(role.name);
-        byName.set(role.name, role);
+    for (const name of blocked) {
+        byName.delete(name);
+        sources.delete(name);
     }
-    return [...byName.values()];
+    return { roles: [...byName.values()].map((role) => applyRoleDefaults(role, defaults)), sources, errors };
+}
+/** Select one catalog Role, naming invalid files that claim it. */
+export function findRole(catalog, name) {
+    const role = catalog.roles.find((candidate) => candidate.name === name);
+    if (role)
+        return role;
+    const invalid = catalog.errors.filter((error) => error.name === name);
+    if (invalid.length)
+        throw new Error(`Subagent role ${name} is unavailable: ${invalid.map(({ message }) => message).join("; ")}`);
+    throw new Error(`Unknown Subagent role: ${name}. Available roles: ${catalog.roles.map((candidate) => candidate.name).join(", ") || "none"}.${catalog.errors.length ? ` ${catalog.errors.length} invalid Role file(s); run /subagent roles.` : ""}`);
 }
 export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
     let config;
@@ -376,9 +475,7 @@ export async function resolveConfiguredRoleLaunch(pi, ctx, input) {
     const roleName = parseRoleName(input.role);
     if (input.modelClass === undefined)
         throw new Error("Configured Role launch requires an explicit modelClass.");
-    const role = loadRoles().find((role) => role.name === roleName);
-    if (!role)
-        throw new Error(`Required configured Role ${roleName} is missing or ambiguous.`);
+    const role = findRole(loadRoleCatalog(), roleName);
     if (role.mcps?.length)
         loadRoleMcpConfig(getAgentDir(), role.mcps, { codemode: roleActivatesCodemode(role.tools) });
     const resources = await resolveRolePackageResources(role, ctx);

package/dist/integration-git.js

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { runGit } from "./git-process.js";
 import { CheckedGitRuntime } from "./git-runtime.js";
-import { createChildWorktree, inspectWorktreeDirty, WorktreeSetupError } from "./worktree.js";
+import { createChildWorktree, inspectWorktreeDirty, OWNED_BRANCH_PATTERN, WORKTREES_DIRNAME, WorktreeSetupError } from "./worktree.js";
 import { checkBatchPasses, reviewEvidencePasses, sameIdentity, } from "./schema.js";
 const oidPattern = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const diagnostic = (value) => value.trim().slice(0, 500);
@@ -52,8 +52,8 @@ async function ownershipMetadata(root, info, signal) {
     const repoRoot = await realpath(primary.slice("worktree ".length));
     if (await realpath(await requireGit(["rev-parse", "--show-toplevel"], root, signal)) !== canonical
         || info.repoRoot !== repoRoot || info.cwd !== info.path
-        || !/^pi-subagent\/subagent-[0-9a-f]{24}$/.test(info.branch)
-        || info.path !== join(repoRoot, ".worktrees", basename(info.branch))) {
+        || !OWNED_BRANCH_PATTERN.test(info.branch)
+        || info.path !== join(repoRoot, WORKTREES_DIRNAME, basename(info.branch))) {
         throw new Error("Git worktree is not an exact owned checkout of Main.");
     }
 }

package/dist/prune.d.ts

@@ -0,0 +1,50 @@
+import { type GitRunner } from "./git-process.ts";
+/** One reviewed pi-subagent branch, with its registered checkout when one exists. */
+export interface PruneItem {
+    branch: string;
+    tip: string;
+    path?: string;
+    prunable: boolean;
+    /** Why the item is prunable, or every exact blocker. */
+    reason: string;
+    /** Ignored entries as Git collapses them; removing the checkout deletes them. */
+    ignored: readonly string[];
+}
+export interface PruneOwnership {
+    /** The request or state that may still own a resource name (`subagent-<hex>`), if any. */
+    owner(name: string): string | undefined;
+    /** The live productive lease that blocks pruning, if any. */
+    lease?: string;
+}
+export interface PruneGuards {
+    /** Ownership and lease evidence across the repository's existing checkouts. */
+    ownership(checkouts: readonly string[]): Promise<PruneOwnership>;
+    /** Every Herdr pane; rejects when Herdr cannot be inspected. */
+    panes(): Promise<readonly {
+        paneId: string;
+        cwds: readonly string[];
+    }[]>;
+    /** The confirming session still owns the command; checked immediately before each removal step. */
+    current?(): boolean;
+}
+export type PruneRemoval = {
+    outcome: "removed" | "skipped" | "failed";
+    item: PruneItem;
+    reason: string;
+};
+/** Every pane in every Herdr workspace with its shell and foreground working directories. */
+export declare function listHerdrPanes(cwd: string): Promise<{
+    paneId: string;
+    cwds: string[];
+}[]>;
+/** Read-only review of every pi-subagent worker or integration branch and its checkout. */
+export declare function inspectPruneCandidates(root: string, mainCwd: string, guards: PruneGuards, run?: GitRunner): Promise<PruneItem[]>;
+/**
+ * Re-verify each reviewed prunable item immediately before removing its checkout, then delete its
+ * branch only at the reviewed tip. Ignored entries are deleted only when `allowIgnored` and all of
+ * them were in the review. Returns the repository checkouts that still exist.
+ */
+export declare function removePruneCandidates(root: string, mainCwd: string, reviewed: readonly PruneItem[], allowIgnored: boolean, guards: PruneGuards, run?: GitRunner): Promise<{
+    removals: PruneRemoval[];
+    checkouts: string[];
+}>;

package/dist/prune.js

@@ -0,0 +1,192 @@
+import { existsSync, realpathSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { createHerdrClient } from "@henryqw/pi-herdr";
+import { runGit } from "./git-process.js";
+import { runProcess } from "./process.js";
+import { inspectWorktreeDirty, OWNED_BRANCH_PATTERN, WORKTREES_DIRNAME } from "./worktree.js";
+const HERDR_TIMEOUT_MS = 30_000;
+const IN_PROGRESS_MARKERS = ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD", "BISECT_LOG", "rebase-merge", "rebase-apply", "sequencer"];
+async function requireGit(run, args, cwd) {
+    const result = await run(args, cwd);
+    if (result.code !== 0)
+        throw new Error(`git ${args[0]} failed (exit ${result.code}): ${result.stderr.trim().slice(0, 200)}`);
+    return result.stdout.trimEnd();
+}
+const within = (directory, path) => path === directory || path.startsWith(`${directory}${sep}`);
+/** Every pane in every Herdr workspace with its shell and foreground working directories. */
+export async function listHerdrPanes(cwd) {
+    const response = await createHerdrClient(runProcess).json(["pane", "list"], { cwd, timeoutMs: HERDR_TIMEOUT_MS });
+    const result = response.result;
+    if (result?.type !== "pane_list" || !Array.isArray(result.panes))
+        throw new Error("Herdr pane list response is malformed.");
+    return result.panes.map((pane) => {
+        const cwds = [pane.cwd, pane.foreground_cwd].filter((cwd) => typeof cwd === "string");
+        if (typeof pane.pane_id !== "string" || !cwds.length)
+            throw new Error("Herdr listed a pane without an ID or working directory.");
+        return { paneId: pane.pane_id, cwds };
+    });
+}
+async function snapshot(root, mainCwd, run) {
+    const checkouts = [];
+    let current;
+    for (const field of (await requireGit(run, ["worktree", "list", "--porcelain", "-z"], root)).split("\0")) {
+        if (field.startsWith("worktree "))
+            checkouts.push(current = { path: field.slice("worktree ".length), locked: false, missing: false });
+        else if (current && field.startsWith("branch refs/heads/"))
+            current.branch = field.slice("branch refs/heads/".length);
+        else if (current && (field === "locked" || field.startsWith("locked ")))
+            current.locked = true;
+        else if (current && (field === "prunable" || field.startsWith("prunable ")))
+            current.missing = true;
+    }
+    if (!checkouts[0])
+        throw new Error("Primary Git worktree is unavailable.");
+    const branches = new Map();
+    for (const line of (await requireGit(run, ["for-each-ref", "--format=%(refname:lstrip=2) %(objectname)", "refs/heads/"], root)).split("\n")) {
+        const [branch, tip] = line.split(" ");
+        if (branch && tip && OWNED_BRANCH_PATTERN.test(branch))
+            branches.set(branch, tip);
+    }
+    const targets = [{ label: "Main HEAD", head: await requireGit(run, ["rev-parse", "--verify", "HEAD^{commit}"], mainCwd) }];
+    const origin = await run(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], root);
+    if (origin.code === 0) {
+        const ref = origin.stdout.trim();
+        targets.push({ label: ref.replace(/^refs\/remotes\//, ""), head: await requireGit(run, ["rev-parse", "--verify", `${ref}^{commit}`], root) });
+    }
+    return { primary: checkouts[0].path, checkouts, branches, targets };
+}
+async function classify(snap, branch, mainCwd, ownership, panes, run, root) {
+    const tip = snap.branches.get(branch);
+    const name = basename(branch);
+    const ownedPath = join(snap.primary, WORKTREES_DIRNAME, name);
+    // A detached or switched owned checkout no longer names the branch; find it by its owned path too.
+    const checkout = snap.checkouts.find((item) => item.branch === branch) ?? snap.checkouts.find((item) => item.path === ownedPath);
+    const blockers = [];
+    if (checkout && checkout.branch !== branch)
+        blockers.push(`owned checkout is ${checkout.branch ? `on branch ${checkout.branch}` : "detached"}; inspect it manually`);
+    let ignored = [];
+    const owner = ownership.owner(name);
+    if (owner)
+        blockers.push(owner);
+    if (ownership.lease)
+        blockers.push(ownership.lease);
+    let merged;
+    for (const target of snap.targets) {
+        const result = await run(["merge-base", "--is-ancestor", tip, target.head], root);
+        if (result.code === 0) {
+            merged = target.label;
+            break;
+        }
+        if (result.code !== 1)
+            throw new Error(`git merge-base failed (exit ${result.code}): ${result.stderr.trim().slice(0, 200)}`);
+    }
+    if (!merged)
+        blockers.push(`branch has commits not in ${snap.targets.map(({ label }) => label).join(" or ")}`);
+    if (checkout) {
+        const path = checkout.path;
+        if (path !== ownedPath)
+            blockers.push("checkout is not at its owned .worktrees path");
+        if (checkout.locked)
+            blockers.push("checkout is locked");
+        if (checkout.missing || !existsSync(path))
+            blockers.push("checkout directory is missing; inspect it, then run git worktree prune");
+        else {
+            const real = realpathSync.native(path);
+            if (within(real, realpathSync.native(mainCwd)))
+                blockers.push("Main runs inside the checkout");
+            const gitDir = await requireGit(run, ["rev-parse", "--absolute-git-dir"], path);
+            const markers = IN_PROGRESS_MARKERS.filter((marker) => existsSync(join(gitDir, marker)));
+            if (markers.length)
+                blockers.push(`Git operation in progress (${markers.join(", ")})`);
+            const dirty = await inspectWorktreeDirty(path, run, false);
+            if (dirty.failure)
+                blockers.push(`checkout could not be inspected: ${dirty.failure}`);
+            else if (dirty.dirty)
+                blockers.push("checkout has tracked or untracked changes");
+            else if (dirty.initializedSubmodules)
+                blockers.push("checkout has initialized submodules; Git cannot remove it without force, so remove it manually");
+            if (typeof panes === "string")
+                blockers.push(`Herdr unavailable (${panes}); cannot prove no pane uses the checkout`);
+            else {
+                const used = panes.filter((pane) => pane.cwds.some((cwd) => within(path, cwd) || within(real, cwd)));
+                if (used.length)
+                    blockers.push(`Herdr pane ${used.map(({ paneId }) => paneId).join(", ")} works inside the checkout`);
+            }
+            ignored = (await requireGit(run, ["status", "--porcelain=v1", "-z", "--ignored=matching", "--untracked-files=normal"], path))
+                .split("\0").filter((entry) => entry.startsWith("!! ")).map((entry) => entry.slice(3));
+        }
+    }
+    return {
+        branch, tip, ...(checkout ? { path: checkout.path } : {}), prunable: !blockers.length, ignored,
+        reason: blockers.length ? blockers.join("; ") : `merged into ${merged}; ${checkout ? "clean checkout" : "no checkout"}`,
+    };
+}
+const existing = (snap) => snap.checkouts.filter((item) => !item.missing && existsSync(item.path)).map(({ path }) => path);
+async function evidence(root, mainCwd, guards, run) {
+    const snap = await snapshot(root, mainCwd, run);
+    const ownership = await guards.ownership(existing(snap));
+    let panes;
+    try {
+        panes = await guards.panes();
+    }
+    catch (error) {
+        panes = (error instanceof Error ? error.message : String(error)).slice(0, 200);
+    }
+    return { snap, ownership, panes };
+}
+/** Read-only review of every pi-subagent worker or integration branch and its checkout. */
+export async function inspectPruneCandidates(root, mainCwd, guards, run = runGit) {
+    const { snap, ownership, panes } = await evidence(root, mainCwd, guards, run);
+    const items = [];
+    for (const branch of [...snap.branches.keys()].sort())
+        items.push(await classify(snap, branch, mainCwd, ownership, panes, run, root));
+    return items;
+}
+async function removeOne(root, mainCwd, reviewed, allowIgnored, guards, run) {
+    const skip = (reason) => ({ outcome: "skipped", item: reviewed, reason });
+    const fail = (reason) => ({ outcome: "failed", item: reviewed, reason });
+    const { snap, ownership, panes } = await evidence(root, mainCwd, guards, run);
+    if (snap.branches.get(reviewed.branch) !== reviewed.tip)
+        return skip("branch was deleted or moved since review");
+    const fresh = await classify(snap, reviewed.branch, mainCwd, ownership, panes, run, root);
+    if (!fresh.prunable)
+        return skip(fresh.reason);
+    if (fresh.path !== reviewed.path)
+        return skip("checkout registration changed since review");
+    if (fresh.ignored.some((entry) => !allowIgnored || !reviewed.ignored.includes(entry)))
+        return skip("ignored content was not approved or changed since review");
+    const stale = () => guards.current !== undefined && !guards.current();
+    if (fresh.path) {
+        if (stale())
+            return skip("session or branch changed before removal; reopen /subagent prune");
+        // Git removes ignored content without --force; the checks above approved it.
+        const removed = await run(["worktree", "remove", fresh.path], root);
+        if (removed.code !== 0)
+            return fail(`git worktree remove failed: ${removed.stderr.trim().slice(0, 200)}`);
+        if (existsSync(fresh.path))
+            return fail("git worktree remove succeeded but the checkout remains");
+    }
+    if (stale())
+        return skip(`${fresh.path ? "checkout removed; " : ""}session or branch changed before branch deletion; branch kept`);
+    const deleted = await run(["update-ref", "-d", `refs/heads/${reviewed.branch}`, reviewed.tip], root);
+    if (deleted.code !== 0)
+        return fail(`${fresh.path ? "checkout removed; " : ""}branch kept: ${deleted.stderr.trim().slice(0, 200)}`);
+    return { outcome: "removed", item: reviewed, reason: fresh.reason };
+}
+/**
+ * Re-verify each reviewed prunable item immediately before removing its checkout, then delete its
+ * branch only at the reviewed tip. Ignored entries are deleted only when `allowIgnored` and all of
+ * them were in the review. Returns the repository checkouts that still exist.
+ */
+export async function removePruneCandidates(root, mainCwd, reviewed, allowIgnored, guards, run = runGit) {
+    const removals = [];
+    for (const item of reviewed) {
+        try {
+            removals.push(await removeOne(root, mainCwd, item, allowIgnored, guards, run));
+        }
+        catch (error) {
+            removals.push({ outcome: "failed", item, reason: (error instanceof Error ? error.message : String(error)).slice(0, 300) });
+        }
+    }
+    return { removals, checkouts: existing(await snapshot(root, mainCwd, run)) };
+}

package/dist/runner.d.ts

@@ -1,7 +1,10 @@
 import type { EphemeralSubagentExecutor } from "./ephemeral.ts";
+import type { PruneOwnership } from "./prune.ts";
 import { IntegrationGit } from "./integration-git.ts";
 import { type AllocationKind, type CheckCommand, type ChangesetTaskRequest, type CleanupKind, type ExecuteRequest, type ExecutionPolicySnapshot, type HostAllocationIntent, type HostAllocationPlan, type ModelClass, type ReviewEvidence, type ResumeRequest, type RunState, type TaskAttempt, type TaskRequest, type TaskState, type WorktreeAllocationIntent, type WorktreeAllocationPlan, type WorkspaceIdentity } from "./schema.ts";
 import { FileRunStore } from "./store.ts";
+/** One durable follow-up per attempt; the runner itself never commits, stages, stashes, or discards. */
+export declare const COMMIT_NUDGE_INSTRUCTION = "Your turn ended with uncommitted changes in your worktree. Commit the intended changes now so the worktree is clean, or explain in your reply why they must not be committed. Do not discard work.";
 export declare const CLEANUP_SAFETY_BUDGET_MS = 30000;
 export declare const TERMINATION_SAFETY_BUDGET_MS = 15000;
 export declare const STATUS_INSPECTION_BUDGET_MS = 5000;
@@ -65,6 +68,11 @@ export type WorkerResult = {
 } | {
     outcome: "blocked" | "not_prompted";
     diagnostic: string;
+}
+/** The exact turn finished in its valid owned worktree with tracked or untracked changes. */
+ | {
+    outcome: "uncommitted";
+    diagnostic: string;
 } | {
     outcome: "unknown" | "interrupted";
     diagnostic: string;
@@ -314,6 +322,11 @@ export declare class IsolatedRunner {
         invalidIds: string[];
         leaseBusy: boolean;
     }>;
+    /** Prune evidence across checkouts. A non-terminal state owns every resource name its saved text
+     * mentions; an unreadable state owns every name its raw text mentions, or every name when unreadable. */
+    pruneOwnership(checkouts: readonly string[]): Promise<PruneOwnership>;
+    /** After pruning, reconcile aborted requests that recorded a removed resource through the guarded abort path. */
+    reconcilePrunedAborts(checkouts: readonly string[], names: readonly string[]): Promise<string[]>;
     canFollowup(root: string, requestId: string, taskId: string): boolean;
     drainFollowups(root: string, requestId: string, taskId: string): string[];
     queueFollowup(root: string, requestId: string, taskId: string, instruction: string): string;