@hcflabs/pi-subagent 28.3.3 → 28.4.0

package/README.md

@@ -46,7 +46,7 @@ Commands, prompts, and UI are for you. Tools and the packaged skill are for Main
 | Direct status widget (`D`) | ui | Show direct workflows as a tree under `Main` with references, names, Role badges, status, routes, elapsed time, measured task tokens, cost, and tool activity. In fullscreen mode, a click on a working or finished worker row focuses that worker's verified Herdr pane. |
 | Isolated status widget (`I`) | ui | Show recorded task state, Role/model-class badges, and retained workspaces in the TUI. Readiness does not mean promotion. |
 
-`delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only. Main must make these decisions visibly; `codemode` scripts can call only `subagent_status`.
+`delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only. Main must make these decisions visibly; `codemode` scripts can call only `subagent_status` and `subagent_repos`.
 
 ### Direct workflow
 
@@ -269,6 +269,8 @@ Role Markdown files in `~/.pi/agent/config/pi-subagent/` require frontmatter and
 | `mcps` | Optional exact global server names from `~/.pi/agent/mcp.json`, using native `mcpServers` format. Omitted or `[]` denies access to `mcp.json` servers. Servers that Role extensions register always connect. |
 | body | Required system instructions |
 
+A Role's `modelClass` selects a Task Profile. When the profile has a primary and a fallback that resolve in Main, the worker selects the Task Profile Model `task/<profile>`. A retryable error on the primary then moves the worker to the fallback. The launch record names the primary route. A designated `model` uses no fallback.
+
 The package ships `implementer`, `reviewer`, and `scout`; same-name user Roles override built-ins. Roles define capabilities, not access or isolation. Unknown frontmatter keys invalidate that file and report its path and key. Other valid Roles load; duplicate names become unavailable. Delegation to an invalid file's claimed Role fails with that file's error. Inspect `/subagent roles`.
 
 The built-in reviewer answers exactly `PASS` when it finds no actionable correctness risk. Otherwise, each finding starts with a priority and a confidence (`high`, `medium`, or `low`), for example `[P1] confidence: high`. Then it gives file and line evidence, the trigger, the impact, and the smallest fix. Each finding blocks approval.

package/dist/index.d.ts

