@maxiaochao/pi-toolkit 0.13.7 → 0.13.9

package/packages/herdr-subagents/ARCHITECTURE.md

@@ -82,9 +82,12 @@ There is no global dispatcher, persisted background queue, blocked response lane
 
 Each task owns one Herdr pane and one single-task Pi process. Herdr first starts and detects the interactive Pi, then submits the prompt exactly once. At Pi’s final `agent_settled` boundary, the child extension records settled state but leaves the interactive process alive. The atomic report remains the authoritative task result. Early-finishing children remain visible while sibling tasks continue. Once the whole run settles, the orchestrator closes an unfocused owned tab immediately and defers a focused tab until the user leaves it, so Pi can restore the terminal normally.
 
+A completed round without a terminal report gets one child-side reminder at `agent_before_settle`. The marker is written before continuation. Another omission publishes an unconfirmed `missing_report` diagnostic; final errors use `child_error`. Native cancellation skips that boundary, so `agent_settled` publishes only `child_aborted`, never a model wake-up. Existing terminal reports are not replaced. None of this adds a parent monitoring loop.
+
 The child writes:
 
-- `results/<attempt-id>.md`
+- `attempt-results/<attempt-id>.md`
+- `attempts/<attempt-id>.reminded` (one durable reminder budget)
 - `reports/<attempt-id>.json`
 
 Both are attempt-scoped. The report is published with atomic rename. The orchestrator validates it, verifies the attempt identity, and promotes it to `report.json`.

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2026-10-23 - v0.7.5
+
+- bound missing-report recovery and close unconfirmed child outcomes
+- Regenerate real three-pane media and preserve configured model/authentication sources in the media parent launcher.
+
+- Ship the lifecycle test runtime resolver inside the Herdr package and execute all ten offline lifecycle cases from a real unpacked tarball without sibling packages.
+
+- At agent_before_settle, accept an existing terminal attempt report without another request; otherwise remind a completed child once to report existing work.
+- Persist the reminder before continuation so rounds and reloads cannot reset its budget.
+- Publish unconfirmed-result diagnostics after repeated omission or final provider error. Native cancellation bypasses before-settle, so agent_settled writes only a cancellation diagnostic, with no model wake-up.
+- Preserve report idempotency, interactive child lifetime, and parent-side report polling. Add offline native Pi lifecycle regressions.
+
 ## 2026-10-22 - v0.7.4
 
 - preserve Codex patch editing in child allowlists and hide the parent shortcut footer hint

package/packages/herdr-subagents/README.md

@@ -10,7 +10,7 @@ The implementation is intentionally small: one task state machine, one derived r
 
 https://github.com/user-attachments/assets/8ddf3ae6-a11a-492b-9cae-d9496ba65b67
 
-The reproducible source recording is retained as [`docs/demo.webm`](docs/demo.webm).
+The embedded video is the previously published walkthrough. The current release acceptance recording is retained in full as [`docs/demo.webm`](docs/demo.webm).
 
 ## Requirements and install
 
@@ -96,7 +96,8 @@ Records are stored under:
     system-prompt.md
     report.json
     reports/<attempt-id>.json
-    results/<attempt-id>.md
+    attempt-results/<attempt-id>.md
+    attempts/<attempt-id>.reminded
 ```
 
 The orchestrator is the only writer of `run.json`, `task.json`, and promoted `report.json`. The child only writes its attempt-scoped result and report.
@@ -348,3 +349,11 @@ Use `/herdr-subagents agents`, `/herdr-subagents models`, and `/herdr-subagents
 ## Development and tests
 
 See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packaging, and real Herdr smoke requirements. The real smoke preserves your configured `analyst` model, thinking level, and explicit extensions (including authentication providers) inside its isolated fixture; unrelated Persona settings remain isolated.
+
+## Missing reports and terminal diagnostics
+
+The child checks `reports/<attempt-id>.json` at `agent_before_settle`. A valid completed or failed report adds zero requests. A normally completed round without a report receives one reminder to submit existing results, not redo the task. `attempts/<attempt-id>.reminded` is persisted before continuing; rounds and reloads cannot reset it.
+
+A second omission produces a `failed` protocol report with `error: missing_report`, an explicitly **unconfirmed** result, and the child session path. This does not assert the delegated work itself failed. Final provider errors produce `child_error` without a reminder. Pi skips before-settle on cancellation; the child writes `child_aborted` at `agent_settled`, without waking the model or replacing an existing report. Parent-requested cancellation retains its existing cancelled lifecycle.
+
+The parent still waits for an atomic attempt report or process exit. It does not infer success from idle/settled or run a second reminder monitor. Report idempotency and focus-aware tab cleanup are unchanged.

package/packages/herdr-subagents/TESTING.md

@@ -57,3 +57,15 @@ This preserves authentication extensions such as `npm:@maxiaochao/pi-openai-acco
 `HERDR_SUBAGENTS_E2E_MODEL=provider/model` overrides only the smoke model; configured extensions remain loaded. Set `HERDR_SUBAGENTS_E2E_FOCUS_CLEANUP=1` to also verify deferred cleanup while focused and restoration of the original workspace/tab focus.
 
 For real smoke testing, verify that each child appears in a visible pane and can be focused and inspected. An early-finishing child must remain visible while sibling tasks continue. After the whole run settles, a focused child must remain at its restored Pi UI until focus leaves the run tab; the tab must then close automatically. Verify that the parent returns only after all requested tasks settle. Also verify cancellation closes the run tab and does not overwrite a report already atomically published.
+
+## Missing-report regressions
+
+`tests/report-boundary.mjs` checks completed/failed report idempotency, one durable reminder across rounds and extension reload, conflicting report rejection, unconfirmed diagnostics with a session path, and cancellation/error without continuation.
+
+`tests/report-lifecycle.mjs` uses the real installed Pi SDK and a fully offline provider. It covers ten cases: normal report, failed report, successful reminder, repeated omission, transient retry, exhausted retry, queued follow-up, another before-settle continuation, cancellation, and a fresh prompt from a settled listener. A normal report makes one request; a reminder adds at most one. Native cancellation does not emit before-settle and must still get a terminal diagnostic. These are native lifecycle checks, not a claim of real-Herdr pane/concurrency coverage.
+
+Use `PI_TEST_BINARY` to select Pi 1.4.0 for these checks rather than an older workspace-local Pi. No paid model or real credential is used by the new regression fixtures.
+
+`tests/standalone-package.mjs` packs the actual child package into a temporary directory, unpacks it outside the workspace, and runs all ten native/offline lifecycle scenarios there. `tests/runtime.mjs` resolves peers from the selected installed Pi; no sibling package or copied Pi runtime is needed.
+
+The media recorder also uses the effective analyst model, thinking level and explicit extension sources for its parent Pi. `PI_HERDR_MEDIA_MODEL` overrides only the model; required authentication extensions remain loaded. It does not copy or expose credentials.

package/packages/herdr-subagents/extensions/subagent-report.ts

@@ -4,7 +4,8 @@ import { dirname, resolve } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
+import { parseReport } from "../src/records.ts";
 import { resultPathForAttemptId } from "../src/result-path.ts";
 import { PARENT_PANE_ENV } from "../src/live-agent.ts";
 import { attemptReportPath, attemptStatePath, requireAttemptId, type AttemptState } from "../src/attempts.ts";
@@ -41,11 +42,53 @@ function writeAtomic(path: string, content: string): void {
 	renameSync(temporary, path);
 }
 
+function saveReport(taskDirectory: string, attemptId: string, params: Static<typeof ReportParams>) {
+	mkdirSync(taskDirectory, { recursive: true, mode: 0o700 });
+	const resultPath = resultPathForAttemptId(taskDirectory, attemptId);
+	const reportPath = attemptReportPath(taskDirectory, attemptId);
+	const documents = (params.documents ?? []).map((document) => ({
+		path: resolve(process.cwd(), document.path),
+		description: document.description,
+	}));
+	if (!documents.some((document) => document.path === resultPath)) {
+		documents.unshift({ path: resultPath, description: "Complete task result" });
+	}
+	const report = {
+		attemptId,
+		status: params.status,
+		summary: params.summary,
+		documents,
+		...(params.error ? { error: params.error } : {}),
+		reportedAt: new Date().toISOString(),
+	};
+	if (existsSync(reportPath)) {
+		const existing = JSON.parse(readFileSync(reportPath, "utf8")) as Record<string, unknown>;
+		const comparable = ({ reportedAt: _reportedAt, ...value }: Record<string, unknown>) => value;
+		const sameReport = JSON.stringify(comparable(existing)) === JSON.stringify(comparable(report));
+		const sameResult = existsSync(resultPath) && readFileSync(resultPath, "utf8") === params.result;
+		if (!sameReport || !sameResult) throw new Error("Conflicting subagent_report already exists for this task.");
+	} else {
+		writeAtomic(resultPath, params.result);
+		writeAtomic(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+	}
+	return report;
+}
+
 function currentAttemptId(taskDirectory: string): string {
 	const task = JSON.parse(readFileSync(resolve(taskDirectory, "task.json"), "utf8")) as { currentAttemptId?: unknown };
 	return requireAttemptId(task.currentAttemptId);
 }
 
+function saveUnconfirmed(taskDirectory: string, attemptId: string, reason: string, sessionFile: string | undefined): void {
+	saveReport(taskDirectory, attemptId, {
+		status: "failed",
+		summary: `${reason}: delegated result is unconfirmed; inspect the child session.`,
+		result: `No terminal subagent_report was submitted. Diagnostic: ${reason}.\nThis does not establish whether the delegated work succeeded or failed.\nChild session: ${sessionFile ?? "unavailable"}\n`,
+		error: reason,
+		documents: sessionFile ? [{ path: sessionFile, description: "Child session with unconfirmed task results" }] : [],
+	});
+}
+
 function writeAttemptState(taskDirectory: string, attemptId: string, state: AttemptState): void {
 	writeAtomic(attemptStatePath(taskDirectory, attemptId), `${JSON.stringify({ attemptId, state, at: new Date().toISOString() }, null, 2)}\n`);
 }
@@ -72,9 +115,47 @@ export default function (pi: ExtensionAPI) {
 		writeAttemptState(taskDirectory, activeAttemptId, "working");
 	});
 	pi.on("agent_start", () => reportHerdrState("working"));
-	pi.on("agent_settled", (_event, ctx) => {
+	pi.on("agent_before_settle", (event, ctx) => {
+		const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
+		if (!taskDirectory) return;
+		const attemptId = activeAttemptId ?? currentAttemptId(taskDirectory);
+		const reportPath = attemptReportPath(taskDirectory, attemptId);
+		if (existsSync(reportPath)) {
+			const report = parseReport(JSON.parse(readFileSync(reportPath, "utf8")), reportPath);
+			if (report.attemptId !== attemptId || report.status === "blocked") throw new Error("Invalid terminal attempt report.");
+			return; // A valid failed report is terminal too. Never ask for it again.
+		}
+		if (event.outcome === "completed") {
+			const reminderPath = resolve(taskDirectory, "attempts", `${attemptId}.reminded`);
+			mkdirSync(dirname(reminderPath), { recursive: true, mode: 0o700 });
+			try {
+				// Persist before continuing. Neither a new round nor /reload resets this budget.
+				writeFileSync(reminderPath, new Date().toISOString(), { flag: "wx", mode: 0o600 });
+				return {
+					entries: [...event.entries, {
+						type: "custom_message" as const,
+						customType: "herdr-subagents-missing-report",
+						content: "Do not redo the task. Submit the results you already have with subagent_report now. If you cannot confirm completion, report failed and explain what is unconfirmed.",
+						display: true,
+					}],
+					continue: true,
+				};
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			}
+		}
+		const reason = event.outcome === "completed" ? "missing_report" : event.outcome === "aborted" ? "child_aborted" : "child_error";
+		saveUnconfirmed(taskDirectory, attemptId, reason, ctx.sessionManager.getSessionFile());
+		// Cancellation and final provider errors receive a diagnostic, never a wake-up.
+	});
+	pi.on("agent_settled", (event, ctx) => {
 		const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
 		if (taskDirectory && activeAttemptId) {
+			// Pi skips before-settle on cancellation. Close the protocol without
+			// claiming the work failed, replacing a report, or requesting more tokens.
+			if (event.aborted && !existsSync(attemptReportPath(taskDirectory, activeAttemptId))) {
+				saveUnconfirmed(taskDirectory, activeAttemptId, "child_aborted", ctx.sessionManager.getSessionFile());
+			}
 			writeAttemptState(taskDirectory, activeAttemptId, "settled");
 		}
 		// Keep the interactive child alive at Pi's final automatic-work boundary.
@@ -121,34 +202,7 @@ export default function (pi: ExtensionAPI) {
 			const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
 			if (!taskDirectory) throw new Error("PI_HERDR_SUBAGENTS_TASK_DIR is not set");
 			const attemptId = activeAttemptId ?? currentAttemptId(taskDirectory);
-			mkdirSync(taskDirectory, { recursive: true, mode: 0o700 });
-			const resultPath = resultPathForAttemptId(taskDirectory, attemptId);
-			const reportPath = attemptReportPath(taskDirectory, attemptId);
-			const documents = (params.documents ?? []).map((document) => ({
-				path: resolve(process.cwd(), document.path),
-				description: document.description,
-			}));
-			if (!documents.some((document) => document.path === resultPath)) {
-				documents.unshift({ path: resultPath, description: "Complete task result" });
-			}
-			const report = {
-				attemptId,
-				status: params.status,
-				summary: params.summary,
-				documents,
-				...(params.error ? { error: params.error } : {}),
-				reportedAt: new Date().toISOString(),
-			};
-			if (existsSync(reportPath)) {
-				const existing = JSON.parse(readFileSync(reportPath, "utf8")) as Record<string, unknown>;
-				const comparable = ({ reportedAt: _reportedAt, ...value }: Record<string, unknown>) => value;
-				const sameReport = JSON.stringify(comparable(existing)) === JSON.stringify(comparable(report));
-				const sameResult = existsSync(resultPath) && readFileSync(resultPath, "utf8") === params.result;
-				if (!sameReport || !sameResult) throw new Error("Conflicting subagent_report already exists for this task.");
-			} else {
-				writeAtomic(resultPath, params.result);
-				writeAtomic(reportPath, `${JSON.stringify(report, null, 2)}\n`);
-			}
+			const report = saveReport(taskDirectory, attemptId, params);
 			return {
 				content: [{ type: "text" as const, text: `${params.status}: ${params.summary}` }],
 				details: report,

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [
@@ -37,7 +37,7 @@
     "typebox": "*"
   },
   "scripts": {
-    "test": "node --experimental-strip-types tests/config.mjs && node --experimental-strip-types tests/core-state-machine.mjs && node --experimental-strip-types tests/real-herdr-config.test.mjs",
+    "test": "node --experimental-strip-types tests/config.mjs && node --experimental-strip-types tests/core-state-machine.mjs && node --experimental-strip-types tests/report-boundary.mjs && node --experimental-strip-types tests/report-lifecycle.mjs && node tests/standalone-package.mjs && node --experimental-strip-types tests/real-herdr-config.test.mjs",
     "test:real-herdr": "node --experimental-strip-types tests/real-herdr-smoke.mjs",
     "load-test": "env -u PI_HERDR_SUBAGENTS_CHILD \"${PI_TEST_BINARY:-pi}\" -ne -ns --no-session -e ./tests/extension-contract.ts && env -u PI_HERDR_SUBAGENTS_CHILD \"${PI_TEST_BINARY:-pi}\" -ne -ns --no-session -e ./extensions/herdr-subagents.ts && node --experimental-strip-types tests/extension-sources-load.mjs",
     "test:legacy": "node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types tests/cleanup-timing.mjs"

package/packages/herdr-subagents/tests/report-boundary.mjs

@@ -0,0 +1,83 @@
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import registerReport from "../extensions/subagent-report.ts";
+
+const root = mkdtempSync(join(tmpdir(), "herdr-report-boundary-"));
+const previous = process.env.PI_HERDR_SUBAGENTS_TASK_DIR;
+process.env.PI_HERDR_SUBAGENTS_TASK_DIR = root;
+const sessionFile = join(root, "session.jsonl");
+writeFileSync(sessionFile, "");
+const ctx = { sessionManager: { getSessionFile: () => sessionFile }, isIdle: () => true };
+function fixture() {
+  const handlers = new Map();
+  let tool;
+  registerReport({
+    on: (name, handler) => handlers.set(name, handler),
+    registerTool: (value) => { tool = value; },
+    registerCommand() {}, registerShortcut() {}, events: { on() {} },
+  });
+  return { handlers, tool };
+}
+function attempt() {
+  const id = randomUUID();
+  writeFileSync(join(root, "task.json"), JSON.stringify({ currentAttemptId: id }));
+  return { id, report: join(root, "reports", `${id}.json`) };
+}
+const boundary = (outcome = "completed") => ({ outcome, entries: [], continue: false, context: { canContinue: true } });
+try {
+  const f = fixture();
+  assert.equal(typeof f.handlers.get("agent_before_settle"), "function", "child must handle the real pre-settlement boundary");
+  for (const status of ["completed", "failed"]) {
+    const a = attempt();
+    await f.handlers.get("before_agent_start")();
+    const input = { status, summary: status, result: "Already done", ...(status === "failed" ? { error: "Expected" } : {}) };
+    await f.tool.execute("first", input);
+    const original = readFileSync(a.report, "utf8");
+    assert.equal(await f.handlers.get("agent_before_settle")(boundary(), ctx), undefined);
+    await f.tool.execute("repeat", input);
+    await assert.rejects(() => f.tool.execute("conflict", { ...input, summary: "different" }), /Conflicting/);
+    assert.equal(readFileSync(a.report, "utf8"), original, "normal and failed reports need no extra request or replacement");
+  }
+  const a = attempt();
+  await f.handlers.get("before_agent_start")();
+  const reminder = await f.handlers.get("agent_before_settle")(boundary(), ctx);
+  assert.equal(reminder.continue, true);
+  assert.match(JSON.stringify(reminder.entries), /Do not redo|do not redo/);
+  assert.equal(existsSync(a.report), false, "a reminder is not a completion report");
+  // A new round and even extension reload must not reset the per-attempt budget.
+  const reloaded = fixture();
+  await reloaded.handlers.get("before_agent_start")();
+  assert.equal(await reloaded.handlers.get("agent_before_settle")(boundary(), ctx), undefined);
+  const diagnostic = JSON.parse(readFileSync(a.report, "utf8"));
+  assert.equal(diagnostic.status, "failed");
+  assert.equal(diagnostic.error, "missing_report");
+  assert.match(diagnostic.summary, /unconfirmed/);
+  assert.ok(diagnostic.documents.some(({ path }) => path === sessionFile));
+  assert.equal(await reloaded.handlers.get("agent_before_settle")(boundary(), ctx), undefined);
+
+  for (const outcome of ["aborted", "error"]) {
+    const current = attempt();
+    const run = fixture();
+    await run.handlers.get("before_agent_start")();
+    assert.equal(await run.handlers.get("agent_before_settle")(boundary(outcome), ctx), undefined, `${outcome}: do not wake or retry the child`);
+    const report = JSON.parse(readFileSync(current.report, "utf8"));
+    assert.equal(report.status, "failed");
+    assert.equal(report.error, outcome === "aborted" ? "child_aborted" : "child_error");
+    assert.match(report.summary, /unconfirmed/);
+  }
+  const repaired = attempt();
+  const run = fixture();
+  await run.handlers.get("before_agent_start")();
+  assert.equal((await run.handlers.get("agent_before_settle")(boundary(), ctx)).continue, true);
+  await run.tool.execute("repair", { status: "completed", summary: "Recovered existing work", result: "Existing result" });
+  assert.equal(await run.handlers.get("agent_before_settle")(boundary(), ctx), undefined);
+  assert.equal(JSON.parse(readFileSync(repaired.report, "utf8")).status, "completed");
+  console.log("PASS report boundary: zero-request completion, one durable reminder, unconfirmed failure, cancellation/error, idempotency");
+} finally {
+  if (previous === undefined) delete process.env.PI_HERDR_SUBAGENTS_TASK_DIR;
+  else process.env.PI_HERDR_SUBAGENTS_TASK_DIR = previous;
+  rmSync(root, { recursive: true, force: true });
+}

package/packages/herdr-subagents/tests/report-lifecycle.mjs

@@ -0,0 +1,69 @@
+// Native Pi lifecycle regression with an offline provider; no Herdr panes or paid requests.
+import "./runtime.mjs";
+import assert from 'node:assert/strict';
+import {randomUUID} from 'node:crypto';
+import {mkdtempSync,mkdirSync,writeFileSync,readFileSync,existsSync,rmSync} from 'node:fs';
+import {join} from 'node:path';
+import {tmpdir} from 'node:os';
+const {createAgentSession,DefaultResourceLoader,ModelRuntime,SessionManager,SettingsManager}=await import('@earendil-works/pi-coding-agent');
+const {createAssistantMessageEventStream}=await import('@earendil-works/pi-ai');
+const {default:childReport}=await import('../extensions/subagent-report.ts');
+// Real Pi lifecycle, offline provider. No Herdr panes, no delegated model, no network.
+delete process.env.HERDR_ENV;delete process.env.HERDR_SOCKET_PATH;
+const root=mkdtempSync(join(tmpdir(),'pi-native-settled-review-'));
+process.env.PI_CODING_AGENT_DIR=root;
+const cases=['reported','failed_report','remind_success','normal_no_report','transient_retry','retry_exhausted','queued_followup','boundary_continue','abort','settled_hook_new_prompt'];
+try{
+ for(const scenario of cases){
+  const dir=join(root,scenario);mkdirSync(dir);
+  const attemptId=randomUUID();const statePath=join(dir,'attempts',attemptId+'.json');
+  process.env.PI_HERDR_SUBAGENTS_TASK_DIR=dir;
+  writeFileSync(join(dir,'task.json'),JSON.stringify({currentAttemptId:attemptId}));
+  const trace=[],states=[],errors=[],inputs=[];let requests=0,ended=0,boundaries=0,settled=0;
+  const entered=Promise.withResolvers();let session;
+  const runtime=await ModelRuntime.create({authPath:join(dir,'auth.json'),modelsPath:join(dir,'models.json'),refreshOnCreate:false});
+  runtime.registerProvider('review',{name:'Offline lifecycle fixture',baseUrl:'http://127.0.0.1:1',api:'review',apiKey:'fixture-not-secret',models:[{id:'offline',name:'Offline',reasoning:false,input:['text'],contextWindow:128000,maxTokens:4096,cost:{input:0,output:0,cacheRead:0,cacheWrite:0}}],
+   streamSimple(model,context,options){
+    inputs.push(structuredClone(context.messages));requests++;const index=requests;trace.push('request:'+index);entered.resolve();const stream=createAssistantMessageEventStream();
+    void(async()=>{
+     let reason='stop',error;
+     if(scenario==='abort'){if(!options.signal.aborted)await new Promise(r=>options.signal.addEventListener('abort',r,{once:true}));reason='aborted';error='Request was aborted';}
+     else if((scenario==='transient_retry'&&index===1)||scenario==='retry_exhausted'){reason='error';error='500 Internal Server Error';}
+     const reportNow=scenario==='reported'||scenario==='failed_report'||(scenario==='remind_success'&&index===2);
+     const message={role:'assistant',api:model.api,provider:model.provider,model:model.id,timestamp:Date.now(),content:reportNow?[{type:'toolCall',id:'fixture-report',name:'subagent_report',arguments:{status:scenario==='failed_report'?'failed':'completed',summary:'Offline test report',result:'Offline complete result'}}]:reason==='stop'?[{type:'text',text:'A normal final answer without subagent_report'}]:[],stopReason:reportNow?'toolUse':reason,...(error?{errorMessage:error}:{}),usage:{input:1,output:1,cacheRead:0,cacheWrite:0,totalTokens:2,cost:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0}}};
+     stream.push({type:'start',partial:message});
+     stream.push(reason==='stop'?{type:'done',reason:message.stopReason,message}:{type:'error',reason,error:message});
+    })().catch(e=>{console.error(e);process.exitCode=1});return stream;
+   }
+  });
+  const settingsManager=SettingsManager.inMemory({retry:{enabled:true,maxRetries:1,baseDelayMs:1,maxDelayMs:1},compaction:{enabled:false},cacheWarming:'off'});
+  const loader=new DefaultResourceLoader({cwd:dir,agentDir:dir,settingsManager,noExtensions:true,noSkills:true,noPromptTemplates:true,noThemes:true,noContextFiles:true,extensionFactories:[childReport,pi=>{
+   pi.on('before_agent_start',()=>trace.push('before_agent_start'));
+   pi.on('agent_start',()=>trace.push('agent_start'));
+   pi.on('agent_end',()=>{trace.push('agent_end');ended++;if(scenario==='queued_followup'&&ended===1)pi.sendUserMessage('Queued followup',{deliverAs:'followUp'});});
+   pi.on('agent_before_settle',event=>{trace.push('before_settle:'+event.outcome);boundaries++;if(scenario==='boundary_continue'&&boundaries===1)return {entries:[...event.entries,{type:'custom_message',customType:'review',content:'One continuation',display:false}],continue:true};});
+   pi.on('agent_settled',(event,ctx)=>{settled++;trace.push('agent_settled:'+event.aborted);states.push({aborted:event.aborted,idle:ctx.isIdle(),file:JSON.parse(readFileSync(statePath,'utf8')),requests});if(scenario==='settled_hook_new_prompt'&&settled===1)pi.sendUserMessage('New prompt from settlement hook');});
+  }]});
+  await loader.reload();
+  session=(await createAgentSession({cwd:dir,agentDir:dir,modelRuntime:runtime,model:runtime.getModel('review','offline'),resourceLoader:loader,settingsManager,sessionManager:SessionManager.create(dir,dir),tools:['subagent_report']})).session;
+  session.extensionRunner.onError(e=>errors.push(e));
+  try{
+   await session.bindExtensions({});
+   const running=session.prompt('Run offline lifecycle check');
+   if(scenario==='abort'){await entered.promise;await session.abort();}
+   await running;
+   assert.equal(errors.length,0,JSON.stringify(errors));
+   const expectedRequests={reported:1,failed_report:1,remind_success:2,normal_no_report:2,transient_retry:3,retry_exhausted:2,queued_followup:3,boundary_continue:2,abort:1,settled_hook_new_prompt:3}[scenario];
+   assert.equal(requests,expectedRequests,scenario);
+   assert.equal(settled,scenario==='settled_hook_new_prompt'?2:1,scenario);
+   assert.ok(states.every(s=>s.aborted===(scenario==='abort')));
+   const report=JSON.parse(readFileSync(join(dir,'reports',attemptId+'.json'),'utf8'));
+   assert.equal(report.status,['reported','remind_success'].includes(scenario)?'completed':'failed');
+   if(['abort','retry_exhausted'].includes(scenario))assert.equal(inputs.some(input=>JSON.stringify(input).includes('Do not redo the task')),false);
+   if(!['reported','failed_report','remind_success'].includes(scenario))assert.ok(report.documents.some(document=>document.path===session.sessionManager.getSessionFile()));
+   if(scenario==='remind_success')assert.ok(JSON.stringify(inputs[1]).includes('Do not redo the task'));
+   assert.ok(trace.indexOf('agent_end')<trace.indexOf('before_settle:completed')||['abort','retry_exhausted'].includes(scenario));
+   console.log(JSON.stringify({scenario,requests,agentEnds:ended,settledEvents:settled,trace,states:states.map(({file,...s})=>({...s,fileState:file.state})),reportExists:existsSync(join(dir,'reports',attemptId+'.json'))}));
+  }finally{await session.abort();await session.extensionRunner.emit({type:'session_shutdown',reason:'quit'});session.dispose();}
+ }
+}finally{rmSync(root,{recursive:true,force:true});}

package/packages/herdr-subagents/tests/runtime.mjs

@@ -0,0 +1,26 @@
+// Package-local host-peer resolution so the packed lifecycle test needs no sibling package.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { delimiter, dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const hostPath = (process.env.PATH ?? "").split(delimiter).filter((entry) => !entry.endsWith("node_modules/.bin")).join(delimiter);
+const binary = process.env.PI_TEST_BINARY || execFileSync("sh", ["-c", "command -v pi"], {
+	encoding: "utf8", env: { ...process.env, PATH: hostPath },
+}).trim();
+let root = dirname(realpathSync(binary));
+while (!existsSync(join(root, "package.json")) || JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name !== "@earendil-works/pi-coding-agent") {
+	const parent = dirname(root);
+	if (parent === root) throw new Error(`Cannot locate Pi runtime next to ${binary}. Set PI_TEST_BINARY to the installed Pi executable.`);
+	root = parent;
+}
+const hostURL = pathToFileURL(join(root, "dist/index.js")).href;
+const peers = new Set(["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai", "@earendil-works/pi-tui", "typebox"]);
+registerHooks({
+	resolve(specifier, context, nextResolve) {
+		return peers.has(specifier)
+			? nextResolve(specifier, { ...context, parentURL: hostURL })
+			: nextResolve(specifier, context);
+	},
+});

package/packages/herdr-subagents/tests/standalone-package.mjs

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const root = mkdtempSync(join(tmpdir(), "herdr-standalone-"));
+try {
+	const source = resolve(import.meta.dirname, "..");
+	const [packed] = JSON.parse(execFileSync("npm", [
+		"pack", source, "--ignore-scripts", "--json", "--pack-destination", root,
+	], { cwd: root, encoding: "utf8" }));
+	execFileSync("tar", ["-xzf", join(root, packed.filename), "-C", root]);
+	const output = execFileSync(process.execPath, ["--experimental-strip-types", "tests/report-lifecycle.mjs"], {
+		cwd: join(root, "package"), encoding: "utf8", timeout: 30000,
+	});
+	const results = output.trim().split("\n").map((line) => JSON.parse(line));
+	assert.equal(results.length, 10, "all native lifecycle cases must execute outside the workspace");
+	assert.ok(results.every((result) => result.reportExists));
+	console.log("PASS standalone Herdr tarball: ten native offline lifecycle cases without sibling packages");
+} finally {
+	rmSync(root, { recursive: true, force: true });
+}

package/packages/worktree/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- Return Git's canonical worktree root for already-active create calls made from a nested directory; preserve the dirty flag.
+
 ## 2026-10-12 - v0.4.0
 
 - Replace CLI start and prepare with the create-only command

package/packages/worktree/README.md

@@ -72,3 +72,7 @@ pi-worktree prune
 `create` 是幂等接口；`create --json` 供 Extension 和其他宿主使用，返回 `created`、`attached`、`reused` 或 `already-active`，以及绝对路径、分支和 dirty 状态。已有 worktree 会复用；已存在但未挂载的同名分支会挂载；stale 注册、非法名称和路径冲突会显式失败。
 
 Agent 用法见 `skills/pi-worktree/SKILL.md`。测试流程、夹具和结果见 [TESTING.md](TESTING.md)。
+
+## Already-active paths
+
+`pi-worktree create --json <current-worktree-name>` returns the canonical Git worktree root, even when called from a nested directory. The `already-active` status and whole-worktree `dirty` flag remain unchanged. The extension uses the same CLI result.

package/packages/worktree/TESTING.md

@@ -24,3 +24,7 @@
 ## 最近验证结果
 
 验收要求全部 Node/shell 断言通过，Extension 能被 Pi 单独加载，且 `npm pack --dry-run` 包含 `bin/`、`extensions/`、`skills/` 和 `scripts/install.mjs`。
+
+## Review regressions
+
+The CLI integration suite also calls `create --json` from a nested linked-worktree directory. It asserts `already-active`, the canonical worktree root, and the whole-worktree dirty flag. Load the extension with `pi -ne -ns --no-session -e ./packages/worktree/extensions/worktree.ts`; this package has no `load-test` npm script.

package/packages/worktree/bin/pi-worktree

@@ -246,7 +246,7 @@ create_wt() {
     [[ "$current_branch" == "$name" ]] \
       || die "already inside linked worktree '$current_branch'; return to the main checkout first"
     CREATE_STATUS="already-active"
-    CREATE_DIR=$(pwd -P)
+    CREATE_DIR=$(cd "$(git rev-parse --show-toplevel)" && pwd -P)
     CREATE_BRANCH="$current_branch"
     CREATE_DIRTY=false
     if [[ -n "$(git status --porcelain)" ]]; then CREATE_DIRTY=true; fi

package/packages/worktree/tests/run-tests.sh

@@ -95,6 +95,16 @@ node -e '
   if (value.status !== "already-active" || value.dirty !== true) process.exit(1);
 ' "$ROOT/active.json"
 
+mkdir -p .worktrees/prepared/nested/path
+(cd .worktrees/prepared/nested/path && bash "$PACKAGE_DIR/bin/pi-worktree" create --json prepared) > "$ROOT/active-subdir.json"
+node -e '
+  const fs = require("node:fs");
+  const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (value.status !== "already-active" || value.path !== process.argv[2] || value.dirty !== true) {
+    throw new Error("already-active must return the worktree root even when called from a subdirectory");
+  }
+' "$ROOT/active-subdir.json" "$ROOT/repo/.worktrees/prepared"
+
 if bash "$PACKAGE_DIR/bin/pi-worktree" create --json ../escape >/dev/null 2>&1; then
   echo "create accepted an unsafe worktree name" >&2
   exit 1

package/skills/web-browser/SKILL.md

@@ -14,7 +14,7 @@ Minimal CDP tools for collaborative site exploration.
 ./scripts/start.js --headless            # Recommended: isolated reusable profile
 ./scripts/start.js --headless --profile  # Headless with a copy of your profile
 ./scripts/start.js                       # Visible browser window when needed
-./scripts/start.js --headless --reset-profile  # Clear cached profile before launch
+./scripts/start.js --headless --reset-profile  # Clear a stopped cached profile before launch
 ```
 
 Starts Chrome with remote debugging (default port `:9222`). **Agents should use `--headless` by default** because it is less disruptive and supports navigation, evaluation, screenshots, emulation, and logging. User extensions are disabled for headless launches; a copied profile still provides its cookies and other browser state, but extension-based features are unavailable. Headed launches continue to load extensions normally. Use headed mode only when a person needs to see or interact with the browser, such as for `pick.js`, manual authentication, or debugging a headless-specific difference.
