@abelxiaoxing/cadence 2.0.22 → 2.0.24

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 (42) hide show
  1. package/README.de.md +4 -10
  2. package/README.es.md +4 -10
  3. package/README.fr.md +4 -10
  4. package/README.ja.md +4 -10
  5. package/README.ko.md +4 -10
  6. package/README.md +5 -13
  7. package/README.pt-BR.md +4 -10
  8. package/README.ru.md +4 -10
  9. package/README.zh-CN.md +4 -12
  10. package/docs/conversation-mode.md +22 -2
  11. package/docs/history.md +50 -0
  12. package/docs/service-management.md +1 -1
  13. package/package.json +9 -7
  14. package/src/agent-panel-cadence.ts +4 -4
  15. package/src/cadence-mode.ts +284 -166
  16. package/src/coordinator-tools.mjs +9 -0
  17. package/src/data-shapes.ts +16 -0
  18. package/src/history-shell.ts +370 -0
  19. package/src/index.ts +3 -3
  20. package/src/native-build.ts +1 -1
  21. package/src/native-client.ts +1 -1
  22. package/src/native-workflow-history.ts +134 -0
  23. package/src/operator-cli.mjs +93 -65
  24. package/src/research-tools.mjs +365 -0
  25. package/src/sdk-worker.mjs +59 -9
  26. package/src/service/checkout-lock.ts +142 -0
  27. package/src/service/contracts/workbench.ts +43 -23
  28. package/src/service/contracts/workflow.ts +137 -2
  29. package/src/service/coordination.ts +6 -7
  30. package/src/service/private-files.ts +2 -1
  31. package/src/service-cli.mjs +259 -425
  32. package/src/service-host.mjs +3680 -6048
  33. package/src/worker-public.mjs +16 -1
  34. package/src/workspace.ts +302 -0
  35. package/web/dist/assets/cadence.css +1 -1
  36. package/web/dist/assets/cadence.js +16 -15
  37. package/web/dist/manifest.json +7 -7
  38. package/config/workflow-task.example.json +0 -7
  39. package/src/plan-proposal.ts +0 -87
  40. package/src/task-shell.ts +0 -1059
  41. package/src/task-store.ts +0 -593
  42. package/src/task-types.ts +0 -184
@@ -1,6 +1,7 @@
1
1
  // Isolated SDK child, not Pi CLI startup. Task discovery stays disabled;
2
2
  // ordinary conversations explicitly load only context/skills, never extensions.
3
- import { writeFileSync } from "node:fs";
3
+ import { createHash } from "node:crypto";
4
+ import { readFileSync, writeFileSync } from "node:fs";
4
5
  import {
5
6
  createProvider,
6
7
  InMemoryCredentialStore,
@@ -13,6 +14,7 @@ import {
13
14
  ModelRuntime,
14
15
  SessionManager,
15
16
  SettingsManager,
17
+ VERSION,
16
18
  } from "@earendil-works/pi-coding-agent";
17
19
  import {
18
20
  encodeConversationContext,
@@ -20,6 +22,7 @@ import {
20
22
  } from "./conversation-context.mjs";
21
23
  import { conversationResources } from "./conversation-resources.mjs";
22
24
  import { coordinatorTools } from "./coordinator-tools.mjs";
25
+ import { researchClock, researchTools } from "./research-tools.mjs";
23
26
  import { CaptureEmitter, SdkCapture } from "./worker-capture.mjs";
24
27
  import {
25
28
  closed,
@@ -198,12 +201,14 @@ try {
198
201
  new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)),
199
202
  LIMITS.workerRequestBytes,
200
203
  );
201
- const envelope = closed(
202
- parsed,
203
- Object.hasOwn(parsed ?? {}, "conversation")
204
- ? ["request", "cwd", "model", "auth", "conversation"]
205
- : ["request", "cwd", "model", "auth"],
206
- );
204
+ const envelope = closed(parsed, [
205
+ "request",
206
+ "cwd",
207
+ "model",
208
+ "auth",
209
+ ...(Object.hasOwn(parsed ?? {}, "conversation") ? ["conversation"] : []),
210
+ ...(Object.hasOwn(parsed ?? {}, "investigation") ? ["investigation"] : []),
211
+ ]);
207
212
  const conversation =
208
213
  envelope.conversation === undefined
209
214
  ? null
@@ -221,6 +226,25 @@ try {
221
226
  typeof conversation.agentDir !== "string")
222
227
  )
223
228
  refuse("parse", "invalid-conversation");
229
+ const investigation =
230
+ envelope.investigation === undefined
231
+ ? null
232
+ : closed(envelope.investigation, ["roots", "timeoutMs", "deadlineMs"]);
233
+ if (
234
+ investigation &&
235
+ (!Array.isArray(investigation.roots) ||
236
+ investigation.roots.length < 1 ||
237
+ investigation.roots.length > 8 ||
238
+ investigation.roots.some(
239
+ (p) => typeof p !== "string" || !p || p.length > 4096,
240
+ ) ||
241
+ !Number.isSafeInteger(investigation.timeoutMs) ||
242
+ investigation.timeoutMs < 100 ||
243
+ investigation.timeoutMs > LIMITS.workerMs ||
244
+ !Number.isSafeInteger(investigation.deadlineMs) ||
245
+ investigation.deadlineMs < 0)
246
+ )
247
+ refuse("parse", "invalid-investigation");
224
248
  const publicRequest = decodeWorkerPublicRequest(envelope.request);
225
249
  const coordinator = conversation?.coordinator === true;
226
250
  if (
@@ -393,7 +417,19 @@ try {
393
417
  emitter.queue,
394
418
  ),
395
419
  ]
396
- : [],
420
+ : conversation
421
+ ? []
422
+ : researchTools(
423
+ cwd,
424
+ investigation?.roots ?? [cwd],
425
+ investigation ?? {
426
+ timeoutMs: LIMITS.workerMs,
427
+ // Standalone protocol callers without a launcher policy still
428
+ // start at process birth, never at tool construction.
429
+ deadlineMs:
430
+ researchClock() + LIMITS.workerMs - process.uptime() * 1000,
431
+ },
432
+ ),
397
433
  resourceLoader:
398
434
  conversation && !coordinator
399
435
  ? conversationResources(resourceLoader, cwd, conversation.agentDir)
@@ -506,11 +542,25 @@ try {
506
542
  }
507
543
  });
508
544
  stage = "ready";
509
- await emitter.emit({ kind: "ready", requestProtocol: 2 });
545
+ await emitter.emit({
546
+ kind: "ready",
547
+ requestProtocol: 2,
548
+ runtime: {
549
+ sdkVersion: VERSION,
550
+ workerHash: createHash("sha256")
551
+ .update(readFileSync(new URL(import.meta.url)))
552
+ .digest("hex"),
553
+ },
554
+ });
510
555
  await capture.context(publicRequest, session.systemPrompt);
511
556
  stage = "prompt";
