@xzzpig/pi-subagents 0.14.0 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +233 -0
- package/README.md +6 -5
- package/agents/evidence-auditor.md +34 -0
- package/agents/researcher.md +23 -13
- package/agents/reviewer.md +3 -2
- package/docs/agents.md +56 -15
- package/docs/configuration.md +92 -14
- package/docs/extension-api.md +132 -19
- package/docs/missions.md +10 -2
- package/docs/models.md +11 -22
- package/docs/observability.md +63 -11
- package/docs/standalone-background.md +59 -0
- package/docs/tool-reference.md +42 -23
- package/docs/watchdog.md +39 -10
- package/docs/workflows.md +58 -19
- package/index.ts +5 -2
- package/inspector-runner.mjs +2 -2
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
- package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
- package/package.json +9 -4
- package/prompts/parallel-review.md +1 -1
- package/runner-peer-loader.mjs +24 -0
- package/runner-peer-preload.mjs +36 -0
- package/skills/pi-subagents/SKILL.md +34 -22
- package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
- package/skills/pi-subagents/references/execution-controls.md +27 -8
- package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
- package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
- package/skills/pi-subagents/references/review-and-validation.md +3 -3
- package/src/agents/advertised-agent-prompt.ts +94 -0
- package/src/agents/agent-management.ts +71 -59
- package/src/agents/agent-serializer.ts +6 -3
- package/src/agents/agents.ts +198 -72
- package/src/agents/builtin-names.ts +1 -0
- package/src/agents/chain-serializer.ts +5 -0
- package/src/agents/runtime-agent-registry.ts +7 -6
- package/src/api/delegation.ts +4 -0
- package/src/api/preflight.ts +110 -71
- package/src/api/required-child-extensions.ts +6 -0
- package/src/api/shared-types.ts +3 -1
- package/src/api/workflow-resources.ts +6 -0
- package/src/extension/config.ts +14 -37
- package/src/extension/fanout-child.ts +68 -5
- package/src/extension/herdr-pi-bridge.ts +164 -0
- package/src/extension/index.ts +141 -51
- package/src/extension/public-execution.ts +7 -6
- package/src/extension/rpc.ts +8 -21
- package/src/extension/schemas.ts +86 -84
- package/src/extension/tool-description.ts +32 -79
- package/src/inspectors/actions.ts +148 -0
- package/src/inspectors/ghostty/actions.ts +74 -0
- package/src/inspectors/ghostty/plugin.ts +17 -0
- package/src/inspectors/herdr/actions.ts +99 -179
- package/src/inspectors/herdr/plugin.ts +20 -0
- package/src/inspectors/herdr/project-panes.ts +4 -1
- package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
- package/src/inspectors/plugins.ts +8 -0
- package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
- package/src/inspectors/types.ts +51 -0
- package/src/integrations/pi-web-session-liveness.ts +73 -0
- package/src/intercom/intercom-bridge.ts +50 -8
- package/src/intercom/native-supervisor-channel.ts +142 -115
- package/src/intercom/supervisor-ui.ts +3 -2
- package/src/missions/workflow-state.ts +37 -16
- package/src/policy/authority.ts +4 -0
- package/src/profiles/profiles.ts +12 -6
- package/src/runs/background/active-async-capacity.ts +22 -18
- package/src/runs/background/active-run-index.ts +17 -1
- package/src/runs/background/async-execution.ts +359 -176
- package/src/runs/background/async-job-tracker.ts +41 -7
- package/src/runs/background/async-resume.ts +19 -12
- package/src/runs/background/async-retention.ts +20 -0
- package/src/runs/background/async-status-snapshot.ts +10 -12
- package/src/runs/background/async-status.ts +32 -13
- package/src/runs/background/auto-drain.ts +59 -35
- package/src/runs/background/binary-bootstrap.ts +38 -0
- package/src/runs/background/chain-append.ts +1 -1
- package/src/runs/background/chain-root-attachment.ts +22 -33
- package/src/runs/background/control-channel.ts +78 -44
- package/src/runs/background/fleet-view.ts +30 -2
- package/src/runs/background/notify.ts +193 -19
- package/src/runs/background/owned-process-tree.ts +35 -8
- package/src/runs/background/process-terminal.ts +23 -23
- package/src/runs/background/result-files.ts +8 -4
- package/src/runs/background/result-watcher.ts +19 -2
- package/src/runs/background/retained-nested-route-tracker.ts +96 -0
- package/src/runs/background/run-child-session.ts +118 -41
- package/src/runs/background/run-status.ts +78 -5
- package/src/runs/background/runner-aliases.ts +22 -5
- package/src/runs/background/runner-child-launch.ts +93 -0
- package/src/runs/background/runner-child-sessions.ts +5 -4
- package/src/runs/background/runner-http-dispatcher.ts +119 -0
- package/src/runs/background/scheduled-runs.ts +51 -18
- package/src/runs/background/stale-run-reconciler.ts +38 -12
- package/src/runs/background/steering.ts +20 -2
- package/src/runs/background/subagent-runner.ts +766 -432
- package/src/runs/background/subagent-wait.ts +179 -28
- package/src/runs/background/wait-completions.ts +79 -27
- package/src/runs/background/wait-subscriptions.ts +9 -3
- package/src/runs/background/wait-tool.ts +5 -3
- package/src/runs/foreground/async-steering-action.ts +37 -7
- package/src/runs/foreground/async-stop-action.ts +93 -3
- package/src/runs/foreground/execution.ts +174 -194
- package/src/runs/foreground/foreground-history.ts +5 -2
- package/src/runs/foreground/prompt-audit.ts +12 -6
- package/src/runs/foreground/subagent-executor.ts +896 -397
- package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
- package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
- package/src/runs/shared/acceptance.ts +54 -14
- package/src/runs/shared/agent-contract.ts +1 -1
- package/src/runs/shared/async-status-projection.ts +172 -78
- package/src/runs/shared/capability-ceiling.ts +2 -0
- package/src/runs/shared/child-hooks.ts +167 -3
- package/src/runs/shared/child-launch-plan.ts +15 -3
- package/src/runs/shared/child-launch.ts +44 -16
- package/src/runs/shared/child-lifecycle.ts +6 -3
- package/src/runs/shared/child-runtime-config.ts +8 -1
- package/src/runs/shared/child-session.ts +130 -24
- package/src/runs/shared/child-tool-plan.ts +145 -14
- package/src/runs/shared/completion-evidence.ts +2 -2
- package/src/runs/shared/completion-guard.ts +6 -3
- package/src/runs/shared/dynamic-fanout.ts +2 -2
- package/src/runs/shared/effective-system-prompt.ts +33 -0
- package/src/runs/shared/external-cli-contract.ts +11 -1
- package/src/runs/shared/external-cli-preflight.ts +6 -2
- package/src/runs/shared/external-cli-runner.ts +9 -7
- package/src/runs/shared/herdr-connection.ts +134 -0
- package/src/runs/shared/herdr-external-adapters.ts +169 -0
- package/src/runs/shared/herdr-machine.ts +279 -0
- package/src/runs/shared/herdr-pi-protocol.ts +59 -0
- package/src/runs/shared/herdr-placed-run.ts +263 -0
- package/src/runs/shared/host-step-status.ts +11 -11
- package/src/runs/shared/llm-intent-arbiter.ts +40 -21
- package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
- package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
- package/src/runs/shared/model-scope.ts +1 -1
- package/src/runs/shared/nested-events.ts +19 -10
- package/src/runs/shared/orca-progress-tabs.ts +7 -1
- package/src/runs/shared/parallel-handoff.ts +57 -12
- package/src/runs/shared/parallel-utils.ts +10 -4
- package/src/runs/shared/pi-spawn.ts +10 -0
- package/src/runs/shared/readonly-drain-observation.ts +42 -0
- package/src/runs/shared/run-fanout-budget.ts +8 -8
- package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
- package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
- package/src/runs/shared/task-intent.ts +46 -13
- package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
- package/src/runs/shared/worktree-setup-command.ts +213 -0
- package/src/runs/shared/worktree.ts +437 -214
- package/src/shared/child-cache-retention.ts +43 -0
- package/src/shared/fork-context.ts +15 -72
- package/src/shared/launch-contract.ts +70 -8
- package/src/shared/model-response-aliases.ts +13 -0
- package/src/shared/opencode-session-headers.ts +30 -0
- package/src/shared/pruned-fork.ts +1 -1
- package/src/shared/required-child-extensions.ts +81 -0
- package/src/shared/settings.ts +5 -2
- package/src/shared/shortcuts.ts +0 -4
- package/src/shared/types.ts +163 -90
- package/src/shared/utils.ts +10 -2
- package/src/shared/watch-strategy.ts +2 -0
- package/src/shared/workflow-child-permit.ts +18 -13
- package/src/slash/delegation-adapters.ts +3 -1
- package/src/slash/delegation-request.ts +14 -0
- package/src/slash/slash-commands.ts +2 -7
- package/src/slash/subagents-admin.ts +31 -14
- package/src/tui/fleet-status.ts +165 -20
- package/src/tui/fleet.ts +30 -19
- package/src/tui/render.ts +210 -50
- package/src/watchdog/child-status.ts +28 -28
- package/src/watchdog/lsp-diagnostics.ts +1 -1
- package/src/watchdog/model-selection.ts +21 -1
- package/src/watchdog/permission-arbiter.ts +5 -2
- package/src/watchdog/register-child.ts +10 -2
- package/src/watchdog/register-main.ts +39 -35
- package/src/watchdog/render.ts +1 -1
- package/src/watchdog/review.ts +122 -74
- package/src/watchdog/rules.ts +1 -1
- package/src/watchdog/runtime.ts +100 -27
- package/src/watchdog/scope.ts +1 -1
- package/src/watchdog/settings.ts +3 -0
- package/src/watchdog/tool-actions.ts +13 -12
- package/src/watchdog/turn-delta.ts +23 -0
- package/src/watchdog/types.ts +5 -3
- package/src/watchdog/warning-format.ts +1 -1
- package/src/workflows/chat-progress.ts +3 -3
- package/src/workflows/scripted-workflow.ts +349 -26
- package/src/workflows/workflow-checklist.ts +17 -20
- package/src/workflows/workflow-child-summary.ts +57 -8
- package/src/workflows/workflow-preflight.ts +19 -19
- package/src/workflows/workflow-receipt.ts +24 -6
- package/src/workflows/workflow-resources.ts +108 -22
- package/src/workflows/workflow-settlement.ts +3 -0
- package/src/runs/shared/model-exclusions.ts +0 -373
- /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
|
@@ -54,11 +54,19 @@ type Theme = TranscriptTheme;
|
|
|
54
54
|
type ThemeColor = string;
|
|
55
55
|
type ThemeBackground = string;
|
|
56
56
|
export type TranscriptNoticeTone = "info" | "warning" | "error";
|
|
57
|
+
/**
|
|
58
|
+
* How a turn ended. A host that distinguishes a completed exchange from one the
|
|
59
|
+
* user aborted or that failed records it on the turn's end boundary; rendering
|
|
60
|
+
* treats every finished turn the same, so this stays metadata for hosts/tests.
|
|
61
|
+
*/
|
|
62
|
+
export type TranscriptTurnOutcome = "completed" | "aborted" | "failed";
|
|
57
63
|
export type TranscriptEntry = {
|
|
58
64
|
id: number;
|
|
59
65
|
turnId: number;
|
|
60
66
|
type: "turn-boundary";
|
|
61
67
|
phase: "start" | "end";
|
|
68
|
+
/** Present on `end` boundaries when the host reported how the turn ended. */
|
|
69
|
+
outcome?: TranscriptTurnOutcome;
|
|
62
70
|
} | {
|
|
63
71
|
id: number;
|
|
64
72
|
turnId: number;
|
|
@@ -206,10 +214,12 @@ export declare function findLatestEntry<TType extends TranscriptEntry["type"]>(s
|
|
|
206
214
|
* Closes `turnId` (defaulting to the current turn): appends the end boundary
|
|
207
215
|
* unless one already exists, clears streaming flags on the turn's entries,
|
|
208
216
|
* and updates bookkeeping. Idempotent — finishing an already-finished turn is
|
|
209
|
-
* a no-op for boundary creation.
|
|
210
|
-
*
|
|
217
|
+
* a no-op for boundary creation. An optional `outcome` is recorded on the end
|
|
218
|
+
* boundary, letting hosts distinguish completed, aborted, and failed turns.
|
|
219
|
+
* Public building block for hosts that know when a replayed exchange is
|
|
220
|
+
* complete.
|
|
211
221
|
*/
|
|
212
|
-
export declare function finishTurn(state: TranscriptState, turnId?: number | null): void;
|
|
222
|
+
export declare function finishTurn(state: TranscriptState, turnId?: number | null, outcome?: TranscriptTurnOutcome): void;
|
|
213
223
|
export declare function removeTranscriptTurn(state: TranscriptState, turnId: number | null): void;
|
|
214
224
|
/**
|
|
215
225
|
* Degraded stand-in stored on a tool-call entry when the original arguments
|
|
@@ -314,17 +314,29 @@ export function findLatestEntry(state, turnId, type) {
|
|
|
314
314
|
* Closes `turnId` (defaulting to the current turn): appends the end boundary
|
|
315
315
|
* unless one already exists, clears streaming flags on the turn's entries,
|
|
316
316
|
* and updates bookkeeping. Idempotent — finishing an already-finished turn is
|
|
317
|
-
* a no-op for boundary creation.
|
|
318
|
-
*
|
|
317
|
+
* a no-op for boundary creation. An optional `outcome` is recorded on the end
|
|
318
|
+
* boundary, letting hosts distinguish completed, aborted, and failed turns.
|
|
319
|
+
* Public building block for hosts that know when a replayed exchange is
|
|
320
|
+
* complete.
|
|
319
321
|
*/
|
|
320
|
-
export function finishTurn(state, turnId = state.currentTurnId) {
|
|
322
|
+
export function finishTurn(state, turnId = state.currentTurnId, outcome) {
|
|
321
323
|
if (turnId === null)
|
|
322
324
|
return;
|
|
323
|
-
const
|
|
325
|
+
const endBoundary = state.entries.find((entry) => entry.turnId === turnId &&
|
|
324
326
|
entry.type === "turn-boundary" &&
|
|
325
327
|
entry.phase === "end");
|
|
326
|
-
if (
|
|
327
|
-
|
|
328
|
+
if (endBoundary) {
|
|
329
|
+
if (outcome !== undefined)
|
|
330
|
+
endBoundary.outcome = outcome;
|
|
331
|
+
}
|
|
332
|
+
else {
|
|
333
|
+
appendEntry(state, {
|
|
334
|
+
type: "turn-boundary",
|
|
335
|
+
turnId,
|
|
336
|
+
phase: "end",
|
|
337
|
+
...(outcome === undefined ? {} : { outcome }),
|
|
338
|
+
});
|
|
339
|
+
}
|
|
328
340
|
for (const entry of state.entries) {
|
|
329
341
|
if (entry.turnId !== turnId)
|
|
330
342
|
continue;
|
|
@@ -79,12 +79,21 @@ type ThemeBackground = string;
|
|
|
79
79
|
|
|
80
80
|
export type TranscriptNoticeTone = "info" | "warning" | "error";
|
|
81
81
|
|
|
82
|
+
/**
|
|
83
|
+
* How a turn ended. A host that distinguishes a completed exchange from one the
|
|
84
|
+
* user aborted or that failed records it on the turn's end boundary; rendering
|
|
85
|
+
* treats every finished turn the same, so this stays metadata for hosts/tests.
|
|
86
|
+
*/
|
|
87
|
+
export type TranscriptTurnOutcome = "completed" | "aborted" | "failed";
|
|
88
|
+
|
|
82
89
|
export type TranscriptEntry =
|
|
83
90
|
| {
|
|
84
91
|
id: number;
|
|
85
92
|
turnId: number;
|
|
86
93
|
type: "turn-boundary";
|
|
87
94
|
phase: "start" | "end";
|
|
95
|
+
/** Present on `end` boundaries when the host reported how the turn ended. */
|
|
96
|
+
outcome?: TranscriptTurnOutcome;
|
|
88
97
|
}
|
|
89
98
|
| { id: number; turnId: number; type: "user-message"; text: string }
|
|
90
99
|
| {
|
|
@@ -555,22 +564,33 @@ export function findLatestEntry<TType extends TranscriptEntry["type"]>(
|
|
|
555
564
|
* Closes `turnId` (defaulting to the current turn): appends the end boundary
|
|
556
565
|
* unless one already exists, clears streaming flags on the turn's entries,
|
|
557
566
|
* and updates bookkeeping. Idempotent — finishing an already-finished turn is
|
|
558
|
-
* a no-op for boundary creation.
|
|
559
|
-
*
|
|
567
|
+
* a no-op for boundary creation. An optional `outcome` is recorded on the end
|
|
568
|
+
* boundary, letting hosts distinguish completed, aborted, and failed turns.
|
|
569
|
+
* Public building block for hosts that know when a replayed exchange is
|
|
570
|
+
* complete.
|
|
560
571
|
*/
|
|
561
572
|
export function finishTurn(
|
|
562
573
|
state: TranscriptState,
|
|
563
574
|
turnId: number | null = state.currentTurnId,
|
|
575
|
+
outcome?: TranscriptTurnOutcome,
|
|
564
576
|
): void {
|
|
565
577
|
if (turnId === null) return;
|
|
566
|
-
const
|
|
567
|
-
(entry) =>
|
|
578
|
+
const endBoundary = state.entries.find(
|
|
579
|
+
(entry): entry is Extract<TranscriptEntry, { type: "turn-boundary" }> =>
|
|
568
580
|
entry.turnId === turnId &&
|
|
569
581
|
entry.type === "turn-boundary" &&
|
|
570
582
|
entry.phase === "end",
|
|
571
583
|
);
|
|
572
|
-
if (
|
|
573
|
-
|
|
584
|
+
if (endBoundary) {
|
|
585
|
+
if (outcome !== undefined) endBoundary.outcome = outcome;
|
|
586
|
+
} else {
|
|
587
|
+
appendEntry(state, {
|
|
588
|
+
type: "turn-boundary",
|
|
589
|
+
turnId,
|
|
590
|
+
phase: "end",
|
|
591
|
+
...(outcome === undefined ? {} : { outcome }),
|
|
592
|
+
});
|
|
593
|
+
}
|
|
574
594
|
for (const entry of state.entries) {
|
|
575
595
|
if (entry.turnId !== turnId) continue;
|
|
576
596
|
if (
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xzzpig/pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.15.0",
|
|
4
4
|
"description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
|
|
5
5
|
"author": "Nico Bailon",
|
|
6
6
|
"license": "MIT",
|
|
@@ -13,6 +13,8 @@
|
|
|
13
13
|
"./agents": "./src/api/agents.ts",
|
|
14
14
|
"./delegation": "./src/api/delegation.ts",
|
|
15
15
|
"./capability-ceiling": "./src/api/capability-ceiling.ts",
|
|
16
|
+
"./workflow-resources": "./src/api/workflow-resources.ts",
|
|
17
|
+
"./required-child-extensions": "./src/api/required-child-extensions.ts",
|
|
16
18
|
"./preflight": "./src/api/preflight.ts",
|
|
17
19
|
"./agent-management": "./src/api/agent-management.ts",
|
|
18
20
|
"./control-channel": "./src/api/control-channel.ts",
|
|
@@ -88,12 +90,13 @@
|
|
|
88
90
|
"acorn": "8.18.0",
|
|
89
91
|
"jiti": "2.7.0",
|
|
90
92
|
"typebox": "1.1.38",
|
|
93
|
+
"undici": "8.10.0",
|
|
91
94
|
"yaml": "2.8.3"
|
|
92
95
|
},
|
|
93
96
|
"devDependencies": {
|
|
94
|
-
"@earendil-works/pi-agent-core": "
|
|
95
|
-
"@earendil-works/pi-ai": "
|
|
96
|
-
"@earendil-works/pi-tui": "
|
|
97
|
+
"@earendil-works/pi-agent-core": "0.85.1",
|
|
98
|
+
"@earendil-works/pi-ai": "0.85.1",
|
|
99
|
+
"@earendil-works/pi-tui": "0.85.1",
|
|
97
100
|
"@oxlint/plugins": "1.80.0",
|
|
98
101
|
"@types/node": "24.13.3",
|
|
99
102
|
"oxlint": "1.80.0",
|
|
@@ -107,6 +110,8 @@
|
|
|
107
110
|
"@xzzpig/pi-components"
|
|
108
111
|
],
|
|
109
112
|
"scripts": {
|
|
113
|
+
"build:pkg": "node scripts/build-package.mjs",
|
|
114
|
+
"pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
|
|
110
115
|
"typecheck": "tsc --noEmit",
|
|
111
116
|
"test": "npm run test:unit",
|
|
112
117
|
"test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
|
|
@@ -28,7 +28,7 @@ Choose or adapt angles when the work calls for it:
|
|
|
28
28
|
|
|
29
29
|
Prefer three strong reviewers over many vague reviewers.
|
|
30
30
|
|
|
31
|
-
Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete
|
|
31
|
+
Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete and current within the named review target, and supported by source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
|
|
32
32
|
|
|
33
33
|
Do not default first-pass reviews to `blockers only`. That phrase is valid only for final pre-merge re-checks after P1/P2 findings are already inventoried, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred.
|
|
34
34
|
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { pathToFileURL } from "node:url";
|
|
2
|
+
|
|
3
|
+
let aliases = {};
|
|
4
|
+
let nativeRunner = false;
|
|
5
|
+
let compiledRunner = false;
|
|
6
|
+
let packageRootUrl;
|
|
7
|
+
const redirected = new Set([
|
|
8
|
+
"@earendil-works/pi-tui",
|
|
9
|
+
]);
|
|
10
|
+
|
|
11
|
+
export function initialize(data) {
|
|
12
|
+
aliases = data?.aliases ?? {};
|
|
13
|
+
nativeRunner = data?.nativeRunner === true;
|
|
14
|
+
compiledRunner = data?.compiledRunner === true;
|
|
15
|
+
packageRootUrl = data?.packageRootUrl;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export function resolve(specifier, context, nextResolve) {
|
|
19
|
+
const packageImport = typeof packageRootUrl === "string" && context.parentURL?.startsWith(packageRootUrl) === true;
|
|
20
|
+
if (nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier]) {
|
|
21
|
+
return nextResolve(pathToFileURL(aliases[specifier]).href, context);
|
|
22
|
+
}
|
|
23
|
+
return nextResolve(specifier, context);
|
|
24
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import * as nodeModule from "node:module";
|
|
2
|
+
import { pathToFileURL } from "node:url";
|
|
3
|
+
|
|
4
|
+
// Upstream-original preload: JITI_ALIAS is written by the runner launcher, so a malformed value must fail loudly.
|
|
5
|
+
// pi-lens-ignore: unchecked-throwing-call-js
|
|
6
|
+
const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
|
|
7
|
+
const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
|
|
8
|
+
const compiledRunner = process.env.PI_ASYNC_COMPILED_RUNNER === "1";
|
|
9
|
+
// Pi's jiti loader owns aliases for external extensions; these hooks only supply peers to our compiled package.
|
|
10
|
+
const packageRootUrl = new URL("./", import.meta.url).href;
|
|
11
|
+
const redirected = new Set([
|
|
12
|
+
"@earendil-works/pi-tui",
|
|
13
|
+
]);
|
|
14
|
+
|
|
15
|
+
// Upstream-original: Node version feature detection for registerHooks (Node 22.12+ vs register()).
|
|
16
|
+
// pi-lens-ignore: no-runtime-typeof
|
|
17
|
+
if (typeof nodeModule.registerHooks === "function") {
|
|
18
|
+
nodeModule.registerHooks({
|
|
19
|
+
resolve(specifier, context, nextResolve) {
|
|
20
|
+
const packageImport = context.parentURL?.startsWith(packageRootUrl) === true;
|
|
21
|
+
if ((nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier])) {
|
|
22
|
+
return nextResolve(pathToFileURL(aliases[specifier]).href, context);
|
|
23
|
+
}
|
|
24
|
+
try {
|
|
25
|
+
return nextResolve(specifier, context);
|
|
26
|
+
} catch (error) {
|
|
27
|
+
if (nativeRunner && specifier.endsWith(".js")) return nextResolve(`${specifier.slice(0, -3)}.ts`, context);
|
|
28
|
+
throw error;
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
});
|
|
32
|
+
} else {
|
|
33
|
+
nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
|
|
34
|
+
data: { aliases, nativeRunner, compiledRunner, packageRootUrl },
|
|
35
|
+
});
|
|
36
|
+
}
|
|
@@ -1,28 +1,25 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pi-subagents
|
|
3
3
|
description: |
|
|
4
|
-
|
|
5
|
-
review, scripted
|
|
6
|
-
|
|
7
|
-
supply focused context, planning, review, or execution.
|
|
4
|
+
Technical guidance for operator-requested delegation to builtin or custom
|
|
5
|
+
subagents: bounded handoffs, parallel review, scripted workflows, async work,
|
|
6
|
+
forked context, isolation, and coordinated execution.
|
|
8
7
|
---
|
|
9
8
|
|
|
10
9
|
# Pi Subagents
|
|
11
10
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
- Direct parent edits during orchestrator mode should be intentional, small
|
|
25
|
-
interventions with a brief reason.
|
|
11
|
+
The parent works directly by default. Invoke subagents only when the operator
|
|
12
|
+
requested delegation in the current request or through applicable user/project
|
|
13
|
+
instructions. Task size, complexity, risk, tool-call count, recipe fit, or an
|
|
14
|
+
available specialist does not independently authorize delegation.
|
|
15
|
+
|
|
16
|
+
Once authorized, choose the smallest bounded shape that earns its token and
|
|
17
|
+
elapsed-time overhead through concrete evidence, independent review,
|
|
18
|
+
specialization, useful parallelism, or needed isolation. A single child is
|
|
19
|
+
valid; writer, challenge, and review stages must each earn their overhead rather
|
|
20
|
+
than becoming default ceremony. The parent keeps user intent, constraints,
|
|
21
|
+
routing, arbitration, decisions, final acceptance, and publication authority,
|
|
22
|
+
and may perform the work directly where it is the most efficient owner.
|
|
26
23
|
|
|
27
24
|
Children do not spawn subagents unless the parent explicitly delegated fanout
|
|
28
25
|
and their resolved `tools` allow `subagent`.
|
|
@@ -50,6 +47,18 @@ use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
|
|
|
50
47
|
example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
|
|
51
48
|
bounded, but do not add stages or ceremony just to satisfy this skill.
|
|
52
49
|
|
|
50
|
+
When composing `runs.run(...)`, `runs.all(...)`, or `runs.lanes(...)`, always
|
|
51
|
+
supply a short verb + behavior display `label` derived from the task, unless
|
|
52
|
+
the user supplied an explicit label; preserve that label. Keep the stable
|
|
53
|
+
machine `key` independent (for example, `issue2011-writer` with
|
|
54
|
+
`label: "Fix workflow steering"`). For `runs.lanes`, put labels on stage
|
|
55
|
+
items, not lane objects. Use stage-appropriate labels for reviews and retained-child
|
|
56
|
+
follow-ups too (for example, `Review workflow steering`). Generate labels in
|
|
57
|
+
the orchestrator while composing the launch—no extra model call, runtime
|
|
58
|
+
generator, or schema change. Native direct `{ agent, task }` calls have no
|
|
59
|
+
top-level `label` parameter; do not invent one or wrap a tiny single task in
|
|
60
|
+
a workflow just to label it.
|
|
61
|
+
|
|
53
62
|
Use async/background by default. Set `async:false` only when the parent must
|
|
54
63
|
block. Final reviews, validation gates, oracle checks, and publication checks
|
|
55
64
|
stay async.
|
|
@@ -71,6 +80,8 @@ that runner explicitly supports the option.
|
|
|
71
80
|
|
|
72
81
|
## Read the reference for the branch
|
|
73
82
|
|
|
83
|
+
For exact API fields and worked examples, call `subagent({action:"guide",topic:"tool-reference"})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
|
|
84
|
+
|
|
74
85
|
| Branch | Read |
|
|
75
86
|
| --- | --- |
|
|
76
87
|
| Delegate or choose roles, prompts, models, or slash commands | `references/prompting-and-roles.md` |
|
|
@@ -80,9 +91,9 @@ that runner explicitly supports the option.
|
|
|
80
91
|
| List, create, edit, disable, eject, or expose agents/RPC | `references/management-authoring-rpc.md` |
|
|
81
92
|
| Check safety constraints, recipes, or error handling | `references/constraints-and-recipes.md` |
|
|
82
93
|
|
|
83
|
-
For complex
|
|
84
|
-
|
|
85
|
-
review.
|
|
94
|
+
For an authorized complex delegated workflow, read `prompting-and-roles.md` and
|
|
95
|
+
`execution-controls.md`, then load `review-and-validation.md` and
|
|
96
|
+
`constraints-and-recipes.md` before launch or review.
|
|
86
97
|
|
|
87
98
|
## Operating rules
|
|
88
99
|
|
|
@@ -91,7 +102,8 @@ review.
|
|
|
91
102
|
- Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
|
|
92
103
|
- Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
|
|
93
104
|
- For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. See `references/multi-lane-orchestration.md` for lane mechanics.
|
|
94
|
-
- Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required.
|
|
105
|
+
- Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
|
|
106
|
+
- Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
|
|
95
107
|
- For cross-codebase work, record the repo, explicit `cwd`, authority boundary, and expected output before launch.
|
|
96
108
|
- Make parallel prompts distinct by source seam, evidence, and decision. Do not clone prompts with only item numbers swapped.
|
|
97
109
|
- Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
|
|
@@ -52,10 +52,11 @@ This reference keeps cross-cutting policy and failure handling. Load the matchin
|
|
|
52
52
|
| Independent lanes, repositories, worktrees, and handoffs | [`references/multi-lane-orchestration.md`](multi-lane-orchestration.md) |
|
|
53
53
|
| Agent management, file authoring, prompt integration, or RPC | [`references/management-authoring-rpc.md`](management-authoring-rpc.md) |
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
After delegation is operator-authorized, choose the smallest recipe that earns
|
|
56
|
+
its overhead. Recipes select a shape; they do not authorize delegation:
|
|
56
57
|
|
|
57
58
|
- **Recon → plan → implement:** run one focused `scout`, then one `worker` that consumes its findings.
|
|
58
|
-
- **
|
|
59
|
+
- **Implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, and use a bounded scout, writer, or fresh reviewer only where the requested delegation benefits from that stage. Keep one writer, inspect direct evidence, and require every added stage to earn its overhead. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
|
|
59
60
|
- **Parallel analysis:** fan out only independent read/review/validation work, or isolate each writer in its own worktree. Never run concurrent writers in one checkout.
|
|
60
61
|
|
|
61
62
|
## Error Handling
|
|
@@ -24,7 +24,7 @@ Project settings resolve from the nearest parent directory containing `.pi` or `
|
|
|
24
24
|
|
|
25
25
|
An agent may set `runner.type: external-cli` with a non-empty `command`, optional string `args`, and `promptDelivery: stdin` (the default). The command runs with `shell: false`, inherits the resolved cwd and environment, and receives the combined agent instructions and task through stdin. It must already be installed; pi-subagents adds no CLI dependency.
|
|
26
26
|
|
|
27
|
-
External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, nested subagents,
|
|
27
|
+
External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, nested subagents, and sessions are also unsupported.
|
|
28
28
|
|
|
29
29
|
### External job profiles
|
|
30
30
|
|
|
@@ -32,7 +32,7 @@ An agent may set `runner.type: external-job` with a non-empty `provider` and opt
|
|
|
32
32
|
|
|
33
33
|
External job profiles are async-only. The provider owns the remote job and Pi owns the async run record. Status persists provider name, provider job id, prompt digest, provider options, handle/conversation URLs when supplied, result artifact path, last known state, and provider failure code/message. Recovery uses existing provider job metadata to call `reattach` and `result`; it refuses to redispatch a prompt when the persisted provider job does not match the prompt digest.
|
|
34
34
|
|
|
35
|
-
External job profiles do not support foreground/clarify, steer/resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions,
|
|
35
|
+
External job profiles do not support foreground/clarify, steer/resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions, or Pi child sessions. Capacity conflicts fail closed and include the blocking provider job id when the provider supplies it.
|
|
36
36
|
|
|
37
37
|
### Single agent
|
|
38
38
|
|
|
@@ -83,10 +83,10 @@ lanes, or a fanout that the parent will consume together.
|
|
|
83
83
|
```js
|
|
84
84
|
subagent({
|
|
85
85
|
workflowScript: `
|
|
86
|
-
const scan = await runs.run("scan", { agent: "scout", task: "Map the target" });
|
|
86
|
+
const scan = await runs.run("scan", { label: "Map target behavior", agent: "scout", task: "Map the target" });
|
|
87
87
|
const reviews = await runs.all([
|
|
88
|
-
{ key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
89
|
-
{ key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
88
|
+
{ key: "correctness", label: "Review target correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
89
|
+
{ key: "tests", label: "Review target test coverage", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
90
90
|
]);
|
|
91
91
|
return reviews.map(result => result.output);
|
|
92
92
|
`
|
|
@@ -109,6 +109,7 @@ Terminal async workflows also persist `workflow-receipt.json` beside `status.jso
|
|
|
109
109
|
|
|
110
110
|
```js
|
|
111
111
|
return runs.run("cross-oracle", {
|
|
112
|
+
label: "Challenge proposed direction",
|
|
112
113
|
resume: { workflowRunId: "<pass-1-workflow-id>", key: "advisor-oracle", latest: true },
|
|
113
114
|
task: "Review the focused challenge packet."
|
|
114
115
|
});
|
|
@@ -120,7 +121,8 @@ Keyed resume reads that one exact receipt and revalidates the retained run at la
|
|
|
120
121
|
|
|
121
122
|
For a broad plan with a known set of narrow, visible stages per lane, use
|
|
122
123
|
`runs.lanes(...)` inside a `workflowScript`; it is a nested helper, not a
|
|
123
|
-
top-level `subagent` mode. Give each lane and stage a stable key
|
|
124
|
+
top-level `subagent` mode. Give each lane and stage a stable key; give stage
|
|
125
|
+
items a short verb + behavior `label`, preserving explicit user labels. The first
|
|
124
126
|
stage from every lane is launched together, then later stages sequence per lane.
|
|
125
127
|
`resume: "previous"` requires the retained predecessor, and a failed or blocked
|
|
126
128
|
stage blocks only that lane. The returned board exposes lane/stage results for
|
|
@@ -246,15 +248,19 @@ Use diagnostics when setup or child startup looks wrong:
|
|
|
246
248
|
subagent({ action: "doctor" })
|
|
247
249
|
```
|
|
248
250
|
|
|
251
|
+
### Failed lane recovery and execution-mode changes
|
|
252
|
+
|
|
253
|
+
A failure in the subagent workflow, child launch, prompt runtime, extension loading, or child tooling setup is a lane infrastructure blocker, not permission to silently change execution mode. Stop and report the exact failure, run/status, and repo/cwd/worktree/branch/ref state. Retry or fix the `subagent` path only through a clear same-protocol retry; before retrying or asking the owner, verify the worktree is clean or capture the partial diff. For backlog lanes and other subagent-governed workflows, switching to `interactive_shell`, `pi -ne`, Codex/Claude/Cursor CLI, a foreground agent, or another external mode requires explicit owner approval. Pi core may print a generic `pi -ne` extension-load hint; that hint is outside this package and is not protocol-approved. A verified compaction abort may continue the retained child session once on the same resolved model; provider failures never select another model automatically.
|
|
254
|
+
|
|
249
255
|
### External terminal work
|
|
250
256
|
|
|
251
|
-
Use native `subagent` runs for unattended implementation, review, and gate work that needs managed isolation, durable artifacts, and process controls. Use `interactive_shell` for visible terminal work, alternate CLIs, trust prompts,
|
|
257
|
+
Use native `subagent` runs for unattended implementation, review, and gate work that needs managed isolation, durable artifacts, and process controls. Use `interactive_shell` for visible terminal work, alternate CLIs, trust prompts, or recovery only when the user explicitly requests that mode or the task is outside the governed subagent protocol; it is not an implicit replacement for a failed `subagent` lane.
|
|
252
258
|
|
|
253
259
|
A cooperating terminal runtime can register read-only external records through `@xzzpig/pi-subagents/external-runs`. Records include the source, session, state, optional report path, and completion reason. They are observations only: pi-subagents does not start, stop, steer, or otherwise own the foreign process. Run unattended raw terminal agents in an explicit isolated cwd or worktree; do not use a live project checkout as disposable review space.
|
|
254
260
|
|
|
255
261
|
### Scheduled subagent runs
|
|
256
262
|
|
|
257
|
-
Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for.
|
|
263
|
+
Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for. To keep schedules outside the project repository, set `{ "scheduledRuns": { "storeRoot": "~/.pi/subagent-schedules" } }` in the same config: `storeRoot` accepts an absolute path or a `~/`-prefixed path, and records land under `<storeRoot>/<sha256(path.resolve(cwd)) first 20 hex>/<scheduleId>/`.
|
|
258
264
|
|
|
259
265
|
```typescript
|
|
260
266
|
// One-shot reviewer
|
|
@@ -323,6 +329,19 @@ subagent({ action: "steer", id: "abc123", message: "Focus on the failing test."
|
|
|
323
329
|
|
|
324
330
|
The action waits up to three seconds for the child Pi session to accept the correlated user input and returns a request id with `delivered`, `scheduled`, `pending`, `partial`, `recovered`, or `failed` plus per-child states. Indexed pending children return `scheduled` immediately. Only a top-level single-child run may automatically interrupt after a missed acknowledgment and recover after confirmed pause within a further 15 seconds. Recovery preserves the original child contract and only its remaining deadline, turn, and tool budgets. If the session is missing, a budget is exhausted, the pause cannot be confirmed, or replacement launch fails, the source remains paused when pausing succeeded and the action returns the exact failure. Chain, parallel, and nested runs never auto-interrupt; inspect their per-child outcomes and handle failures explicitly. A late acknowledgment is recorded and cannot cancel committed recovery.
|
|
325
331
|
|
|
332
|
+
Steering supports three delivery modes via the `mode` parameter (`steer` is the default):
|
|
333
|
+
|
|
334
|
+
- `mode: "steer"` — interrupt the child at the next safe point of its current turn and deliver the message.
|
|
335
|
+
- `mode: "follow_up"` — do not interrupt; queue input through Pi's native follow-up path for the next turn boundary. Eligible completed retained workflow children (single-step runs in state `complete` with a stored session file) receive the message as a revival brief (`queueRevivalBrief`) when they are revived; paused children reject follow-up steering outright. The 20-message queue limit applies to retained revival briefs, not live follow-up input.
|
|
336
|
+
- `mode: "auto"` — same next-safe-point delivery path as `steer`, but without the automatic pause-and-revive recovery after a missed acknowledgment.
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
subagent({ action: "steer", id: "abc123", mode: "follow_up", message: "After this step, also validate the config file." })
|
|
340
|
+
subagent({ action: "steer", id: "abc123", mode: "auto", message: "Switch to the failing test now." })
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
For async runs, `delivered` records that the child consumed the correlated user input; foreground `delivered` records in-process transport acceptance. Neither is proof of model compliance. A live foreground follow-up acknowledgment reports `queued`, meaning Pi accepted it into its follow-up queue, not that it was delivered. The foreground transport does not provide a later correlated queued-to-delivered receipt.
|
|
344
|
+
|
|
326
345
|
## Watchdog
|
|
327
346
|
|
|
328
347
|
The subagent watchdog is an **opt-in** adversarial change reviewer. It is not the
|
|
@@ -96,6 +96,7 @@ A minimal agent file looks like this:
|
|
|
96
96
|
name: my-agent
|
|
97
97
|
package: code-analysis
|
|
98
98
|
description: What this agent does
|
|
99
|
+
advertise: true
|
|
99
100
|
aliases: developer, coder
|
|
100
101
|
model: provider/model-id
|
|
101
102
|
thinking: high
|
|
@@ -111,12 +112,11 @@ skillPath: ./skills, ../shared-skills
|
|
|
111
112
|
Your system prompt here.
|
|
112
113
|
```
|
|
113
114
|
|
|
114
|
-
That is only a starting point. Omit `package` for the traditional unqualified runtime name. Common optional fields include:
|
|
115
|
+
That is only a starting point. Omit `package` for the traditional unqualified runtime name. Set `advertise: true` only when the parent should receive this agent's name and description before deciding whether to delegate; advertisement is off by default. Common optional fields include:
|
|
115
116
|
- `defaultProgress`
|
|
116
117
|
- `defaultReads`
|
|
117
118
|
- `output`
|
|
118
119
|
- `aliases`
|
|
119
|
-
- `fallbackModels`
|
|
120
120
|
- `subagentOnlyExtensions`
|
|
121
121
|
- `skills`
|
|
122
122
|
- `skillPath`
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Use this reference when several independent tasks need coordinated workers, worktrees, or repositories. It defines lane ownership; use the other pi-subagents references for run controls, prompts, and mission details. The parent remains the final decision-maker.
|
|
4
4
|
|
|
5
|
-
Create lanes only
|
|
5
|
+
Create lanes only after delegation is operator-authorized and each lane materially improves evidence, independent review, specialization, useful parallelism, or isolated execution. Do not manufacture parallelism: keep dependent work serial, and only split work when each lane has a distinct decision and useful output.
|
|
6
6
|
|
|
7
7
|
## Lane board and authority
|
|
8
8
|
|
|
@@ -46,6 +46,8 @@ After a writer produces a candidate, run the required fresh-context, read-only r
|
|
|
46
46
|
|
|
47
47
|
Use stable lane-qualified artifact paths for reports and review output. A handoff states the lane status, repository and worktree, changed files, validation, open decisions, next action, and artifact or receipt paths. Copy only the final evidence to memory, a mission record, or a PR/comment, then remove scratch files from the active worktree before closing the lane.
|
|
48
48
|
|
|
49
|
+
For backlog lanes and other subagent-governed workflows, a setup/runtime/tooling failure remains an infrastructure blocker. Preserve the exact failure, run/status, and repository/cwd/worktree/branch/ref state; verify a clean worktree or capture any partial diff before a same-protocol retry or asking the owner. Do not start another writer or switch to an external, foreground, or CLI execution mode without explicit owner approval.
|
|
50
|
+
|
|
49
51
|
Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
|
|
50
52
|
|
|
51
53
|
Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.
|