pi-herdr-agents 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -7,7 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v3.0.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.0...v3.0.1)
+## [v3.0.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.1...v3.0.2)
+
+### Merged
+
+- fix(subagents): resolve submodule sources and refresh fallback context [`#76`](https://github.com/giuseppecrj/pi-herdr-agents/pull/76)
+
+## [v3.0.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.0...v3.0.1) - 2026-10-06
 
 ### Merged
 
@@ -16,6 +22,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 ### Commits
 
 - docs: README for 3.0.0: pstack ships poteto-mode not a role, safety and uninstall, contents, agent pointer [`7ed9969`](https://github.com/giuseppecrj/pi-herdr-agents/commit/7ed99693b1a2d25137d4ba2430f23255923ce3ea)
+- chore: release v3.0.1 [`ba349db`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ba349db4a4280a39b70a067fb62e7816f9a2061f)
 - docs: hero image uses generic agent labels instead of removed role names [`70ad6f0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/70ad6f04d492f58e04062e01c1a529ddd1708431)
 - docs: address review: full write footprint, worktree cleanup before uninstall, skill table delimiter [`ababee3`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ababee3a3f18d2112ec8959303986e1a08e3dc2a)
 

package/README.md

@@ -625,10 +625,17 @@ example `provider/preferred, provider/fallback`. The tool argument also accepts
 candidate before launch, then launches later candidates only after the selected
 child settles with a provider/agent error. Pi owns any automatic transient
 retrying inside that child; the extension does not infer retry counts or
-permanence from the error text. A completed child result, including a negative
-task result, never switches models. Completion metadata reports the requested
-candidate, every attempted candidate, the model actually used, and each raw
-model failure in attempt order when fallbacks are tried.
+permanence from the error text. A later candidate that launches after a parent
+`/reload`, `/new`, `/resume`, or `/fork` uses the live parent session for its
+artifacts and lineage, as completion delivery does. Its candidate list and
+thinking level stay those of the original call. The original parent directory
+and process directory remain the bases for directory resolution. Role files are
+read again for each attempt, so a changed role `cwd` can redirect a fallback
+when the tool call did not specify `cwd`. If no live parent context is available,
+that candidate fails without launching. A completed child result, including a
+negative task result, never switches models. Completion metadata reports the
+requested candidate, every attempted candidate, the model actually used, and
+each raw model failure in attempt order when fallbacks are tried.
 
 A catalog-listed model and configured authentication do not prove that the
 active provider account can use that model. Providers may reject an account /
@@ -865,7 +872,7 @@ is no other parent/child protocol.
 
 Parent sessions can call `worktree_remove({ target: "<path|branch|workspace-id>", preserve: true })` or `/worktree remove <target> [--preserve]`. Preservation is optional and never implied: dirty work is blocked unless explicitly committed first or preserved as a WIP commit. The result reports its SHA even if removal later fails or is refused. A failed preservation commit restores the pre-preservation index and never proceeds to removal. Inventory and removal reports disclose exact ignored-file counts: enumeration is streamed rather than buffered as one listing. Ignored files do not block cleanup and are not captured by preservation; failed counting still blocks removal.
 
-Eligibility is rechecked at removal time: canonical source-repository cwd containment, registered linked checkout, no detected process holder, known live child, or persistent lease, and clean Git state with no untracked files or conflicts. A successful launch from a linked checkout does not itself authorize its removal; cleanup uses the canonical principal/source repository under the invoking parent session's cwd, not `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at that principal checkout or an ancestor containing it, then use normal explicit cleanup; `cd` inside an existing Pi session does not change the session cwd. Unknown inspection, identity disagreements, detached HEAD, locked checkouts, and initialized submodules block removal. Out-of-scope repositories are never eligible. Open workspaces use Herdr removal; orphans use Git removal and registration pruning after checkout absence is verified. Owned reachable manifests are marked `removed`; manifests from other sessions are not required or rewritten. Stale removed manifests never govern a recreated checkout. Missing or dangling manifest paths do not affect unrelated checkouts; undecidable or conflicting manifest identity still blocks removal. A failed manifest update after removal is reported as a warning. Symlinked ancestors are supported; checkout symlinks escaping the canonical managed root are blocked. Process inspection covers observable same-user processes across sessions, regardless of runtime name, exempting only Herdr-confirmed idle retained shells, never runtimes at the same PID. Unreadable individual process details produce non-blocking warnings without an override flag; scanning continues so another observable holder still blocks removal. Human and structured inventory/removal results disclose incomplete coverage, including warnings seen before a later recheck or failure. Same-user inspection is permission-limited, and other-user processes are not inspected: a protected process could hold the checkout undetected. Warnings aggregate counts and bounded PID samples, not commands or environments. Linux uses `/proc`; macOS uses same-user `lsof` cwd records and warns for unreadable individual records. Unsupported platforms, failed global enumeration (including a failed `lsof` with partial output), and other unverifiable eligibility evidence still block removal. Cleanup Git and Herdr calls have 30-second timeouts.
+Eligibility is rechecked at removal time: canonical source-repository cwd containment, registered linked checkout, no detected process holder, known live child, or persistent lease, and clean Git state with no untracked files or conflicts. A successful launch from a linked checkout does not itself authorize its removal; cleanup uses the canonical principal/source repository under the invoking parent session's cwd, not `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at that principal checkout or an ancestor containing it, then use normal explicit cleanup; `cd` inside an existing Pi session does not change the session cwd. A source repository that is a Git submodule is located through the `core.worktree` setting of its shared Git directory under the superproject's `.git/modules`, not through that directory's parent. Unknown inspection, identity disagreements, detached HEAD, locked checkouts, and initialized submodules block removal. Out-of-scope repositories are never eligible. Open workspaces use Herdr removal; orphans use Git removal and registration pruning after checkout absence is verified. Owned reachable manifests are marked `removed`; manifests from other sessions are not required or rewritten. Stale removed manifests never govern a recreated checkout. Missing or dangling manifest paths do not affect unrelated checkouts; undecidable or conflicting manifest identity still blocks removal. A failed manifest update after removal is reported as a warning. Symlinked ancestors are supported; checkout symlinks escaping the canonical managed root are blocked. Process inspection covers observable same-user processes across sessions, regardless of runtime name, exempting only Herdr-confirmed idle retained shells, never runtimes at the same PID. Unreadable individual process details produce non-blocking warnings without an override flag; scanning continues so another observable holder still blocks removal. Human and structured inventory/removal results disclose incomplete coverage, including warnings seen before a later recheck or failure. Same-user inspection is permission-limited, and other-user processes are not inspected: a protected process could hold the checkout undetected. Warnings aggregate counts and bounded PID samples, not commands or environments. Linux uses `/proc`; macOS uses same-user `lsof` cwd records and warns for unreadable individual records. Unsupported platforms, failed global enumeration (including a failed `lsof` with partial output), and other unverifiable eligibility evidence still block removal. Cleanup Git and Herdr calls have 30-second timeouts.
 
 Cleanup never deletes or rewrites branches, uses force flags, or runs automatically. Session startup does not scan worktree inventory, avoiding blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory. Child sessions retain `/worktree list` and `/worktree <name>`, but receive neither cleanup tools nor the remove subcommand. Their repository-local listing labels detached entries `(detached HEAD)`; a detached sibling does not prevent inspection of named branches. See [cleanup and recovery](docs/worktree-subagents.md#cleanup) for details.
 

package/docs/worktree-subagents.md

@@ -223,6 +223,8 @@ The equivalent tools are `worktree_list({})` and `worktree_remove({ target, pres
 
 Authorization uses **cwd containment**: the canonical source repository root must equal or descend from the canonical session cwd. For linked checkouts, this means the canonical principal/source repository under the invoking parent session's cwd; a successful launch does not itself authorize cleanup, and authorization does not use `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at the principal checkout or an ancestor containing it, then use normal explicit cleanup; changing directories inside an existing Pi session does not change its session cwd. It does not use the managed checkout's location or require a current-session manifest. Discovery scans `~/.herdr/worktrees/*/*/`, joins Git registration and Herdr workspace state, and includes orphans from ended sessions. Out-of-scope entries are never removable; unregistered residue and failed probes are unknown, not clean. Inventory includes path, branch, source, workspace, Git state, manifest presence, concrete blockers, and separate process-inspection warnings. The managed root, source, and cwd are canonicalized: symlinked ancestors work normally, but a checkout symlink escaping the managed root is blocked.
 
+A source repository can be a Git submodule. Its shared Git directory lives under the superproject's `.git/modules`, so cleanup reads `core.worktree` through `git config`, which also follows included configuration files. Cleanup then requires the same top-level and common-directory proofs as for any other source. If the read or a proof fails, the entry is unknown and cannot be removed. Initialized submodules inside a managed checkout still block removal.
+
 Removal rechecks containment, Git registration, no detected process holder, known live child, or persistent-specialist lease, and no uncommitted, untracked, or conflicted files. Liveness checks observable same-user processes from any session with a cwd inside the checkout, regardless of runtime name (including thread-suffixed Node names). Only Herdr-confirmed idle retained shell PIDs are exempt; an active runtime at the same PID is not. Detached HEAD, locked checkouts, initialized submodules, and conflicting identity evidence block removal. For initialized submodules, deinitialize them deliberately or use operator removal. No force option is provided.
 
 Unreadable individual process details are **warnings, not blockers**, with no override flag. Scanning continues after each unreadable entry, so another observable holder still blocks removal. Unknown processes are not classified as unrelated. Inventory rows expose separate `blockers` and `warnings` arrays; removal results expose `warnings` and retain warnings from earlier inspections, including refusals and preservation/removal failures when available. Human-readable output includes the same warnings, with counts and at most ten sampled PIDs per inspection, not process commands or environments. Pi tool refusals and failures use thrown errors, so their warnings travel in the error message rather than structured tool details.

package/maestro/runtime/worktree-operations.ts

@@ -11,7 +11,7 @@ import {
 	unlinkSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isRecord, type JsonObject } from "../core/config/type-guards.ts";
 import type { SurfaceProvider } from "../core/surface-provider.ts";
 import type {
@@ -245,7 +245,19 @@ function resolveSource(path: string): string {
 			"--git-common-dir",
 		]).trim(),
 	);
-	const root = realpathSync(dirname(common));
+	// A submodule's common directory lives under the superproject's
+	// .git/modules; only core.worktree, including included config, names its checkout.
+	const configured = git(common, [
+		`--git-dir=${common}`,
+		"config",
+		"--default",
+		"",
+		"--get",
+		"core.worktree",
+	]).trim();
+	const root = realpathSync(
+		configured ? resolve(common, configured) : dirname(common),
+	);
 	if (realpathSync(git(root, ["rev-parse", "--show-toplevel"]).trim()) !== root)
 		throw new Error("Cannot prove source repository root");
 	if (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Asynchronous Pi subagents in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",

package/pi-extension/subagents/index.ts

@@ -1950,10 +1950,6 @@ function startWidgetRefresh() {
 	writeGlobalSlot(WIDGET_INTERVAL_KEY, widgetInterval);
 }
 
-/**
- * Normalize each actual attempt against its invocation context. Role files may
- * change between attempts; the validated runtime candidates do not.
- */
 function normalizePiAttempt(
 	params: typeof SubagentParams.static,
 	ctx: {
@@ -1975,6 +1971,7 @@ function normalizePiAttempt(
 	options: {
 		id: string;
 		controlTaskId: string;
+		origin: Pick<PiLaunchSnapshot["parent"], "cwd" | "invocationCwd">;
 	},
 ): PiAttemptSnapshot {
 	const agentDefs = params.agent
@@ -1999,15 +1996,19 @@ function normalizePiAttempt(
 	const taskId = randomUUID();
 	const parentSessionFile = ctx.sessionManager.getSessionFile();
 	if (!parentSessionFile) throw new Error("No session file");
+	const snapshot = launchSnapshot(ctx, parentThinking);
 
 	return {
-		snapshot: launchSnapshot(ctx, parentThinking),
+		snapshot: {
+			...snapshot,
+			parent: { ...snapshot.parent, ...options.origin },
+		},
 		task: {
 			id: options.controlTaskId,
 			name: params.name,
 			prompt: params.task,
 			role: params.agent ?? "",
-			cwd: ctx.cwd,
+			cwd: options.origin.cwd,
 			worktree: params.worktree ?? undefined,
 			session: { mode: resolveEffectiveSessionMode(params, agentDefs) },
 			behavior: {
@@ -2792,20 +2793,24 @@ export default function subagentsExtension(
 				);
 				runtime.latestCtx = ctx;
 				const id = randomUUID();
-				const first = normalizePiAttempt(params, ctx, parentThinking, {
+				const attempt = {
 					id,
 					controlTaskId: id,
-				});
+					origin: { cwd: ctx.cwd, invocationCwd: process.cwd() },
+				};
+				const first = normalizePiAttempt(params, ctx, parentThinking, attempt);
 				const [plan, ...fallbacks] = runtimePlans;
 				if (!plan) throw new Error("No resolved runtime plans");
 				const input: PiLaunchInput = {
 					...first,
 					plans: [plan, ...fallbacks],
-					prepareAttempt: () =>
-						normalizePiAttempt(params, ctx, parentThinking, {
-							id,
-							controlTaskId: id,
-						}),
+					// Fallbacks outlive this tool call; session replacement invalidates ctx.
+					prepareAttempt: () => {
+						const live = runtime.latestCtx;
+						if (!live)
+							throw new Error("No live parent context for the fallback launch");
+						return normalizePiAttempt(params, live, parentThinking, attempt);
+					},
 				};
 				const session = runtime.session!;
 				const handle = await session.spawnPi(input);