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
package/README.md CHANGED
@@ -31,7 +31,8 @@ The API is `runtime-client/src/runtime/client.mjs`, exporting `ensureRuntime`.
31
31
  - Explicit tool allowlists for child sessions, and `skills` for prompt exposure: omit it to keep user-catalog discovery, pass `[]` for no skills, or pass absolute `SKILL.md` paths for exactly those. See [skill exposure](docs/usage.md#skill-exposure).
32
32
  - Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
33
33
  - Live background-work navigator for active runs.
34
- - Harness-owned run timing: every run gets independent factual alerts for a tool call left open (5 min) and for no progress (10 min), plus a 60-minute hard timeout. Change the timeout in `/subagents settings`; `0` disables it. Soft deadlines remain opt-in. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`, globally in `config.json` / `PI_SUBAGENT_*_MINUTES`, or in `/subagents settings`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-tool-wait-stuck).
34
+ - Git writers start in separate Clones by default. **Git workspace** in `/subagents settings` also offers Worktree. Results carry the working directory or a recoverable copy, including incomplete work. [Workspace recovery](docs/usage.md#git-workspaces)
35
+ - Harness-owned run timing: every run gets independent factual alerts for a tool call left open (5 min) and for no progress (10 min), plus a 60-minute hard timeout. Choose a duration or **No limit** under **Run timeout** in `/subagents settings`. Soft deadlines remain opt-in. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`, globally in `config.json` / `PI_SUBAGENT_*_MINUTES`, or in `/subagents settings`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-tool-wait-stuck).
35
36
 
36
37
  Every single or batch launch automatically joins one shared supervision watcher in the
37
38
  foreground Pi process. The last active run's exit or stop tears it down; a later
@@ -41,6 +42,8 @@ alerts retain supervision until their handoff is handled, so lost work is not si
41
42
 
42
43
  ## Worker Ownership
43
44
 
45
+ Every subagent follows the same contract for preserving work and delivering results to its parent. It applies to read-only investigations as well as tasks that create or change files. [Subagent lifecycle, preservation and delivery](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/adr/0007-subagent-lifecycle.md)
46
+
44
47
  Every child launch, including clean, batch and unsandboxed launches, loads a Pi
45
48
  hook that keeps external CI/PR monitoring with its coordinator. Workers finish
46
49
  their assigned implementation or diagnosis, run focused checks, push only when
@@ -87,25 +90,24 @@ pi -e npm:pi-better-subagents
87
90
 
88
91
  Sandboxing starts Off for fresh settings, including standalone subagents without published settings. Explicit saved profiles and session choices remain unchanged. Set `sandbox:true` for a confined launch; `sandbox:false` cannot bypass a human-enabled Subagents profile.
89
92
 
90
- Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or newer. `/sandbox` controls the independent Subagents profile, which each launch freezes. Pi handles its own startup, authentication, and provider connection; task tools obey the selected file, command, and network permissions. Outside project defaults to Write: tasks write across home and temp but can remove files outside the workspace only in temp, hidden home directories, and worktree folders (Linux keeps ordinary home folders read-only instead). Confined children admit `read`, `write`, `edit`, and policy-permitted `bash` or guarded `run_application`, the guarded `apply_patch` (Codex patches that follow the file rules), and the trusted tools ticked in `/sandbox` → Subagents · Tools (default `web_fetch` and `web_search`), which run outside the file rules. Other requested tools are reported as unavailable, with the reason. For direct applications without shell scripts, set Subagents → Sandbox On, Run applications On, Shell scripts Off, and Command time limit to 10 min in `/sandbox`, then press Ctrl+S. This is an explicit choice, not the default. New launches capture the policy; running children keep theirs. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox) for the runtime boundary and supported configurations.
93
+ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or newer. `/sandbox` controls the independent Subagents profile, which each launch freezes. Pi handles its own startup, authentication, and provider connection; task tools obey the selected file, command, and network permissions. Outside project defaults to Write: tasks write across home and temp but can remove files outside the workspace only in temp, hidden home directories, and worktree folders (Linux keeps ordinary home folders read-only instead). Confined children admit `read`, `write`, `edit`, and policy-permitted `bash` or guarded `run_application`, the guarded `apply_patch` (Codex patches that follow the file rules), and the selected extension tools with verified providers (defaults include `web_fetch` and `web_search`), which run outside the file rules. Other requested tools are reported as unavailable, with the reason. For direct applications without shell scripts, set Subagents → Sandbox On, Run applications On, Shell scripts Off, and Command time limit to 10 min in `/sandbox`, then press Ctrl+S. This is an explicit choice, not the default. New launches capture the policy; running children keep theirs. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox) for the runtime boundary and supported configurations.
91
94
 
92
95
  ## Delegation Modes
93
96
 
94
97
  The user config sets `delegationMode` to `manual`, `adaptive` (default), or
95
98
  `coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
96
- for delegation mode, the concurrent-subagent cap (default 6), the tool-wait
97
- alert (default 5 minutes), the no-progress alert (default 10 minutes), and the
98
- default skill exposure. The two time values are edited independently; `0` turns
99
- one alert off. Skill exposure cycles between Discover automatically and No skill
99
+ for delegation mode, the concurrent-subagent cap (default 6), and Git workspace
100
+ (Clone or Worktree). Run timeout supports a duration or **No limit**. The
101
+ tool-wait alert (default 5 minutes) and no-progress alert (default 10 minutes)
102
+ have separate intervals. Enter `0` to turn an alert off. Skill exposure cycles between Discover automatically and No skill
100
103
  catalog. The Selected skills row opens the same searchable checkbox picker used
101
104
  by `/agents`: it lists loaded skills by name and description, Space toggles one,
102
105
  Enter applies, and typing filters without dropping checked items. Saved paths
103
106
  missing from discovery stay visible as unavailable and survive apply. Zero
104
107
  checked applies No skill catalog, not discovery. Manual Add skill path remains
105
- available. The page names whether the current value comes from the saved config
106
- or this session. The session choice controls the next launch before Ctrl+S, and
107
- edits persist across reloads. Ctrl+S saves mode, cap, timing alerts, and skill
108
- exposure as defaults, and Reset to defaults clears session overrides, including
108
+ available. The Skill exposure row shows where the current skill setting comes from. The session choice controls the next launch before Ctrl+S, and
109
+ edits persist across reloads. Ctrl+S saves delegation, workspace, timing, and skill
110
+ settings as defaults, and Reset to defaults clears session overrides, including
109
111
  the skill list. Agents opens the same catalog as `/agents`; a definition that inherits
110
112
  skill exposure shows whether the live value comes from this session, saved
111
113
  config, or discovery, and an invalid draft is marked invalid rather than shown
@@ -194,7 +196,7 @@ The projection exposes an opaque semantic `revision`, readable `reason`, attempt
194
196
  identity, process status, termination evidence and retained evidence references.
195
197
  Compare revisions for equality; unchanged observations keep the same revision.
196
198
  Unavailable or unsupported coordinator reads report Waiting with an unverified
197
- reason. See the [projection contract](../../docs/adr/0022-assignment-progress-projection.md).
199
+ reason. See the [projection contract](https://github.com/1aboveio/pi-better-harness/blob/main/docs/adr/0022-assignment-progress-projection.md).
198
200
 
199
201
  - Repository: https://github.com/1aboveio/pi-better-harness
200
202
  - Detailed notes: https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md
@@ -3,12 +3,12 @@ import { randomUUID } from "node:crypto";
3
3
  import { isDeepStrictEqual } from "node:util";
4
4
  import { join, relative, isAbsolute, dirname, resolve } from "node:path";
5
5
  import { openSync, closeSync, fstatSync, readSync, realpathSync, constants } from "node:fs";
6
- import { openStore, ownerDiff, StoreError, type OwnerIdentity, type AssignmentOutcomeRecord } from "./shared-operation-coordinator/index.ts";
6
+ import { openStore, ownerDiff, type OwnerIdentity, type AssignmentOutcomeRecord } from "./shared-operation-coordinator/index.ts";
7
7
  import type { RunMeta } from "./registry.ts";
8
8
  import { processStartToken, readMeta } from "./registry.ts";
9
9
  import type { PermissionSnapshot } from "./permission-policy.ts";
10
10
  import { credentialFilePaths } from "./shared-sandbox-core.ts";
11
- import { readAssignmentReport } from "./assignment-report.ts";
11
+ import { assignmentReportOutcomeReason, readAssignmentReport } from "./assignment-report.ts";
12
12
 
13
13
  export const ASSIGNMENT_OUTCOMES_VERSION = 1;
14
14
  const closedHosts = (globalThis as typeof globalThis & { __assignmentOutcomeClosedHosts?: Set<string> }).__assignmentOutcomeClosedHosts ??= new Set<string>();
@@ -93,9 +93,10 @@ export function commitAssignmentTerminal(meta: RunMeta, recoveryFailure = false)
93
93
  : !invalidReport && waits.some((w) => w.acknowledgement?.disposition === "assignment-complete"));
94
94
  try { return store.recordAssignmentOutcome({ ...binding, revision: 1,
95
95
  outcome: complete ? "succeeded" : meta.status === "killed" ? "cancelled" : "failed",
96
- reason: meta.failureReason || invalidReport || (meta.status === "completed" && report ? report.reason : complete ? "Assigned work and required interpretation are complete."
96
+ reason: (meta.failureReason || invalidReport || (meta.status === "completed" && report ? assignmentReportOutcomeReason(report) : complete ? "Assigned work and required interpretation are complete."
97
+ : meta.status === "completed" && meta.assignmentReportRejection ? `Assignment report rejected: ${meta.assignmentReportRejection.reason}`
97
98
  : meta.status === "completed" ? "Assignment completion is unverified: the attempt exited without an evidence-backed completion decision. Inspect retained output and continue unfinished work or report a concrete blocker."
98
- : `Assignment ended ${meta.status}; retained attempt evidence is available.`),
99
+ : `Assignment ended ${meta.status}; retained attempt evidence is available.`)).slice(0, 8192),
99
100
  processUncertain: meta.status === "lost" || typeof meta.exitCode !== "number"
100
101
  || waits.some((w) => w.dependencies.some((d) => d.terminalRevision === 0)
101
102
  || store.listResumeClaims({ waitId: w.waitId, generation: w.generation, state: "published" }).length > 0),
@@ -106,10 +107,12 @@ export function commitAssignmentTerminal(meta: RunMeta, recoveryFailure = false)
106
107
  }); } catch (error) {
107
108
  // A competing finalizer may commit after our initial read. The store
108
109
  // still refuses rewrites; return only the same captured binding's winner.
109
- if (error instanceof StoreError && error.code === "validation" && error.message === "A terminal assignment cannot be rewritten or reopened.") {
110
+ // Borrowed runtime stores use a different coordinator module's StoreError constructor.
111
+ if (error instanceof Error && error.name === "StoreError" && "code" in error
112
+ && error.code === "validation" && error.message === "A terminal assignment cannot be rewritten or reopened.") {
110
113
  const winner = store.getAssignmentOutcome(binding.assignmentId);
111
114
  const current = readMeta(meta.id);
112
- if (winner && winner.assignmentId === binding.assignmentId && ownerDiff(winner.owner, binding.owner) === "none"
115
+ if (winner && winner.assignmentId === binding.assignmentId && winner.revision === 1 && ownerDiff(winner.owner, binding.owner) === "none"
113
116
  && ownerDiff(winner.recipient, binding.recipient) === "none"
114
117
  && current?.assignment?.assignmentId === binding.assignmentId
115
118
  && ownerDiff(current.assignment.owner, binding.owner) === "none" && ownerDiff(current.assignment.recipient, binding.recipient) === "none"
@@ -5,6 +5,8 @@ import { homedir } from "node:os";
5
5
  import { runDir, writeMeta, type RunMeta } from "./registry.ts";
6
6
  import { credentialFilePaths } from "./shared-sandbox-core.ts";
7
7
  import type { PermissionSnapshot, PermissionProfile } from "./permission-policy.ts";
8
+ import { OperationBridgeError, redactSecret } from "./operation-bridge-types.ts";
9
+ import { requireText } from "./shared-operation-coordinator/src/validate.ts";
8
10
 
9
11
  const hash = (bytes: string | Buffer) => createHash("sha256").update(bytes).digest("hex");
10
12
  const inside = (root: string, path: string) => { const rel = relative(root, path); return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)); };
@@ -20,15 +22,62 @@ function retainedBytes(path: string, limit: number): Buffer {
20
22
  }
21
23
  export interface AssignmentReport {
22
24
  version: 1; assignmentId: string; attemptId: string; requestDigest: string; status: "complete" | "incomplete"; reason: string;
23
- evidence: Array<{ path: string; digest: string; source: string; explanation: string }>;
25
+ remainingWork?: string[];
26
+ blocker?: { kind: "permission" | "external-input"; reason: string };
27
+ evidence: Array<{ path: string; digest: string; source: string; explanation: string; range?: { offset: number; bytes: number; sourceBytes: number } }>;
28
+ }
29
+
30
+ interface ReportInput {
31
+ status: string; reason: string;
32
+ remaining_work?: string[];
33
+ blocker?: AssignmentReport["blocker"];
34
+ evidence: Array<{ path: string; explanation: string; offset?: number; max_bytes?: number }>;
35
+ }
36
+
37
+ export function assignmentReportOutcomeReason(report: AssignmentReport): string {
38
+ if (report.status === "complete") return report.reason;
39
+ return (`Assignment incomplete: ${report.reason}`
40
+ + (report.blocker ? ` Blocked (${report.blocker.kind}): ${report.blocker.reason}.` : "")
41
+ + (report.remainingWork ? ` Remaining work: ${report.remainingWork.join("; ")}.` : "")).slice(0, 8192);
42
+ }
43
+
44
+ function validateReportText(report: AssignmentReport): void {
45
+ requireText("report.reason", report.reason, 2048);
46
+ for (const item of report.remainingWork ?? []) requireText("report.remaining_work", item, 1024);
47
+ if (report.blocker) requireText("report.blocker.reason", report.blocker.reason, 1024);
48
+ for (const evidence of report.evidence) requireText("report.evidence.explanation", evidence.explanation, 1024);
49
+ requireText("report.outcome_reason", assignmentReportOutcomeReason(report), 8192);
24
50
  }
25
51
 
26
52
  /** Runs synchronously under the authenticated handler: no yield between authority and persistence. */
27
53
  export function recordAssignmentReport(id: string, input: unknown, assertAuthority: () => RunMeta, current?: PermissionSnapshot) {
28
54
  const meta = assertAuthority();
29
- const report = input as { status: string; reason: string; evidence: Array<{ path: string; explanation: string }> };
55
+ try { return retainAssignmentReport(id, input, meta, assertAuthority, current); }
56
+ catch (error) {
57
+ // Refused input is not a committed report: the same writer may correct it.
58
+ // Recheck the live writer before retaining even diagnostic metadata.
59
+ recordAssignmentReportRejection(error instanceof Error ? error.message : String(error), assertAuthority);
60
+ throw error;
61
+ }
62
+ }
63
+
64
+ /** Also used for authenticated bridge refusals that never enter the report handler. */
65
+ export function recordAssignmentReportRejection(reason: string, assertAuthority: () => RunMeta): void {
66
+ const latest = assertAuthority();
67
+ if (!latest.assignmentReport) writeMeta({ ...latest, assignmentReportRejection: {
68
+ reason: redactSecret(reason), rejectedAt: Date.now(),
69
+ } });
70
+ }
71
+
72
+ function retainAssignmentReport(id: string, input: unknown, meta: RunMeta, assertAuthority: () => RunMeta, current?: PermissionSnapshot) {
73
+ const report = input as ReportInput;
30
74
  if (!["complete", "incomplete"].includes(report.status) || !report.reason?.trim() || report.reason.length > 2048
31
75
  || !Array.isArray(report.evidence) || report.evidence.length < 1 || report.evidence.length > 4) throw new Error("Invalid assignment report.");
76
+ if (report.remaining_work !== undefined && (!Array.isArray(report.remaining_work) || report.remaining_work.length < 1 || report.remaining_work.length > 8
77
+ || report.remaining_work.some((item) => typeof item !== "string" || !item.trim() || item.length > 1024))) throw new Error("Remaining work needs 1 to 8 bounded descriptions.");
78
+ if (report.blocker && (!["permission", "external-input"].includes(report.blocker.kind) || !report.blocker.reason?.trim()
79
+ || report.blocker.reason.length > 1024)) throw new Error("A blocker needs its permission or external-input kind and a concrete reason.");
80
+ if (report.status === "complete" && (report.remaining_work || report.blocker)) throw new Error("A complete assignment cannot have remaining work or a blocker.");
32
81
  const root = realpathSync(meta.cwd);
33
82
  const directory = join(runDir(id), "assignment-report-v1");
34
83
  const captured = (meta.operations?.policy.sandbox as { permissions?: Partial<PermissionProfile> } | null)?.permissions;
@@ -37,28 +86,23 @@ export function recordAssignmentReport(id: string, input: unknown, assertAuthori
37
86
  if (policy?.enabled && policy.projectFiles !== "read" && policy.projectFiles !== "read-write") throw new Error("Current assignment evidence read permission refused.");
38
87
  }
39
88
  if (meta.operations?.policy.sandbox && !current?.permissions) throw new Error("Current assignment evidence read authority unavailable.");
40
- const requestDigest = hash(JSON.stringify([report.status, report.reason, report.evidence.map((e) => [e.path, e.explanation])]));
89
+ // Keep the legacy digest for whole-file reports without the additive fields.
90
+ const request: unknown[] = [report.status, report.reason, report.evidence.map((e) => e.offset === undefined && e.max_bytes === undefined
91
+ ? [e.path, e.explanation] : [e.path, e.explanation, e.offset ?? 0, e.max_bytes])];
92
+ if (report.remaining_work || report.blocker) request.push([report.remaining_work ?? null,
93
+ report.blocker ? [report.blocker.kind, report.blocker.reason] : null]);
94
+ const requestDigest = hash(JSON.stringify(request));
41
95
  if (meta.assignmentReport) {
42
96
  const accepted = readAssignmentReport(meta)!;
43
97
  if (accepted.requestDigest !== requestDigest) throw new Error("Conflicting assignment report refused.");
44
98
  return { reportId: meta.assignmentReport.digest, status: accepted.status, note: "Report retained. Assignment terminalization after exit and exact parent disposition remain separate." };
45
99
  }
46
- const snapshots = report.evidence.map((e) => {
47
- if (!e.path || !e.explanation?.trim() || e.explanation.length > 1024) throw new Error("Evidence needs a bounded explanation.");
48
- const source = realpathSync(resolve(root, e.path));
49
- if (!inside(root, source) || credentialFilePaths(homedir()).some((p) => inside(p, source))) throw new Error("Foreign or credential assignment evidence refused.");
50
- const fd = openSync(source, constants.O_RDONLY | constants.O_NOFOLLOW);
51
- try {
52
- const stat = fstatSync(fd);
53
- if (!stat.isFile() || stat.size > 65536) throw new Error("Assignment evidence must be a file of at most 65536 bytes.");
54
- const bytes = Buffer.alloc(stat.size);
55
- if (readSync(fd, bytes, 0, bytes.length, 0) !== bytes.length) throw new Error("Assignment evidence changed during capture.");
56
- return { bytes, digest: hash(bytes), source, explanation: e.explanation };
57
- } finally { closeSync(fd); }
58
- });
100
+ const snapshots = report.evidence.map((e) => captureEvidence(root, e));
59
101
  const retained: AssignmentReport = { version: 1, assignmentId: meta.assignment!.assignmentId, attemptId: id, requestDigest,
60
102
  status: report.status as AssignmentReport["status"], reason: report.reason,
61
- evidence: snapshots.map(({ digest, source, explanation }) => ({ path: join(directory, digest), digest, source, explanation })) };
103
+ ...(report.remaining_work ? { remainingWork: report.remaining_work } : {}), ...(report.blocker ? { blocker: report.blocker } : {}),
104
+ evidence: snapshots.map(({ digest, source, explanation, range }) => ({ path: join(directory, digest), digest, source, explanation, ...(range ? { range } : {}) })) };
105
+ validateReportText(retained);
62
106
  const text = JSON.stringify(retained);
63
107
  if (Buffer.byteLength(text) > 65536) throw new Error("Assignment report exceeds its retained metadata bound.");
64
108
  const digest = hash(text);
@@ -71,11 +115,44 @@ export function recordAssignmentReport(id: string, input: unknown, assertAuthori
71
115
  for (const snapshot of snapshots) writeFileSync(join(directory, snapshot.digest), snapshot.bytes, { mode: 0o600 });
72
116
  const path = join(directory, `${digest}.json`);
73
117
  writeFileSync(path, text, { mode: 0o600 });
74
- writeMeta({ ...latest, assignmentReport: { version: 1, assignmentId: retained.assignmentId, attemptId: id, digest, path } });
118
+ const updated = { ...latest, assignmentReport: { version: 1 as const, assignmentId: retained.assignmentId, attemptId: id, digest, path } };
119
+ delete updated.assignmentReportRejection;
120
+ writeMeta(updated);
75
121
  }
76
122
  return { reportId: digest, status: report.status, note: "Report retained. Assignment terminalization after exit and exact parent disposition remain separate." };
77
123
  }
78
124
 
125
+ function captureEvidence(root: string, e: ReportInput["evidence"][number]) {
126
+ try {
127
+ if (!e.path || !e.explanation?.trim() || e.explanation.length > 1024) throw new Error("Evidence needs a bounded explanation.");
128
+ const source = realpathSync(resolve(root, e.path));
129
+ if (credentialFilePaths(homedir()).some((p) => inside(p, source))) throw new Error("Foreign or credential assignment evidence refused.");
130
+ if (!inside(root, source)) throw new Error(`Foreign assignment evidence refused: the source must resolve inside the assigned workspace ${JSON.stringify(root)}. A sibling directory is outside this boundary. Use an existing workspace file or place the reportable artifact inside the workspace, then retry.`);
131
+ const fd = openSync(source, constants.O_RDONLY | constants.O_NOFOLLOW);
132
+ try {
133
+ const stat = fstatSync(fd);
134
+ if (!stat.isFile()) throw new Error(`Assignment evidence ${JSON.stringify(e.path)} must be a regular file.`);
135
+ const offset = e.offset ?? 0;
136
+ if (!Number.isSafeInteger(offset) || offset < 0 || offset > stat.size || (offset === stat.size && offset !== 0)
137
+ || (e.offset !== undefined && e.max_bytes === undefined)
138
+ || (e.max_bytes !== undefined && (!Number.isSafeInteger(e.max_bytes) || e.max_bytes < 1 || e.max_bytes > 65536))) {
139
+ throw new Error(`Invalid assignment evidence range for ${JSON.stringify(e.path)} (${stat.size} bytes). Use offset within the file and max_bytes from 1 through 65536.`);
140
+ }
141
+ if (e.max_bytes === undefined && stat.size > 65536) {
142
+ throw new Error(`Assignment evidence ${JSON.stringify(e.path)} is ${stat.size} bytes; the retained limit is 65536 bytes. Retry with offset and max_bytes (at most 65536) for the relevant excerpt.`);
143
+ }
144
+ const bytes = Buffer.alloc(Math.min(stat.size - offset, e.max_bytes ?? stat.size));
145
+ if (readSync(fd, bytes, 0, bytes.length, offset) !== bytes.length) throw new Error("Assignment evidence changed during capture.");
146
+ const after = fstatSync(fd);
147
+ if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) throw new Error("Assignment evidence changed during capture.");
148
+ return { bytes, digest: hash(bytes), source, explanation: e.explanation,
149
+ ...(e.max_bytes === undefined ? {} : { range: { offset, bytes: bytes.length, sourceBytes: stat.size } }) };
150
+ } finally { closeSync(fd); }
151
+ } catch (error) {
152
+ throw new OperationBridgeError("tool-error", error instanceof Error ? error.message : String(error), true);
153
+ }
154
+ }
155
+
79
156
  export function readAssignmentReport(meta: RunMeta): AssignmentReport | null {
80
157
  const ref = meta.assignmentReport;
81
158
  if (!ref) return null;
@@ -86,7 +163,14 @@ export function readAssignmentReport(meta: RunMeta): AssignmentReport | null {
86
163
  const report = JSON.parse(text) as AssignmentReport;
87
164
  if (report.version !== 1 || report.assignmentId !== ref.assignmentId || report.attemptId !== meta.id) throw new Error("Foreign assignment report.");
88
165
  for (const e of report.evidence) {
89
- if (!/^[a-f0-9]{64}$/.test(e.digest) || e.path !== join(runDir(meta.id), "assignment-report-v1", e.digest) || hash(retainedBytes(e.path, 65536)) !== e.digest) throw new Error("Retained assignment evidence changed.");
166
+ if (!/^[a-f0-9]{64}$/.test(e.digest) || e.path !== join(runDir(meta.id), "assignment-report-v1", e.digest)) throw new Error("Retained assignment evidence changed.");
167
+ const bytes = retainedBytes(e.path, 65536);
168
+ if (hash(bytes) !== e.digest || (e.range && (!Number.isSafeInteger(e.range.offset) || e.range.offset < 0
169
+ || !Number.isSafeInteger(e.range.sourceBytes) || e.range.sourceBytes < 0 || e.range.bytes !== bytes.length
170
+ || e.range.offset + e.range.bytes > e.range.sourceBytes))) throw new Error("Retained assignment evidence changed.");
90
171
  }
172
+ // Older accepted reports may contain prose the terminal store cannot retain.
173
+ // Treat those as unverified evidence rather than throwing during finalization.
174
+ validateReportText(report);
91
175
  return report;
92
176
  }
package/batch.mjs CHANGED
@@ -94,13 +94,15 @@ export function mergeJobOptions(shared, job) {
94
94
  cwd: job.cwd ?? shared?.cwd,
95
95
  // Same semantics as subagent_spawn: shared and per-job values must reach
96
96
  // spawnSubagentRun so batch jobs can request disposable clone workspaces.
97
+ isolation: job.isolation ?? shared?.isolation,
98
+ recover_in_clone: job.recover_in_clone,
97
99
  git_clone_workspace: job.git_clone_workspace ?? shared?.git_clone_workspace,
98
100
  approve: job.approve ?? shared?.approve,
99
101
  allow_nested: job.allow_nested ?? shared?.allow_nested,
100
102
  // Native session id selected for this JOB only. A shared value would make
101
103
  // every job contend for the same conversation writer, so it is not inherited.
102
- session_id: typeof job.session_id === "string" ? job.session_id : undefined,
103
- session_name: typeof job.session_name === "string" ? job.session_name : undefined,
104
+ session_id: typeof job.session_id === "string" ? normalizeSessionSelector(job.session_id) : undefined,
105
+ session_name: typeof job.session_name === "string" ? normalizeSessionSelector(job.session_name) : undefined,
104
106
  // Harness timing; an explicit null means "not set", so it falls through to shared.
105
107
  deadline_minutes: job.deadline_minutes ?? shared?.deadline_minutes,
106
108
  grace_minutes: job.grace_minutes ?? shared?.grace_minutes,
@@ -113,6 +115,11 @@ export function mergeJobOptions(shared, job) {
113
115
  };
114
116
  }
115
117
 
118
+ /** Keep nonblank selectors exact. Only a blank string is equivalent to omission. */
119
+ export function normalizeSessionSelector(value) {
120
+ return typeof value === "string" && value.trim() === "" ? undefined : value;
121
+ }
122
+
116
123
  function catalogText(value) {
117
124
  return typeof value === "string" && value.trim() !== "" ? value : undefined;
118
125
  }
@@ -157,9 +164,11 @@ export function validateBatchPlan({ shared, jobs, onCapacity, config }) {
157
164
  if (typeof job.prompt !== "string" || job.prompt.trim() === "") {
158
165
  throw new Error(`job ${i + 1} is missing a non-empty prompt.`);
159
166
  }
160
- if (job.session_id !== undefined && job.session_name !== undefined) throw new Error(`job ${i + 1}: pass either session_id or session_name, not both.`);
161
- if (job.session_name !== undefined && (typeof job.session_name !== "string" || job.session_name.trim() === "")) throw new Error(`job ${i + 1} session_name must be a non-empty name.`);
162
- if (job.session_id !== undefined && (typeof job.session_id !== "string" || job.session_id.trim() === "")) {
167
+ const sessionId = normalizeSessionSelector(job.session_id);
168
+ const sessionName = normalizeSessionSelector(job.session_name);
169
+ if (sessionId !== undefined && sessionName !== undefined) throw new Error(`job ${i + 1}: pass either session_id or session_name, not both.`);
170
+ if (sessionName !== undefined && typeof sessionName !== "string") throw new Error(`job ${i + 1} session_name must be a non-empty name.`);
171
+ if (sessionId !== undefined && typeof sessionId !== "string") {
163
172
  throw new Error(`job ${i + 1} session_id must be a non-empty native session id.`);
164
173
  }
165
174
  if (seenPrompts.has(job.prompt)) {
@@ -0,0 +1,19 @@
1
+ #!/usr/bin/env node
2
+ // Recover a separate checkout, including failed runs that cannot start another writer.
3
+ import { tsImport } from "tsx/esm/api";
4
+ const { readMeta } = await tsImport("../registry.ts", import.meta.url);
5
+ const { readRetainedResult } = await tsImport("../retained-result.ts", import.meta.url);
6
+ const { exportWorkspace } = await tsImport("../isolated-workspace.ts", import.meta.url);
7
+ try {
8
+ const [, , id, destination] = process.argv;
9
+ if (!/^sa_[a-z0-9]+_[a-z0-9]+$/i.test(id ?? "") || !destination || process.argv.length !== 4) {
10
+ throw new Error("Usage: pi-subagents-recover <run-id> <new-directory>");
11
+ }
12
+ const meta = readRetainedResult(id) ?? readMeta(id);
13
+ if (!meta?.recipe?.workspace) throw new Error("No saved Git workspace for " + id);
14
+ exportWorkspace(meta.recipe.workspace, id, destination);
15
+ console.log("Recovered " + id + " to " + destination);
16
+ } catch (error) {
17
+ console.error(error.message);
18
+ process.exitCode = 1;
19
+ }
@@ -2,7 +2,7 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
2
2
  import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
3
3
  import { join } from "node:path";
4
4
  import { processStartToken } from "./registry.ts";
5
- import { WorkClient } from "./shared-work-client.mjs";
5
+ import { WorkClient, connectWorkClient } from "./shared-work-client.mjs";
6
6
  import type { AgentSessionOverrides } from "./agent-session-settings.ts";
7
7
  import { overlayDigest } from "./catalog-overlay.ts";
8
8
  export { overlayDigest } from "./catalog-overlay.ts";
@@ -13,6 +13,8 @@ export function createCatalogHostAdapter() {
13
13
  let live: { client: WorkClient; path: string; key: string; authority: Record<string, unknown> } | undefined;
14
14
  let timer: ReturnType<typeof setInterval> | undefined;
15
15
  let epoch = 0;
16
+ let pendingConnection: AbortController | undefined;
17
+ let refreshPending = false;
16
18
  let admitting: Promise<Record<string, unknown> | undefined> = Promise.resolve(undefined);
17
19
 
18
20
  /** Fixed Pi adapter only. Never exposed as a tool or socket issuance operation. */
@@ -22,6 +24,7 @@ export function createCatalogHostAdapter() {
22
24
 
23
25
  function closeCatalogHost() {
24
26
  epoch++;
27
+ pendingConnection?.abort(); pendingConnection = undefined;
25
28
  clearInterval(timer); timer = undefined;
26
29
  if (live) { live.client.close(); rmSync(live.path, { force: true }); live = undefined; }
27
30
  current = undefined;
@@ -48,9 +51,13 @@ export function createCatalogHostAdapter() {
48
51
  const id = randomUUID(), secret = randomBytes(32).toString("hex"), generation = randomUUID();
49
52
  const path = join(root, `${id}.json`), staging = join(root, `.${id}`);
50
53
  const authority = { id, secret, generation, cwd: scope.cwd, sessionId: scope.sessionId, branchId: scope.branchId };
51
- const client = new WorkClient(socketPath, agentDir, ["runtime-catalog-v1"]);
54
+ const controller = new AbortController();
55
+ pendingConnection = controller;
56
+ const client = await connectWorkClient(socketPath, agentDir, ["runtime-catalog-v1"], { signal: controller.signal })
57
+ .finally(() => { if (pendingConnection === controller) pendingConnection = undefined; });
52
58
  try {
53
59
  const hello = await client.ready;
60
+ if (epoch !== admittedEpoch || !current) throw new Error("catalog-host-revoked");
54
61
  const pidStartTime = processStartToken(process.pid);
55
62
  if (!pidStartTime) throw new Error("catalog-host-identity-unavailable");
56
63
  writeFileSync(staging, JSON.stringify({ version: 1, id, generation, serverInstance: hello.instanceId, pid: process.pid, pidStartTime, secretHash: hash(secret), ...scope }), { mode: 0o600, flag: "wx" });
@@ -58,7 +65,16 @@ export function createCatalogHostAdapter() {
58
65
  await client.request("runtime_bind_catalog_host", { authority });
59
66
  if (epoch !== admittedEpoch || !current) throw new Error("catalog-host-revoked");
60
67
  live = { client, path, key, authority };
61
- if (!timer) { timer = setInterval(() => { void catalogHostAuthority(agentDir, current?.ctx.cwd ?? cwd, socketPath).catch(() => closeCatalogHost()); }, 500); timer.unref(); }
68
+ if (!timer) {
69
+ timer = setInterval(() => {
70
+ if (refreshPending) return;
71
+ refreshPending = true;
72
+ void catalogHostAuthority(agentDir, current?.ctx.cwd ?? cwd, socketPath)
73
+ .catch(() => { if (epoch === admittedEpoch) closeCatalogHost(); })
74
+ .finally(() => { refreshPending = false; });
75
+ }, 500);
76
+ timer.unref();
77
+ }
62
78
  return authority;
63
79
  } catch (error) { client.close(); rmSync(path, { force: true }); rmSync(staging, { force: true }); throw error; }
64
80
  }
@@ -32,7 +32,7 @@ function preferences(id: string, value: unknown): CatalogPreference {
32
32
  }
33
33
 
34
34
  function snapshot(values: CatalogPreferences): { settings: CatalogPreferences; digest: string } {
35
- const settings = Object.freeze(Object.fromEntries(Object.keys(values).sort().map(id => [id, values[id]])));
35
+ const settings = Object.freeze(Object.fromEntries(Object.keys(values).sort().map(id => [id, values[id]!])));
36
36
  return { settings, digest: createHash("sha256").update(JSON.stringify(settings)).digest("hex") };
37
37
  }
38
38
 
@@ -218,7 +218,41 @@ export function inspectCatalog(snapshot: CatalogSnapshot, id: string): CatalogIn
218
218
  };
219
219
  }
220
220
 
221
+ export const catalogResolutionMetrics = { assemblies: 0, hits: 0 };
222
+ const resolutions = new Map<string, Resolution>();
223
+
224
+ function resolveCached(snapshot: CatalogSnapshot, id: string, compute: () => Resolution): Resolution {
225
+ const entry = findEntry(snapshot, id);
226
+ if (!entry) return compute();
227
+ const roleId = entry.definition?.kind === "agent" ? entry.definition.roleId : undefined;
228
+ const role = roleId ? findEntry(snapshot, roleId) : undefined;
229
+ // Only the selected definition, its base role and their own preferences contribute.
230
+ const key = JSON.stringify([{ ...entry, unused: undefined }, role && { ...role, unused: undefined }, snapshot.savedSettings?.[id], roleId && snapshot.savedSettings?.[roleId],
231
+ snapshot.sessionSettings?.[id], roleId && snapshot.sessionSettings?.[roleId]]);
232
+ const cached = resolutions.get(key);
233
+ if (cached) {
234
+ catalogResolutionMetrics.hits++;
235
+ const result = structuredClone(cached);
236
+ result.entry = entry;
237
+ if (result.effective) result.effective.snapshotDigest = snapshot.digest;
238
+ return result;
239
+ }
240
+ catalogResolutionMetrics.assemblies++;
241
+ const result = compute();
242
+ if (new TextEncoder().encode(key).byteLength <= 64 * 1024) resolutions.set(key, structuredClone(result));
243
+ if (resolutions.size > 512) resolutions.delete(resolutions.keys().next().value!);
244
+ return result;
245
+ }
246
+
221
247
  function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
248
+ return resolveCached(snapshot, roleId, () => resolveRoleUncached(snapshot, roleId));
249
+ }
250
+
251
+ function resolveAgent(snapshot: CatalogSnapshot, agentId: string): Resolution {
252
+ return resolveCached(snapshot, agentId, () => resolveAgentUncached(snapshot, agentId));
253
+ }
254
+
255
+ function resolveRoleUncached(snapshot: CatalogSnapshot, roleId: string): Resolution {
222
256
  const entry = findEntry(snapshot, roleId);
223
257
  if (!entry || entry.kind !== "role") {
224
258
  return {
@@ -268,7 +302,7 @@ function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
268
302
  };
269
303
  }
270
304
 
271
- function resolveAgent(snapshot: CatalogSnapshot, agentId: string): Resolution {
305
+ function resolveAgentUncached(snapshot: CatalogSnapshot, agentId: string): Resolution {
272
306
  const entry = findEntry(snapshot, agentId);
273
307
  if (!entry || entry.kind !== "agent") {
274
308
  return {