512
557
  const suppliedPrompt = [
513
558
  publicRequest.context,
559
+ ...(!conversation && kind !== "code"
560
+ ? [
561
+ `Investigation roots: ${JSON.stringify(investigation?.roots ?? [cwd])}. Start at these specific paths, not / or their parents. Tools use bounded cooperative reads; no shell is available. Search filenames and shallow directories before content. Do not repeat broad scans or silently exclude backup trees. Total worker deadline: ${investigation?.timeoutMs ?? LIMITS.workerMs}ms, including model and tool time; activity never extends it. Reserve the last portion for a concise final report. On any budget/coverage limit, summarize partial evidence and unresolved questions; never claim exhaustive absence.`,
562
+ ]
563
+ : []),
514
564
  ...publicRequest.handoff.inputs.map(
515
565
  (input) =>
516
566
  `Dependency ${input.assignmentId} (recorded input):\n${input.text}`,
@@ -0,0 +1,142 @@
1
+ /** Existing checkout lock identity and original filesystem semantics, without task CRUD. */
2
+ import { randomUUID } from "node:crypto";
3
+ import {
4
+ closeSync,
5
+ fsyncSync,
6
+ lstatSync,
7
+ openSync,
8
+ realpathSync,
9
+ unlinkSync,
10
+ writeFileSync,
11
+ } from "node:fs";
12
+ import { hostname } from "node:os";
13
+ import { dirname, join } from "node:path";
14
+ import { object, validId } from "../data-shapes.ts";
15
+ import {
16
+ absent,
17
+ contains,
18
+ defaultStateHome,
19
+ parseRecord,
20
+ privateRootFor,
21
+ privateWorkspace,
22
+ readBounded,
23
+ retryWindowsFileOperation,
24
+ safeDirectory,
25
+ } from "../workspace.ts";
26
+ export interface CheckoutLock {
27
+ schema: "cadence-assistant-lock/1";
28
+ token: string;
29
+ pid: number;
30
+ host: string;
31
+ runId: string;
32
+ root: string;
33
+ }
34
+ export class CheckoutStore {
35
+ readonly root: string;
36
+ readonly privateRoot: string;
37
+ constructor(root: string, stateHome = defaultStateHome()) {
38
+ this.root = realpathSync(root);
39
+ if (privateWorkspace(this.root, stateHome))
40
+ throw new Error("Private state cannot be a workspace");
41
+ this.privateRoot = privateRootFor(this.root, stateHome);
42
+ if (contains(this.root, this.privateRoot))
43
+ throw new Error("Private state home must be outside the working copy");
44
+ }
45
+ get lockPath(): string {
46
+ return join(this.privateRoot, "checkout.lock");
47
+ }
48
+ private inspectPrivate(): void {
49
+ const namespace = dirname(this.privateRoot);
50
+ for (const path of [namespace, this.privateRoot]) {
51
+ if (!safeDirectory(path)) continue;
52
+ const st = lstatSync(path);
53
+ if (
54
+ process.platform !== "win32" &&
55
+ ((st.mode & 0o077) !== 0 ||
56
+ (process.getuid && st.uid !== process.getuid()))
57
+ )
58
+ throw new Error("Private state permissions refused");
59
+ }
60
+ }
61
+ protected inspectPrivateFile(path: string, max: number): void {
62
+ this.inspectPrivate();
63
+ if (!safeDirectory(this.privateRoot)) return;
64
+ try {
65
+ const st = lstatSync(path);
66
+ if (
67
+ !st.isFile() ||
68
+ st.isSymbolicLink() ||
69
+ st.nlink !== 1 ||
70
+ st.size > max ||
71
+ (process.platform !== "win32" &&
72
+ ((st.mode & 0o077) !== 0 ||
73
+ (process.getuid && st.uid !== process.getuid())))
74
+ )
75
+ throw new Error("Unsafe private state file");
76
+ } catch (error) {
77
+ if (!absent(error)) throw error;
78
+ }
79
+ }
80
+ inspectLock(): CheckoutLock | undefined {
81
+ this.inspectPrivateFile(this.lockPath, 8192);
82
+ const data = readBounded(this.lockPath, 8192);
83
+ if (!data) return undefined;
84
+ const lock: unknown = parseRecord(data);
85
+ if (
86
+ !object(lock) ||
87
+ lock.schema !== "cadence-assistant-lock/1" ||
88
+ lock.root !== this.root ||
89
+ typeof lock.token !== "string" ||
90
+ !validId(lock.token) ||
91
+ typeof lock.runId !== "string" ||
92
+ !validId(lock.runId) ||
93
+ typeof lock.host !== "string" ||
94
+ !Number.isInteger(lock.pid) ||
95
+ Number(lock.pid) < 1
96
+ )
97
+ throw new Error("Unknown or corrupt coordination lock");
98
+ return lock as unknown as CheckoutLock;
99
+ }
100
+ acquire(): CheckoutLock {
101
+ this.inspectPrivate();
102
+ safeDirectory(this.privateRoot, true);
103
+ const lock: CheckoutLock = {
104
+ schema: "cadence-assistant-lock/1",
105
+ token: randomUUID(),
106
+ runId: randomUUID(),
107
+ pid: process.pid,
108
+ host: hostname(),
109
+ root: this.root,
110
+ };
111
+ let fd: number;
112
+ try {
113
+ fd = retryWindowsFileOperation(() =>
114
+ openSync(this.lockPath, "wx", 0o600),
115
+ );
116
+ } catch {
117
+ throw new Error(
118
+ "Checkout busy or unresolved lock; inspect and explicitly recover only a dead owner",
119
+ );
120
+ }
121
+ try {
122
+ writeFileSync(fd, JSON.stringify(lock));
123
+ fsyncSync(fd);
124
+ } finally {
125
+ closeSync(fd);
126
+ }
127
+ return lock;
128
+ }
129
+ assertOwner(lock: CheckoutLock): void {
130
+ if (JSON.stringify(this.inspectLock()) !== JSON.stringify(lock))
131
+ throw new Error("Coordination lock changed");
132
+ }
133
+ release(lock: CheckoutLock): void {
134
+ if (lock.pid !== process.pid || lock.host !== hostname())
135
+ throw new Error("Only the owning process may release a lock");
136
+ this.assertOwner(lock);
137
+ retryWindowsFileOperation(
138
+ () => unlinkSync(this.lockPath),
139
+ () => this.assertOwner(lock),
140
+ );
141
+ }
142
+ }
@@ -19,6 +19,7 @@ import {
19
19
  decodeWorkflowRequest,
20
20
  decodeWorkflowResponse,
21
21
  decodeWorkflowRun,
22
+ WORKFLOW_LIMITS,
22
23
  type WorkflowProposal,
23
24
  type WorkflowRequest,
24
25
  type WorkflowResponse,
@@ -67,6 +68,7 @@ export interface WorkflowLink {
67
68
  export type WorkbenchRead =
68
69
  | { kind: "cadence-conversation"; id: string }
69
70
  | { kind: "workflow-active" }
71
+ | { kind: "workflow-history"; after: string | null; scan?: string }
70
72
  | { kind: "workflow-detail"; id: string; stepId: string }
71
73
  | { kind: "workflow-transcript"; id: string; stepId: string }
72
74
  | { kind: "workflow"; id: string }
@@ -120,13 +122,6 @@ export type WorkbenchCommand =
120
122
  epoch: string;
121
123
  request: WorkflowRequest;
122
124
  }
123
- | {
124
- kind: "link-task";
125
- commandId: string;
126
- epoch: string;
127
- taskId: string;
128
- conversationId: string;
129
- }
130
125
  | {
131
126
  kind: "send";
132
127
  commandId: string;
@@ -183,6 +178,12 @@ export interface FileEntry {
183
178
  directory: boolean;
184
179
  }
185
180
  export type WorkbenchResult =
181
+ | { kind: "workflow-history-progress"; after: string | null; scan: string }
182
+ | {
183
+ kind: "workflow-history";
184
+ entries: { id: string; run: WorkflowRun | null }[];
185
+ next: string | null;
186
+ }
186
187
  | {
187
188
  kind: "workflow-transcript";
188
189
  runId: string;
@@ -251,6 +252,15 @@ export function decodeWorkbenchRead(v: unknown): WorkbenchRead {
251
252
  const o = closed(v, ["kind", "id"]);
252
253
  return { kind, id: decodeId(o.id) };
253
254
  }
255
+ case "workflow-history": {
256
+ const continued = Object.hasOwn(v as object, "scan");
257
+ const o = closed(v, ["kind", "after", ...(continued ? ["scan"] : [])]);
258
+ return {
259
+ kind,
260
+ after: nullable(o.after, decodeId),
261
+ ...(continued ? { scan: decodeId(o.scan) } : {}),
262
+ };
263
+ }
254
264
  case "workflow-active":
255
265
  closed(v, ["kind"]);
256
266
  return { kind };
@@ -366,22 +376,7 @@ export function decodeWorkbenchCommand(v: unknown): WorkbenchCommand {
366
376
  request: decodeWorkflowRequest(o.request),
367
377
  };
368
378
  }
369
- if (kind === "link-task") {
370
- const o = closed(v, [
371
- "kind",
372
- "commandId",
373
- "epoch",
374
- "taskId",
375
- "conversationId",
376
- ]);
377
- return {
378
- kind,
379
- commandId: decodeId(o.commandId),
380
- epoch: decodeId(o.epoch),
381
- taskId: decodeId(o.taskId),
382
- conversationId: decodeId(o.conversationId),
383
- };
384
- }
379
+
385
380
  if (kind === "send") {
386
381
  const o = closed(v, [
387
382
  "kind",
@@ -492,6 +487,31 @@ export function decodeWorkbenchResult(v: unknown): WorkbenchResult {
492
487
  const o = closed(v, ["kind", "state"]);
493
488
  return { kind: k, state: decodeCadenceConversation(o.state) };
494
489
  }
490
+ if (k === "workflow-history-progress") {
491
+ const o = closed(v, ["kind", "after", "scan"]);
492
+ return {
493
+ kind: k,
494
+ after: nullable(o.after, decodeId),
495
+ scan: decodeId(o.scan),
496
+ };
497
+ }
498
+ if (k === "workflow-history") {
499
+ const o = closed(v, ["kind", "entries", "next"]);
500
+ const entries = list(o.entries, WORKFLOW_LIMITS.historyPage, (v) => {
501
+ const e = closed(v, ["id", "run"]);
502
+ const id = decodeId(e.id),
503
+ run = nullable(e.run, decodeWorkflowRun);
504
+ if (run && run.id !== id) throw new ContractError("invalid");
505
+ return { id, run };
506
+ });
507
+ const next = nullable(o.next, decodeId);
508
+ if (
509
+ new Set(entries.map((e) => e.id)).size !== entries.length ||
510
+ (next !== null && next !== entries.at(-1)?.id)
511
+ )
512
+ throw new ContractError("invalid");
513
+ return { kind: k, entries, next };
514
+ }
495
515
  if (k === "workflow-active") {
496
516
  const linked =
497
517
  v !== null && typeof v === "object" && Object.hasOwn(v, "links");
@@ -19,7 +19,11 @@ export const WORKFLOW_LIMITS = {
19
19
  checks: 16,
20
20
  repairs: 2,
21
21
  bytes: 256 * 1024,
22
- runs: 200,
22
+ // Read budgets, never a lifetime cap on retained runs.
23
+ historyScanEntries: 200,
24
+ historyPage: 20,
25
+ historyScans: 16,
26
+ historyIdleMs: 120000,
23
27
  durationMs: 90 * 60 * 1000,
24
28
  } as const;
25
29
  export interface WorkflowCheck {
@@ -57,7 +61,33 @@ export interface WorkflowProposal {
57
61
  cwd: string;
58
62
  display?: { model: string; branch: string; baseCommit: string };
59
63
  }
64
+ export interface WorkflowTiming {
65
+ createdAt: number;
66
+ preparedAt: number | null;
67
+ startedAt: number | null;
68
+ stopRequestedAt: number | null;
69
+ closedAt: number | null;
70
+ settledAt: number | null;
71
+ timeoutMs: number;
72
+ stopReason: string | null;
73
+ }
74
+ export interface WorkflowDiagnostics {
75
+ acceptedAt: number;
76
+ acquiredAt: number | null;
77
+ settledAt: number | null;
78
+ owner: {
79
+ version: string;
80
+ build: string;
81
+ entry: string;
82
+ pid: number;
83
+ node: string;
84
+ platform: string;
85
+ startedAt: number;
86
+ };
87
+ }
60
88
  export interface WorkflowStep {
89
+ timing?: WorkflowTiming;
90
+ runtime?: { sdkVersion: string; workerHash: string };
61
91
  id: string;
62
92
  childRunId?: string;
63
93
  kind: "research" | "implementation" | "review" | "check" | "git";
@@ -73,6 +103,7 @@ export interface WorkflowStep {
73
103
  truncated: boolean;
74
104
  }
75
105
  export interface WorkflowRun {
106
+ diagnostics?: WorkflowDiagnostics;
76
107
  id: string;
77
108
  epoch: string;
78
109
  goal: string;
@@ -101,6 +132,7 @@ export type WorkflowRequest =
101
132
  action: "research";
102
133
  goal: string;
103
134
  questions: string[];
135
+ roots?: string[];
104
136
  model: ChoiceVersion;
105
137
  }
106
138
  | { action: "propose"; plan: WorkflowPlan; model: ChoiceVersion }
@@ -350,15 +382,28 @@ export function decodeWorkflowProposal(v: unknown): WorkflowProposal {
350
382
  export function decodeWorkflowRequest(v: unknown): WorkflowRequest {
351
383
  const action = Object.getOwnPropertyDescriptor(v ?? {}, "action")?.value;
352
384
  if (action === "research") {
353
- const o = closed(v, ["action", "goal", "questions", "model"]);
385
+ const o = closed(v, [
386
+ "action",
387
+ "goal",
388
+ "questions",
389
+ "model",
390
+ ...(Object.hasOwn(v ?? {}, "roots") ? ["roots"] : []),
391
+ ]);
354
392
  const questions = list(o.questions, WORKFLOW_LIMITS.parallel, (q) =>
355
393
  text(q, 8192, true),
356
394
  );
357
395
  if (!questions.length) throw new Error("Research needs a question");
396
+ const roots =
397
+ o.roots === undefined
398
+ ? undefined
399
+ : list(o.roots, 8, (p) => text(p, 4096, true));
400
+ if (roots && !roots.length)
401
+ throw new Error("Research needs a specific root");
358
402
  return {
359
403
  action,
360
404
  goal: text(o.goal, 8192, true),
361
405
  questions,
406
+ ...(roots ? { roots } : {}),
362
407
  model: decodeChoiceVersion(o.model),
363
408
  };
364
409
  }
@@ -399,6 +444,7 @@ export function decodeWorkflowRun(v: unknown): WorkflowRun {
399
444
  "notice",
400
445
  "mergedCommit",
401
446
  "humanReviewed",
447
+ ...(Object.hasOwn(v ?? {}, "diagnostics") ? ["diagnostics"] : []),
402
448
  ]);
403
449
  const status = (x: unknown) =>
404
450
  oneOf(x, [
@@ -412,6 +458,9 @@ export function decodeWorkflowRun(v: unknown): WorkflowRun {
412
458
  if (o.humanReviewed !== false)
413
459
  throw new Error("Automatic execution is not human review");
414
460
  return {
461
+ ...(o.diagnostics === undefined
462
+ ? {}
463
+ : { diagnostics: decodeWorkflowDiagnostics(o.diagnostics) }),
415
464
  id: decodeId(o.id),
416
465
  epoch: decodeId(o.epoch),
417
466
  goal: text(o.goal, 8192),
@@ -437,9 +486,25 @@ export function decodeWorkflowRun(v: unknown): WorkflowRun {
437
486
  "text",
438
487
  "exitCode",
439
488
  "truncated",
489
+ ...(Object.hasOwn(v ?? {}, "timing") ? ["timing"] : []),
490
+ ...(Object.hasOwn(v ?? {}, "runtime") ? ["runtime"] : []),
440
491
  ...(linked ? ["childRunId"] : []),
441
492
  ]);
442
493
  return {
494
+ ...(s.timing === undefined
495
+ ? {}
496
+ : { timing: decodeWorkflowTiming(s.timing) }),
497
+ ...(s.runtime === undefined
498
+ ? {}
499
+ : {
500
+ runtime: (() => {
501
+ const r = closed(s.runtime, ["sdkVersion", "workerHash"]);
502
+ return {
503
+ sdkVersion: text(r.sdkVersion, 128, true),
504
+ workerHash: decodeHash(r.workerHash),
505
+ };
506
+ })(),
507
+ }),
443
508
  id: text(s.id, 160, true),
444
509
  ...(linked ? { childRunId: decodeId(s.childRunId) } : {}),
445
510
  kind: oneOf(s.kind, [
@@ -489,3 +554,73 @@ export function readableWorkflowPlan(p: WorkflowPlan): string {
489
554
  "\n\n",
490
555
  )}\n\n## Setup (explicitly authorized commands)\n${p.setup.map((c) => `${c.name}: ${c.command} (${c.timeoutMs}ms)`).join("\n") || "None; no dependency installation or copying."}\n\n## Baseline verification\n${p.baselineChecks.map((c) => `${c.name}: ${c.command} (${c.timeoutMs}ms)`).join("\n") || "No separate baseline checks declared."}\n\n## Verification\n${p.checks.map((c) => `${c.name}: ${c.command} (${c.timeoutMs}ms)`).join("\n")}\n\n## Automation boundary\nAt most ${p.repairAttempts} repair rounds. ${p.delivery === "local-merge" ? "Authorize isolated task worktrees, local task commits and fast-forward integration into the current branch." : "Direct working-copy edits; failures leave actual edits for inspection. No Git commit or merge."} No push, publication, deployment, unplanned installation or recursive delegation. Generated project context and workflow Markdown are included. Worktrees/tools are not a sandbox.\n\n## Project context\n${p.projectContext}\n`;
491
556
  }
557
+
558
+ const timestamp = (v: unknown) => integer(v, 0, 8640000000000000);
559
+ function decodeWorkflowTiming(v: unknown): WorkflowTiming {
560
+ const o = closed(v, [
561
+ "createdAt",
562
+ "preparedAt",
563
+ "startedAt",
564
+ "stopRequestedAt",
565
+ "closedAt",
566
+ "settledAt",
567
+ "timeoutMs",
568
+ "stopReason",
569
+ ]);
570
+ return {
571
+ createdAt: timestamp(o.createdAt),
572
+ preparedAt: nullable(o.preparedAt, timestamp),
573
+ startedAt: nullable(o.startedAt, timestamp),
574
+ stopRequestedAt: nullable(o.stopRequestedAt, timestamp),
575
+ closedAt: nullable(o.closedAt, timestamp),
576
+ settledAt: nullable(o.settledAt, timestamp),
577
+ timeoutMs: integer(o.timeoutMs, 100, 1200000),
578
+ stopReason: nullable(o.stopReason, (v) => text(v, 32, true)),
579
+ };
580
+ }
581
+ function decodeWorkflowDiagnostics(v: unknown): WorkflowDiagnostics {
582
+ const o = closed(v, ["acceptedAt", "acquiredAt", "settledAt", "owner"]);
583
+ const r = closed(o.owner, [
584
+ "version",
585
+ "build",
586
+ "entry",
587
+ "pid",
588
+ "node",
589
+ "platform",
590
+ "startedAt",
591
+ ]);
592
+ return {
593
+ acceptedAt: timestamp(o.acceptedAt),
594
+ acquiredAt: nullable(o.acquiredAt, timestamp),
595
+ settledAt: nullable(o.settledAt, timestamp),
596
+ owner: {
597
+ version: text(r.version, 128, true),
598
+ build: text(r.build, 64, true),
599
+ entry: text(r.entry, 4096, true),
600
+ pid: integer(r.pid, 1),
601
+ node: text(r.node, 128, true),
602
+ platform: text(r.platform, 32, true),
603
+ startedAt: timestamp(r.startedAt),
604
+ },
605
+ };
606
+ }
607
+ /** Owner observations, never inferred from a parent's batched tool-result timestamp. */
608
+ export function workflowDiagnostics(run: WorkflowRun): string {
609
+ const d = run.diagnostics;
610
+ if (!d) return "Owner timing/runtime observations not recorded.";
611
+ const at = (v: number | null) =>
612
+ v === null ? "not observed" : new Date(v).toISOString();
613
+ return [
614
+ `Owner: Cadence ${d.owner.version} · ${d.owner.platform} · Node ${d.owner.node} · PID ${d.owner.pid} · epoch ${run.epoch}`,
615
+ `Build: ${d.owner.build} · entry: ${d.owner.entry} · owner started: ${at(d.owner.startedAt)}`,
616
+ `Accepted: ${at(d.acceptedAt)} · checkout acquired: ${at(d.acquiredAt)} · settled: ${at(d.settledAt)}`,
617
+ `Checkout wait: ${d.acquiredAt === null ? "still waiting or not acquired" : `${Math.max(0, d.acquiredAt - d.acceptedAt)}ms`}. Runs share an exclusive checkout; questions within one research run may overlap.`,
618
+ ...run.steps.flatMap((s) =>
619
+ s.timing
620
+ ? [
621
+ `${s.id}: preparing ${at(s.timing.createdAt)} · prepared ${at(s.timing.preparedAt)} · spawned ${at(s.timing.startedAt)} · stop ${at(s.timing.stopRequestedAt)} (${s.timing.stopReason ?? "none"}) · direct child closed ${at(s.timing.closedAt)} · settled ${at(s.timing.settledAt)} · total process budget ${s.timing.timeoutMs}ms${s.runtime ? ` · worker SDK ${s.runtime.sdkVersion} · worker hash ${s.runtime.workerHash}` : ""}`,
622
+ ]
623
+ : [],
624
+ ),
625
+ ].join("\n");
626
+ }
@@ -3,12 +3,11 @@ import { opendirSync } from "node:fs";
3
3
  import { hostname } from "node:os";
4
4
  import { dirname, isAbsolute, join, relative, sep } from "node:path";
5
5
  import {
6
- type CheckoutLock,
7
6
  canonicalAmbientRoot,
8
7
  defaultStateHome,
9
8
  resolveWorkspace,
10
- TaskStore,
11
- } from "../task-store.ts";
9
+ } from "../workspace.ts";
10
+ import { type CheckoutLock, CheckoutStore } from "./checkout-lock.ts";
12
11
  import {
13
12
  ContractError,
14
13
  closed,
@@ -247,7 +246,7 @@ export type CoordinationStatus =
247
246
  * task creation, stale reclaim or accepting execution route lives here.
248
247
  */
249
248
  export class ServiceCoordination {
250
- private readonly project?: TaskStore;
249
+ private readonly project?: CheckoutStore;
251
250
  readonly files: PrivateFiles;
252
251
  readonly registryDirectory: string;
253
252
  readonly stateHome: string;
@@ -256,7 +255,7 @@ export class ServiceCoordination {
256
255
  this.project =
257
256
  workspace === null
258
257
  ? undefined
259
- : new TaskStore(resolveWorkspace(workspace).root, stateHome);
258
+ : new CheckoutStore(resolveWorkspace(workspace).root, stateHome);
260
259
  this.stateHome = this.project
261
260
  ? dirname(dirname(this.project.privateRoot))
262
261
  : canonicalAmbientRoot(stateHome ?? defaultStateHome());
@@ -264,7 +263,7 @@ export class ServiceCoordination {
264
263
  this.files = new PrivateFiles(namespace);
265
264
  this.registryDirectory = join(namespace, "service-registry-v1");
266
265
  }
267
- get store(): TaskStore {
266
+ get store(): CheckoutStore {
268
267
  if (!this.project) throw new ContractError("forbidden");
269
268
  return this.project;
270
269
  }
@@ -1079,7 +1078,7 @@ export class ServiceCoordination {
1079
1078
  }
1080
1079
 
1081
1080
  /** Held only by the original owner. Raw-byte AND inode/time identities supplement
1082
- * TaskStore's semantic lock assertion, including whitespace-only interference. */
1081
+ * CheckoutStore's semantic lock assertion, including whitespace-only interference. */
1083
1082
  export class OwnerLease {
1084
1083
  private released = false;
1085
1084
  constructor(
@@ -14,7 +14,8 @@ import {
14
14
  writeFileSync,
15
15
  } from "node:fs";
16
16
  import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
17
- import { retryWindowsFileOperation, safeDirectory } from "../task-store.ts";
17
+ import { retryWindowsFileOperation, safeDirectory } from "../workspace.ts";
18
+
18
19
  import { ContractError, parseWireJson } from "./contracts/core.ts";
19
20
 
20
21
  export const METADATA_BYTES = 16 * 1024;