@@ -33,6 +33,8 @@ If Chrome is installed in a non-standard location, set:
 BROWSER_BIN=/path/to/chrome ./scripts/start.js --headless
 ```
 
+`--reset-profile` refuses to delete an active profile. Close Chrome first, including instances on another debugging port. Missing launcher state does not bypass native profile locks; an unverifiable lock fails closed. These checks also run before profile-copy and stale-lock cleanup.
+
 The launcher auto-detects common macOS and Linux paths. Under WSL, it also detects Windows Chrome in the standard `Program Files` locations and launches it through PowerShell with an isolated Windows-local profile.
 
 Optional debug endpoint override:

package/skills/web-browser/scripts/start.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 import { spawn, execFileSync, execSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync, mkdirSync, readFileSync, readlinkSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -122,8 +122,8 @@ function isProcessAlive(pid) {
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
-    return false;
+  } catch (error) {
+    return error.code !== "ESRCH";
   }
 }
 
@@ -162,16 +162,16 @@ async function isDebugEndpointUp() {
 
 ensureDir(BROWSER_ROOT);
 
-if (resetProfile) {
-  rmSync(userDataFsDir, { recursive: true, force: true });
-}
-
 const state = readState();
 if (state?.pid && !isProcessAlive(state.pid)) {
   clearState();
 }
 
 if (await isDebugEndpointUp()) {
+  if (resetProfile) {
+    console.error(`✗ Cannot reset a profile while debugging endpoint :${DEBUG_PORT} is in use. Close Chrome first.`);
+    process.exit(1);
+  }
   const runningState = readState();
 
   if (
@@ -211,6 +211,40 @@ if (await isDebugEndpointUp()) {
   process.exit(1);
 }
 
+// A different debug port (or missing state.json) does not mean the profile is
+// unused. Check before reset, profile copy, or removing Chrome's singleton locks.
+try {
+  if (state?.userDataDir === userDataDir && state.pid && isProcessAlive(state.pid)) {
+    throw new Error("The selected profile is still in use by Chrome");
+  }
+  if (usesWindowsChrome) {
+    const escaped = userDataDir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = `--user-data-dir(?:=|\\s+)"?${escaped}(?:"|\\s|$)`;
+    const inUse = commandOutput("powershell.exe", [
+      "-NoProfile", "-NonInteractive", "-Command",
+      `$ErrorActionPreference = 'Stop'; if (Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match ${powershellQuote(pattern)} }) { 'busy' } else { 'free' }`,
+    ]);
+    if (inUse !== "free") throw new Error("The selected Windows profile is still in use by Chrome");
+  } else {
+    let lock;
+    try { lock = readlinkSync(join(userDataFsDir, "SingletonLock")); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (lock) {
+      const match = /^(.*)-(\d+)$/.exec(lock);
+      if (!match || match[1] !== hostname() || isProcessAlive(Number(match[2]))) {
+        throw new Error("The selected profile has a live or unverifiable Chrome lock");
+      }
+    }
+  }
+} catch (error) {
+  console.error(`✗ ${error.message}. Close Chrome before resetting or changing its profile.`);
+  process.exit(1);
+}
+
+if (resetProfile) {
+  rmSync(userDataFsDir, { recursive: true, force: true });
+}
+
 ensureDir(userDataFsDir);
 
 if (useProfile) {