@@ -73,6 +73,11 @@ export interface PreparedRoleLaunch extends ResolvedRoleLaunch {
 export interface CreateRoleLaunchInput {
     role: Role;
     route: ResolvedTaskRoute;
+    /**
+     * Task Profile of the route. When set, the child selects the Task Profile Model `task/<profile>`,
+     * so a retryable error on the primary route moves the child to the fallback route.
+     */
+    failoverProfile?: ProfileName;
     extensions?: readonly string[];
     tools?: readonly string[];
     env?: Readonly<Record<string, string>>;

package/dist/index.js

@@ -6,7 +6,7 @@ import { createConfigStore, extensionConfigDir, field, formatConfigIssues, parse
 import { hasDisplayControlCharacters } from "./display-text.js";
 import { DEFAULT_MAX_TURNS } from "./ephemeral.js";
 import { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
-import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@hcflabs/pi-task-models";
+import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, TASK_PROFILE_MODELS_EXTENSION, taskProfileModelReference, } from "@hcflabs/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
 export { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
@@ -450,6 +450,14 @@ function resolveConfiguredRoute(ctx, profileName, profile) {
     }
     throw new Error(`No usable ${profileName} task model route. Run /task-models.`);
 }
+/** Return the profile when it has a primary and a fallback route that resolve in this session, so failover can help. */
+function failoverProfile(ctx, profileName, agentDir = getAgentDir()) {
+    const profile = loadTaskModelsConfig(agentDir).value.profiles[profileName];
+    if (!profile)
+        return undefined;
+    const usable = orderedProfileRoutes(profile).filter((route) => resolveTaskModelRoute(ctx, route) !== undefined);
+    return usable.length > 1 ? profileName : undefined;
+}
 export function resolveRoleSkills(pi, role) {
     const skills = new Map(pi.getCommands()
         .filter((command) => command.source === "skill")
@@ -512,6 +520,8 @@ function prepareRoleLaunchFromSkills(ctx, input, skills) {
         ROLE_MCP_EXTENSION,
         ...(role.tools.includes("git_read") ? [GIT_READ_EXTENSION] : []),
         ROLE_TOOLS_EXTENSION,
+        // The child runs with --no-extensions, so it loads the Task Profile Models only from this path.
+        ...(input.failoverProfile ? [TASK_PROFILE_MODELS_EXTENSION] : []),
     ];
     const env = Object.fromEntries(Object.entries(input.env ?? {}).map(([key, value]) => {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
@@ -527,7 +537,7 @@ function prepareRoleLaunchFromSkills(ctx, input, skills) {
     for (const skill of skills.paths)
         args.push("--skill", skill);
     args.push(`--${ROLE_TOOL_POLICY_FLAG}`, JSON.stringify(tools));
-    args.push("--model", modelReference(input.route.model));
+    args.push("--model", input.failoverProfile ? taskProfileModelReference(input.failoverProfile) : modelReference(input.route.model));
     if (input.route.thinkingLevel)
         args.push("--thinking", input.route.thinkingLevel);
     args.push(ctx.isProjectTrusted() ? "--approve" : "--no-approve");
@@ -546,11 +556,16 @@ function prepareRoleLaunchFromSkills(ctx, input, skills) {
 function prepareResolvedRoleLaunch(pi, ctx, input) {
     const { task, modelClass, agentDir, ...launchInput } = input;
     const selectedClass = modelClass ?? input.role.modelClass;
+    const route = selectedClass === undefined
+        ? resolveConfiguredTaskRoute(ctx, task, agentDir)
+        : resolveTaskRoute(ctx, selectedClass, agentDir);
+    // The route resolved, so the config loads. A task without a class uses its assigned or declared profile.
+    const profileName = selectedClass ?? loadTaskModelsConfig(agentDir).value.tasks[task.id] ?? task.defaultProfile;
+    const failover = failoverProfile(ctx, profileName, agentDir);
     return prepareRoleLaunchFromSkills(ctx, {
         ...launchInput,
-        route: selectedClass === undefined
-            ? resolveConfiguredTaskRoute(ctx, task, agentDir)
-            : resolveTaskRoute(ctx, selectedClass, agentDir),
+        route,
+        ...(failover ? { failoverProfile: failover } : {}),
     }, resolveRoleSkills(pi, input.role));
 }
 export function resolveRoleLaunch(pi, ctx, input) {
@@ -589,9 +604,12 @@ export async function resolveConfiguredRoleLaunch(pi, ctx, input) {
         ...namedSkills,
         paths: [...new Set([...namedSkills.paths, ...resources.skills])],
     };
+    const route = resolveTaskRoute(ctx, input.modelClass);
+    const failover = failoverProfile(ctx, input.modelClass);
     const prepared = prepareRoleLaunchFromSkills(ctx, {
         role: effectiveRole,
-        route: resolveTaskRoute(ctx, input.modelClass),
+        route,
+        ...(failover ? { failoverProfile: failover } : {}),
     }, skills);
     assertNoMissingRoleSkills(effectiveRole, prepared);
     const args = [

package/docs/orchestration.md

@@ -81,7 +81,7 @@ Direct `changeset` is rejected; use isolated mode for checked integration. Resou
 
 ### Dry run
 
-Set `"dryRun": true` on a direct or isolated `delegate_task` request to check it without a launch. The dry run does the same checks as a launch: request shape, Role lookup, route and model with thinking level, Skills, tools, MCP allowlist, Role extensions, config, and `continueFrom` eligibility. For an isolated request, it also checks the task graph and that Main is clean and committed. If the request has a changeset task, it also selects the Full suite, adds it to the final checks, and shows it. A failed check gives the same error as a launch.
+Set `"dryRun": true` on a direct or isolated `delegate_task` request to check it without a launch. The dry run does the same checks as a launch: request shape, Role lookup, route and model with thinking level, Skills, tools, MCP allowlist, Role extensions, config, and `continueFrom` eligibility. For an isolated request, it also checks the task graph and pins Main's committed branch, HEAD, and tree. Dirty files in Main do not block the dry run or admission. If the request has a changeset task, it also selects the Full suite, adds it to the final checks, and shows it. A failed check gives the same error as a launch.
 
 The result is a bounded plan. It shows each task's Role, resolved `provider/model`, thinking level, access or kind, dependencies, and checks. An isolated plan also shows the final checks. The dry run makes no Herdr call, Herdr tab, session record, saved state, worktree, lease, checkout admission, or follow-up. The plan lists each check it cannot do without such an effect as `Not checked: <reason>`. Examples are the Herdr host preflight, checkout admission, and the stop of a continued agent.
 
@@ -281,7 +281,7 @@ Every task declares `id`, `kind`, `role`, `modelClass`, `requirements`, `deliver
 
 Admission and worker-wave dispatch pin Main's exact committed branch, HEAD, and tree without inspecting or modifying its staged, unstaged, or untracked edits. Worker allocation verifies the same committed identity around worktree creation, including resumed waves; staged-dependent waves verify their clean integration snapshot. A dirty Main can therefore produce a checked retained candidate, but branch/HEAD drift stops new waves. The runner executes ready worker tasks concurrently, inspects clean committed candidates, runs preliminary task checks and optional preliminary judgment, then records ready candidates for Main. **It does not automatically integrate them.**
 
-The extension waits up to about 10 seconds for the shell of a new worker pane to finish startup before it starts Pi.
+The extension waits up to about 10 seconds for the shell of a new worker pane to finish startup. Then it waits up to about 20 more seconds for that shell to own the pane foreground, before the readiness probe and the Pi start.
 
 Main selects exact candidates through `subagent_stage` into an owned integration checkout in explicit order. Each stage is a committed merge of the candidate, not a mutation of Main. Conflicts retain the checkout for Main to resolve; `resolve` verifies the exact two-parent merge instead of replaying an uncertain merge. Main can explicitly run dependent tasks from an exact staged tip with `subagent_integrate advance` and stage their results afterward. Independent candidates may be staged without re-running workers.
 
@@ -396,13 +396,13 @@ If you removed resources outside Pi Subagent, abort can reconcile their absence.
 
 ### Recovery and state
 
-State version 5 lives privately under:
+State version 6 lives privately under:
 
 ```text
 <agent-dir>/config/pi-subagent/state/<repository-hash>/<request-id>.json
 ```
 
-Parsing rejects unknown properties, malformed evidence, invalid lineage, and v4 or older state without migration. Preserve old files and recover work manually. Writes are atomic. A productive lease prevents concurrent execution or resumption but permits status inspection and abort.
+Parsing rejects unknown properties, malformed evidence, invalid lineage, and v5 or older state without migration. Preserve old files and recover work manually. Writes are atomic. A productive lease prevents concurrent execution or resumption but permits status inspection and abort.
 
 `delegate_task`, `subagent_resume`, and `subagent_integrate advance` return a durable request ID after saving the wave. Work continues asynchronously. A saved worker attention state sends a follow-up to the launching session, including while siblings run. The wave also reports its final result.
 
@@ -600,4 +600,7 @@ Worktree finalization returns one of:
 - `retained`: exact commit and dirty measurements are known and work remains; or
 - `recovery`: cleanup or measurement needs deliberate action and reports only proved fields.
 
-No cleanup path uses `git clean`, force deletion, hidden fallback to Main, or deletion of unproved work. The one exception is user-confirmed discard: after the user selects **Close and delete worktrees (discard work)** in `/subagent` and confirms, it force-removes the reviewed owned worktrees.
+No cleanup path uses `git clean`, force deletion, hidden fallback to Main, or deletion of unproved work. There are two exceptions, and each needs user confirmation:
+
+- After the user selects **Close and delete worktrees (discard work)** in `/subagent` and confirms, the extension force-removes the reviewed owned worktrees.
+- After a separate confirmation in `/subagent prune`, the command force-removes the reviewed items that it marked as forceable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hcflabs/pi-subagent",
-  "version": "28.3.3",
+  "version": "28.4.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -74,7 +74,7 @@
     "@hcflabs/pi-herdr": "^0.7.0",
     "@hcflabs/pi-process": "^0.3.0",
     "@hcflabs/pi-repo": "^0.1.0",
-    "@hcflabs/pi-task-models": "^9.0.0",
+    "@hcflabs/pi-task-models": "^9.3.0",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {