@xzzpig/pi-subagents 0.1.0 → 0.3.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 (108) hide show
  1. package/CHANGELOG.md +135 -0
  2. package/README.md +4 -0
  3. package/agents/reviewer.md +3 -4
  4. package/docs/agents.md +343 -0
  5. package/docs/configuration.md +395 -0
  6. package/docs/extension-api.md +308 -0
  7. package/docs/missions.md +121 -0
  8. package/docs/models.md +192 -0
  9. package/docs/observability.md +198 -0
  10. package/docs/tool-reference.md +343 -0
  11. package/docs/watchdog.md +176 -0
  12. package/docs/workflows.md +163 -0
  13. package/package.json +13 -11
  14. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  15. package/skills/pi-subagents/references/execution-controls.md +7 -7
  16. package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
  17. package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
  18. package/src/agents/agents.ts +53 -23
  19. package/src/agents/frontmatter.ts +7 -3
  20. package/src/agents/skills.ts +2 -9
  21. package/src/api/preflight.ts +1 -1
  22. package/src/api/project-panes.ts +30 -0
  23. package/src/extension/config.ts +54 -1
  24. package/src/extension/doctor.ts +40 -0
  25. package/src/extension/fanout-child.ts +5 -4
  26. package/src/extension/index.ts +114 -38
  27. package/src/extension/public-execution.ts +35 -4
  28. package/src/extension/rpc.ts +10 -15
  29. package/src/extension/schemas.ts +33 -11
  30. package/src/extension/subagent-guide.ts +39 -0
  31. package/src/extension/tool-description.ts +38 -18
  32. package/src/inspectors/herdr/actions.ts +11 -2
  33. package/src/inspectors/herdr/inspector-runner.ts +16 -3
  34. package/src/inspectors/herdr/project-panes.ts +459 -63
  35. package/src/intercom/intercom-bridge.ts +7 -2
  36. package/src/intercom/native-supervisor-channel.ts +102 -4
  37. package/src/missions/actions.ts +25 -2
  38. package/src/missions/lifecycle.ts +25 -9
  39. package/src/missions/store.ts +89 -7
  40. package/src/missions/types.ts +33 -0
  41. package/src/missions/workflow-state.ts +25 -15
  42. package/src/runs/background/active-async-capacity.ts +431 -0
  43. package/src/runs/background/active-run-index.ts +46 -0
  44. package/src/runs/background/async-execution.ts +158 -71
  45. package/src/runs/background/async-job-tracker.ts +297 -133
  46. package/src/runs/background/async-resume.ts +37 -5
  47. package/src/runs/background/async-status.ts +39 -5
  48. package/src/runs/background/chain-append.ts +33 -15
  49. package/src/runs/background/completion-replay.ts +267 -0
  50. package/src/runs/background/control-channel.ts +95 -54
  51. package/src/runs/background/fleet-view.ts +18 -5
  52. package/src/runs/background/owned-process-tree.ts +104 -0
  53. package/src/runs/background/process-terminal.ts +17 -3
  54. package/src/runs/background/result-watcher.ts +113 -10
  55. package/src/runs/background/resume-guidance.ts +53 -0
  56. package/src/runs/background/retained-children.ts +14 -6
  57. package/src/runs/background/run-status.ts +119 -5
  58. package/src/runs/background/scheduled-runs.ts +25 -1
  59. package/src/runs/background/stale-run-reconciler.ts +12 -24
  60. package/src/runs/background/subagent-runner.ts +127 -41
  61. package/src/runs/background/subagent-wait.ts +5 -2
  62. package/src/runs/background/wait-completions.ts +39 -5
  63. package/src/runs/background/wait-subscriptions.ts +21 -5
  64. package/src/runs/foreground/async-dismiss-action.ts +85 -0
  65. package/src/runs/foreground/async-steering-action.ts +7 -8
  66. package/src/runs/foreground/chain-execution.ts +40 -2
  67. package/src/runs/foreground/execution.ts +97 -19
  68. package/src/runs/foreground/foreground-control.ts +12 -0
  69. package/src/runs/foreground/foreground-history.ts +137 -0
  70. package/src/runs/foreground/prompt-audit.ts +172 -0
  71. package/src/runs/foreground/subagent-executor.ts +1274 -243
  72. package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
  73. package/src/runs/shared/acceptance.ts +13 -4
  74. package/src/runs/shared/completion-guard.ts +17 -1
  75. package/src/runs/shared/dynamic-fanout.ts +1 -1
  76. package/src/runs/shared/llm-intent-arbiter.ts +302 -0
  77. package/src/runs/shared/model-fallback.ts +8 -4
  78. package/src/runs/shared/model-scope.ts +12 -2
  79. package/src/runs/shared/parallel-utils.ts +3 -0
  80. package/src/runs/shared/pi-args.ts +44 -1
  81. package/src/runs/shared/run-fanout-budget.ts +280 -0
  82. package/src/runs/shared/single-output.ts +4 -2
  83. package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
  84. package/src/runs/shared/task-intent.ts +19 -3
  85. package/src/runs/shared/worktree.ts +20 -7
  86. package/src/shared/agent-stream-options.ts +5 -0
  87. package/src/shared/artifacts.ts +17 -21
  88. package/src/shared/display-text.ts +150 -0
  89. package/src/shared/file-coalescer.ts +9 -0
  90. package/src/shared/fork-context.ts +13 -0
  91. package/src/shared/formatters.ts +4 -6
  92. package/src/shared/node-executable.ts +21 -0
  93. package/src/shared/prompt-resources.ts +51 -0
  94. package/src/shared/settings.ts +15 -2
  95. package/src/shared/types.ts +158 -4
  96. package/src/shared/utf8.ts +11 -0
  97. package/src/shared/utils.ts +46 -34
  98. package/src/slash/prompt-workflows.ts +2 -15
  99. package/src/slash/slash-commands.ts +22 -2
  100. package/src/tui/fleet-status.ts +29 -17
  101. package/src/tui/fleet-transcript.ts +1 -48
  102. package/src/tui/fleet.ts +362 -37
  103. package/src/tui/render.ts +235 -71
  104. package/src/watchdog/change-signature.ts +4 -3
  105. package/src/watchdog/permission-arbiter.ts +2 -1
  106. package/src/watchdog/review.ts +4 -3
  107. package/src/workflows/chat-progress.ts +8 -2
  108. package/src/workflows/scripted-workflow.ts +273 -20
