pi-better-subagents 0.35.0 → 0.37.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.
Files changed (97) hide show
  1. package/README.md +13 -11
  2. package/assignment-outcomes.ts +9 -6
  3. package/assignment-report.ts +103 -19
  4. package/batch.mjs +14 -5
  5. package/bin/recover-workspace.mjs +19 -0
  6. package/catalog-host-admission.ts +19 -3
  7. package/catalog-preferences.ts +1 -1
  8. package/catalog-resolver.ts +35 -1
  9. package/catalog-store.ts +27 -20
  10. package/child-apply-patch.ts +13 -0
  11. package/child-dependencies.mjs +25 -12
  12. package/child-operations.ts +80 -1
  13. package/child-preflight.mjs +8 -2
  14. package/child-process-list.ts +8 -0
  15. package/cleanup.ts +10 -2
  16. package/config.ts +53 -3
  17. package/continuation-authority.ts +3 -1
  18. package/continuation-runtime.ts +88 -0
  19. package/continuation.ts +4 -2
  20. package/docs/usage.md +92 -81
  21. package/extensions.mjs +11 -13
  22. package/failures.ts +10 -2
  23. package/finalization.ts +21 -1
  24. package/goal-provider.ts +44 -2
  25. package/health-observation.ts +43 -48
  26. package/index.ts +417 -155
  27. package/isolated-workspace.ts +557 -0
  28. package/launch-context.ts +23 -0
  29. package/launch-digest.mjs +6 -0
  30. package/list.mjs +2 -2
  31. package/log-cursor.ts +91 -15
  32. package/managed-launch-bootstrap.mjs +2 -2
  33. package/managed-launch-client.ts +28 -8
  34. package/managed-launch-host.ts +168 -15
  35. package/managed-launch-journal.mjs +1 -5
  36. package/managed-launch-port.ts +4 -0
  37. package/operation-bridge-types.ts +27 -2
  38. package/output-payload.ts +26 -12
  39. package/owned-exit.ts +12 -0
  40. package/package.json +4 -2
  41. package/parse.ts +57 -10
  42. package/permission-policy.ts +41 -8
  43. package/process-identity.d.mts +1 -0
  44. package/process-identity.mjs +29 -0
  45. package/registry.ts +77 -38
  46. package/retained-result.ts +65 -0
  47. package/runtime-client/artifacts/darwin-arm64.gz +0 -0
  48. package/runtime-client/artifacts/darwin-arm64.json +1 -1
  49. package/runtime-client/artifacts/darwin-x64.gz +0 -0
  50. package/runtime-client/artifacts/darwin-x64.json +1 -1
  51. package/runtime-client/artifacts/linux-arm64.gz +0 -0
  52. package/runtime-client/artifacts/linux-arm64.json +1 -1
  53. package/runtime-client/artifacts/linux-x64.gz +0 -0
  54. package/runtime-client/artifacts/linux-x64.json +1 -1
  55. package/runtime-client/src/runtime/client.mjs +30 -3
  56. package/runtime-client/src/runtime/root.mjs +5 -2
  57. package/runtime-client/src/runtime/work-client.mjs +150 -7
  58. package/session-selection.ts +2 -1
  59. package/session-store.ts +9 -0
  60. package/settings-page.ts +147 -108
  61. package/shared-callback-batcher.ts +11 -2
  62. package/shared-catalog.ts +29 -21
  63. package/shared-navigator-panels.ts +26 -4
  64. package/shared-navigator.ts +244 -40
  65. package/shared-operation-coordinator/assignment-inbox.mjs +118 -0
  66. package/shared-operation-coordinator/assignment-observation.mjs +43 -35
  67. package/shared-operation-coordinator/src/assignment-changes.ts +73 -0
  68. package/shared-operation-coordinator/src/assignment-outcomes.ts +2 -0
  69. package/shared-operation-coordinator/src/background-requests.ts +14 -3
  70. package/shared-operation-coordinator/src/discovery.ts +5 -3
  71. package/shared-operation-coordinator/src/operations.ts +50 -2
  72. package/shared-operation-coordinator/src/outbox.ts +9 -0
  73. package/shared-operation-coordinator/src/result-supervision.ts +12 -0
  74. package/shared-operation-coordinator/src/rows.ts +2 -0
  75. package/shared-operation-coordinator/src/schema.ts +40 -24
  76. package/shared-operation-coordinator/src/store.ts +40 -8
  77. package/shared-operation-coordinator/src/subagent-launch.ts +24 -1
  78. package/shared-operation-coordinator/src/types.ts +5 -1
  79. package/shared-sandbox-core.ts +1 -1
  80. package/shared-task-exec.ts +12 -1
  81. package/shared-task-process-identity.ts +126 -0
  82. package/shared-task-process-list.ts +8 -2
  83. package/shared-task-sandbox.ts +5 -3
  84. package/shared-task-tools.ts +8 -5
  85. package/shared-work-client.d.mts +10 -0
  86. package/shared-work-client.mjs +150 -7
  87. package/subagent-tools.ts +28 -34
  88. package/task-guard.ts +13 -1
  89. package/task-policy.ts +8 -2
  90. package/timing.ts +10 -1
  91. package/tools.ts +4 -7
  92. package/work-observation.ts +91 -17
  93. package/worker-operations-host.ts +12 -4
  94. package/worker-waits.ts +93 -34
  95. package/workspace-files.ts +114 -0
  96. package/workspace-scope.ts +6 -0
  97. package/worktree-feedback.ts +77 -0
@@ -0,0 +1,88 @@
1
+ /** Select a saved, installed worker closure without changing the server owner. */
2
+ import { readFileSync, realpathSync, statSync } from "node:fs";
3
+ import { basename, dirname, join, normalize, sep } from "node:path";
4
+
5
+ const DOMAIN = join("src", "runtime", "domain", "subagents");
6
+ type Recipe = { runtimeRoot?: string; baseExtensionArgs?: readonly string[]; extensionArgs?: readonly string[] };
7
+ type Command = { file: string; fileArgs: string[] };
8
+
9
+ export function managedRuntimeRoot(domain: string): string | undefined {
10
+ if (!domain.endsWith(`${sep}${DOMAIN}`)) return undefined;
11
+ const root = domain.slice(0, -(DOMAIN.length + 1));
12
+ return basename(dirname(root)) === "releases" && /^[a-f0-9]{64}$/.test(basename(root)) ? root : undefined;
13
+ }
14
+
15
+ export interface ContinuationRuntime {
16
+ root: string;
17
+ mapPath(path: string): string;
18
+ mapArgs(args: readonly string[]): string[];
19
+ command(command: Command): Command;
20
+ }
21
+
22
+ /**
23
+ * Only sibling, published releases are eligible. User extensions retain their
24
+ * original identity check. Permission policy is still generated by the current
25
+ * server; a saved runtime does not grandfather its previous permission grants.
26
+ * Published releases are retained by the installer (it removes staging only).
27
+ * Any future release GC must treat LaunchRecipe.runtimeRoot as a reference.
28
+ */
29
+ export function selectContinuationRuntime(options: { currentDir: string; recipe?: Recipe }): ContinuationRuntime | undefined {
30
+ const current = managedRuntimeRoot(options.currentDir);
31
+ if (!current || !options.recipe) return undefined;
32
+ const recipe = options.recipe;
33
+ // Upgrade recipes written before runtimeRoot existed using the mandatory
34
+ // harness control, never a user-selected/custom extension path.
35
+ const args = recipe.baseExtensionArgs ?? recipe.extensionArgs ?? [];
36
+ const steer = args.find((value, index) => args[index - 1] === "--extension" && value.endsWith(`${sep}${DOMAIN}${sep}child-steer.ts`));
37
+ const saved = recipe.runtimeRoot ?? (steer ? managedRuntimeRoot(dirname(steer)) : undefined);
38
+ if (!saved || saved === current) return undefined;
39
+ const unavailable = (detail: string): never => {
40
+ throw new Error(`Cannot resume: saved runtime ${basename(saved)} unavailable (${detail}). Restore that release or explicitly launch a replacement conversation; no worker was started.`);
41
+ };
42
+ if (normalize(saved) !== saved || dirname(saved) !== dirname(current) || !/^[a-f0-9]{64}$/.test(basename(saved))) {
43
+ return unavailable("not a sibling managed release");
44
+ }
45
+ function manifest(root: string) {
46
+ let value;
47
+ try {
48
+ if (realpathSync(root) !== root) return unavailable("release path is not canonical");
49
+ value = JSON.parse(readFileSync(join(root, "runtime.json"), "utf8"));
50
+ } catch { return unavailable("missing or unreadable release manifest"); }
51
+ if (value.format !== 1 || value.root !== root || value.build?.contentId !== basename(root)
52
+ || value.node !== join(root, "node/bin/node") || value.installRoot !== dirname(dirname(root))) {
53
+ return unavailable("invalid release manifest");
54
+ }
55
+ return value;
56
+ }
57
+ const before = manifest(saved), now = manifest(current);
58
+ // These releases share the existing v1 worker admission/policy/bridge wire
59
+ // formats. Refuse SDK, Node, platform or protocol transitions rather than
60
+ // assuming that a new server can host any historic worker.
61
+ if (before.build.protocolVersion !== 1 || now.build.protocolVersion !== 1
62
+ || ["piSdkVersion", "nodeVersion", "platform"].some(key => !before.build[key] || before.build[key] !== now.build[key])) {
63
+ throw new Error(`Cannot resume: saved runtime ${basename(saved)} is incompatible with the current worker protocol, SDK or platform. Explicit replacement is required; no worker was started.`);
64
+ }
65
+ function required(path: string, directory = false): string {
66
+ try {
67
+ const stat = statSync(path);
68
+ if (realpathSync(path) !== path || !(stat.isFile() || directory && stat.isDirectory())) return unavailable("worker file is missing or redirected");
69
+ } catch { return unavailable("worker file is missing or unreadable"); }
70
+ return path;
71
+ }
72
+ const node = required(before.node);
73
+ const mapPath = (path: string): string => path.startsWith(`${current}${sep}`)
74
+ ? required(join(saved, path.slice(current.length + 1)), true) : path;
75
+ return {
76
+ root: saved,
77
+ mapPath,
78
+ mapArgs: values => values.map((value, index) => values[index - 1] === "--extension" ? mapPath(value) : value),
79
+ command: command => {
80
+ // Only executable slots are rewritten. A prompt or arbitrary CLI
81
+ // value that happens to contain a runtime path must stay untouched.
82
+ const fileArgs = [...command.fileArgs];
83
+ fileArgs[0] = mapPath(fileArgs[0]!);
84
+ if (basename(fileArgs[0]!) === "task-runtime.mjs") fileArgs[1] = mapPath(fileArgs[1]!);
85
+ return { file: node, fileArgs };
86
+ },
87
+ };
88
+ }
package/continuation.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { hasWorkspaceCheckpoint } from "./isolated-workspace.ts";
1
2
  /**
2
3
  * Subagent continuation.
3
4
  *
@@ -536,11 +537,12 @@ export function planContinuation(options: {
536
537
 
537
538
  let workspaceIsDir = false;
538
539
  try { workspaceIsDir = statSync(recipe.cwd).isDirectory(); } catch { workspaceIsDir = false; }
539
- if (!workspaceIsDir) throw refusal(id, `its workspace ${recipe.cwd} is missing.`);
540
+ const recoverable = !workspaceIsDir && recipe.workspace && hasWorkspaceCheckpoint(recipe.workspace);
541
+ if (!workspaceIsDir && !recoverable) throw refusal(id, `its workspace ${recipe.cwd} is missing.`);
540
542
  if (recipe.sandboxDir !== undefined) {
541
543
  let sandboxIsDir = false;
542
544
  try { sandboxIsDir = statSync(recipe.sandboxDir).isDirectory(); } catch { sandboxIsDir = false; }
543
- if (!sandboxIsDir) throw refusal(id, `its sandbox workspace ${recipe.sandboxDir} is missing.`);
545
+ if (!sandboxIsDir && !recoverable) throw refusal(id, `its sandbox workspace ${recipe.sandboxDir} is missing.`);
544
546
  }
545
547
 
546
548
  const lookup: ConversationLookup = findSavedConversation({
package/docs/usage.md CHANGED
@@ -18,12 +18,13 @@ Set `delegationMode` in the user config described under
18
18
  [Tool scoping](#tool-scoping-allowlist) to `manual`, `adaptive`, or
19
19
  `coordinator` (default `adaptive`). This controls foreground delegation guidance,
20
20
  not child permissions or catalog definitions. `/subagents settings` (or simply
21
- `/subagents`) opens the terminal settings page with mode, concurrent-subagent
22
- cap, tool-wait alert, no-progress alert, and default skill-exposure controls, an
23
- Agents shortcut to `/agents`, and Reset to defaults. The two time values are
24
- edited independently in minutes; `0` turns one alert off. The page uses the same
25
- selected-row and active-cell styling as `/sandbox`, with one editable value
26
- column. Skill exposure cycles between
21
+ `/subagents`) opens the terminal settings page. Delegation mode, the concurrency cap, and
22
+ Git workspace appear together. Run timeout and the two alert intervals come next,
23
+ followed by skills, the Agents catalog, and Reset to defaults. As in
24
+ `/harness-settings`, the cursor marks the active row and its help appears
25
+ below the list. On Run timeout, Space selects **No limit** and Enter edits
26
+ the duration. Each alert has a separate interval in minutes. Enter `0`
27
+ to turn that alert off. Skill exposure cycles between
27
28
  Discover automatically and No skill catalog. The Selected skills row opens the
28
29
  shared searchable checkbox picker, which lists loaded skills by name and
29
30
  description, uses Space to toggle, Enter to apply, and Esc to cancel. Typing
@@ -36,8 +37,8 @@ than being dropped.
36
37
  Edits automatically persist for this session, including across reloads; Escape
37
38
  closes the page without undoing them.
38
39
  Enter edits the cap as a positive whole number or a timing value in minutes;
39
- Escape cancels an unfinished edit. Ctrl+S saves mode, cap, timing alerts, and
40
- skill exposure as defaults. Reset to defaults restores them from the saved
40
+ Escape cancels an unfinished edit. Ctrl+S saves the session’s delegation, workspace,
41
+ timing, and skill settings as defaults. Reset to defaults restores them from the saved
41
42
  config. Sandbox permissions remain in `/sandbox`.
42
43
 
43
44
  Command equivalents also work outside the terminal UI:
@@ -112,7 +113,7 @@ thresholds continue to take precedence for subagent health.
112
113
 
113
114
  | Tool | Blocks? | What it does |
114
115
  |------|---------|--------------|
115
- | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `skills` ([skill exposure](#skill-exposure)), `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-tool-wait-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`. |
116
+ | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `skills` ([skill exposure](#skill-exposure)), `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `isolation`, `git_clone_workspace`, `recover_in_clone`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-tool-wait-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`. |
116
117
  | `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; optional per-job `session_id` or `session_name` continues a saved conversation), `onCapacity` (`reject` or `launch-available`). |
117
118
  | `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, `toolWaitMinutes`, `stuckMinutes`, per-setting `sources`/`timingSources` (`environment`, `session`, `config`, or `default`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. Timing values already account for the same environment precedence a launch uses. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
118
119
  | `subagent_list` | never | Compact list for the current folder and descendants across foreground sessions (default 10 rows / 1 KiB page). Each row includes `session_id`. Params: `all` (machine-global search), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. Abandoned launch records are reported separately and are never counted as runs. |
@@ -206,6 +207,12 @@ supervised local commands. The bridge retains the worker's captured permissions
206
207
  and applies the current Background Tasks policy as well. Explicit tool exclusions
207
208
  and clean loadouts can withhold the bridge.
208
209
 
210
+ An explicit tool list containing `wait_for_operations` must also contain
211
+ `acknowledge_operation_result` and either `bg_task_status` or `bg_task_log`.
212
+ The launcher checks this after permission filtering and refuses an incomplete
213
+ combination. A default loadout with no authorized evidence reader withholds
214
+ waiting instead of adding permissions.
215
+
209
216
  A worker starts a long validation command, continues independent work, then calls
210
217
  `wait_for_operations` with its owned task ids. Call this tool directly as the only
211
218
  tool call in its assistant message. A nested codemode call cannot deliver the
@@ -230,6 +237,23 @@ checked again. Full capacity leaves the wait ready. Missing or conflicting
230
237
  recovery evidence leaves it held with a reason. The runner survives worker and Pi
231
238
  exit, but v1 does not run an unattended model after Pi shuts down.
232
239
 
240
+ ## Reporting completion
241
+
242
+ Bound assignments use `report_assignment_result` with evidence from inside the
243
+ assigned workspace. A sibling results directory is outside that boundary. An
244
+ existing workspace source file can be evidence; read-only workers need not write
245
+ a new artifact. Use `offset` and `max_bytes` to retain an excerpt from a file
246
+ larger than 65,536 bytes.
247
+
248
+ Before accepting an unblocked incomplete report with concrete `remaining_work`,
249
+ the child allows one chance to continue that work. A normal model stop without
250
+ an accepted report can use the same correction allowance to submit or correct
251
+ the report. The allowance belongs to the current attempt, survives reload, and
252
+ keeps the original deadline and permissions. Concrete blockers, aborted/error
253
+ stops, parked work and expired deadlines do not trigger correction. Accepted
254
+ reports remain immutable; exhausted correction retains the incomplete or
255
+ unverified result for the coordinator.
256
+
233
257
  ## Codemode batch launches
234
258
 
235
259
  On Pi 0.99.1 or newer, enable native codemode alongside the existing direct
@@ -280,14 +304,15 @@ by the existing harness runtime.
280
304
 
281
305
  ## Run timing (deadline, ceiling, tool wait, stuck)
282
306
 
307
+ When a limit stops the run, `subagent_result` identifies the limit, the last recorded work, open tool calls and the available files. Unfinished checks remain unverified. The same read works with `callback:false`.
308
+
283
309
  Timeout control belongs to the harness, not to the prompt or the skill that
284
310
  launched the run. A time limit written into a prompt is enforced by nothing, and
285
311
  a parent that only notices late tends to kill a child that was still making
286
312
  progress. Every run gets a tool-wait alert, stall detection, and a 60-minute hard
287
313
  timeout by default. Soft deadlines remain opt-in because total runtime does not
288
314
  distinguish a slow agent from a stalled one.
289
- Use Timeout (minutes) in `/subagents settings` to change the session default;
290
- Ctrl+S saves it for future sessions. `0` disables the timeout. Changes apply to
315
+ Choose **Run timeout** in `/subagents settings`. Enter a duration in minutes, type **No limit**, or press Space to select **No limit**. Ctrl+S saves the choice for future sessions. Changes apply to
291
316
  new attempts, not runs already in progress.
292
317
 
293
318
  | Control | Default | What happens |
@@ -414,11 +439,10 @@ given.
414
439
  pending completion, so the caller receives one `killed`/`completed`/`failed`
415
440
  row instead of discovering the outcome by polling `subagent_list()`. A run
416
441
  stopped while the session is shutting down is recovered by the next session.
417
- - **Optional busy steering.** In `/harness-settings`, set **Completions while
418
- busy** to **Steer active run** to receive ordinary completions during
442
+ - **Optional busy steering.** In `/harness-settings`, set **Completion delivery** to **During run** to receive ordinary completions during
419
443
  foreground work. Changes autosave to the current session branch and apply
420
444
  immediately; **Ctrl+S** saves the choice as the user default for future
421
- sessions, including standalone callback packages. **Wait until idle** is the
445
+ sessions, including standalone callback packages. **When idle** is the
422
446
  default. The former `PI_BETTER_CALLBACK_WHILE_BUSY` environment variable is
423
447
  no longer supported. Completions spanning multiple accumulation windows during
424
448
  one tool call stay together until the final active tool ends, then share one
@@ -452,8 +476,7 @@ an enabled human profile. Saved enabled profiles and session choices stay enable
452
476
  cache directories when Outside is Read or Read/write. Credential and control
453
477
  denials retain precedence. See the permission details below.
454
478
  - **Tool allowlist.** Confined children admit only verified read/write/edit/bash
455
- implementations, guarded `run_application`, the guarded `apply_patch`, and the trusted tools ticked in
456
- `/sandbox`. The fixed `process_list` adapter is available with Process access
479
+ implementations, guarded `run_application`, the guarded `apply_patch`, and the selected extension tools with verified providers. The fixed `process_list` adapter is available with Process access
457
480
  set to Read. Other requested tools are reported as unavailable, with the reason.
458
481
  - **No runaway recursion.** Confined children cannot spawn nested agents.
459
482
  `allow_nested:true` loads nested-agent support only for unconfined children.
@@ -497,7 +520,14 @@ does not start an emulator or allocate test resources. The setting governs
497
520
  the fixed adapter only, not every OS process operation available through bash
498
521
  or trusted tools. New launches capture changes; running children retain their
499
522
  launch-time setting. Raw macOS `/bin/ps` remains subject to setuid execution
500
- restrictions. See [ADR 0011](../../../docs/adr/0011-fixed-read-only-process-inventory.md).
523
+ restrictions. With Process Read and Commands On, the task PATH includes a
524
+ protected non-setuid compatibility entry for exactly
525
+ `ps -p PID -o lstart= -o comm=`. It returns the current-user process's start time
526
+ and executable path, without exposing arguments or environment. The harness
527
+ requires Xcode Command Line Tools to build this fixed helper; failure refuses
528
+ identity queries without disabling other commands. This does not alter absolute
529
+ `/bin/ps` or callers that replace PATH. See [ADR 0024](../../../docs/adr/0024-sandbox-process-identity-compatibility.md)
530
+ and [ADR 0011](../../../docs/adr/0011-fixed-read-only-process-inventory.md).
501
531
  Network Off blocks task network access while Pi's provider transport remains
502
532
  available. The confined file worker has an 8 MiB file limit and rejects larger
503
533
  files explicitly; use confined commands for larger files when commands are On.
@@ -522,9 +552,8 @@ limit to 10 min in `/sandbox`, then press Ctrl+S. New launches capture the polic
522
552
  running children keep theirs. An incompatible older consumer is rejected rather
523
553
  than silently dropping these restrictions.
524
554
 
525
- Extension tools are
526
- chosen in `/sandbox` → Subagents · Tools
527
- ([ADR 0009](../../../docs/adr/0009-guarded-and-trusted-subagent-tools.md)):
555
+ Select tools in the role, worker defaults or spawn request. Loading a tool grants access to call it. Use `/sandbox` to edit the resource rules.
556
+ [Sandbox tool loading and permission to use tools](../../../docs/adr/0027-sandbox-tools-and-permissions.md) defines the contract.
528
557
 
529
558
  - **Guarded:** `apply_patch`, a harness adapter with the Codex tool's name,
530
559
  schema and patch format. Every add, update, move and delete goes through the
@@ -534,17 +563,14 @@ chosen in `/sandbox` → Subagents · Tools
534
563
  checked first; no file is left half-patched, and a failure part-way reports
535
564
  what was and wasn't applied. It is added for a child that may `edit` or
536
565
  `write`, or asks for it.
537
- - **Trusted:** third-party tools you tick (default `web_fetch` and `web_search`).
538
- Their package is loaded into the child and they run in the child Pi process,
539
- **outside the file rules**. The child admits one only when both its name and
540
- its package match the ticked entry, so another package registering the same
541
- name is refused. A single extension file with no package manifest is loaded
542
- and admitted by itself, never its directory. Known network tool names
543
- (`web_fetch`, `web_search`, `firecrawl_scrape`, `firecrawl_extract`, `mcp`, `mcpScript`, `remote_bash`, and any `mcp__*` name) are refused while Network access is Off; this is a name list, not a
544
- network sandbox. A ticked tool whose package can't be found is left out of a
545
- default loadout and reported with its reason in the launch output; an explicit
546
- `tools` request for a tool the task boundary cannot provide refuses the launch.
547
- Ticked tools join the default tool list; an explicit `tools` list still decides.
566
+ - **Extension tools:** the child loads the selected provider and checks its
567
+ canonical source at dispatch. A single user-installed extension entrypoint is
568
+ loaded by itself. Known network tools require Network access On. The extension
569
+ runs in the trusted Pi process, outside guarded file operations.
570
+ If a trusted tool is inherited from the defaults, registers in the child, and
571
+ is then inactive (for example, because the extension requires a different
572
+ model), the child logs the omission once and continues without it. Missing
573
+ registrations and unavailable explicitly requested tools still fail preflight.
548
574
 
549
575
  Other tools are disabled in confined children. One that only joined the default
550
576
  loadout is omitted from the child and listed in launch output with the reason;
@@ -569,45 +595,30 @@ there but refuse unlink, leaving an empty lock even when status exits zero.
569
595
  The default skips optional index refreshes; it does not disable required locks
570
596
  for `git add` or commits, grant metadata removal, or remove existing locks.
571
597
 
572
- A sandboxed subagent that will mutate Git should set **`git_clone_workspace:true`**
573
- on `subagent_spawn`. The parent prepares a fresh, self-contained Git clone whose
574
- `.git/` directory lives **inside the sandbox writable root**, then runs the child
575
- in that clone.
576
-
577
- Why this matters: a linked Git worktree (created with `git worktree add`) has a
578
- `.git` file that points back to administrative state under the main repository,
579
- typically outside the sandbox directory. A sandbox that only allows writes under
580
- the worktree directory therefore cannot support normal Git producer operations
581
- such as fetch, rebase, commit, and push — the child stalls or fails when Git
582
- tries to write metadata it cannot reach. `git_clone_workspace:true` avoids this
583
- by cloning the repository with a real `.git/` directory inside the writable root.
584
-
585
- The clone uses:
586
-
587
- ```
588
- git clone --reference-if-able <local-reference-repo> --dissociate \
589
- <remote-url> <sandbox-workspace>
590
- ```
591
-
592
- `--reference-if-able` borrows local objects from the parent repository during
593
- setup; `--dissociate` removes the alternates link afterwards, so the clone is
594
- self-contained and safe to delete. The clone source prefers the source
595
- workspace's upstream remote URL (`origin` when set) so the disposable
596
- workspace's `origin` points at the real remote rather than the parent working
597
- tree — pushes therefore target upstream, not the sandboxed parent. The local
598
- repository is used only as a reference (and as a content fallback when no
599
- remote is configured). Source remotes are re-synced after clone. The
600
- checked-out branch/commit matches the source workspace at spawn time.
601
- Repo-local Git identity settings from the source (`user.name`, `user.email`,
602
- and `user.signingkey` when set) are copied into the clone so ordinary commits
603
- work without reconfiguring identity inside the disposable workspace.
604
-
605
- If the source workspace is a linked worktree, the clone is prepared from the
606
- main repository's object database and the requested branch/commit; the child is
607
- never launched into the structurally broken linked-worktree sandbox. If clone
608
- preparation fails, the spawn fails fast with a message explaining that the
609
- linked-worktree Git metadata is outside the sandbox and recommending
610
- `git_clone_workspace:true`.
598
+ ### Git workspaces
599
+
600
+ Single and batch launches give each Git writer an independent checkout of the
601
+ source HEAD. **Git workspace** in `/subagents settings` selects **Clone** (the
602
+ default) or **Worktree** for new launches. Ctrl+S saves the selection. Clone
603
+ keeps Git metadata inside the checkout. Worktree shares the source object store.
604
+ A read-only launch, an explicit `sandbox_dir`, or `isolation:false` can use the
605
+ supplied directory. The explicit `git_clone_workspace:true` option keeps its
606
+ existing branch and upstream selection.
607
+
608
+ `subagent_result` reports the checkout or its saved result. Inspect and apply the
609
+ changes you want. Cleanup verifies an independent copy before reclaiming an idle
610
+ checkout and its Worktree registration. The saved files include the exact Git
611
+ index, working files, ignored outputs and local commits. Identical file contents
612
+ share storage. After cleanup, use `pi-subagents-recover <run-id> <new-directory>`
613
+ to inspect an independent copy, including an unsuccessful attempt. An eligible
614
+ continuation restores its saved workspace and history.
615
+
616
+ When sandbox rules block a Git metadata update in Worktree, the parent can
617
+ review the existing changes or continue with `session_id` and
618
+ `recover_in_clone:true`. The handoff verifies the copy under the conversation's
619
+ writer lease. The next attempt uses the same sandbox policy. If Git has an open
620
+ transaction or recovery cannot verify the copy, inspect the original directory
621
+ reported in the result.
611
622
 
612
623
  The mandatory task guard is independent of optional guardrails extensions.
613
624
  Adding a package to the tool map does not make its tools safe to execute outside
@@ -713,12 +724,10 @@ The effective config also sets:
713
724
 
714
725
  ## The allowlist also decides what LOADS
715
726
 
716
- For confined children, the requested list is first restricted to tools with
717
- verified task adapters and the trusted tools ticked in `/sandbox`; only the
718
- ticked tools' packages load. `toolExtensions` still chooses which package to
719
- load for a tool (an override), but the child admits it only if that is the
720
- ticked package. Provider extensions can still load as trusted runtime
721
- dependencies. Nested spawning and
727
+ For confined children, the requested list selects verified task adapters and
728
+ extension providers. A worker mapping takes precedence over an active
729
+ user-installed entrypoint. Previously saved trusted-package records can
730
+ identify a provider for a selected tool. Nested spawning and
722
731
  inherited extension discovery are currently unavailable under confinement.
723
732
 
724
733
  The mapping behavior below applies to unconfined children and to admitted
@@ -731,9 +740,10 @@ which extension *code* is loaded into it. A child launches as
731
740
  pi -p --mode json --no-extensions -e <package backing a requested tool> ...
732
741
  ```
733
742
 
734
- so a package that backs no requested tool never loads. With the default
735
- allowlist (`read, bash, edit, write, web_search, web_fetch`) exactly one package
736
- loads — the web-tools one — and `web_fetch` works normally.
743
+ The default editable worker gets the Harness `apply_patch` adapter. An explicit
744
+ `process_list` request loads the bounded current-user inventory adapter. Each
745
+ can use an ordinary provider override. The default web tools load their
746
+ configured package. Both execution modes use the selected tools without an additional permission checkbox.
737
747
 
738
748
  Two maps in `config.json` drive it, with a built-in default for provider auth:
739
749
 
@@ -748,8 +758,9 @@ same provider replaces the built-in one, and an empty list disables it. A mapped
748
758
  package that is not installed still fails the launch with the explicit
749
759
  missing-extension error rather than starting without provider auth.
750
760
 
751
- Ask for a tool with no mapping and the spawn still succeeds, but says so at
752
- launch — the tool simply will not exist in the child.
761
+ A required tool with no possible provider fails admission. If an extension
762
+ could supply the name, the worker checks the active registration during
763
+ startup. Both failures identify the missing tool.
753
764
 
754
765
  `clean:true` is the narrowest case of the same mechanism: no extensions at all.
755
766
  For unconfined children, `allow_nested:true` loads this package into the child;
package/extensions.mjs CHANGED
@@ -34,7 +34,7 @@
34
34
  * A builtin needs no extension, so it never counts as unmapped.
35
35
  */
