@henryqw/pi-subagent 27.5.3 → 27.6.0

package/README.md

@@ -33,7 +33,7 @@ Commands and UI are for you. Tools and the packaged skill are for Main, except `
 | `/subagent roles` | command | List Role sources, resources, resolved model and thinking level, route errors, and file errors. Read-only; requires no Herdr pane. |
 | `/subagent prune` | command | Review remaining worker and integration branches and worktrees. Remove merged resources after confirmation. Requires a running Herdr server; without interactive UI, only reports. |
 | `/subagent recover` | command | Classify interrupted isolated work in the canonical repository. Send Main request IDs, blockers, and next actions. Requires no UI or Herdr pane. |
-| `delegate_task` | tool | Start authorized shared-checkout work or a durable isolated checked graph. |
+| `delegate_task` | tool | Start authorized shared-checkout work or a durable isolated checked graph. With `dryRun: true`, check the request and show the resolved plan without a launch. |
 | `subagent_status` | tool | Read saved isolated state, exact identities, failed review verdicts, and allowed continuation. Does not replay work. Supports structured output for `codemode`. |
 | `subagent_resume` | tool | Perform the reported `retry`, `verify`, or `finalize` continuation, not staging or integration. Same-worker correction retries accept optional `instruction` text. |
 | `subagent_stage` | tool | Stage, resolve, reject, or revise an exact candidate. Rejecting a staged candidate freezes its generation. |
@@ -41,7 +41,7 @@ Commands and UI are for you. Tools and the packaged skill are for Main, except `
 | `subagent_abort` | tool | Terminate an isolated request without discarding retained work. Retained candidates and integration work require release or proof of absence. |
 | `git_read` | tool | Let Role-declared children inspect bounded local Git evidence without Bash, tests, network access, or writes. Not available to Main. |
 | `pi-subagent` | skill | Guide Main through authorization, delegation, checks, integration, and recovery. |