@@ -22,6 +22,7 @@ export const NATIVE_SUPERVISOR_TOOL_NAME = "subagent_supervisor";
22
22
  const MAX_MESSAGE_BYTES = 64 * 1024;
23
23
  const DEFAULT_ASK_TIMEOUT_MS = 10 * 60 * 1000;
24
24
  const CHANNEL_POLL_MS = Math.min(POLL_INTERVAL_MS, 500);
25
+ const CHANNEL_SAFETY_POLL_MS = 5000;
25
26
  const STALE_EMPTY_CHANNEL_AGE_MS = 60 * 1000;
26
27
  const STALE_EMPTY_CHANNEL_CLEANUP_INTERVAL_MS = 60 * 1000;
27
28
 
@@ -69,6 +70,13 @@ interface IntercomParams {
69
70
  replyTo?: string;
70
71
  }
71
72
 
73
+ type SupervisorWatch = (filename: fs.PathLike, listener: fs.WatchListener<string>) => fs.FSWatcher;
74
+
75
+ interface NativeSupervisorChannelDeps {
76
+ platform?: NodeJS.Platform;
77
+ watch?: SupervisorWatch;
78
+ }
79
+
72
80
  const ContactSupervisorParamsSchema = Type.Object({
73
81
  reason: Type.String({ enum: ["need_decision", "interview_request", "progress_update"] }),
74
82
  message: Type.Optional(Type.String()),
@@ -626,10 +634,16 @@ function buildParentIntercomTool(pending: Map<string, PendingSupervisorRequest>,
626
634
  };
627
635
  }
628
636
 
629
- export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentState): { start: () => void; dispose: () => void; pending: Map<string, PendingSupervisorRequest> } {
637
+ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentState, deps: NativeSupervisorChannelDeps = {}): { start: () => void; dispose: () => void; pending: Map<string, PendingSupervisorRequest> } {
638
+ const watch = deps.watch ?? fs.watch;
630
639
  const pending = new Map<string, PendingSupervisorRequest>();
631
640
  const seenFiles = new Set<string>();
641
+ const requestWatchers = new Map<string, fs.FSWatcher>();
642
+ let rootWatcher: fs.FSWatcher | undefined;
632
643
  let poller: ReturnType<typeof setInterval> | undefined;
644
+ let safetyPoller: ReturnType<typeof setInterval> | undefined;
645
+ let deferredWatcherRefresh: ReturnType<typeof setImmediate> | undefined;
646
+ let started = false;
633
647
  let lastStaleCleanupAt = 0;
634
648
 
635
649
  const registerParentTools = (): void => {
@@ -696,17 +710,101 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
696
710
  }
697
711
  };
698
712
 
713
+ const startPolling = (): void => {
714
+ if (poller) return;
715
+ poller = setInterval(poll, CHANNEL_POLL_MS);
716
+ poller.unref?.();
717
+ };
718
+ const startSafetyPolling = (): void => {
719
+ if (safetyPoller) return;
720
+ safetyPoller = setInterval(() => {
721
+ watchExistingRequestDirs();
722
+ poll();
723
+ }, CHANNEL_SAFETY_POLL_MS);
724
+ safetyPoller.unref?.();
725
+ };
726
+ const watchRequestDir = (requestsDir: string): void => {
727
+ if (requestWatchers.has(requestsDir)) return;
728
+ try {
729
+ const watcher = watch(requestsDir, () => poll());
730
+ watcher.on("error", () => {
731
+ try { watcher.close(); } catch {}
732
+ requestWatchers.delete(requestsDir);
733
+ startPolling();
734
+ });
735
+ watcher.unref?.();
736
+ requestWatchers.set(requestsDir, watcher);
737
+ } catch (error) {
738
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") startPolling();
739
+ }
740
+ };
741
+ const watchExistingRequestDirs = (): void => {
742
+ let channelEntries: fs.Dirent[];
743
+ try {
744
+ channelEntries = fs.readdirSync(SUPERVISOR_CHANNEL_ROOT, { withFileTypes: true });
745
+ } catch (error) {
746
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
747
+ startPolling();
748
+ return;
749
+ }
750
+ for (const entry of channelEntries) {
751
+ if (entry.isDirectory()) watchRequestDir(path.join(SUPERVISOR_CHANNEL_ROOT, entry.name, REQUESTS_DIR));
752
+ }
753
+ };
754
+ const scheduleWatcherRefresh = (): void => {
755
+ if (deferredWatcherRefresh) return;
756
+ deferredWatcherRefresh = setImmediate(() => {
757
+ deferredWatcherRefresh = undefined;
758
+ if (!started) return;
759
+ watchExistingRequestDirs();
760
+ poll();
761
+ });
762
+ deferredWatcherRefresh.unref?.();
763
+ };
764
+
699
765
  return {
700
766
  start: () => {
701
- if (poller) return;
767
+ if (started) return;
768
+ started = true;
702
769
  registerParentTools();
703
770
  poll();
704
- poller = setInterval(poll, CHANNEL_POLL_MS);
705
- poller.unref?.();
771
+ try {
772
+ fs.mkdirSync(SUPERVISOR_CHANNEL_ROOT, { recursive: true });
773
+ if ((deps.platform ?? process.platform) === "win32") {
774
+ startPolling();
775
+ return;
776
+ }
777
+ watchExistingRequestDirs();
778
+ rootWatcher = watch(SUPERVISOR_CHANNEL_ROOT, () => {
779
+ watchExistingRequestDirs();
780
+ poll();
781
+ scheduleWatcherRefresh();
782
+ });
783
+ rootWatcher.on("error", startPolling);
784
+ startSafetyPolling();
785
+ scheduleWatcherRefresh();
786
+ } catch {
787
+ startPolling();
788
+ }
706
789
  },
707
790
  dispose: () => {
791
+ started = false;
792
+ try {
793
+ rootWatcher?.close();
794
+ } catch {
795
+ // Best effort during shutdown.
796
+ }
797
+ rootWatcher = undefined;
798
+ for (const watcher of requestWatchers.values()) {
799
+ try { watcher.close(); } catch {}
800
+ }
801
+ requestWatchers.clear();
708
802
  if (poller) clearInterval(poller);
709
803
  poller = undefined;
804
+ if (safetyPoller) clearInterval(safetyPoller);
805
+ safetyPoller = undefined;
806
+ if (deferredWatcherRefresh) clearImmediate(deferredWatcherRefresh);
807
+ deferredWatcherRefresh = undefined;
710
808
  pending.clear();
711
809
  seenFiles.clear();
712
810
  },
@@ -34,6 +34,7 @@ export const MISSION_ACTIONS = [
34
34
  "mission.list",
35
35
  "mission.show",
36
36
  "mission.update",
37
+ "mission.resolve-decision",
37
38
  "mission.attach-run",
38
39
  "mission.close",
39
40
  ] as const;
@@ -298,9 +299,20 @@ function formatMission(record: MissionRecord): string {
298
299
  lines.push("Runs:");
299
300
  for (const run of record.runs) lines.push(` ${run.runId} (${run.mode}${run.status ? `, ${run.status}` : ""})${run.asyncDir ? ` — ${run.asyncDir}` : ""}`);
300
301
  }
302
+ if (record.workflowChildren.length) {
303
+ lines.push("Workflow children:");
304
+ for (const child of record.workflowChildren) {
305
+ const identity = child.runId ? `${child.key} (${child.runId})` : child.key;
306
+ const heartbeat = child.heartbeat ? `; heartbeat ${child.heartbeat.status ?? child.status}${child.heartbeat.phase ? `/${child.heartbeat.phase}` : ""} at ${child.heartbeat.updatedAt}` : "";
307
+ const recovery = child.sessionPath ? `; session ${child.sessionPath}` : child.artifactPaths.length ? `; artifacts ${child.artifactPaths.length}` : "";
308
+ lines.push(` ${identity}: ${child.status}${child.agent ? ` — ${child.agent}` : ""}${child.phase ? ` [${child.phase}]` : ""}; updated ${child.updatedAt}${heartbeat}${recovery}`);
309
+ }
310
+ }
301
311
  if (record.decisions.length) {
302
312
  lines.push("Decisions:");
303
- for (const decision of record.decisions) lines.push(` ${decision.id}: ${decision.status} — ${decision.title}`);
313
+ for (const decision of record.decisions) {
314
+ lines.push(` ${decision.id}: ${decision.status} — ${decision.title}${decision.resolution ? `; resolution: ${decision.resolution}` : ""}`);
315
+ }
304
316
  }
305
317
  if (record.artifacts.length) {
306
318
  lines.push("Artifacts:");
@@ -351,7 +363,11 @@ export function handleMissionAction(
351
363
  const listed = listMissions(location);
352
364
  const lines = listed.records.length === 0
353
365
  ? ["No project missions."]
354
- : listed.records.map((record) => `${record.id} ${record.status} ${record.title} ${record.updatedAt}`);
366
+ : listed.records.map((record) => {
367
+ const open = record.decisions.filter((decision) => decision.status === "open").length;
368
+ const resolved = record.decisions.length - open;
369
+ return `${record.id} ${record.status} ${record.title} ${record.updatedAt}${record.decisions.length ? ` decisions: ${open} open, ${resolved} resolved` : ""}`;
370
+ });
355
371
  if (listed.warnings.length) lines.push("", ...listed.warnings.map((warning) => `Warning: ${warning}`));
356
372
  return textResult(lines.join("\n"), { mode: "management", results: [], missions: { records: listed.records, warnings: listed.warnings } });
357
373
  }
@@ -372,6 +388,13 @@ export function handleMissionAction(
372
388
  const record = updateMission(location, requireMissionId(params), validateMissionUpdate(params.missionUpdate));
373
389
  return textResult(`Updated mission ${record.id}.\n\n${formatMission(record)}`, { mode: "management", results: [], missionId: record.id, missionPath: pathFor(record.id), mission: record });
374
390
  }
391
+ if (action === "mission.resolve-decision") {
392
+ const missionId = requireMissionId(params);
393
+ const decisionId = validateMissionId(params.id, "id");
394
+ if (typeof params.summary !== "string" || !params.summary.trim()) throw new Error("mission.resolve-decision requires a non-empty summary");
395
+ const record = updateMission(location, missionId, { resolveDecision: { id: decisionId, resolution: params.summary.trim() } });
396
+ return textResult(`Resolved decision ${decisionId} for mission ${record.id}.\n\n${formatMission(record)}`, { mode: "management", results: [], missionId: record.id, missionPath: pathFor(record.id), mission: record });
397
+ }
375
398
  if (action === "mission.attach-run") {
376
399
  const missionId = requireMissionId(params);
377
400
  const runId = params.runId ?? params.id;
@@ -2,6 +2,7 @@ import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
3
  import type { AgentToolResult } from "@earendil-works/pi-agent-core";
4
4
  import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
5
+ import { PROMPT_REDACTED } from "../shared/utils.ts";
5
6
  import type { Details, SubagentRunMode } from "../shared/types.ts";
6
7
  import { validateMissionLaunch } from "./actions.ts";
7
8
  import type { MissionArtifact, MissionRecord, MissionRunLink, MissionRunMode, MissionStatus, MissionStoreConfig, MissionStoreLocation } from "./types.ts";
@@ -47,11 +48,6 @@ function workflowObjective(params: MissionLaunchParams): string | undefined {
47
48
  return undefined;
48
49
  }
49
50
 
50
- function conciseTitle(objective: string): string {
51
- const firstLine = objective.split(/\r?\n/, 1)[0]?.trim() || objective.trim();
52
- return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;
53
- }
54
-
55
51
  export function prepareMissionLaunch(input: {
56
52
  params: MissionLaunchParams;
57
53
  projectRoot: string;
@@ -73,10 +69,11 @@ export function prepareMissionLaunch(input: {
73
69
  return { missionId, location, autoCreated: false, announceInContent: true };
74
70
  }
75
71
  const mission = input.params.mission !== undefined ? validateMissionLaunch(input.params.mission) : undefined;
76
- const title = mission?.title || conciseTitle(objective!);
72
+ const promptDerivedObjective = mission?.objective ?? (mission ? mission.title : objective ? PROMPT_REDACTED : undefined);
73
+ const title = mission?.title || PROMPT_REDACTED;
77
74
  const record = createMission(location, {
78
75
  title,
79
- objective: mission?.objective || objective || title,
76
+ objective: promptDerivedObjective || title,
80
77
  ...(mission?.goal === true ? { goal: true as const } : {}),
81
78
  ...(mission?.budget ? { budget: mission.budget } : {}),
82
79
  status: "active",
@@ -160,7 +157,7 @@ function persistedBinding(binding: MissionLaunchBinding): PersistedMissionBindin
160
157
  };
161
158
  }
162
159
 
163
- function writeAsyncBinding(asyncDir: string, binding: MissionLaunchBinding): void {
160
+ export function writeMissionAsyncBinding(asyncDir: string, binding: MissionLaunchBinding): void {
164
161
  writePrivateAtomicJson(path.join(asyncDir, MISSION_BINDING_FILE), persistedBinding(binding));
165
162
  }
166
163
 
@@ -210,7 +207,7 @@ export function attachMissionToLaunchResult(input: {
210
207
  ...(input.result.details.results.length === 1 && input.result.details.results[0]?.acceptance ? { acceptance: input.result.details.results[0].acceptance } : {}),
211
208
  });
212
209
  if (input.result.details.asyncDir) {
213
- writeAsyncBinding(input.result.details.asyncDir, input.binding);
210
+ writeMissionAsyncBinding(input.result.details.asyncDir, input.binding);
214
211
  const statusPath = path.join(input.result.details.asyncDir, "status.json");
215
212
  if (fs.existsSync(statusPath)) {
216
213
  try {
@@ -337,10 +334,29 @@ export function syncMissionFromAsyncCompletion(value: unknown): MissionRecord |
337
334
  return total + (usageFromUnknown((result as { tokens?: unknown }).tokens)?.tokens ?? 0);
338
335
  }, 0) }
339
336
  : undefined);
337
+ const workflowRunId = typeof event.parentWorkflowRunId === "string" && event.parentWorkflowRunId.trim() ? event.parentWorkflowRunId.trim() : undefined;
338
+ const workflowKey = typeof event.workflowKey === "string" && event.workflowKey.trim() ? event.workflowKey.trim() : undefined;
339
+ const workflowChildStatus = runStatus === "complete" || runStatus === "completed" || event.success === true
340
+ ? "completed"
341
+ : runStatus === "paused"
342
+ ? "paused"
343
+ : runStatus === "stopped"
344
+ ? "stopped"
345
+ : "failed";
346
+ const workflowChildTerminal = !["running", "queued", "active", "paused"].includes(workflowChildStatus);
340
347
  return updateMission(binding.location, binding.missionId, {
341
348
  status: missionStatusForRun(current, runId, runStatus),
342
349
  addRuns: [{ runId, mode: typeof event.mode === "string" && ["single", "parallel", "chain", "workflow"].includes(event.mode) ? event.mode as SubagentRunMode : "external", asyncDir: event.asyncDir, status: runStatus, completedAt, ...(usage && usage.tokens > 0 ? { usage } : {}) }],
343
350
  addArtifacts: artifacts,
351
+ ...(workflowRunId && workflowKey ? { upsertWorkflowChildren: [{
352
+ workflowRunId,
353
+ key: workflowKey,
354
+ runId,
355
+ status: workflowChildStatus,
356
+ artifactPaths: artifacts.map((artifact) => artifact.path),
357
+ ...(workflowChildTerminal ? { completedAt } : {}),
358
+ heartbeat: { status: workflowChildStatus, ...(summary ? { message: summary } : {}) },
359
+ }] } : {}),
344
360
  ...(summary ? { summary } : {}),
345
361
  });
346
362
  }
@@ -27,6 +27,7 @@ import {
27
27
  type MissionTokenBudget,
28
28
  type MissionTokenUsage,
29
29
  type MissionUpdateInput,
30
+ type MissionWorkflowChild,
30
31
  } from "./types.ts";
31
32
 
32
33
  const MISSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -149,6 +150,33 @@ function parseDecision(value: unknown, label: string): MissionDecision {
149
150
  };
150
151
  }
151
152
 
153
+ function parseWorkflowChild(value: unknown, label: string): MissionWorkflowChild {
154
+ const input = asObject(value, label);
155
+ const artifactPaths = input.artifactPaths === undefined ? [] : stringArray(input.artifactPaths, `${label}.artifactPaths`);
156
+ const heartbeat = input.heartbeat === undefined ? undefined : asObject(input.heartbeat, `${label}.heartbeat`);
157
+ return {
158
+ workflowRunId: requiredString(input.workflowRunId, `${label}.workflowRunId`),
159
+ key: validateMissionId(input.key, `${label}.key`),
160
+ status: requiredString(input.status, `${label}.status`),
161
+ startedAt: timestamp(input.startedAt, `${label}.startedAt`),
162
+ updatedAt: timestamp(input.updatedAt, `${label}.updatedAt`),
163
+ artifactPaths,
164
+ ...(optionalString(input.runId, `${label}.runId`) ? { runId: input.runId as string } : {}),
165
+ ...(optionalString(input.agent, `${label}.agent`) ? { agent: input.agent as string } : {}),
166
+ ...(optionalString(input.task, `${label}.task`) ? { task: input.task as string } : {}),
167
+ ...(optionalString(input.label, `${label}.label`) ? { label: input.label as string } : {}),
168
+ ...(optionalString(input.phase, `${label}.phase`) ? { phase: input.phase as string } : {}),
169
+ ...(input.completedAt !== undefined ? { completedAt: timestamp(input.completedAt, `${label}.completedAt`) } : {}),
170
+ ...(optionalString(input.sessionPath, `${label}.sessionPath`) ? { sessionPath: input.sessionPath as string } : {}),
171
+ ...(heartbeat ? { heartbeat: {
172
+ updatedAt: timestamp(heartbeat.updatedAt, `${label}.heartbeat.updatedAt`),
173
+ ...(optionalString(heartbeat.status, `${label}.heartbeat.status`) ? { status: heartbeat.status as string } : {}),
174
+ ...(optionalString(heartbeat.phase, `${label}.heartbeat.phase`) ? { phase: heartbeat.phase as string } : {}),
175
+ ...(optionalString(heartbeat.message, `${label}.heartbeat.message`) ? { message: heartbeat.message as string } : {}),
176
+ } } : {}),
177
+ };
178
+ }
179
+
152
180
  function parseArtifact(value: unknown, label: string): MissionArtifact {
153
181
  const input = asObject(value, label);
154
182
  const kind = requiredString(input.kind, `${label}.kind`) as MissionArtifactKind;
@@ -186,10 +214,12 @@ export function parseMissionRecord(value: unknown, source = "mission record"): M
186
214
  const input = asObject(value, source);
187
215
  if (input.schemaVersion !== 1) throw new Error(`${source}.schemaVersion must be 1`);
188
216
  if (!Array.isArray(input.runs)) throw new Error(`${source}.runs must be an array`);
217
+ if (input.workflowChildren !== undefined && !Array.isArray(input.workflowChildren)) throw new Error(`${source}.workflowChildren must be an array`);
189
218
  if (!Array.isArray(input.decisions)) throw new Error(`${source}.decisions must be an array`);
190
219
  if (!Array.isArray(input.artifacts)) throw new Error(`${source}.artifacts must be an array`);
191
220
  if (input.receipts !== undefined && !Array.isArray(input.receipts)) throw new Error(`${source}.receipts must be an array`);
192
221
  const runs = input.runs as unknown[];
222
+ const workflowChildren = (input.workflowChildren ?? []) as unknown[];
193
223
  const decisions = input.decisions as unknown[];
194
224
  const artifacts = input.artifacts as unknown[];
195
225
  const receipts = (input.receipts ?? []) as unknown[];
@@ -211,6 +241,7 @@ export function parseMissionRecord(value: unknown, source = "mission record"): M
211
241
  createdAt: timestamp(input.createdAt, `${source}.createdAt`),
212
242
  updatedAt: timestamp(input.updatedAt, `${source}.updatedAt`),
213
243
  runs: runs.map((item, index) => parseRunLink(item, `${source}.runs[${index}]`)),
244
+ workflowChildren: workflowChildren.map((item, index) => parseWorkflowChild(item, `${source}.workflowChildren[${index}]`)),
214
245
  decisions: decisions.map((item, index) => parseDecision(item, `${source}.decisions[${index}]`)),
215
246
  artifacts: artifacts.map((item, index) => parseArtifact(item, `${source}.artifacts[${index}]`)),
216
247
  receipts: receipts.map((item, index) => parseReceipt(item, `${source}.receipts[${index}]`)),
@@ -227,6 +258,11 @@ function expandConfiguredPath(value: string, projectRoot: string): string {
227
258
  return path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(projectRoot, expanded);
228
259
  }
229
260
 
261
+ function projectMissionDirectory(agentDir: string, projectRoot: string): string {
262
+ const projectKey = createHash("sha256").update(projectRoot).digest("hex");
263
+ return path.join(agentDir, "missions", "projects", projectKey);
264
+ }
265
+
230
266
  export function validateMissionStoreConfig(value: unknown, label = "config.missions"): MissionStoreConfig | undefined {
231
267
  if (value === undefined) return undefined;
232
268
  const input = asObject(value, label);
@@ -257,12 +293,13 @@ export function resolveMissionStoreLocation(input: {
257
293
  agentDir?: string;
258
294
  }): MissionStoreLocation {
259
295
  const projectRoot = path.resolve(input.projectRoot);
296
+ const agentDir = input.agentDir ?? getAgentDir();
260
297
  const missionDir = input.config?.directory
261
298
  ? expandConfiguredPath(input.config.directory, projectRoot)
262
- : path.join(projectRoot, ".pi-subagents", "missions");
299
+ : projectMissionDirectory(agentDir, projectRoot);
263
300
  const globalIndexDir = input.config?.globalIndexDir
264
301
  ? expandConfiguredPath(input.config.globalIndexDir, projectRoot)
265
- : path.join(input.agentDir ?? getAgentDir(), "missions", "index");
302
+ : path.join(agentDir, "missions", "index");
266
303
  return {
267
304
  projectRoot,
268
305
  missionDir,
@@ -346,6 +383,7 @@ export function createMission(location: MissionStoreLocation, input: MissionCrea
346
383
  updatedAt: createdAt,
347
384
  cwd: location.projectRoot,
348
385
  runs: [],
386
+ workflowChildren: [],
349
387
  decisions: [],
350
388
  artifacts: [],
351
389
  receipts: [],
@@ -363,11 +401,11 @@ export class MissionNotFoundError extends Error {
363
401
  readonly missionId: string;
364
402
  readonly missionDir: string;
365
403
 
366
- constructor(missionId: string, missionDir: string) {
367
- super(`Mission '${missionId}' was not found in ${missionDir}`);
404
+ constructor(missionId: string, location: MissionStoreLocation) {
405
+ super(`Mission '${missionId}' was not found in mission directory '${location.missionDir}' for project root '${location.projectRoot}'. If it was created in another worktree, run the request from that worktree.`);
368
406
  this.name = "MissionNotFoundError";
369
407
  this.missionId = missionId;
370
- this.missionDir = missionDir;
408
+ this.missionDir = location.missionDir;
371
409
  }
372
410
  }
373
411
 
@@ -377,7 +415,7 @@ export function readMission(location: MissionStoreLocation, missionId: string):
377
415
  try {
378
416
  raw = fs.readFileSync(filePath, "utf-8");
379
417
  } catch (error) {
380
- if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new MissionNotFoundError(missionId, location.missionDir);
418
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new MissionNotFoundError(missionId, location);
381
419
  throw error;
382
420
  }
383
421
  try {
@@ -412,6 +450,28 @@ export function updateMission(location: MissionStoreLocation, missionId: string,
412
450
  if (existingIndex === -1) runs.push(run);
413
451
  else runs[existingIndex] = { ...runs[existingIndex]!, ...run };
414
452
  }
453
+ const workflowChildren = [...current.workflowChildren];
454
+ for (const candidate of update.upsertWorkflowChildren ?? []) {
455
+ const nowIso = now.toISOString();
456
+ const parsed = parseWorkflowChild({
457
+ ...candidate,
458
+ startedAt: candidate.startedAt ?? nowIso,
459
+ updatedAt: nowIso,
460
+ artifactPaths: candidate.artifactPaths ?? [],
461
+ ...(candidate.heartbeat ? { heartbeat: { ...candidate.heartbeat, updatedAt: nowIso } } : {}),
462
+ }, "mission.update.upsertWorkflowChildren[]");
463
+ const existingIndex = workflowChildren.findIndex((child) => child.workflowRunId === parsed.workflowRunId && child.key === parsed.key);
464
+ if (existingIndex === -1) workflowChildren.push(parsed);
465
+ else {
466
+ const existing = workflowChildren[existingIndex]!;
467
+ workflowChildren[existingIndex] = parseWorkflowChild({
468
+ ...existing,
469
+ ...parsed,
470
+ startedAt: existing.startedAt,
471
+ artifactPaths: [...new Set([...existing.artifactPaths, ...parsed.artifactPaths])],
472
+ }, "mission.update.upsertWorkflowChildren[]");
473
+ }
474
+ }
415
475
  const artifacts = [...current.artifacts];
416
476
  for (const candidate of update.addArtifacts ?? []) {
417
477
  const artifact = parseArtifact(candidate, "mission.update.addArtifacts[]");
@@ -439,6 +499,18 @@ export function updateMission(location: MissionStoreLocation, missionId: string,
439
499
  ...(decision.recommendation ? { recommendation: requiredString(decision.recommendation, "mission.update.addDecisions[].recommendation") } : {}),
440
500
  })),
441
501
  ];
502
+ if (update.resolveDecision) {
503
+ const decisionId = validateMissionId(update.resolveDecision.id, "mission.update.resolveDecision.id");
504
+ const decisionIndex = decisions.findIndex((decision) => decision.id === decisionId);
505
+ if (decisionIndex === -1) throw new Error(`Decision '${decisionId}' was not found in mission '${missionId}'`);
506
+ if (decisions[decisionIndex]!.status === "resolved") throw new Error(`Decision '${decisionId}' is already resolved`);
507
+ decisions[decisionIndex] = {
508
+ ...decisions[decisionIndex]!,
509
+ status: "resolved",
510
+ resolvedAt: createdAt,
511
+ resolution: requiredString(update.resolveDecision.resolution, "mission.update.resolveDecision.resolution").trim(),
512
+ };
513
+ }
442
514
  const budget = update.budget !== undefined ? parseBudget(update.budget, "mission.update.budget") : current.budget;
443
515
  const usage = update.usage !== undefined
444
516
  ? parseUsage(update.usage, "mission.update.usage")
@@ -452,10 +524,20 @@ export function updateMission(location: MissionStoreLocation, missionId: string,
452
524
  ? { status: "active" }
453
525
  : goal;
454
526
  }
527
+ const hasOpenDecisions = decisions.some((decision) => decision.status === "open");
528
+ const requestedStatus = update.status !== undefined ? missionStatus(update.status, "mission.update.status") : undefined;
529
+ const candidateStatus = requestedStatus
530
+ ?? (update.addDecisions?.length && current.status === "active"
531
+ ? "needs_decision"
532
+ : update.resolveDecision && current.status === "needs_decision" && !hasOpenDecisions
533
+ ? "active"
534
+ : current.status);
535
+ const decisionStatus = hasOpenDecisions && (candidateStatus === "active" || candidateStatus === "completed") ? "needs_decision" : candidateStatus;
455
536
  const next: MissionRecord = {
456
537
  ...current,
457
538
  updatedAt: createdAt,
458
539
  runs,
540
+ workflowChildren,
459
541
  artifacts,
460
542
  receipts,
461
543
  decisions,
@@ -463,7 +545,7 @@ export function updateMission(location: MissionStoreLocation, missionId: string,
463
545
  ...(update.objective !== undefined ? { objective: requiredString(update.objective, "mission.update.objective").trim() } : {}),
464
546
  ...(budget ? { budget } : {}),
465
547
  ...(goal ? { goal, usage } : {}),
466
- ...(update.status !== undefined ? { status: missionStatus(update.status, "mission.update.status") } : {}),
548
+ status: decisionStatus,
467
549
  ...(update.summary !== undefined ? { summary: requiredString(update.summary, "mission.update.summary") } : {}),
468
550
  ...(update.labels !== undefined ? { labels: stringArray(update.labels, "mission.update.labels") } : {}),
469
551
  ...(update.acceptance !== undefined ? { acceptance: update.acceptance } : {}),
@@ -51,6 +51,36 @@ export interface MissionDecision {
51
51
  resolution?: string;
52
52
  }
53
53
 
54
+ export interface MissionChildHeartbeat {
55
+ updatedAt: string;
56
+ status?: string;
57
+ phase?: string;
58
+ message?: string;
59
+ }
60
+
61
+ export interface MissionWorkflowChild {
62
+ workflowRunId: string;
63
+ key: string;
64
+ status: string;
65
+ startedAt: string;
66
+ updatedAt: string;
67
+ runId?: string;
68
+ agent?: string;
69
+ task?: string;
70
+ label?: string;
71
+ phase?: string;
72
+ completedAt?: string;
73
+ sessionPath?: string;
74
+ artifactPaths: string[];
75
+ heartbeat?: MissionChildHeartbeat;
76
+ }
77
+
78
+ export type MissionWorkflowChildUpdate = Pick<MissionWorkflowChild, "workflowRunId" | "key" | "status"> & Partial<Omit<MissionWorkflowChild, "workflowRunId" | "key" | "status" | "startedAt" | "updatedAt" | "artifactPaths" | "heartbeat">> & {
79
+ startedAt?: string;
80
+ artifactPaths?: string[];
81
+ heartbeat?: Omit<MissionChildHeartbeat, "updatedAt"> & { updatedAt?: string };
82
+ };
83
+
54
84
  export interface MissionArtifact {
55
85
  kind: MissionArtifactKind;
56
86
  path: string;
@@ -80,6 +110,7 @@ export interface MissionRecord {
80
110
  cwd?: string;
81
111
  ownerSessionId?: string;
82
112
  runs: MissionRunLink[];
113
+ workflowChildren: MissionWorkflowChild[];
83
114
  decisions: MissionDecision[];
84
115
  artifacts: MissionArtifact[];
85
116
  receipts: MissionReceipt[];
@@ -151,7 +182,9 @@ export interface MissionUpdateInput {
151
182
  labels?: string[];
152
183
  acceptance?: unknown;
153
184
  addRuns?: MissionRunLink[];
185
+ upsertWorkflowChildren?: MissionWorkflowChildUpdate[];
154
186
  addArtifacts?: MissionArtifact[];
155
187
  addDecisions?: Array<Omit<MissionDecision, "id" | "status" | "createdAt">>;
188
+ resolveDecision?: { id: string; resolution: string };
156
189
  addReceipts?: Array<Omit<MissionReceipt, "createdAt">>;
157
190
  }
@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
3
3
  import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
5
  import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
6
- import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, waitForFileSystemRetry } from "../shared/file-system-retry.ts";
6
+ import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, isRetryableFileSystemError, waitForFileSystemRetry } from "../shared/file-system-retry.ts";
7
7
  import { assertWorkflowJsonValue } from "../workflows/scripted-workflow.ts";
8
8
  import type { MissionStoreLocation } from "./types.ts";
9
9
  import { validateMissionId } from "./store.ts";
@@ -95,8 +95,12 @@ function stateLockIsStale(lockPath: string, now = Date.now()): boolean {
95
95
  const owner = readStateLockOwner(lockPath);
96
96
  if (owner) {
97
97
  if (!isProcessAlive(owner.pid)) return true;
98
- const currentProcessKey = processStartKey(owner.pid);
99
- return Boolean(owner.processKey && currentProcessKey && owner.processKey !== currentProcessKey);
98
+ if (owner.processKey) {
99
+ const currentProcessKey = owner.pid === process.pid ? CURRENT_PROCESS_KEY : processStartKey(owner.pid);
100
+ if (currentProcessKey) return owner.processKey !== currentProcessKey;
101
+ if (owner.pid === process.pid) return true;
102
+ }
103
+ return false;
100
104
  }
101
105
  try {
102
106
  return now - fs.statSync(lockPath).mtimeMs > STATE_LOCK_STALE_MS;
@@ -162,24 +166,30 @@ function withStateFileLock<T>(filePath: string, operation: () => T): T {
162
166
  waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
163
167
  continue;
164
168
  }
169
+ let acquired = false;
165
170
  try {
166
- fs.mkdirSync(lockPath, { mode: 0o700 });
167
- owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(CURRENT_PROCESS_KEY ? { processKey: CURRENT_PROCESS_KEY } : {}) };
168
- try {
169
- fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
170
- } catch (error) {
171
- removeOwnedStateLock(lockPath, owner);
172
- owner = undefined;
173
- throw error;
174
- }
175
- break;
171
+ acquired = tryMakeDirectory(lockPath, 0o700);
176
172
  } catch (error) {
177
- if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
178
- throw new Error(`Failed to acquire mission state lock '${lockPath}': ${error instanceof Error ? error.message : String(error)}`);
173
+ if (isRetryableFileSystemError(error)) {
174
+ waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
175
+ continue;
179
176
  }
177
+ throw new Error(`Failed to acquire mission state lock '${lockPath}': ${error instanceof Error ? error.message : String(error)}`);
178
+ }
179
+ if (!acquired) {
180
180
  if (reclaimStaleStateLock(lockPath, reclaimPath)) continue;
181
181
  waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
182
+ continue;
183
+ }
184
+ owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(CURRENT_PROCESS_KEY ? { processKey: CURRENT_PROCESS_KEY } : {}) };
185
+ try {
186
+ fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
187
+ } catch (error) {
188
+ fs.rmSync(lockPath, { recursive: true, force: true });
189
+ owner = undefined;
190
+ throw error;
182
191
  }
192
+ break;
183
193
  }
184
194
  try {
185
195
  return operation();