36
36
  // codemode is supplied by the harness child adapter, not a discovered package.
37
- export const BUILTIN_TOOLS = ["read", "bash", "edit", "write", "codemode"];
37
+ export const BUILTIN_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls", "codemode"];
38
38
 
39
39
  /** Marker spec meaning "this extension's own package" (for allow_nested). */
40
40
  export const SELF_SPEC = "self";
@@ -88,11 +88,11 @@ export function toolList(tools) {
88
88
  * @returns {{mode: "isolated"|"clean"|"inherit", specs: string[], unmapped: string[], reasons: Record<string,string[]>}}
89
89
  * mode — "isolated" passes --no-extensions + explicit -e (the default);
90
90
  * "clean" passes --no-extensions with no -e;
91
- * "inherit" passes neither (operator opt-out, NOT model-selectable).
91
+ * "inherit" keeps discovery and adds explicitly selected mappings.
92
92
  * specs — extension specs to load, deduped, in a stable order.
93
93
  * unmapped — requested tools that are neither builtin nor mapped to an
94
- * extension. They simply will not exist in the child; surfaced so
95
- * the human sees it instead of the child silently lacking a tool.
94
+ * extension. Admission rejects a known missing required provider.
95
+ * Preflight verifies registrations supplied by loaded extensions.
96
96
  * reasons — spec -> what pulled it in, for the spawn diagnostic.
97
97
  */
98
98
  export function resolveExtensions(a = {}) {
@@ -107,13 +107,10 @@ export function resolveExtensions(a = {}) {
107
107
 
108
108
  // allow_nested is honored in every mode: it is an explicit caller request,
109
109
  // and without our own package loaded the child has no subagent tools at all.
110
- if (a.allowNested) add(SELF_SPEC, "allow_nested");
111
-
112
- if (cfg.inheritExtensions === true) {
113
- return { mode: "inherit", specs: [], unmapped: [], reasons: {} };
114
- }
110
+ const inherit = cfg.inheritExtensions === true;
111
+ if (a.allowNested && !inherit) add(SELF_SPEC, "allow_nested");
115
112
  if (a.clean === true) {
116
- return { mode: "clean", specs, unmapped: [], reasons };
113
+ return { mode: inherit ? "inherit" : "clean", specs, unmapped: [], reasons };
117
114
  }
118
115
 
119
116
  const toolMap = cfg.toolExtensions ?? {};
@@ -122,12 +119,14 @@ export function resolveExtensions(a = {}) {
122
119
  if (BUILTIN_TOOLS.includes(tool)) continue;
123
120
  const mapped = toSpecList(toolMap[tool]);
124
121
  if (mapped.length === 0) {
125
- if (!unmapped.includes(tool)) unmapped.push(tool);
122
+ if (!inherit && !unmapped.includes(tool)) unmapped.push(tool);
126
123
  continue;
127
124
  }
128
125
  for (const spec of mapped) add(spec, `tool:${tool}`);
129
126
  }
130
127
 
128
+ if (inherit) return { mode: "inherit", specs, unmapped, reasons };
129
+
131
130
  // Model auth is not tool-shaped: xai/grok needs pi-xai-oauth loaded or the
132
131
  // child cannot authenticate at all, whatever tools it was granted. A user
133
132
  // entry for a provider wins over the built-in one, including an empty list
@@ -151,8 +150,7 @@ export function resolveExtensions(a = {}) {
151
150
  * @returns {{args: string[], missing: string[]}}
152
151
  */
153
152
  export function extensionArgs(resolution, resolvePath) {
154
- if (resolution.mode === "inherit") return { args: [], missing: [] };
155
- const args = ["--no-extensions"];
153
+ const args = resolution.mode === "inherit" ? [] : ["--no-extensions"];
156
154
  const missing = [];
157
155
  for (const spec of resolution.specs) {
158
156
  const path = resolvePath(spec);
package/failures.ts CHANGED
@@ -1,4 +1,5 @@
1
- import { closeSync, fstatSync, openSync, readSync } from "node:fs";
1
+ import { resultDir } from "./session-store.ts";
2
+ import { existsSync, closeSync, fstatSync, openSync, readSync } from "node:fs";
2
3
  import { join } from "node:path";
3
4
  import { logPathFor, runDir, taskRuntimeTrust } from "./registry.ts";
4
5
  import { activeFailures, actionableFailures, disposeIncidents, failureIdentity, findIncident, formatFailureSummary, formatTerminalFailureFacts, markFailureAttentionDelivered,
@@ -18,7 +19,10 @@ const workerDiagnostics = new SandboxDiagnostics({ context: "worker",
18
19
 
19
20
  export { formatFailureSummary, pendingFailureAttention, markFailureAttentionDelivered, toolOperation };
20
21
  export const failurePath = (id: string) => join(runDir(id), "failures.jsonl");
21
- export const readRunFailures = (id: string): FailureState => readFailureState(failurePath(id));
22
+ export function readRunFailures(id: string): FailureState {
23
+ const retained = !existsSync(runDir(id)) && resultDir(id);
24
+ return readFailureState(retained ? join(retained, "failures.jsonl") : failurePath(id));
25
+ }
22
26
  interface Scan {
23
27
  offset: number; head: string; identity: string; model: IncidentModel; retry?: number;
24
28
  /**
@@ -162,6 +166,10 @@ function exactRuleLeftovers(path: string, prior: FailureState): Set<string> {
162
166
  /** Scan complete source records, independent of the finite progress/transcript tail. */
163
167
  export function collectRunFailures(id: string, cwd: string, terminal = false, assertCurrent: () => void = () => {}): FailureState {
164
168
  assertCurrent();
169
+ if (!existsSync(runDir(id))) {
170
+ const retained = resultDir(id);
171
+ if (retained && existsSync(join(retained, "result.json"))) return readRunFailures(id);
172
+ }
165
173
  const path = failurePath(id);
166
174
  let fd: number;
167
175
  try { fd = openSync(logPathFor(id), "r"); }
package/finalization.ts CHANGED
@@ -26,8 +26,11 @@ import {
26
26
  } from "./registry.ts";
27
27
  import { fmtElapsed, fmtSpend } from "./widget.ts";
28
28
  import { evaluateParkDisposition, type ParkDisposition } from "./worker-waits.ts";
29
+ import { reconcileRun, type ProcessProbe, type ReconcileResult } from "./health.ts";
29
30
 
30
31
  export interface FinalizeHooks {
32
+ /** Recovery proved the original writer gone; the exit observer was lost. */
33
+ recoveredWriterExit?: boolean;
31
34
  renderWidget?: () => void;
32
35
  notify?: (message: string, level: "info" | "warning") => void;
33
36
  sendMessage?: (
@@ -45,6 +48,20 @@ export interface FinalizeResult {
45
48
  park?: ParkDisposition;
46
49
  }
47
50
 
51
+ /** The current management owner calls this only for an interrupted, unobserved writer. */
52
+ export function reconcileInterruptedRun(meta: RunMeta, probe: ProcessProbe, now: number, hooks: FinalizeHooks = {}): {
53
+ reconciliation: ReconcileResult; finalization?: FinalizeResult;
54
+ } {
55
+ const reconciliation = reconcileRun(meta, probe, now);
56
+ if ((meta.status === "running" || meta.status === "orphaned") && meta.supervisionInterruptedAt !== undefined && reconciliation.status === "lost") {
57
+ const run = parseRunForLifecycle(meta.id);
58
+ if (run.sawEnd && run.unmatchedToolCalls.length === 0) {
59
+ return { reconciliation, finalization: finalizeRun(meta.id, null, { ...hooks, recoveredWriterExit: true }) };
60
+ }
61
+ }
62
+ return { reconciliation };
63
+ }
64
+
48
65
  /**
49
66
  * Finalize a run once its child exits. Idempotent: a run already marked
50
67
  * terminal is left alone. Persists lifecycle classification + failureReason
@@ -92,7 +109,10 @@ export function finalizeRun(
92
109
  // and the recorded wait is held for its owner.
93
110
  const park = evaluateParkDisposition({
94
111
  runId: id,
95
- cleanExit: code === 0 && !outcome.incomplete && !outcome.diagnostics.modelError,
112
+ // Preserve a verified staged checkpoint for post-restart park recovery.
113
+ // The coordinator still requires writer-exit and lease-release proof.
114
+ cleanExit: (code === 0 || (code === null && hooks.recoveredWriterExit === true))
115
+ && completed && !outcome.incomplete && !outcome.diagnostics.modelError,
96
116
  });
97
117
  const parked = park.parked && park.record !== undefined;
98
118
  if (parked && park.record) {
package/goal-provider.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import { activateWorkObservation, hasWorkObservationContext, workObservation, onWorkObservation } from "./work-observation.ts";
2
3
  import {
3
4
  belongsToOrigin,
4
5
  effectiveStatus,
@@ -38,13 +39,42 @@ function parkActivity(meta: Parameters<typeof effectiveStatus>[0]): Record<strin
38
39
  };
39
40
  }
40
41
 
42
+ function observedActivity(observed: any, ctx?: ExtensionContext) {
43
+ if (observed?.status !== "ready") throw new Error(observed?.reason ?? "Subagent activity is unverified");
44
+ return {
45
+ providerId: "subagents", label: "Subagents", nextDeadline: observed.nextDeadline ?? null,
46
+ items: observed.rows.filter((row: any) => !ctx || (
47
+ belongsToOrigin(row.meta, { cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId() }) &&
48
+ (!row.meta.callbackOrigin?.branchId || ctx.sessionManager.getBranch().some(entry => entry.id === row.meta.callbackOrigin.branchId))
49
+ )).map((row: any) => {
50
+ const status = row.assignment.state;
51
+ const active = status === "running" || status === "waiting";
52
+ return { id: row.meta.id, label: row.meta.name, status, active, terminal: !active,
53
+ attention: !active && status !== "completed", unhealthy: row.meta.status === "orphaned",
54
+ startedAt: row.meta.startedAt, endedAt: row.meta.endedAt,
55
+ details: { assignment: row.assignment, sourceRevision: row.sourceRevision } };
56
+ }),
57
+ };
58
+ }
59
+
41
60
  export function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
42
61
  const emitProvider = (): void => {
43
62
  pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
44
63
  id: "subagents",
45
64
  label: "Subagents",
46
65
  scope: "session",
47
- getActivity: (ctx?: ExtensionContext) => {
66
+ activityVersion: 1,
67
+ getActivity: (ctx?: ExtensionContext, options?: { cachedOnly?: boolean }) => {
68
+ const observed = workObservation();
69
+ if (!observed && options?.cachedOnly) {
70
+ return { providerId: "subagents", coverage: "unverified", items: [], nextDeadline: null };
71
+ }
72
+ if (!observed && hasWorkObservationContext()) {
73
+ return activateWorkObservation().then(() => observedActivity(workObservation(), ctx));
74
+ }
75
+ if (observed) {
76
+ return observedActivity(observed, ctx);
77
+ }
48
78
  let sessionId: string | undefined;
49
79
  try {
50
80
  sessionId = ctx?.sessionManager?.getSessionId();
@@ -54,9 +84,11 @@ export function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
54
84
  const origin = ctx ? { cwd: ctx.cwd, sessionId } : undefined;
55
85
  return {
56
86
  providerId: "subagents",
87
+ nextDeadline: null,
57
88
  label: "Subagents",
58
89
  items: listMetasForParent(process.pid)
59
90
  .filter((meta) => !origin || belongsToOrigin(meta, origin))
91
+ .filter((meta) => !ctx || !meta.callbackOrigin?.branchId || ctx.sessionManager.getBranch().some(entry => entry.id === meta.callbackOrigin?.branchId))
60
92
  .map((meta) => {
61
93
  const status = effectiveStatus(meta);
62
94
  const active = status === "running" || status === "orphaned";
@@ -79,7 +111,17 @@ export function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
79
111
  }),
80
112
  };
81
113
  },
82
- onActivityChanged: onMetaChanged,
114
+ onActivityChanged: (notify: () => void, ctx?: ExtensionContext) => {
115
+ const offObservation = onWorkObservation(notify);
116
+ const offMeta = onMetaChanged((meta) => {
117
+ if (ctx && meta) {
118
+ if (!belongsToOrigin(meta, { cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId() })) return;
119
+ if (meta.callbackOrigin?.branchId && !ctx.sessionManager.getBranch().some(entry => entry.id === meta.callbackOrigin?.branchId)) return;
120
+ }
121
+ notify();
122
+ });
123
+ return () => { offObservation(); offMeta(); };
124
+ },
83
125
  });
84
126
  };
85
127
  if (!goalReadySubscriptions.has(pi)) {