-| Direct status widget (`D`) | ui | Show direct references, names, Role badges, status, routes, elapsed time, measured task tokens, and tool activity in the TUI. |
+| Direct status widget (`D`) | ui | Show direct references, names, Role badges, status, routes, elapsed time, measured task tokens, cost, and tool activity in the TUI. |
 | 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`.
@@ -82,7 +82,11 @@ Tasks in write requests must return one JSON completion object:
 
 `outcome` accepts `succeeded`, `failed`, or `blocked`; `answer` must be non-empty. Plain text, malformed completion, blocked work, or failure stops later dispatch. Success is the worker's report, not independent validation. Checkout admission depends on proved termination, not the reported outcome.
 
-The launch returns a task ID and first Herdr tab, not the answer. One follow-up delivers results when the workflow finishes. Busy Main receives it after its current turn; idle Main starts a turn. Failed partial output stays marked as partial, never success. Worker output carries no user authority.
+A write task can declare `"paths": ["src/**"]` with repo-relative globs. For each task in a write request, the result lists new commits and changed paths, and it flags changed paths outside `paths`. This is a report only, not enforcement, and it cannot exclude changes from other processes. For a read request, the result warns `checkout changed during task; result may be stale` when the checkout changed while the task ran. Outside a Git repository, the extension makes no report. See [Checkout change reports](./docs/orchestration.md#checkout-change-reports).
+
+To check a request before a launch, add `"dryRun": true`. The dry run does the launch checks and shows each task's Role, model, thinking level, access, and dependencies. It starts no worker and opens no tab. It also reserves no checkout and sends no follow-up. A failed check gives the same error as a launch. For the full list of checks, see [Dry run](./docs/orchestration.md#dry-run).
+
+The launch returns a task ID and first Herdr tab, not the answer. One follow-up delivers results when the workflow finishes. The results show the tokens and cost of each worker and the total cost of the request. Busy Main receives it after its current turn; idle Main starts a turn. Failed partial output stays marked as partial, never success. Worker output carries no user authority.
 
 To continue a finished worker, add `"continueFrom": "D7.1"` with the same `role`. This opens a new tab with the saved conversation and a new reference. Continue the newest reference from the original checkout and workspace. For eligibility and stop behavior, see [Continue or stop one direct worker](./docs/orchestration.md#continue-or-stop-one-direct-worker).
 
@@ -125,6 +129,10 @@ Keep the durable ID; Main can work or end its turn without polling. Inspect read
 
 Readiness requires preliminary checks and any task `judgment`; it does not permit promotion. Checks and judgments bind to exact Git identities. Staging, combined validation, and promotion require unchanged, clean Main at the pinned identity. Changed identities, conflicts, or uncertain outcomes block promotion and preserve evidence. A definitive combined check or review failure permits one committed integration correction, recorded with `subagent_integrate correct`, and another validation.
 
+Combined validation can reuse a passed preliminary check of a staged candidate. The candidate must have the same tree as the combined tip, and the check must have the identical command and argv. Then the final check does not run again. This usually occurs when you stage one candidate onto unchanged Main. Status shows each reused result and its candidate. Final judgment still runs.
+
+Reuse assumes that checks use only tracked content. Ignored files, for example `node_modules`, can be different between worktrees.
+
 The extension sends follow-ups when a candidate becomes ready, a worker needs attention, and the wave finishes. A missed follow-up does not authorize replay. Read [Isolated contract](./docs/orchestration.md#isolated-contract) and [Exact integration actions](./docs/orchestration.md#exact-integration-actions) for graph, judgment, revision, refresh, and release details.
 
 ### Inspect work

package/dist/direct-herdr.d.ts

@@ -8,10 +8,10 @@ export interface DirectHandle {
     sessionFile: string;
     prompt: string;
     answer(maxBytes: number): Promise<string>;
-    usageTokens(): Promise<number | undefined>;
+    usage(): Promise<DirectUsage>;
     /** Bounded assistant text from this turn so far; failure evidence only, never completion. */
     partialText(maxChars: number): Promise<string | undefined>;
-    /** Display-only activity from the last usageTokens() sample. */
+    /** Display-only activity from the last usage() sample. */
     readonly activity?: DirectToolActivity;
     cancel(): Promise<void>;
 }
@@ -19,6 +19,12 @@ export declare function exactDirectTerminalTurn(jsonl: string, prompt: string):
 /** Refuse continuation unless the saved session's exact recorded turn is terminal and no later user turn exists. */
 export declare function assertSettledDirectSession(sessionFile: string, turn: string): Promise<void>;
 export declare function exactDirectAnswer(jsonl: string, prompt: string, maxBytes?: number, requireSuccess?: boolean): string;
+/** Measured from one session read; each field is absent when no turn record carried it. */
+export interface DirectUsage {
+    tokens?: number;
+    /** Sum of assistant `usage.cost.total`. */
+    cost?: number;
+}
 export interface DirectToolActivity {
     pending: string[];
     latest?: {
@@ -26,14 +32,13 @@ export interface DirectToolActivity {
         durationMs?: number;
     };
 }
-export declare function directSessionUsage(jsonl: string, prompt: string): {
-    tokens?: number;
+export declare function directSessionUsage(jsonl: string, prompt: string): DirectUsage & {
     activity?: DirectToolActivity;
 };
 /** The last `maxChars` of assistant text in the exact prompt's turn; ignores a partial trailing entry. */
 export declare function directPartialText(jsonl: string, prompt: string, maxChars: number): string | undefined;
 /** One reader per handle; only complete, valid lines advance the byte offset. */
-export declare function createDirectSessionReader(sessionFile: string, prompt: string): Pick<DirectHandle, "usageTokens" | "partialText" | "activity">;
+export declare function createDirectSessionReader(sessionFile: string, prompt: string): Pick<DirectHandle, "usage" | "partialText" | "activity">;
 /** `turn` is the prompt's random turn identity; it proves which session turn a record owns.
  * `workspaceId` and `cwd` bind the record to its launching Herdr workspace and checkout. */
 export type DirectTab = Pick<DirectHandle, "name" | "tabId" | "paneId" | "sessionFile"> & {

package/dist/direct-herdr.js

@@ -126,6 +126,7 @@ class DirectSessionState {
     active = false;
     total = 0;
     observed = false;
+    cost;
     pending = new Map();
     latest;
     texts = [];
@@ -150,6 +151,7 @@ class DirectSessionState {
             if (this.active) {
                 this.total = 0;
                 this.observed = false;
+                this.cost = undefined;
                 this.pending.clear();
                 this.latest = undefined;
                 this.texts = [];
@@ -163,6 +165,9 @@ class DirectSessionState {
                     this.total += values.reduce((sum, value) => sum + value, 0);
                     this.observed = true;
                 }
+                const cost = usage.cost?.total;
+                if (typeof cost === "number" && Number.isFinite(cost) && cost >= 0)
+                    this.cost = (this.cost ?? 0) + cost;
             }
             if (Array.isArray(message.content))
                 for (const part of message.content) {
@@ -187,7 +192,7 @@ class DirectSessionState {
         return true;
     }
     usage() {
-        return { tokens: this.observed ? this.total : undefined,
+        return { tokens: this.observed ? this.total : undefined, cost: this.cost,
             activity: this.pending.size || this.latest ? { pending: [...this.pending.values()], latest: this.latest } : undefined };
     }
     partialText(maxChars) {
@@ -258,9 +263,9 @@ export function createDirectSessionReader(sessionFile, prompt) {
     const sample = () => reading ??= read().finally(() => { reading = undefined; });
     return {
         get activity() { return lastUsage.activity; },
-        async usageTokens() {
+        async usage() {
             lastUsage = await sample() ? state.usage() : {};
-            return lastUsage.tokens;
+            return { tokens: lastUsage.tokens, cost: lastUsage.cost };
         },
         async partialText(maxChars) {
             return await sample() ? state.partialText(maxChars) : undefined;
@@ -426,7 +431,7 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                 return {
                     name, tabId, paneId, sessionFile, prompt,
                     get activity() { return session.activity; },
-                    usageTokens: session.usageTokens,
+                    usage: session.usage,
                     partialText: session.partialText,
                     async answer(maxBytes) {
                         const readAnswer = async () => {

package/dist/integration-git.d.ts

@@ -1,5 +1,5 @@
 import { type WorktreeInfo } from "./worktree.ts";
-import { type CheckBatchEvidence, type CheckCommand, type ReviewEvidence, type WorkspaceIdentity } from "./schema.ts";
+import { type CheckBatchEvidence, type CheckCommand, type IntegrationCandidate, type ReviewEvidence, type WorkspaceIdentity } from "./schema.ts";
 export type StageReceipt = {
     previous: WorkspaceIdentity;
     worker: WorkspaceIdentity;
@@ -42,6 +42,8 @@ export declare class IntegrationGit {
         stages: readonly StageReceipt[];
         checks: CheckBatchEvidence;
         commands: readonly CheckCommand[];
+        /** Staged candidates that may supply reused final results; omitted accepts no reuse. */
+        sources?: readonly IntegrationCandidate[];
         review?: ReviewEvidence;
         criterion?: string;
         correction?: {

package/dist/integration-git.js

@@ -317,7 +317,8 @@ export class IntegrationGit {
             return { outcome: "blocked", failure: "No worker stages to promote." };
         const tip = input.correction ? (await this.inspectCorrection(root, integration, base, stages, input.correction.from, input.correction.to, signal), input.correction.to)
             : await this.inspectCombined(root, integration, base, stages, signal);
-        if (input.checks.phase !== "final" || !checkBatchPasses(input.checks, input.commands, tip)
+        const sources = (input.sources ?? []).filter((source) => stages.some((stage) => sameIdentity(stage.worker, source.tip)));
+        if (input.checks.phase !== "final" || !checkBatchPasses(input.checks, input.commands, tip, sources)
             || (input.criterion !== undefined && !reviewEvidencePasses(input.review, "final", input.criterion, base, tip))
             || (input.criterion === undefined && input.review !== undefined)) {
             return { outcome: "blocked", failure: "Exact combined-tip final checks/review evidence is missing or failed." };

package/dist/launch-runtime.d.ts

@@ -1,5 +1,5 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { CoordinatorRuntime, OperationContext, TransientLaunchHandle, VerifiedLaunch } from "./runner.ts";
+import type { CoordinatorRuntime, OperationContext, ResolvedRoute, TransientLaunchHandle, VerifiedLaunch } from "./runner.ts";
 import { type ExecuteRequest, type ModelClass, type WorkspaceIdentity } from "./schema.ts";
 export declare const ISOLATED_MODEL_TASK: {
     readonly id: "pi-subagent/isolatedRoleLaunch";
@@ -43,9 +43,11 @@ export declare class RoleLaunchRuntime implements CoordinatorRuntime {
     preflight(input: {
         request: ExecuteRequest;
         cwd: string;
+        dryRun?: boolean;
     }, context: OperationContext): Promise<{
         root: string;
         main: WorkspaceIdentity;
+        routes: ResolvedRoute[];
     }>;
     acquireLaunch(role: string, modelClass: ModelClass, context: OperationContext): Promise<TransientLaunchHandle<VerifiedLaunch>>;
 }

package/dist/launch-runtime.js

@@ -150,7 +150,7 @@ export class RoleLaunchRuntime {
         if (!rootInfo.isDirectory())
             throw new Error("Pi Subagent root must be an existing local directory.");
         context.signal?.throwIfAborted();
-        if (input.request.tasks.some((task) => task.kind === "changeset")) {
+        if (!input.dryRun && input.request.tasks.some((task) => task.kind === "changeset")) {
             await this.options.preflightHost?.({ request: input.request, cwd: input.cwd, root }, context);
         }
         const main = await this.options.inspectMainBase({ root }, context);
@@ -168,11 +168,14 @@ export class RoleLaunchRuntime {
         if (input.request.finalJudgment) {
             addRequired(input.request.finalJudgment.role, input.request.finalJudgment.modelClass);
         }
+        const routes = [];
         for (const [role, modelClasses] of required) {
-            for (const modelClass of modelClasses)
-                await this.prepareLaunch(role, modelClass, context);
+            for (const modelClass of modelClasses) {
+                const { launch } = await this.prepareLaunch(role, modelClass, context);
+                routes.push({ role, modelClass, model: launch.model, thinkingLevel: launch.thinkingLevel });
+            }
         }
-        return { root, main };
+        return { root, main, routes };
     }
     async acquireLaunch(role, modelClass, context) {
         const prepared = await this.prepareLaunch(role, modelClass, context);

package/dist/runner.d.ts

@@ -96,6 +96,14 @@ export interface VerifiedLaunch {
     readonly env: Readonly<Record<string, string>>;
     readonly tools: readonly string[];
 }
+export type ResolvedRoute = Pick<VerifiedLaunch, "role" | "modelClass" | "model" | "thinkingLevel">;
+/** A dry-run result: the normalized request and the resolved routes; no state exists for it. */
+export interface ExecutePlan {
+    request: ExecuteRequest;
+    root: string;
+    main: WorkspaceIdentity;
+    routes: readonly ResolvedRoute[];
+}
 export interface TransientLaunchHandle<Launch extends VerifiedLaunch = VerifiedLaunch> {
     readonly launch: Launch;
     cleanup(): Promise<void>;
@@ -109,12 +117,16 @@ export declare function withTransientLaunch<Launch extends VerifiedLaunch, Resul
 export interface CoordinatorRuntime {
     now(): number;
     randomToken(): string;
+    /** `dryRun` skips checks that call Herdr; every other check runs. */
     preflight(input: {
         request: ExecuteRequest;
         cwd: string;
+        dryRun?: boolean;
     }, context: OperationContext): Promise<{
         root: string;
         main: WorkspaceIdentity;
+        /** Resolved route of each distinct Role and model class, when the coordinator reports it. */
+        routes?: readonly ResolvedRoute[];
     }>;
     acquireLaunch(role: string, modelClass: ModelClass, context: OperationContext): Promise<TransientLaunchHandle<VerifiedLaunch>>;
 }
@@ -340,6 +352,10 @@ export declare class IsolatedRunner {
     private saveProductive;
     private callProductive;
     private rethrowStopped;
+    /** Every execute check before durable state; a dry run also skips the Herdr host preflight. */
+    private admitExecute;
+    /** Dry run of execute: no state, lock, lease, worktree, or Herdr call. */
+    plan(value: unknown, cwd: string, outerSignal?: AbortSignal): Promise<ExecutePlan>;
     execute(value: unknown, cwd: string, outerSignal?: AbortSignal): Promise<RunResponse>;
     resume(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
     /** Main selects an exact retained candidate; only the owned integration checkout is writable. */
@@ -350,6 +366,7 @@ export declare class IsolatedRunner {
     private releaseRejected;
     private releaseSuperseded;
     private cleanupPromoted;
+    private cleanupPromotedStage;
     private requireExactIntegration;
     listOrphanRequests(cwd: string): Promise<{
         invalidIds: string[];