@xiangyixie/dsh-superagent 0.12.1 → 0.14.1

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.
@@ -21,7 +21,20 @@ import fsp from 'node:fs/promises'
21
21
  import os from 'node:os'
22
22
  import path from 'node:path'
23
23
  import { applyCost, computeCost } from './cost.js'
24
+ import {
25
+ assessRound,
26
+ buildRoundInstruction,
27
+ composeGoalReport,
28
+ fingerprintWorkspace,
29
+ hasMachineChecks,
30
+ normalizeGoalSpec,
31
+ parseVerdict,
32
+ roundGoal,
33
+ runChecks,
34
+ verifierPrompt,
35
+ } from './goal.js'
24
36
  import { extractMemoryBlock } from './memory.js'
37
+ import { extractUserMemoryBlock } from './user-memory.js'
25
38
  import { ACTIVE_STATUSES, GOAL_GUARD_PREFIX, TERMINAL_STATUSES } from './store.js'
26
39
  import { createWorkspaceManager } from './workspace.js'
27
40
 
@@ -32,6 +45,8 @@ const CANCEL_POLL_MS = 1000
32
45
  const CANCEL_ACK_MS = 5000
33
46
  /** How often a live run refreshes its heartbeat in the state file. */
34
47
  const HEARTBEAT_MS = 30 * 1000
48
+ /** How often a running planner attempt is checked against its call budget. */
49
+ const PLANNER_POLL_MS = 250
35
50
  /** A run with no heartbeat for this long is treated as orphaned. */
36
51
  const ORPHAN_MS = 3 * HEARTBEAT_MS
37
52
  /** A child that ignores abort must not hold a cancel call open forever. */
@@ -227,7 +242,21 @@ export function capText(text, maxBytes) {
227
242
  * zero or more subtasks; `id` and `dependsOn` appear only when the planner set them.
228
243
  */
229
244
  export function extractPlan(text) {
230
- if (typeof text !== 'string') return []
245
+ return extractPlanObject(text).subtasks
246
+ }
247
+
248
+ /**
249
+ * Extract the whole planner reply: ordered subtasks plus the questions the
250
+ * planner refuses to answer by guessing.
251
+ *
252
+ * `extractPlan` keeps returning the bare subtask array for callers that only
253
+ * schedule work; the run needs `needsInput` as well, so it uses this form.
254
+ *
255
+ * @param {string} text - raw planner reply, possibly wrapped in prose or fences.
256
+ * @returns {{ subtasks: Array<object>, needsInput: Array<{question: string, options?: string[], reason?: string}>, ambiguities: Array<{phrase: string, why: string, question: string}> }}
257
+ */
258
+ export function extractPlanObject(text) {
259
+ if (typeof text !== 'string') return { subtasks: [], needsInput: [] }
231
260
  const candidates = []
232
261
  for (let start = 0; start < text.length; start++) {
233
262
  if (text[start] !== '{') continue
@@ -261,30 +290,358 @@ export function extractPlan(text) {
261
290
  } catch {
262
291
  continue
263
292
  }
264
- const raw = parsed?.subtasks
265
- if (!Array.isArray(raw)) continue
266
- const subtasks = []
267
- for (const item of raw) {
268
- if (!item || typeof item !== 'object') continue
269
- const prompt = typeof item.prompt === 'string' ? item.prompt.trim() : ''
270
- if (!prompt) continue
271
- const title = typeof item.title === 'string' && item.title.trim()
272
- ? item.title.trim().slice(0, 80)
273
- : prompt.slice(0, 60)
274
- const entry = { title, prompt }
275
- const id = oneLine(item.id, 32)
276
- if (/^[A-Za-z0-9][A-Za-z0-9._:-]{0,31}$/.test(id)) entry.id = id
277
- if (Array.isArray(item.dependsOn)) {
278
- // References are kept verbatim here; whether each one names a real
279
- // subtask (by id or title) is decided once the whole plan is known.
280
- const dependsOn = [...new Set(item.dependsOn.map(ref => oneLine(ref, 80)).filter(Boolean))]
281
- if (dependsOn.length > 0) entry.dependsOn = dependsOn
282
- }
283
- subtasks.push(entry)
284
- }
285
- if (subtasks.length > 0) return subtasks
286
- }
287
- return []
293
+ // Some models wrap the plan in another object (`{"plan":{...}}`) or in a
294
+ // result envelope. Refusing that shape used to send the run into the
295
+ // single-task fallback even though the plan itself was valid.
296
+ for (const plan of planShapes(parsed, 0)) {
297
+ const normalized = planFromParsed(plan)
298
+ if (normalized) return normalized
299
+ }
300
+ }
301
+ // A reply cut off after `"subtasks": [...]` still has a complete, usable
302
+ // array; recover it instead of discarding a real plan over trailing prose.
303
+ const salvaged = salvageSubtaskArray(text)
304
+ if (salvaged) {
305
+ const normalized = planFromParsed({ subtasks: salvaged })
306
+ if (normalized) return { ...normalized, repaired: 'salvaged-subtasks' }
307
+ }
308
+ return { subtasks: [], needsInput: [], ambiguities: [] }
309
+ }
310
+
311
+ /** Every object in a parsed reply that could itself be the plan. */
312
+ function planShapes(value, depth) {
313
+ if (!value || typeof value !== 'object' || Array.isArray(value) || depth > 4) return []
314
+ const shapes = [value]
315
+ for (const child of Object.values(value)) {
316
+ if (child && typeof child === 'object' && !Array.isArray(child)) {
317
+ shapes.push(...planShapes(child, depth + 1))
318
+ }
319
+ }
320
+ return shapes
321
+ }
322
+
323
+ /** Turn one object into a plan when it carries at least one usable field. */
324
+ function planFromParsed(parsed) {
325
+ const raw = parsed?.subtasks
326
+ if (!Array.isArray(raw)) return null
327
+ const subtasks = []
328
+ for (const item of raw) {
329
+ if (!item || typeof item !== 'object') continue
330
+ const prompt = typeof item.prompt === 'string' ? item.prompt.trim() : ''
331
+ if (!prompt) continue
332
+ const title = typeof item.title === 'string' && item.title.trim()
333
+ ? item.title.trim().slice(0, 80)
334
+ : prompt.slice(0, 60)
335
+ const entry = { title, prompt }
336
+ const id = oneLine(item.id, 32)
337
+ if (/^[A-Za-z0-9][A-Za-z0-9._:-]{0,31}$/.test(id)) entry.id = id
338
+ if (Array.isArray(item.dependsOn)) {
339
+ // References are kept verbatim here; whether each one names a real
340
+ // subtask (by id or title) is decided once the whole plan is known.
341
+ const dependsOn = [...new Set(item.dependsOn.map(ref => oneLine(ref, 80)).filter(Boolean))]
342
+ if (dependsOn.length > 0) entry.dependsOn = dependsOn
343
+ }
344
+ const assumptions = stringList(item.assumptions, { maxItems: 6, maxChars: 300 })
345
+ if (assumptions.length > 0) entry.assumptions = assumptions
346
+ const requires = capabilityList(item.requires)
347
+ if (requires.length > 0) entry.requires = requires
348
+ const deliverables = normalizeDeliverables(item.deliverables)
349
+ if (deliverables.length > 0) entry.deliverables = deliverables
350
+ subtasks.push(entry)
351
+ }
352
+ const needsInput = normalizeNeedsInput(parsed?.needsInput)
353
+ const ambiguities = normalizeAmbiguities(parsed?.ambiguities)
354
+ // A planner that stops to ask may return no subtasks; its questions are
355
+ // still a valid reply and must not be mistaken for an unparsable plan.
356
+ if (subtasks.length > 0 || needsInput.length > 0 || ambiguities.length > 0) {
357
+ return { subtasks, needsInput, ambiguities }
358
+ }
359
+ return null
360
+ }
361
+
362
+ /** Recover a complete `"subtasks": [...]` array from an otherwise broken reply. */
363
+ function salvageSubtaskArray(text) {
364
+ const key = text.search(/"subtasks"\s*:/)
365
+ if (key < 0) return null
366
+ const open = text.indexOf('[', key)
367
+ if (open < 0) return null
368
+ let depth = 0
369
+ let inString = false
370
+ let escaped = false
371
+ for (let index = open; index < text.length; index++) {
372
+ const char = text[index]
373
+ if (inString) {
374
+ if (escaped) escaped = false
375
+ else if (char === '\\') escaped = true
376
+ else if (char === '"') inString = false
377
+ continue
378
+ }
379
+ if (char === '"') inString = true
380
+ else if (char === '[') depth++
381
+ else if (char === ']') {
382
+ depth--
383
+ if (depth === 0) {
384
+ try {
385
+ const value = JSON.parse(text.slice(open, index + 1))
386
+ return Array.isArray(value) ? value : null
387
+ } catch {
388
+ return null
389
+ }
390
+ }
391
+ }
392
+ }
393
+ return null
394
+ }
395
+
396
+ /** Deliverable kinds a planner may declare, and the aliases models emit. */
397
+ const DELIVERABLE_KIND_ALIASES = {
398
+ screenshot: 'image',
399
+ image: 'image',
400
+ png: 'image',
401
+ jpg: 'image',
402
+ jpeg: 'image',
403
+ photo: 'image',
404
+ picture: 'image',
405
+ report: 'text',
406
+ document: 'text',
407
+ doc: 'text',
408
+ markdown: 'text',
409
+ md: 'text',
410
+ text: 'text',
411
+ txt: 'text',
412
+ file: 'file',
413
+ data: 'file',
414
+ artifact: 'file',
415
+ }
416
+
417
+ /** Normalize `deliverables` entries into `{ path, kind, minBytes }`, bounded and deduped. */
418
+ function normalizeDeliverables(value) {
419
+ if (!Array.isArray(value)) return []
420
+ const out = []
421
+ for (const item of value) {
422
+ const raw = typeof item === 'string' ? { path: item } : item
423
+ if (!raw || typeof raw !== 'object') continue
424
+ const filePath = oneLine(raw.path ?? raw.file ?? raw.name, 300)
425
+ if (!filePath || out.some(entry => entry.path === filePath)) continue
426
+ const declared = oneLine(raw.kind ?? raw.type, 24).toLowerCase()
427
+ const kind = DELIVERABLE_KIND_ALIASES[declared]
428
+ ?? (/^[a-z][a-z0-9._-]{0,23}$/.test(declared) ? declared : 'file')
429
+ const minBytes = Number.isFinite(Number(raw.minBytes))
430
+ ? Math.max(1, Math.trunc(Number(raw.minBytes)))
431
+ : 1
432
+ out.push({ path: filePath, kind, minBytes })
433
+ if (out.length >= 8) break
434
+ }
435
+ return out
436
+ }
437
+
438
+ const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
439
+
440
+ /**
441
+ * Inspect one declared deliverable from its size and leading bytes.
442
+ *
443
+ * This is deliberately narrow: it only runs for subtasks that declared a
444
+ * deliverable, and it judges what the declaration claims. A screenshot must be
445
+ * a real image, not a 1x1 or a text file renamed to .png; a report must be
446
+ * text. Anything the check cannot judge is `unverified`, never `verified`.
447
+ *
448
+ * @param {{ path: string, kind: string, bytes: number, head: Buffer }} input
449
+ * @returns {{ status: 'verified'|'failed'|'unverified', code?: string, reason?: string }}
450
+ */
451
+ export function inspectDeliverable({ path: filePath, kind, bytes, head }) {
452
+ const where = oneLine(filePath, 200) || 'declared deliverable'
453
+ const size = Number(bytes)
454
+ if (!Number.isFinite(size) || size <= 0) {
455
+ return { status: 'failed', code: 'empty', reason: `declared deliverable is empty: ${where}` }
456
+ }
457
+ const buffer = Buffer.isBuffer(head) ? head : Buffer.alloc(0)
458
+ const normalized = DELIVERABLE_KIND_ALIASES[oneLine(kind, 24).toLowerCase()] ?? kind
459
+ if (normalized === 'image') {
460
+ const png = pngDimensions(buffer)
461
+ if (png) {
462
+ if (png.width < 32 || png.height < 32) {
463
+ return {
464
+ status: 'failed',
465
+ code: 'placeholder',
466
+ reason: `declared image is a ${png.width}x${png.height} placeholder, not a real capture: ${where}`,
467
+ }
468
+ }
469
+ return { status: 'verified' }
470
+ }
471
+ if (isJpeg(buffer) || isGif(buffer) || isWebp(buffer)) {
472
+ // A real capture or export is never this small; a 1x1 JPEG is ~300-600 B.
473
+ if (size < 1024) {
474
+ return {
475
+ status: 'failed',
476
+ code: 'placeholder',
477
+ reason: `declared image is only ${size} bytes, too small to be a real capture: ${where}`,
478
+ }
479
+ }
480
+ return { status: 'verified' }
481
+ }
482
+ return {
483
+ status: 'failed',
484
+ code: 'type',
485
+ reason: `declared image is not a PNG/JPEG/GIF/WebP file: ${where}`,
486
+ }
487
+ }
488
+ if (normalized === 'text') {
489
+ if (buffer.includes(0)) {
490
+ return { status: 'failed', code: 'type', reason: `declared report is binary, not text: ${where}` }
491
+ }
492
+ if (buffer.toString('utf8').trim().length === 0) {
493
+ return { status: 'failed', code: 'empty', reason: `declared report has no readable content: ${where}` }
494
+ }
495
+ return { status: 'verified' }
496
+ }
497
+ if (normalized === 'file') return { status: 'verified' }
498
+ return {
499
+ status: 'unverified',
500
+ reason: `cannot check a deliverable of kind "${kind}"; verify it yourself: ${where}`,
501
+ }
502
+ }
503
+
504
+ /** Width and height from a PNG header, or null when this is not a PNG. */
505
+ function pngDimensions(buffer) {
506
+ if (buffer.length < 24 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return null
507
+ if (buffer.subarray(12, 16).toString('latin1') !== 'IHDR') return null
508
+ return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
509
+ }
510
+
511
+ function isJpeg(buffer) {
512
+ return buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff
513
+ }
514
+
515
+ function isGif(buffer) {
516
+ return buffer.length >= 6 && buffer.subarray(0, 3).toString('latin1') === 'GIF'
517
+ }
518
+
519
+ function isWebp(buffer) {
520
+ return buffer.length >= 12
521
+ && buffer.subarray(0, 4).toString('latin1') === 'RIFF'
522
+ && buffer.subarray(8, 12).toString('latin1') === 'WEBP'
523
+ }
524
+
525
+ /** Keep a planner-declared list of strings, de-duplicated and bounded. */
526
+ function stringList(value, { maxItems, maxChars }) {
527
+ if (!Array.isArray(value)) return []
528
+ const out = []
529
+ for (const item of value) {
530
+ if (typeof item !== 'string') continue
531
+ const text = capChars(oneLine(item, maxChars), maxChars)
532
+ if (text && !out.includes(text)) out.push(text)
533
+ if (out.length >= maxItems) break
534
+ }
535
+ return out
536
+ }
537
+
538
+ /** Normalize `requires` into lowercase capability tags. */
539
+ function capabilityList(value) {
540
+ if (!Array.isArray(value)) return []
541
+ const out = []
542
+ for (const item of value) {
543
+ if (typeof item !== 'string') continue
544
+ const tag = oneLine(item, 40).toLowerCase().replace(/\s+/g, '.')
545
+ if (/^[a-z][a-z0-9._-]{0,39}$/.test(tag) && !out.includes(tag)) out.push(tag)
546
+ if (out.length >= 8) break
547
+ }
548
+ return out
549
+ }
550
+
551
+ /** Normalize top-level `needsInput` entries, accepting plain strings too. */
552
+ function normalizeNeedsInput(value) {
553
+ if (!Array.isArray(value)) return []
554
+ const out = []
555
+ const seen = new Set()
556
+ for (const item of value) {
557
+ const question = oneLine(typeof item === 'string' ? item : item?.question, 400)
558
+ if (!question || seen.has(question)) continue
559
+ seen.add(question)
560
+ const options = Array.isArray(item?.options)
561
+ ? stringList(item.options, { maxItems: 6, maxChars: 120 })
562
+ : []
563
+ const reason = oneLine(item?.reason, 300)
564
+ out.push({ question, ...(options.length > 0 ? { options } : {}), ...(reason ? { reason } : {}) })
565
+ if (out.length >= 6) break
566
+ }
567
+ return out
568
+ }
569
+
570
+ /**
571
+ * How each capability tag a planner may emit is recognized in the host's tool
572
+ * list. Matching is by tool name: descriptions mention many tools and would
573
+ * make every capability look available.
574
+ *
575
+ * `shell` also satisfies `git` and `gh` because both are command-line tools;
576
+ * `gui` and `desktop` share a matcher because hosts name the desktop tool
577
+ * differently and a subtask needing one is equally stuck without it.
578
+ */
579
+ const CAPABILITY_MATCHERS = {
580
+ shell: /^(bash|shell|sh|zsh|fish|terminal|run_command|exec_command|powershell|pwsh|cmd)([_-]|$)/i,
581
+ 'net.http': /^(web_search|web_fetch|http|https|fetch|curl|url)([_-]|$)/i,
582
+ browser: /browser/i,
583
+ gui: /(^|[_-])(cua|computer|desktop|gui)([_-]|$)/i,
584
+ desktop: /(^|[_-])(cua|computer|desktop|gui)([_-]|$)/i,
585
+ git: /^git([_-]|$)/i,
586
+ gh: /^(gh|github)([_-]|$)/i,
587
+ }
588
+
589
+ /** Capability names the planner is told to use, exported for the prompt test. */
590
+ export const KNOWN_CAPABILITIES = Object.keys(CAPABILITY_MATCHERS)
591
+
592
+ const CAPABILITY_ALIASES = {
593
+ http: 'net.http',
594
+ net: 'net.http',
595
+ web: 'net.http',
596
+ terminal: 'shell',
597
+ bash: 'shell',
598
+ computer: 'gui',
599
+ cua: 'gui',
600
+ browseruse: 'browser',
601
+ github: 'gh',
602
+ }
603
+
604
+ /** What the user can enable when a capability is missing. */
605
+ export function capabilitySuggestion(capability) {
606
+ switch (capability) {
607
+ case 'shell': return 'enable a shell/terminal tool in this session'
608
+ case 'net.http': return 'enable a web or HTTP tool in this session'
609
+ case 'browser': return 'enable a browser-control plugin in this session'
610
+ case 'gui':
611
+ case 'desktop': return 'enable a desktop/computer-use plugin in this session'
612
+ case 'git': return 'enable a shell or git tool in this session'
613
+ case 'gh': return 'enable a shell or GitHub tool in this session'
614
+ default: return `no tool in this session provides "${capability}"; remove it or name a capability the host offers`
615
+ }
616
+ }
617
+
618
+ /**
619
+ * Report which of a subtask's declared capabilities the given tool names do not
620
+ * cover. An empty `toolNames` array is a known-empty inventory, not "unknown":
621
+ * the caller passes null when the host cannot list its tools at all.
622
+ *
623
+ * @param {string[]} requires - capability tags from the plan.
624
+ * @param {string[]} toolNames - tool names available to the session.
625
+ * @returns {string[]} missing capability tags, in declaration order.
626
+ */
627
+ export function capabilityGaps(requires, toolNames) {
628
+ const names = Array.isArray(toolNames)
629
+ ? toolNames.filter(name => typeof name === 'string' && name.length > 0)
630
+ : []
631
+ const has = capability => names.some(name => CAPABILITY_MATCHERS[capability]?.test(name))
632
+ const gaps = []
633
+ for (const raw of requires ?? []) {
634
+ const declared = oneLine(raw, 40).toLowerCase()
635
+ const capability = CAPABILITY_ALIASES[declared] ?? declared
636
+ if (!capability || gaps.includes(capability)) continue
637
+ const covered = capability === 'git' || capability === 'gh'
638
+ ? has('shell') || has(capability)
639
+ : CAPABILITY_MATCHERS[capability]
640
+ ? has(capability)
641
+ : false
642
+ if (!covered) gaps.push(capability)
643
+ }
644
+ return gaps
288
645
  }
289
646
 
290
647
  /** Collapse arbitrary text into at most `maxChars` characters. */
@@ -463,6 +820,56 @@ function findCycle(keys, edges) {
463
820
  }
464
821
 
465
822
  /** Planner prompt for one goal. */
823
+ /**
824
+ * Normalize the planner's ambiguity list. Entries without an exact phrase and
825
+ * a question are dropped: a vague finding cannot become a question for the user.
826
+ */
827
+ export function normalizeAmbiguities(value) {
828
+ if (!Array.isArray(value)) return []
829
+ const out = []
830
+ const seen = new Set()
831
+ for (const item of value) {
832
+ const phrase = oneLine(item?.phrase, 200)
833
+ const question = oneLine(item?.question, 400)
834
+ if (!phrase || !question || seen.has(phrase)) continue
835
+ seen.add(phrase)
836
+ out.push({ phrase, why: oneLine(item?.why, 300), question })
837
+ if (out.length >= 8) break
838
+ }
839
+ return out
840
+ }
841
+
842
+ /**
843
+ * Fold audit questions into the plan's needsInput. A finding the planner
844
+ * already asked about (the phrase or the same question appears there) is left
845
+ * alone; every other finding is appended, so an odd phrase cannot be silently
846
+ * dropped just because the planner normalized it away.
847
+ *
848
+ * @param {Array<object>} needsInput - planner's own questions.
849
+ * @param {Array<object>} ambiguities - audit findings.
850
+ * @returns {Array<object>} merged questions, bounded.
851
+ */
852
+ export function mergeAuditNeedsInput(needsInput, ambiguities = []) {
853
+ const merged = [...(needsInput ?? [])]
854
+ const fingerprint = value => String(value ?? '').replace(/\s+/g, '').toLowerCase()
855
+ for (const finding of ambiguities) {
856
+ const phrase = fingerprint(finding.phrase)
857
+ const question = fingerprint(finding.question)
858
+ const already = merged.some(item => {
859
+ const haystack = fingerprint([item.question, item.reason, ...(item.options ?? [])].join(' '))
860
+ return (phrase && haystack.includes(phrase)) || (question && fingerprint(item.question) === question)
861
+ })
862
+ if (already) continue
863
+ merged.push({
864
+ question: finding.question,
865
+ reason: finding.why || `the goal phrase "${finding.phrase}" is ambiguous`,
866
+ source: 'ambiguity-audit',
867
+ })
868
+ if (merged.length >= 8) break
869
+ }
870
+ return merged
871
+ }
872
+
466
873
  function plannerPrompt(goal, maxSubtasks, context, carried = []) {
467
874
  return [
468
875
  'You are the planner for a long-horizon autonomous run.',
@@ -483,19 +890,89 @@ function plannerPrompt(goal, maxSubtasks, context, carried = []) {
483
890
  : []),
484
891
  `Decompose the goal into at most ${maxSubtasks} subtasks. Independent subtasks run in parallel; when one needs`,
485
892
  'another subtask\'s output, say so with "dependsOn" instead of duplicating that work.',
486
- 'Each subtask is executed by a separate agent that sees only the prompt you write for it, plus the reports of',
487
- 'the subtasks it depends on.',
893
+ 'Workers see the overall goal but nothing else from your output. Each prompt must state only that subtask\'s',
894
+ 'work and the artifacts it depends on; do not repeat the overall goal in it.',
488
895
  '',
489
896
  'Return ONLY a JSON object, with no prose and no code fences, in exactly this shape:',
490
- '{"subtasks":[{"id":"w1","title":"short title","prompt":"complete self-contained instruction","dependsOn":["w1"]}]}',
897
+ '{"ambiguities":[{"phrase":"exact words from the goal","why":"...","question":"..."}],'
898
+ + '"subtasks":[{"id":"w1","title":"short title","prompt":"instruction for this subtask only",'
899
+ + '"dependsOn":["w1"],"requires":["shell"],"assumptions":["..."],'
900
+ + '"deliverables":[{"path":"reports/summary.md","kind":"text"}]}],'
901
+ + '"needsInput":[{"question":"...","reason":"..."}]}',
491
902
  '',
492
903
  'Rules:',
904
+ '- Answer from this prompt alone. Do not call tools, read files, or inspect the environment before replying:',
905
+ ' this step must not touch the workspace, and a tool call here produces no plan at all.',
906
+ '- Fill "ambiguities" first, before planning. Quote every phrase you cannot map to a concrete object,',
907
+ ' including unusual modifiers, possible typos, and unidentified referents. Use [] only when nothing is unclear.',
493
908
  `- Use 2 to ${maxSubtasks} subtasks; use 1 only when the goal truly cannot be split.`,
494
909
  '- Give every subtask a unique id such as w1, w2; ids are what dependsOn refers to.',
495
910
  '- Add "dependsOn" only for real ordering; omit it otherwise, because a dependency serializes that part of the work.',
496
911
  '- Never create a dependency cycle (w1 -> w2 -> w1): a plan with one is rejected before any work starts.',
497
- '- Every prompt must restate the context it needs; workers cannot see the goal text or unrelated subtasks.',
498
912
  '- Prefer concrete research, construction, or verification work over vague summaries.',
913
+ '',
914
+ 'Ambiguity is not for you to fill in:',
915
+ '- First find every referent the goal leaves open: workspace, project, repository, platform, account, file,',
916
+ ' version, output format, or a qualifier that may be a typo, shorthand, or stray modifier.',
917
+ '- Quote the exact wording that is unclear. A phrase you cannot map to a concrete object is not context to',
918
+ ' repeat: it goes into "needsInput" instead of being copied into a prompt next to a noun.',
919
+ '- Never silently choose one. If a worker can settle it without the user, add a clarification subtask that',
920
+ ' runs first (for example, one command that lists the candidates) and make the others depend on it.',
921
+ '- A question only the user can answer goes into "needsInput". Do not create a subtask whose only job is to',
922
+ ' ask it again.',
923
+ '- Every other subtask must produce work product. When it depends on an unanswered question, proceed under an',
924
+ ' assumption listed in "assumptions" and put the question in "needsInput".',
925
+ '- Plan the work the user asked for, not only the questions around it. Clarification subtasks are additions;',
926
+ ' they never replace the redesign, submission, or review work the goal itself requires.',
927
+ '- Anything the plan cannot resolve goes into "needsInput" as one concrete question, and is not guessed at.',
928
+ '- Every assumption you do make must be listed in that subtask\'s "assumptions" array. Any name, path, norm,',
929
+ ' version, or output format the user did not state must be marked there; it must never appear in a prompt as',
930
+ ' if it were a requirement.',
931
+ '- A prompt may carry a phrase from the goal only after you have either resolved it to a concrete object or',
932
+ ' listed what you take it to mean in "assumptions". An unresolved phrase is a "needsInput" question.',
933
+ '- If a phrase looks unusual, unidiomatic, or out of place for the sentence (a possible typo, speech-to-text',
934
+ ' slip, or stray modifier), quote it in "needsInput"; do not smooth it into fluent wording and do not drop it.',
935
+ '- Before returning, re-read the goal phrase by phrase. Each content phrase must be used by a subtask,',
936
+ ' interpreted in an "assumptions" entry, or asked about in "needsInput". A phrase with none of these is an',
937
+ ' omission: ask about it now.',
938
+ '',
939
+ 'Capabilities:',
940
+ `- "requires" lists the host capabilities the subtask truly needs: ${KNOWN_CAPABILITIES.join(', ')}.`,
941
+ ' shell = run commands; net.http = fetch URLs or search the web; browser = drive a logged-in browser;',
942
+ ' gui/desktop = operate desktop apps and windows, including DCC tools and game engines; git = git tools;',
943
+ ' gh = GitHub tools. Shell also counts for git and gh.',
944
+ '- A subtask that only reads or writes files lists no capability; never list one the work does not use.',
945
+ '- The host checks this list before any worker starts, so an over-broad list stops work that could have run.',
946
+ '',
947
+ 'Deliverables:',
948
+ '- Add "deliverables" only when the subtask must hand back a file the user can open: a report, document,',
949
+ ' image, or screenshot. Give each path relative to the worker\'s own working directory and a kind: text,',
950
+ ' image, or file. Never write an absolute path, a checkout path, or a "current working directory" claim:',
951
+ ' workers run in their own checkout, which you do not know and must not guess.',
952
+ '- Omit the field entirely for subtasks that only return findings in their report.',
953
+ '- Never declare a deliverable the goal did not ask for, and never name an existing file the subtask only',
954
+ ' reads. A declared path is a promise the host checks: missing, empty, or wrong-type files fail the subtask.',
955
+ '- A screenshot or image must be a real capture or export. A placeholder (1x1, a blank canvas, a text file',
956
+ ' renamed to .png) does not satisfy the check and must never be produced just to pass it.',
957
+ ].join('\n')
958
+ }
959
+
960
+ /**
961
+ * Second planner attempt after an unusable reply. The schema is the same; the
962
+ * difference is that the broken output is quoted back and tool use is banned,
963
+ * because a planner that spends its turn on tools returns no plan at all.
964
+ */
965
+ function plannerRepairPrompt(goal, maxSubtasks, context, carried, previous) {
966
+ return [
967
+ plannerPrompt(goal, maxSubtasks, context, carried),
968
+ '',
969
+ '## Repair round',
970
+ 'Your previous reply could not be parsed as that JSON object. It began:',
971
+ '<<<',
972
+ capChars(String(previous ?? '').trim() || '(empty reply)', 1200),
973
+ '>>>',
974
+ 'Reply again with exactly one JSON object in the shape above. No prose, no code fences, no tool calls.',
975
+ 'If something is missing, put the question in "needsInput" instead of leaving it out or inventing it.',
499
976
  ].join('\n')
500
977
  }
501
978
 
@@ -508,20 +985,32 @@ function workerPrompt(run, subtask, workspace = null, carried = []) {
508
985
  'You are one worker in a long-horizon autonomous run. Do not ask the user questions and do not wait for input.',
509
986
  '',
510
987
  'Overall goal:',
511
- run.goal,
988
+ roundGoal(run),
512
989
  '',
513
990
  `Your assigned subtask (${subtask.title}):`,
514
991
  subtask.prompt,
515
992
  '',
993
+ ...(subtask.assumptions?.length > 0
994
+ ? [
995
+ 'Assumptions the planner made for this subtask (not facts from the user):',
996
+ ...subtask.assumptions.map(assumption => `- ${assumption}`),
997
+ 'If one of these is wrong, say so in your report instead of silently choosing another interpretation.',
998
+ '',
999
+ ]
1000
+ : []),
516
1001
  ...(workspace
517
1002
  ? [
518
1003
  'Isolated working directory:',
519
1004
  `- Your working directory is ${workspace.dir}`,
1005
+ `- Relative paths in your tool calls, and every path you write in a deliverable, resolve against`,
1006
+ ` ${workspace.dir}. Write files there, not in ${workspace.base}.`,
520
1007
  `- It is a private git worktree on branch ${workspace.branch} of ${workspace.base}. Other workers are`,
521
1008
  ' editing the same repository at the same time in their own worktrees, so read and write files ONLY',
522
1009
  ' inside your directory. Do not edit the main checkout or another worker\'s path.',
523
1010
  '- Do not create or remove worktrees, do not switch or delete branches, do not commit, merge, rebase, or',
524
1011
  ' push. The run merges your branch back when you finish; leaving the files changed is enough.',
1012
+ '- The host file sandbox only allows writes inside this directory. If a write is still denied, report the',
1013
+ ' exact path and error instead of changing permissions or retrying elsewhere.',
525
1014
  '',
526
1015
  ]
527
1016
  : []),
@@ -568,7 +1057,7 @@ function directPrompt(run, carried = []) {
568
1057
  'You are completing one task directly in an autonomous run. Do not ask the user questions and do not wait for input.',
569
1058
  '',
570
1059
  'Task:',
571
- run.goal,
1060
+ roundGoal(run),
572
1061
  '',
573
1062
  ...instructionLines(carried),
574
1063
  ...(run.recovery
@@ -598,7 +1087,7 @@ function directPrompt(run, carried = []) {
598
1087
  }
599
1088
 
600
1089
  /** Aggregator prompt over completed subtask reports. */
601
- function aggregatorPrompt(run, completed, context, carried = []) {
1090
+ function aggregatorPrompt(run, completed, context, carried = [], wantUserMemory = false) {
602
1091
  const sections = completed.map(subtask => [
603
1092
  `### ${subtask.title}`,
604
1093
  capText(subtask.result ?? '', 8000),
@@ -611,7 +1100,7 @@ function aggregatorPrompt(run, completed, context, carried = []) {
611
1100
  'You are the aggregator of a long-horizon autonomous run.',
612
1101
  '',
613
1102
  'Goal:',
614
- run.goal,
1103
+ roundGoal(run),
615
1104
  '',
616
1105
  ...(context
617
1106
  ? [
@@ -627,10 +1116,10 @@ function aggregatorPrompt(run, completed, context, carried = []) {
627
1116
  ...(unfinished.length > 0
628
1117
  ? [
629
1118
  'Subtasks that delivered no report:',
630
- ...unfinished.map(subtask => `- ${subtask.title}: ${subtask.status}`
631
- + `${subtask.skippedReason ? ` — ${subtask.skippedReason}` : subtask.error ? ` — ${subtask.error}` : ''}`),
1119
+ ...unfinished.map(subtask => `- ${subtask.title}: ${subtask.status}${missingReason(subtask)}`),
632
1120
  '',
633
- 'Say in the report which of these are missing and why; do not present a skipped subtask as finished work.',
1121
+ 'Say in the report which of these are missing and why; do not present a skipped, blocked, or failed',
1122
+ 'subtask as finished work.',
634
1123
  '',
635
1124
  ]
636
1125
  : []),
@@ -660,6 +1149,24 @@ function aggregatorPrompt(run, completed, context, carried = []) {
660
1149
  '- If a note above is now wrong, emit an entry with the same key and corrected text. To drop one entirely, use',
661
1150
  ' {"key":"the-key","status":"retracted"}.',
662
1151
  '- If nothing is worth keeping, emit {"entries":[]}.',
1152
+ ...(wantUserMemory
1153
+ ? [
1154
+ '',
1155
+ 'Then append exactly one fenced `user-memory` block: durable knowledge about this user that a later, unrelated',
1156
+ 'task should inherit. It is stripped from the report and stored apart from the run notebook:',
1157
+ '```user-memory',
1158
+ '{"facts":[{"key":"stack","text":"one durable fact"}],'
1159
+ + '"preferences":[{"key":"reporting","text":"how this user wants work done"}],'
1160
+ + '"decisions":[{"key":"choose-db","choice":"what was chosen","rejected":"what was given up",'
1161
+ + '"reason":"why","rollback":"how to undo it"}]}',
1162
+ '```',
1163
+ '- `facts` are stable context (stack, environment, conventions); `preferences` are what the user likes or',
1164
+ ' dislikes about how work is delivered; a `decision` must have a choice and a reason, and should name what',
1165
+ ' was rejected and how to roll it back so a later run can revisit it instead of guessing.',
1166
+ '- Record only what survives this task. Never record credentials, personal contact details, or a copy of the',
1167
+ ' report. Emit {"facts":[],"preferences":[],"decisions":[]} when nothing is durable.',
1168
+ ]
1169
+ : []),
663
1170
  ].join('\n')
664
1171
  }
665
1172
 
@@ -675,17 +1182,25 @@ function deterministicJoin(run) {
675
1182
  if (unfinished.length > 0) {
676
1183
  parts.push('## Not delivered', '')
677
1184
  for (const subtask of unfinished) {
678
- parts.push(`- ${subtask.title}: ${subtask.status}`
679
- + `${subtask.skippedReason ? ` — ${subtask.skippedReason}` : subtask.error ? ` — ${subtask.error}` : ''}`)
1185
+ parts.push(`- ${subtask.title}: ${subtask.status}${missingReason(subtask)}`)
680
1186
  }
681
1187
  }
682
1188
  return parts.join('\n').trim()
683
1189
  }
684
1190
 
1191
+ /** One line explaining why a subtask delivered nothing. */
1192
+ function missingReason(subtask) {
1193
+ if (subtask.blockedReason) return ` — ${subtask.blockedReason}`
1194
+ if (subtask.skippedReason) return ` — ${subtask.skippedReason}`
1195
+ if (subtask.unverifiedReason) return ` — unverified: ${subtask.unverifiedReason}`
1196
+ if (subtask.error) return ` — ${subtask.error}`
1197
+ return ''
1198
+ }
1199
+
685
1200
  /**
686
- * Mark every subtask whose dependency failed or was skipped as skipped, in
687
- * graph order, so one dead subtask cannot leave the tasks behind it queued
688
- * forever and cannot be mistaken for success.
1201
+ * Mark every subtask whose dependency failed, was skipped, or is blocked by a
1202
+ * missing capability as skipped, in graph order, so one dead subtask cannot
1203
+ * leave the tasks behind it queued forever and cannot be mistaken for success.
689
1204
  *
690
1205
  * @param {object} run - live run record.
691
1206
  * @param {Map<string, object>} byKey - subtask lookup by key.
@@ -699,13 +1214,19 @@ function cascadeSkips(run, byKey) {
699
1214
  if (subtask.status !== 'pending' && subtask.status !== 'waiting') continue
700
1215
  const blocker = (subtask.dependsOn ?? [])
701
1216
  .map(key => byKey.get(key))
702
- .find(dependency => dependency && (dependency.status === 'failed' || dependency.status === 'skipped'))
1217
+ .find(dependency => dependency
1218
+ && (dependency.status === 'failed' || dependency.status === 'skipped'
1219
+ || dependency.status === 'blocked' || dependency.status === 'unverified'))
703
1220
  if (!blocker) continue
704
1221
  subtask.status = 'skipped'
705
1222
  subtask.skipKind = 'upstream'
706
1223
  subtask.skippedReason = blocker.status === 'failed'
707
1224
  ? `not started because ${blocker.key} failed`
708
- : `not started because ${blocker.key} was skipped`
1225
+ : blocker.status === 'blocked'
1226
+ ? `not started because ${blocker.key} was blocked by a missing capability`
1227
+ : blocker.status === 'unverified'
1228
+ ? `not started because ${blocker.key}'s deliverable could not be verified`
1229
+ : `not started because ${blocker.key} was skipped`
709
1230
  subtask.waitingOn = []
710
1231
  round = true
711
1232
  changed = true
@@ -778,8 +1299,12 @@ function ensureCounters(run) {
778
1299
  * @param {(childId: string) => Promise<object | null>} deps.readUsage
779
1300
  * @param {(run: object) => object | void | Promise<object | void>} deps.notify - wake the owning session once.
780
1301
  * @param {object | null} [deps.memory] - cross-run notebook from `createMemory`; null disables it.
1302
+ * @param {object | null} [deps.userMemory] - user-level profile from `createUserMemory`; null keeps it off.
781
1303
  * @param {object | null} [deps.guard] - worker safety guard from `createGuard`; its
782
1304
  * snapshot is attached to each run record and its events to the report.
1305
+ * @param {(parent: object) => string[] | null | Promise<string[] | null>} [deps.toolInventory] -
1306
+ * names of the tools the calling session can use. Null means the host cannot
1307
+ * list them, in which case capability preflight is skipped rather than guessed.
783
1308
  * @param {(message: string) => void} [deps.log]
784
1309
  * @param {() => number} [deps.now]
785
1310
  * @param {(ms: number) => Promise<void>} [deps.sleep]
@@ -794,12 +1319,15 @@ export function createOrchestrator(deps) {
794
1319
  readUsage,
795
1320
  notify,
796
1321
  memory = null,
1322
+ userMemory = null,
797
1323
  workspace = null,
798
1324
  guard = null,
799
1325
  audit = null,
800
1326
  steerChild = null,
801
1327
  inspectChild = null,
802
1328
  watchChild = null,
1329
+ toolInventory = null,
1330
+ cwd = process.cwd(),
803
1331
  log = () => {},
804
1332
  now = () => Date.now(),
805
1333
  sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
@@ -829,19 +1357,38 @@ export function createOrchestrator(deps) {
829
1357
  return clamp(config.maxActiveRuns ?? 2, 1, 8)
830
1358
  }
831
1359
 
832
- /** Cached manager; a test may inject one instead of spawning real git. */
1360
+ /**
1361
+ * The host's sandbox boundary: the session cwd a delegated child inherits and
1362
+ * `workspace-write` takes as its writable root. It is not `workspaceRoot`; the
1363
+ * host may have been started in a different directory.
1364
+ *
1365
+ * @param {object | null} parent - the agent that asked for this run.
1366
+ * @returns {string} absolute directory the sandbox allows writes under.
1367
+ */
1368
+ function sessionCwd(parent) {
1369
+ const cwd = parent?.session?.header?.cwd
1370
+ const value = typeof cwd === 'string' ? cwd.trim() : ''
1371
+ return path.resolve(value || process.cwd())
1372
+ }
1373
+
1374
+ /** Cached managers, keyed by boundary; a test may inject one instead of spawning real git. */
833
1375
  let workspaceManagerRef = workspace
834
- function workspaceManager() {
1376
+ const workspaceManagers = new Map()
1377
+ function workspaceManager(boundary) {
835
1378
  if (workspaceManagerRef) return workspaceManagerRef
836
- const stateRoot = typeof store.root === 'string' ? store.root : path.join(os.tmpdir(), 'dsh-superagent')
837
- const configured = typeof config.workspaceRoot === 'string' ? config.workspaceRoot.trim() : ''
838
- workspaceManagerRef = createWorkspaceManager({
839
- root: path.join(stateRoot, 'workspaces'),
840
- baseDir: configured ? path.resolve(configured) : process.cwd(),
841
- log,
842
- sleep,
843
- })
844
- return workspaceManagerRef
1379
+ const key = boundary ?? process.cwd()
1380
+ if (!workspaceManagers.has(key)) {
1381
+ const configured = typeof config.workspaceRoot === 'string' ? config.workspaceRoot.trim() : ''
1382
+ // A checkout outside the boundary gets every write denied, so the pool
1383
+ // is anchored there even when `workspaceRoot` points somewhere else.
1384
+ workspaceManagers.set(key, createWorkspaceManager({
1385
+ baseDir: configured ? path.resolve(configured) : key,
1386
+ boundary: key,
1387
+ log,
1388
+ sleep,
1389
+ }))
1390
+ }
1391
+ return workspaceManagers.get(key)
845
1392
  }
846
1393
 
847
1394
  /**
@@ -852,14 +1399,15 @@ export function createOrchestrator(deps) {
852
1399
  * the decision instead of silently switching modes mid-plan.
853
1400
  *
854
1401
  * @param {object} run - live run record.
1402
+ * @param {object | null} parent - the agent that asked for this run.
855
1403
  * @returns {Promise<object | null>} usable workspace record, or null.
856
1404
  */
857
- async function ensureWorkspace(run) {
1405
+ async function ensureWorkspace(run, parent) {
858
1406
  if (config.workspaceIsolation !== true) return null
859
1407
  if (run.workspace) return run.workspace.mode === 'git-worktree' ? run.workspace : null
860
1408
  let verdict
861
1409
  try {
862
- verdict = await workspaceManager().probe()
1410
+ verdict = await workspaceManager(sessionCwd(parent)).probe()
863
1411
  } catch (error) {
864
1412
  verdict = { ok: false, base: null, reason: error?.message ?? String(error) }
865
1413
  }
@@ -874,7 +1422,8 @@ export function createOrchestrator(deps) {
874
1422
  run.workspace = {
875
1423
  mode: 'git-worktree',
876
1424
  base: verdict.base,
877
- root: workspaceManager().root ?? null,
1425
+ root: verdict.root ?? null,
1426
+ boundary: sessionCwd(parent),
878
1427
  reason: null,
879
1428
  merges: [],
880
1429
  conflicts: 0,
@@ -890,11 +1439,12 @@ export function createOrchestrator(deps) {
890
1439
  *
891
1440
  * @param {object} run - live run record.
892
1441
  * @param {object} subtask - subtask entering `running`.
1442
+ * @param {object | null} parent - the agent that asked for this run.
893
1443
  * @returns {Promise<{ dir: string, branch: string, base: string } | null>}
894
1444
  */
895
- async function openWorkspaceFor(run, subtask) {
1445
+ async function openWorkspaceFor(run, subtask, parent) {
896
1446
  if (run.workspace?.mode !== 'git-worktree') return null
897
- const handle = await workspaceManager().prepare({ runId: run.id, index: subtask.index })
1447
+ const handle = await workspaceManager(sessionCwd(parent)).prepare({ runId: run.id, index: subtask.index })
898
1448
  if (!handle?.ok) {
899
1449
  subtask.workspaceError = handle?.reason ?? 'workspace isolation failed for this subtask'
900
1450
  run.workspace.failures = Array.isArray(run.workspace.failures) ? run.workspace.failures : []
@@ -927,7 +1477,7 @@ export function createOrchestrator(deps) {
927
1477
  async function harvestWorkspace(run, subtask) {
928
1478
  const handle = subtask.workspace
929
1479
  if (!handle || !handle.dir) return
930
- const outcome = await workspaceManager().harvest({
1480
+ const outcome = await workspaceManager(run.workspace?.boundary).harvest({
931
1481
  dir: handle.dir,
932
1482
  branch: handle.branch,
933
1483
  index: subtask.index,
@@ -939,13 +1489,167 @@ export function createOrchestrator(deps) {
939
1489
  handle.detail = outcome.detail
940
1490
  if (outcome.status === 'no-changes') {
941
1491
  // An empty checkout is debris; drop it now instead of leaving it behind.
942
- await workspaceManager().release({ dir: handle.dir, branch: handle.branch }).catch(() => {})
1492
+ await workspaceManager(run.workspace?.boundary).release({ dir: handle.dir, branch: handle.branch }).catch(() => {})
943
1493
  handle.dir = null
944
1494
  handle.branch = null
945
1495
  }
946
1496
  await save(run)
947
1497
  }
948
1498
 
1499
+ /**
1500
+ * Directory against which a subtask's declared deliverables are resolved:
1501
+ * its own checkout when isolated, the shared checkout otherwise.
1502
+ */
1503
+ function deliverableRoot(run, subtask) {
1504
+ return subtask.workspace?.dir ?? run.workspace?.base ?? config.workspaceRoot ?? cwd
1505
+ }
1506
+
1507
+ /**
1508
+ * Check the files a subtask promised to hand back before it is allowed to
1509
+ * count as completed.
1510
+ *
1511
+ * Only subtasks that declared deliverables are checked; a task that returns
1512
+ * findings in its report is unaffected. A missing, empty, outside-the-root,
1513
+ * or wrong-type file fails the subtask. A missing file that exists in the
1514
+ * shared checkout instead is reported as `misplaced`, so a worker that wrote
1515
+ * outside its root is not confused with one that produced nothing. A kind
1516
+ * this plugin cannot judge is `unverified` — it stops the completion claim
1517
+ * without asserting the file is bad.
1518
+ *
1519
+ * @param {object} run - live run record.
1520
+ * @param {object} subtask - subtask whose worker just claimed completion.
1521
+ * @returns {Promise<{ at: string, root: string, items: Array<object>, failed: Array<object>, unverified: Array<object> } | null>}
1522
+ */
1523
+ async function verifyDeliverables(run, subtask) {
1524
+ const declared = subtask.deliverables ?? []
1525
+ if (declared.length === 0) return null
1526
+ const root = path.resolve(deliverableRoot(run, subtask))
1527
+ const items = []
1528
+ for (const entry of declared) {
1529
+ const resolved = path.resolve(root, entry.path)
1530
+ // A plan cannot widen its own reach by naming ../../ or an absolute path.
1531
+ const inside = resolved === root || resolved.startsWith(root + path.sep)
1532
+ if (!inside) {
1533
+ items.push({
1534
+ ...entry,
1535
+ status: 'failed',
1536
+ reason: `declared deliverable is outside the working directory: ${entry.path}`,
1537
+ })
1538
+ continue
1539
+ }
1540
+ let stats
1541
+ try {
1542
+ stats = await fsp.stat(resolved)
1543
+ } catch (error) {
1544
+ const missing = error?.code === 'ENOENT' || error?.code === 'ENOTDIR'
1545
+ if (!missing) {
1546
+ items.push({
1547
+ ...entry,
1548
+ status: 'unverified',
1549
+ reason: `could not read ${entry.path}: ${error?.message ?? error}`,
1550
+ })
1551
+ continue
1552
+ }
1553
+ // Not found where this worker was supposed to write. Before calling it
1554
+ // missing, check whether the file landed in the shared checkout: that is
1555
+ // a misplaced write, not an empty result.
1556
+ const misplaced = await misplacedDeliverable(run, subtask, entry)
1557
+ items.push({
1558
+ ...entry,
1559
+ status: 'failed',
1560
+ code: misplaced ? 'misplaced' : 'missing',
1561
+ reason: misplaced
1562
+ ? `declared deliverable "${entry.path}" exists only in the shared checkout (${misplaced}), not in `
1563
+ + `this worker's isolated checkout (${root})`
1564
+ : `declared deliverable "${entry.path}" is missing`,
1565
+ })
1566
+ continue
1567
+ }
1568
+ if (!stats.isFile()) {
1569
+ items.push({
1570
+ ...entry,
1571
+ status: 'failed',
1572
+ reason: `declared deliverable "${entry.path}" is not a file`,
1573
+ })
1574
+ continue
1575
+ }
1576
+ const minBytes = Number.isFinite(Number(entry.minBytes))
1577
+ ? Math.max(1, Math.trunc(Number(entry.minBytes)))
1578
+ : 1
1579
+ if (stats.size < minBytes) {
1580
+ items.push({
1581
+ ...entry,
1582
+ bytes: stats.size,
1583
+ status: 'failed',
1584
+ code: 'empty',
1585
+ reason: `declared deliverable "${entry.path}" is empty (${stats.size} bytes)`,
1586
+ })
1587
+ continue
1588
+ }
1589
+ let head = Buffer.alloc(0)
1590
+ try {
1591
+ const handle = await fsp.open(resolved, 'r')
1592
+ try {
1593
+ // Type checks only need the header; a huge report is not loaded whole.
1594
+ const length = Math.min(stats.size, 65536)
1595
+ const buffer = Buffer.alloc(length)
1596
+ const { bytesRead } = await handle.read(buffer, 0, length, 0)
1597
+ head = buffer.subarray(0, bytesRead)
1598
+ } finally {
1599
+ await handle.close()
1600
+ }
1601
+ } catch (error) {
1602
+ items.push({
1603
+ ...entry,
1604
+ status: 'unverified',
1605
+ reason: `could not read ${entry.path}: ${error?.message ?? error}`,
1606
+ })
1607
+ continue
1608
+ }
1609
+ items.push({
1610
+ ...entry,
1611
+ bytes: stats.size,
1612
+ ...inspectDeliverable({ path: entry.path, kind: entry.kind, bytes: stats.size, head }),
1613
+ })
1614
+ }
1615
+ return {
1616
+ at: new Date(now()).toISOString(),
1617
+ root,
1618
+ items,
1619
+ failed: items.filter(item => item.status === 'failed'),
1620
+ unverified: items.filter(item => item.status === 'unverified'),
1621
+ }
1622
+ }
1623
+
1624
+ /**
1625
+ * Look for a missing deliverable in the shared checkout.
1626
+ *
1627
+ * This is a diagnosis, not an acceptable location. With isolation on, the
1628
+ * worker starts in its own checkout, so a copy in the base checkout means the
1629
+ * write ignored that root. Keeping the two cases apart matters: "missing"
1630
+ * means no file was produced, while "misplaced" means the file exists where
1631
+ * neither the merge nor the check will see it — a different defect.
1632
+ *
1633
+ * @param {object} run - live run record.
1634
+ * @param {object} subtask - subtask being verified.
1635
+ * @param {object} entry - declared deliverable.
1636
+ * @returns {Promise<string|null>} absolute path when it exists only in the base checkout.
1637
+ */
1638
+ async function misplacedDeliverable(run, subtask, entry) {
1639
+ if (run.workspace?.mode !== 'git-worktree') return null
1640
+ const base = run.workspace.base ? path.resolve(run.workspace.base) : null
1641
+ const here = path.resolve(deliverableRoot(run, subtask))
1642
+ if (!base || base === here) return null
1643
+ const candidate = path.resolve(base, entry.path)
1644
+ if (candidate !== base && !candidate.startsWith(base + path.sep)) return null
1645
+ try {
1646
+ const stats = await fsp.stat(candidate)
1647
+ return stats.isFile() ? candidate : null
1648
+ } catch {
1649
+ return null
1650
+ }
1651
+ }
1652
+
949
1653
  /**
950
1654
  * Checkouts that no merge covers, so a kept worktree is never invisible.
951
1655
  *
@@ -992,7 +1696,7 @@ export function createOrchestrator(deps) {
992
1696
  run.workspace.merges = leftoverWorkspaces(run)
993
1697
  return
994
1698
  }
995
- const outcomes = await workspaceManager().mergeAll(workers)
1699
+ const outcomes = await workspaceManager(run.workspace?.boundary).mergeAll(workers)
996
1700
  run.workspace.merges = [...outcomes, ...leftoverWorkspaces(run)]
997
1701
  run.workspace.conflicts = outcomes.filter(outcome => outcome.status === 'conflict').length
998
1702
  for (const outcome of outcomes) {
@@ -1049,6 +1753,33 @@ export function createOrchestrator(deps) {
1049
1753
  return run?.queue?.waiting === true
1050
1754
  }
1051
1755
 
1756
+ /**
1757
+ * Another active run of the same schedule, if any.
1758
+ *
1759
+ * A plan may own one active run at a time, and the run records are the lock:
1760
+ * a timer-driven start and a person's resume both take the start gate and
1761
+ * both read this, so whichever comes second sees the first. Without it a
1762
+ * resume that revives a failed run and a catch-up for the same window can
1763
+ * both become active, and every later window is then skipped behind the pair.
1764
+ *
1765
+ * @param {string | null} runId - the run being started or resumed, if it exists yet.
1766
+ * @param {object | null} origin - origin of the run being started, for a start.
1767
+ * @returns {Promise<object | null>} the active peer, or null.
1768
+ */
1769
+ async function activePeerForScheduled(runId, origin) {
1770
+ const planId = origin?.kind === 'scheduled' ? origin.scheduleId : null
1771
+ if (!planId) return null
1772
+ const runs = new Map()
1773
+ for (const run of await store.list()) runs.set(run.id, run)
1774
+ for (const [id, rt] of runtime) runs.set(id, rt.run)
1775
+ for (const run of runs.values()) {
1776
+ if (runId && run.id === runId) continue
1777
+ if (run.origin?.kind !== 'scheduled' || run.origin.scheduleId !== planId) continue
1778
+ if (ACTIVE_STATUSES.has(run.status) && !isWaiting(run)) return run
1779
+ }
1780
+ return null
1781
+ }
1782
+
1052
1783
  /** Persist the queue positions so `status` and `list` show the real place in line. */
1053
1784
  async function refreshQueuePositions() {
1054
1785
  let changed = false
@@ -2049,47 +2780,71 @@ export function createOrchestrator(deps) {
2049
2780
  * nothing to carry, so a first run's prompts stay unchanged.
2050
2781
  *
2051
2782
  * Notes are layered: `rules` holds project rules, `profile` holds user
2052
- * preferences, and `memoryScope` holds what earlier runs learned. The first
2053
- * two are curated by hand (the `superagent_memory` tool), so they always come
2054
- * before run notes: a rule must not be drowned out by recent observations.
2783
+ * preferences, `memoryScope` holds what earlier runs learned, and the optional
2784
+ * user-level profile holds facts, preferences and decisions that outlive one
2785
+ * task. The first two are curated by hand (the `superagent_memory` tool), so
2786
+ * they always come before run notes: a rule must not be drowned out by recent
2787
+ * observations.
2055
2788
  *
2056
2789
  * @param {string | null} currentId - run being started or resumed.
2057
2790
  * @param {string} goal - the run's goal, used to recall the notes that matter.
2058
2791
  */
2059
2792
  async function memoryContext(currentId, goal = '') {
2060
- if (!memory) return null
2793
+ if (!memory && !userMemory) return null
2061
2794
  const settings = memorySettings()
2062
2795
  const layers = []
2063
2796
  let noteCount = 0
2797
+ let userNoteCount = 0
2064
2798
  try {
2065
- for (const [label, scope] of [
2066
- ['Project rules', 'rules'],
2067
- ['User profile', 'profile'],
2068
- ]) {
2069
- const text = await memory.digest({
2070
- scope,
2799
+ if (memory) {
2800
+ for (const [label, scope] of [
2801
+ ['Project rules', 'rules'],
2802
+ ['User profile', 'profile'],
2803
+ ]) {
2804
+ const text = await memory.digest({
2805
+ scope,
2806
+ maxEntries: settings.digestEntries,
2807
+ maxChars: Math.floor(settings.digestChars / 3),
2808
+ maxAgeDays: settings.maxAgeDays,
2809
+ })
2810
+ if (!text) continue
2811
+ const read = await memory.read({ scope, maxAgeDays: settings.maxAgeDays })
2812
+ noteCount += read.entries.length
2813
+ layers.push(`${label} (scope "${scope}"):\n${text}`)
2814
+ }
2815
+ }
2816
+ // The learned profile sits between the hand-curated layers and this run's
2817
+ // notebook: it is about the user, so it outranks one run's observations.
2818
+ if (userMemory) {
2819
+ const learned = await userMemory.digest({
2820
+ query: goal,
2821
+ maxEntries: 6,
2822
+ maxChars: Math.floor(settings.digestChars / 2),
2823
+ })
2824
+ if (learned) {
2825
+ const userStats = await userMemory.stats()
2826
+ userNoteCount = userStats.total
2827
+ layers.push(
2828
+ 'User profile learned across tasks (facts, preferences, decisions with rationale; may be stale, '
2829
+ + 'verify before relying on it):\n' + learned,
2830
+ )
2831
+ }
2832
+ }
2833
+ if (memory) {
2834
+ const notes = await memory.digest({
2835
+ scope: settings.scope,
2836
+ // Rank notes against this goal instead of only taking the newest ones,
2837
+ // so a run with many predecessors still finds the relevant experience.
2838
+ query: goal,
2071
2839
  maxEntries: settings.digestEntries,
2072
- maxChars: Math.floor(settings.digestChars / 3),
2840
+ maxChars: settings.digestChars,
2073
2841
  maxAgeDays: settings.maxAgeDays,
2074
2842
  })
2075
- if (!text) continue
2076
- const read = await memory.read({ scope, maxAgeDays: settings.maxAgeDays })
2077
- noteCount += read.entries.length
2078
- layers.push(`${label} (scope "${scope}"):\n${text}`)
2079
- }
2080
- const notes = await memory.digest({
2081
- scope: settings.scope,
2082
- // Rank notes against this goal instead of only taking the newest ones,
2083
- // so a run with many predecessors still finds the relevant experience.
2084
- query: goal,
2085
- maxEntries: settings.digestEntries,
2086
- maxChars: settings.digestChars,
2087
- maxAgeDays: settings.maxAgeDays,
2088
- })
2089
- if (notes) {
2090
- const read = await memory.read({ scope: settings.scope, maxAgeDays: settings.maxAgeDays })
2091
- noteCount += read.entries.length
2092
- layers.push(notes)
2843
+ if (notes) {
2844
+ const read = await memory.read({ scope: settings.scope, maxAgeDays: settings.maxAgeDays })
2845
+ noteCount += read.entries.length
2846
+ layers.push(notes)
2847
+ }
2093
2848
  }
2094
2849
  } catch (error) {
2095
2850
  log(`cannot read cross-run memory: ${error?.message ?? error}`)
@@ -2128,6 +2883,7 @@ export function createOrchestrator(deps) {
2128
2883
  return {
2129
2884
  digest,
2130
2885
  notes: noteCount,
2886
+ userNotes: userNoteCount,
2131
2887
  runs: runCount,
2132
2888
  digestChars: digest.length,
2133
2889
  scopes: ['rules', 'profile', settings.scope],
@@ -2337,7 +3093,78 @@ export function createOrchestrator(deps) {
2337
3093
  })
2338
3094
  }
2339
3095
 
2340
- /** Dispose one child activation without letting it block the caller. */
3096
+ /**
3097
+ * Bound one planner attempt by wall-clock time and model calls.
3098
+ *
3099
+ * A planner that starts calling tools can loop for dozens of model calls
3100
+ * without ever returning a plan. Without a bound the whole run budget is
3101
+ * spent before an honest failure can be written; both limits therefore stop
3102
+ * the child and fail the attempt instead of letting it run on.
3103
+ */
3104
+ function guardPlannerAttempt(promise, { ms, budget, baseCalls, readCalls, onStop }) {
3105
+ if (!ms && !budget) return promise
3106
+ return new Promise((resolve, reject) => {
3107
+ let done = false
3108
+ let timer = null
3109
+ let poller = null
3110
+ const finish = () => {
3111
+ done = true
3112
+ if (timer) clearTimeout(timer)
3113
+ if (poller) clearInterval(poller)
3114
+ }
3115
+ const stop = error => {
3116
+ if (done) return
3117
+ finish()
3118
+ try {
3119
+ onStop?.(error)
3120
+ } catch {
3121
+ // Stopping the child is best effort; the attempt still fails.
3122
+ }
3123
+ reject(error)
3124
+ }
3125
+ if (ms) {
3126
+ timer = setTimeout(() => {
3127
+ const error = new Error(`planner attempt timed out after ${ms}ms`)
3128
+ error.code = 'planner-timeout'
3129
+ stop(error)
3130
+ }, ms)
3131
+ }
3132
+ if (budget) {
3133
+ // The child's usage file is the only live signal the host exposes, so
3134
+ // the budget is enforced by polling it rather than by asking the child.
3135
+ poller = setInterval(async () => {
3136
+ if (done) return
3137
+ let calls = 0
3138
+ try {
3139
+ calls = Number(await readCalls()) || 0
3140
+ } catch {
3141
+ return
3142
+ }
3143
+ if (done) return
3144
+ if (baseCalls + calls >= budget) {
3145
+ const error = new Error(
3146
+ `planner stopped at the model-call budget (${baseCalls + calls}/${budget} calls)`,
3147
+ )
3148
+ error.code = 'planner-budget'
3149
+ stop(error)
3150
+ }
3151
+ }, PLANNER_POLL_MS)
3152
+ }
3153
+ promise.then(
3154
+ value => {
3155
+ if (done) return
3156
+ finish()
3157
+ resolve(value)
3158
+ },
3159
+ error => {
3160
+ if (done) return
3161
+ finish()
3162
+ reject(error)
3163
+ },
3164
+ )
3165
+ })
3166
+ }
3167
+
2341
3168
  async function disposeQuietly(handle) {
2342
3169
  if (!handle || typeof handle.dispose !== 'function') return
2343
3170
  try {
@@ -2366,34 +3193,158 @@ export function createOrchestrator(deps) {
2366
3193
  }
2367
3194
 
2368
3195
  async function makePlan(run, parent, rt) {
2369
- try {
2370
- const carried = carriedEntries(run)
2371
- const handle = await spawn(run, rt, {
2372
- label: 'superagent-plan',
2373
- prompt: plannerPrompt(run.goal, run.limits.maxSubtasks, run.memory?.digest ?? '', carried),
2374
- parent,
2375
- })
2376
- // The planner prompt carried them, so record where they landed before
2377
- // the run moves on; status must not claim they are still waiting.
2378
- if (carried.length > 0 && markFollowupsApplied(carried, 'planner')) await save(run)
2379
- rt.activations.add(handle)
2380
- run.steps.planner = { childId: handle.childId }
3196
+ const goal = roundGoal(run)
3197
+ const carried = carriedEntries(run)
3198
+ let previous = ''
3199
+ let attempts = 0
3200
+ let lastReason = ''
3201
+ // Every planner call is recorded with its cost so a stuck plan can be
3202
+ // diagnosed from the run file instead of from the session archive.
3203
+ const plannerAttempts = []
3204
+ run.steps.planner = { childId: null, attempts: plannerAttempts }
3205
+ const callBudget = Number(config.plannerMaxModelCalls) > 0
3206
+ ? Math.trunc(Number(config.plannerMaxModelCalls))
3207
+ : 0
3208
+ const callsSpent = () => plannerAttempts.reduce((total, entry) => total + (entry.modelCalls ?? 0), 0)
3209
+ // A real planner occasionally answers with prose, a nested envelope, or a
3210
+ // reply truncated mid-JSON. One repair round with the broken reply quoted
3211
+ // back is cheap; inventing a single do-everything task is not.
3212
+ for (let round = 1; round <= 2; round++) {
3213
+ attempts = round
3214
+ const spent = callsSpent()
3215
+ if (callBudget > 0 && spent >= callBudget) {
3216
+ lastReason = `planner model-call budget reached (${spent}/${callBudget} calls)`
3217
+ log(`planner attempt ${round} not started: ${lastReason}`)
3218
+ break
3219
+ }
3220
+ let record = null
3221
+ const startedAt = now()
2381
3222
  try {
2382
- const result = await abortable(handle.result, rt.controller.signal)
2383
- const text = textOf(result.output)
2384
- const subtasks = extractPlan(text).slice(0, run.limits.maxSubtasks)
2385
- if (subtasks.length > 0) return { mode: 'planned', subtasks }
2386
- log(`planner reply had no parsable plan; running the goal as one subtask`)
2387
- } finally {
2388
- await recordUsage(run, handle.childId)
2389
- rt.activations.delete(handle)
2390
- await disposeQuietly(handle)
3223
+ const handle = await spawn(run, rt, {
3224
+ label: 'superagent-plan',
3225
+ prompt: round === 1
3226
+ ? plannerPrompt(goal, run.limits.maxSubtasks, run.memory?.digest ?? '', carried)
3227
+ : plannerRepairPrompt(goal, run.limits.maxSubtasks, run.memory?.digest ?? '', carried, previous),
3228
+ parent,
3229
+ // A planner only needs to read the prompt and answer with JSON. In a
3230
+ // host that declares a tool-less preset, this is what stops the child
3231
+ // from inheriting bash/edit tools and looping instead of planning.
3232
+ ...(config.plannerPreset ? { preset: config.plannerPreset } : {}),
3233
+ // Planning is one cheap JSON turn; a stronger model here can be worth
3234
+ // it even when workers stay on a fast route.
3235
+ ...(config.plannerModel ? { model: config.plannerModel } : {}),
3236
+ ...(config.plannerProvider ? { provider: config.plannerProvider } : {}),
3237
+ })
3238
+ // The planner prompt carried them, so record where they landed before
3239
+ // the run moves on; status must not claim they are still waiting.
3240
+ if (carried.length > 0 && markFollowupsApplied(carried, 'planner')) await save(run)
3241
+ rt.activations.add(handle)
3242
+ record = {
3243
+ attempt: round,
3244
+ childId: handle.childId,
3245
+ startedAt: new Date(startedAt).toISOString(),
3246
+ outcome: null,
3247
+ ms: null,
3248
+ modelCalls: null,
3249
+ tokens: null,
3250
+ }
3251
+ plannerAttempts.push(record)
3252
+ run.steps.planner.childId = handle.childId
3253
+ await save(run)
3254
+ try {
3255
+ const plannerMs = Number(config.plannerTimeoutSeconds) > 0
3256
+ ? Number(config.plannerTimeoutSeconds) * 1000
3257
+ : 0
3258
+ const result = await guardPlannerAttempt(abortable(handle.result, rt.controller.signal), {
3259
+ ms: plannerMs,
3260
+ budget: callBudget,
3261
+ baseCalls: spent,
3262
+ readCalls: async () => {
3263
+ const usage = await recordUsage(run, handle.childId)
3264
+ return usage?.modelCalls ?? 0
3265
+ },
3266
+ onStop: error => {
3267
+ log(`planner attempt ${round} stopped: ${error?.message ?? error}`)
3268
+ Promise.resolve(handle.dispose()).catch(() => {})
3269
+ },
3270
+ })
3271
+ if (!result || result.output === undefined) {
3272
+ // A disposed child can settle without a result; that is a failed
3273
+ // attempt with a reason, not a reason to read `output` of nothing.
3274
+ const error = new Error('planner attempt finished without a result')
3275
+ error.code = 'planner-empty'
3276
+ throw error
3277
+ }
3278
+ const text = textOf(result.output)
3279
+ previous = text
3280
+ const parsed = extractPlanObject(text)
3281
+ const subtasks = parsed.subtasks.slice(0, run.limits.maxSubtasks)
3282
+ const ambiguities = parsed.ambiguities ?? []
3283
+ // The planner is asked to list ambiguity before planning, but a
3284
+ // finding it then forgets must still be asked: merge it here instead
3285
+ // of trusting that needsInput stayed in sync.
3286
+ const needsInput = mergeAuditNeedsInput(parsed.needsInput, ambiguities)
3287
+ if (subtasks.length > 0) {
3288
+ if (parsed.repaired) log(`planner reply needed ${parsed.repaired}; recovered ${subtasks.length} subtask(s)`)
3289
+ record.outcome = 'planned'
3290
+ return {
3291
+ mode: 'planned',
3292
+ subtasks,
3293
+ needsInput,
3294
+ ...(parsed.repaired ? { repaired: parsed.repaired } : {}),
3295
+ ...(ambiguities.length > 0 ? { ambiguities } : {}),
3296
+ }
3297
+ }
3298
+ if (needsInput.length > 0) {
3299
+ // The planner refused to plan rather than guess. Starting a worker
3300
+ // anyway would recreate the behaviour this is meant to stop.
3301
+ record.outcome = 'needs-input'
3302
+ return {
3303
+ mode: 'needs-input',
3304
+ subtasks: [],
3305
+ needsInput,
3306
+ ...(ambiguities.length > 0 ? { ambiguities } : {}),
3307
+ }
3308
+ }
3309
+ record.outcome = 'unparsable'
3310
+ lastReason = `attempt ${round} replied with no parsable plan (${text.length} chars)`
3311
+ log(`planner reply on attempt ${round} had no parsable plan (${text.length} chars)`)
3312
+ } finally {
3313
+ const usage = await recordUsage(run, handle.childId)
3314
+ if (record) {
3315
+ record.ms = now() - startedAt
3316
+ record.modelCalls = usage?.modelCalls ?? null
3317
+ record.tokens = usage?.totalTokens ?? null
3318
+ record.outcome = record.outcome ?? 'no-plan'
3319
+ await save(run)
3320
+ }
3321
+ rt.activations.delete(handle)
3322
+ await disposeQuietly(handle)
3323
+ }
3324
+ } catch (error) {
3325
+ lastReason = error?.message ?? String(error)
3326
+ if (record) {
3327
+ record.outcome = error?.code ?? 'error'
3328
+ record.error = lastReason
3329
+ }
3330
+ log(`planner attempt ${round} failed: ${lastReason}`)
3331
+ if (error?.code === 'subagent-unavailable') {
3332
+ markHostGone(rt, error)
3333
+ break
3334
+ }
2391
3335
  }
2392
- } catch (error) {
2393
- log(`planner failed: ${error?.message ?? error}`)
2394
- if (error?.code === 'subagent-unavailable') markHostGone(rt, error)
2395
3336
  }
2396
- return { mode: 'degraded', subtasks: [{ title: 'Complete the goal', prompt: run.goal }] }
3337
+ // No fallback worker. A single "complete the goal" task looks like a plan
3338
+ // while dropping the ambiguity handling and capability preflight the plan
3339
+ // exists to enforce, so an unusable reply stops the run instead.
3340
+ return {
3341
+ mode: 'invalid',
3342
+ subtasks: [],
3343
+ needsInput: [],
3344
+ attempts,
3345
+ ...(lastReason ? { reason: lastReason } : {}),
3346
+ ...(previous ? { reply: capChars(previous, 1200) } : {}),
3347
+ }
2397
3348
  }
2398
3349
 
2399
3350
  async function runSubtask(run, subtask, parent, rt, { model = null } = {}) {
@@ -2412,7 +3363,7 @@ export function createOrchestrator(deps) {
2412
3363
  let handle = null
2413
3364
  // A retry reuses the checkout from the previous attempt, so work the
2414
3365
  // earlier attempt already wrote is not thrown away.
2415
- const workspace = await openWorkspaceFor(run, subtask)
3366
+ const workspace = await openWorkspaceFor(run, subtask, parent)
2416
3367
  try {
2417
3368
  handle = await spawn(run, rt, {
2418
3369
  label: run.mode === 'direct' ? 'superagent-direct' : `superagent-${subtask.index}`,
@@ -2421,6 +3372,13 @@ export function createOrchestrator(deps) {
2421
3372
  : workerPrompt(run, subtask, workspace, carried),
2422
3373
  parent,
2423
3374
  model,
3375
+ // The worker's relative writes must land in the checkout the
3376
+ // deliverable check reads, not in the shared checkout.
3377
+ ...(workspace?.dir ? { cwd: workspace.dir } : {}),
3378
+ // The permission escalation and the audit trail are per plan entry;
3379
+ // this is the same identifier attention items use.
3380
+ subtaskId: `subtask-${subtask.index}`,
3381
+ requires: subtask.requires ?? [],
2424
3382
  })
2425
3383
  rt.activations.add(handle)
2426
3384
  subtask.childId = handle.childId
@@ -2442,17 +3400,59 @@ export function createOrchestrator(deps) {
2442
3400
  // A valid block is stripped; an unusable one stays in the worker result
2443
3401
  // so the report the user reads still contains what was asked.
2444
3402
  const text = cleaned.attention ? cleaned.text : raw
2445
- subtask.status = 'completed'
2446
- subtask.result = capText(text, config.resultCapBytes)
2447
- subtask.error = null
2448
- subtask.finishedAt = new Date(now()).toISOString()
2449
- await recordUsage(run, handle.childId)
2450
- await harvestWorkspace(run, subtask)
2451
- await save(run)
2452
- return
3403
+ // Completion is a claim about an artifact, not about the turn ending.
3404
+ // A declared file must exist, be non-empty, and match the kind the
3405
+ // plan declared; with no declaration the reply is the artifact, so it
3406
+ // must not be empty either.
3407
+ const verdict = await verifyDeliverables(run, subtask)
3408
+ if (verdict) {
3409
+ subtask.deliverables = verdict.items
3410
+ subtask.deliverableCheck = {
3411
+ at: verdict.at,
3412
+ checked: verdict.items.length,
3413
+ verified: verdict.items.filter(item => item.status === 'verified').length,
3414
+ failed: verdict.failed.length,
3415
+ misplaced: verdict.items.filter(item => item.code === 'misplaced').length,
3416
+ unverified: verdict.unverified.length,
3417
+ }
3418
+ }
3419
+ const problems = []
3420
+ if (verdict?.failed.length > 0) problems.push(...verdict.failed.map(item => item.reason))
3421
+ if (!verdict && !text.trim()) problems.push('the reply was empty and no deliverable was declared')
3422
+ if (problems.length > 0) {
3423
+ // A missing or wrong artifact is retryable: the next attempt may
3424
+ // still write what it promised. It is never counted as completed.
3425
+ subtask.error = `empty deliverable: ${problems.join('; ')}`
3426
+ log(`subtask ${subtask.index} attempt ${attempt} did not deliver: ${subtask.error}`)
3427
+ } else if (verdict?.unverified.length > 0) {
3428
+ // The file may be fine, but this session cannot judge it. Claiming
3429
+ // completion would be a guess, so the subtask stays out of the
3430
+ // completed count until a person or a capable tool checks it.
3431
+ subtask.status = 'unverified'
3432
+ subtask.unverifiedReason = verdict.unverified.map(item => item.reason).join('; ')
3433
+ subtask.result = capText(text, config.resultCapBytes)
3434
+ subtask.error = null
3435
+ subtask.finishedAt = new Date(now()).toISOString()
3436
+ await recordUsage(run, handle.childId)
3437
+ await save(run)
3438
+ log(`subtask ${subtask.index}: deliverable could not be verified: ${subtask.unverifiedReason}`)
3439
+ return
3440
+ } else {
3441
+ subtask.status = 'completed'
3442
+ subtask.result = capText(text, config.resultCapBytes)
3443
+ subtask.error = null
3444
+ subtask.finishedAt = new Date(now()).toISOString()
3445
+ await recordUsage(run, handle.childId)
3446
+ await harvestWorkspace(run, subtask)
3447
+ await save(run)
3448
+ return
3449
+ }
3450
+ } else {
3451
+ subtask.error = result.stopReason === 'completed' && !raw
3452
+ ? 'empty deliverable: the worker returned no text and declared no file'
3453
+ : result.diagnostic || `child stopped with reason "${result.stopReason}"`
3454
+ log(`subtask ${subtask.index} attempt ${attempt} did not complete: ${subtask.error}`)
2453
3455
  }
2454
- subtask.error = result.diagnostic || `child stopped with reason "${result.stopReason}"`
2455
- log(`subtask ${subtask.index} attempt ${attempt} did not complete: ${subtask.error}`)
2456
3456
  } catch (error) {
2457
3457
  subtask.error = error?.message ?? String(error)
2458
3458
  log(`subtask ${subtask.index} attempt ${attempt} threw: ${subtask.error}`)
@@ -2606,7 +3606,7 @@ export function createOrchestrator(deps) {
2606
3606
  if (carried.length > 0 && markFollowupsApplied(carried, 'aggregator')) await save(run)
2607
3607
  const handle = await spawn(run, rt, {
2608
3608
  label: 'superagent-aggregate',
2609
- prompt: aggregatorPrompt(run, completed, run.memory?.digest ?? '', carried),
3609
+ prompt: aggregatorPrompt(run, completed, run.memory?.digest ?? '', carried, Boolean(userMemory)),
2610
3610
  parent,
2611
3611
  })
2612
3612
  rt.activations.add(handle)
@@ -2635,6 +3635,10 @@ export function createOrchestrator(deps) {
2635
3635
  if (rt.abortCause === 'host-gone') return 'interrupted'
2636
3636
  const subtasks = run.subtasks ?? []
2637
3637
  const completed = subtasks.filter(subtask => subtask.status === 'completed').length
3638
+ // A goal run is complete only when its acceptance step said so. Reaching a
3639
+ // limit or stalling leaves the work partial even when every subtask of the
3640
+ // last round finished: the goal, not the round, is what was started.
3641
+ if (run.goalMode) return run.goalMode.achieved ? 'completed' : (completed > 0 ? 'partial' : 'failed')
2638
3642
  if (completed === 0) return 'failed'
2639
3643
  if (rt.abortCause === 'deadline') {
2640
3644
  return completed === subtasks.length ? 'completed' : 'partial'
@@ -2691,7 +3695,7 @@ export function createOrchestrator(deps) {
2691
3695
  }
2692
3696
  }
2693
3697
  applyCost(run, config.pricing)
2694
- const nextStatus = terminalStatus(run, rt)
3698
+ let nextStatus = terminalStatus(run, rt)
2695
3699
  const finishedAt = new Date(now()).toISOString()
2696
3700
 
2697
3701
  // An instruction that arrived in the last moments of a run never reached a
@@ -2771,12 +3775,45 @@ export function createOrchestrator(deps) {
2771
3775
  }
2772
3776
  }
2773
3777
  }
3778
+ // The user-level profile has its own fence and its own lifetime. It is read
3779
+ // only when the layer is enabled, and a write failure is recorded rather
3780
+ // than escalated: like the run notebook, it must never fail the run.
3781
+ if (userMemory && TERMINAL_STATUSES.has(nextStatus) && typeof run.report === 'string' && run.report) {
3782
+ const block = extractUserMemoryBlock(run.report)
3783
+ if (block.found) {
3784
+ run.report = block.report
3785
+ try {
3786
+ const written = await userMemory.writeBlock({ runId: run.id, block: block.block })
3787
+ run.userMemoryWrite = {
3788
+ at: new Date(now()).toISOString(),
3789
+ written: written.fact + written.preference + written.decision,
3790
+ reason: block.error ?? null,
3791
+ }
3792
+ } catch (writeError) {
3793
+ log(`cannot write user-level memory for run ${run.id}: ${writeError?.message ?? writeError}`)
3794
+ run.userMemoryWrite = {
3795
+ at: new Date(now()).toISOString(),
3796
+ written: 0,
3797
+ reason: `write failed: ${writeError?.message ?? writeError}`,
3798
+ }
3799
+ }
3800
+ }
3801
+ }
2774
3802
  // The guard's event list belongs in the user-facing report, not only in the
2775
3803
  // status line: a blocked command is part of what happened during the run.
2776
3804
  const guardSection = guard?.reportSection?.(run.id)
2777
3805
  if (guardSection && typeof run.report === 'string' && run.report) {
2778
3806
  run.report = `${run.report.trimEnd()}\n\n${guardSection}`
2779
3807
  }
3808
+ // Stripping an attention-only or notebook-only reply can leave nothing
3809
+ // behind. A run that "completed" with no artifact is not a completion:
3810
+ // keep the evidence and downgrade it so a schedule does not report success
3811
+ // for an empty result.
3812
+ if (nextStatus === 'completed' && !String(run.report ?? '').trim()) {
3813
+ nextStatus = 'partial'
3814
+ run.error = run.error || 'the run produced an empty deliverable; an empty report is not a completion'
3815
+ log(`run ${run.id}: completed with an empty report; recorded as partial`)
3816
+ }
2780
3817
  // The report gets a durable address before the run is announced, so a
2781
3818
  // notification or status line can point at a file that already exists.
2782
3819
  if (TERMINAL_STATUSES.has(nextStatus)) await writeReportArtifact(run)
@@ -2794,7 +3831,12 @@ export function createOrchestrator(deps) {
2794
3831
 
2795
3832
  let outcome = null
2796
3833
  if (TERMINAL_STATUSES.has(nextStatus)) {
2797
- if (watchedHere(rt)) {
3834
+ if (run.notifyMuted) {
3835
+ // A scheduled run is announced by the scheduler, which knows whether
3836
+ // this plan already woke the session about a failure. Waking the parent
3837
+ // here too would turn a half-hourly plan into half-hourly noise.
3838
+ outcome = { delivered: false, reason: 'muted: the run was started by a schedule; the scheduler reports its outcome' }
3839
+ } else if (watchedHere(rt)) {
2798
3840
  outcome = { delivered: false, reason: 'skipped: a caller in this process is reading the run' }
2799
3841
  } else {
2800
3842
  try {
@@ -2887,6 +3929,10 @@ export function createOrchestrator(deps) {
2887
3929
  index: index + 1,
2888
3930
  title: entry.title,
2889
3931
  prompt: entry.prompt,
3932
+ requires: Array.isArray(entry.requires) ? entry.requires : [],
3933
+ deliverables: Array.isArray(entry.deliverables) ? entry.deliverables : [],
3934
+ assumptions: Array.isArray(entry.assumptions) ? entry.assumptions : [],
3935
+ deliverableCheck: null,
2890
3936
  status: 'pending',
2891
3937
  attempts: 0,
2892
3938
  childId: null,
@@ -2899,13 +3945,217 @@ export function createOrchestrator(deps) {
2899
3945
  }
2900
3946
  }
2901
3947
 
3948
+ /**
3949
+ * Compare each subtask's declared capabilities with the tools the calling
3950
+ * session actually has. A missing capability blocks that subtask before a
3951
+ * worker is spawned and is never counted as a success.
3952
+ *
3953
+ * When the host cannot list its tools, the preflight says so and does not
3954
+ * block: guessing an inventory would either stop work that could run or
3955
+ * promise a capability that does not exist.
3956
+ *
3957
+ * @param {object} run - live run record.
3958
+ * @param {object} parent - calling session.
3959
+ */
3960
+ async function preflightCapabilities(run, parent) {
3961
+ const candidates = run.subtasks.filter(subtask =>
3962
+ subtask.status === 'pending' || subtask.status === 'waiting' || subtask.status === 'blocked')
3963
+ if (!candidates.some(subtask => (subtask.requires ?? []).length > 0)) {
3964
+ run.preflight = { at: new Date(now()).toISOString(), status: 'no-requirements', blocked: 0 }
3965
+ await save(run)
3966
+ return
3967
+ }
3968
+ const unavailable = async reason => {
3969
+ run.preflight = {
3970
+ at: new Date(now()).toISOString(),
3971
+ status: 'unavailable',
3972
+ blocked: 0,
3973
+ reason,
3974
+ }
3975
+ await save(run)
3976
+ log(`capability preflight skipped: ${reason}`)
3977
+ }
3978
+ if (typeof toolInventory !== 'function') {
3979
+ await unavailable('the host did not expose a tool inventory')
3980
+ return
3981
+ }
3982
+ let tools
3983
+ try {
3984
+ tools = await toolInventory(parent)
3985
+ } catch (error) {
3986
+ await unavailable(`the host tool inventory could not be read (${error?.message ?? error})`)
3987
+ return
3988
+ }
3989
+ if (!Array.isArray(tools)) {
3990
+ await unavailable('the host did not expose a tool inventory')
3991
+ return
3992
+ }
3993
+ const inventory = [...new Set(tools.filter(name => typeof name === 'string' && name.length > 0))]
3994
+ let changed = false
3995
+ for (const subtask of candidates) {
3996
+ const gaps = capabilityGaps(subtask.requires ?? [], inventory)
3997
+ if (gaps.length > 0) {
3998
+ if (subtask.status !== 'blocked' || (subtask.missingCapabilities ?? []).join() !== gaps.join()) {
3999
+ changed = true
4000
+ }
4001
+ subtask.status = 'blocked'
4002
+ subtask.blockKind = 'capability'
4003
+ subtask.missingCapabilities = gaps
4004
+ subtask.blockedReason = `missing ${gaps.join(', ')} capability; not started`
4005
+ subtask.waitingOn = []
4006
+ } else if (subtask.status === 'blocked') {
4007
+ // A resume in a session that now has the tool may still run this work.
4008
+ subtask.status = 'pending'
4009
+ subtask.blockKind = null
4010
+ subtask.missingCapabilities = []
4011
+ subtask.blockedReason = null
4012
+ changed = true
4013
+ }
4014
+ }
4015
+ const blocked = candidates.filter(subtask => subtask.status === 'blocked')
4016
+ run.preflight = {
4017
+ at: new Date(now()).toISOString(),
4018
+ status: 'checked',
4019
+ toolCount: inventory.length,
4020
+ blocked: blocked.length,
4021
+ }
4022
+ await save(run)
4023
+ if (blocked.length > 0) {
4024
+ log(
4025
+ `capability preflight: ${blocked.length}/${candidates.length} subtask(s) blocked; `
4026
+ + blocked.map(subtask => `${subtask.key} needs ${subtask.missingCapabilities.join(', ')}`).join('; ')
4027
+ + ` (${inventory.length} tool(s) available)`,
4028
+ )
4029
+ } else {
4030
+ log(`capability preflight: every declared capability is covered by ${inventory.length} tool(s)`)
4031
+ }
4032
+ if (changed) await save(run)
4033
+ }
4034
+
4035
+ /** Deterministic report for a planner that stopped to ask instead of guessing. */
4036
+ function needsInputReport(run) {
4037
+ const lines = [
4038
+ `# ${run.goal}`,
4039
+ '',
4040
+ 'No worker was started: the planner needs answers before it can plan this safely.',
4041
+ '',
4042
+ '## Questions',
4043
+ '',
4044
+ ]
4045
+ for (const item of run.plan?.needsInput ?? []) {
4046
+ lines.push(`- ${item.question}${item.reason ? ` — ${item.reason}` : ''}`)
4047
+ }
4048
+ const ambiguities = run.plan?.ambiguities ?? []
4049
+ if (ambiguities.length > 0) {
4050
+ lines.push('', '## Wording it refused to guess at', '')
4051
+ for (const item of ambiguities) lines.push(`- "${item.phrase}"${item.why ? ` — ${item.why}` : ''}`)
4052
+ }
4053
+ return lines.join('\n').trim()
4054
+ }
4055
+
4056
+ /** Deterministic report when the planner never produced a usable plan. */
4057
+ function invalidPlanReport(run) {
4058
+ const lines = [
4059
+ `# ${run.goal}`,
4060
+ '',
4061
+ 'No worker was started: the planner did not return a plan this run could execute.',
4062
+ '',
4063
+ `- The reply was not a JSON object with a "subtasks" array (${run.plan?.attempts ?? 1} attempt(s), `
4064
+ + 'including one repair round where the unusable reply was quoted back).',
4065
+ ...(run.plan?.invalidReason ? [`- Last planner attempt: ${run.plan.invalidReason}`] : []),
4066
+ '- The goal was deliberately not handed to a fallback "complete the goal" worker: that would skip the '
4067
+ + 'ambiguity questions and the capability preflight, which is how a run spends tokens on work it cannot do.',
4068
+ '',
4069
+ '## What to do',
4070
+ '',
4071
+ '- Retry the run, or split the goal into one task per line so each part can be planned and checked separately.',
4072
+ '- If part of the goal is unclear, say what each name or phrase refers to; the planner will ask instead of '
4073
+ + 'guessing when it can parse the request.',
4074
+ ]
4075
+ if (run.plan?.invalidReply) {
4076
+ lines.push('', '## Start of the reply that could not be parsed', '', '```text', run.plan.invalidReply, '```')
4077
+ }
4078
+ return lines.join('\n').trim()
4079
+ }
4080
+
4081
+ /** Deterministic report for a plan that cannot start at all. */
4082
+ function capabilityGapReport(run) {
4083
+ const blocked = run.subtasks.filter(subtask => subtask.status === 'blocked')
4084
+ const lines = [
4085
+ `# ${run.goal}`,
4086
+ '',
4087
+ 'No worker was started: every planned subtask needs a capability this session does not have.',
4088
+ '',
4089
+ '## Capability gaps',
4090
+ '',
4091
+ ]
4092
+ for (const subtask of blocked) {
4093
+ const gaps = subtask.missingCapabilities ?? []
4094
+ lines.push(`- **${subtask.key} — ${subtask.title}**: needs ${gaps.join(', ')}`)
4095
+ for (const suggestion of new Set(gaps.map(capabilitySuggestion))) lines.push(` - ${suggestion}`)
4096
+ }
4097
+ const needsInput = run.plan?.needsInput ?? []
4098
+ if (needsInput.length > 0) {
4099
+ lines.push('', '## Input needed from you', '')
4100
+ for (const item of needsInput) {
4101
+ lines.push(`- ${item.question}${item.reason ? ` — ${item.reason}` : ''}`)
4102
+ }
4103
+ }
4104
+ const assumed = run.subtasks.filter(subtask => (subtask.assumptions ?? []).length > 0)
4105
+ if (assumed.length > 0) {
4106
+ lines.push('', '## Assumptions the planner recorded', '')
4107
+ for (const subtask of assumed) {
4108
+ for (const assumption of subtask.assumptions) lines.push(`- ${subtask.key}: ${assumption}`)
4109
+ }
4110
+ }
4111
+ return lines.join('\n').trim()
4112
+ }
4113
+
2902
4114
  /** Planner, parallel workers, self-heal, then one merged report. */
2903
4115
  async function runPlanned(run, parent, rt) {
2904
4116
  if (!Array.isArray(run.subtasks) || run.subtasks.length === 0) {
2905
4117
  run.status = 'planning'
2906
4118
  await save(run)
2907
4119
  const plan = await makePlan(run, parent, rt)
2908
- run.plan = { mode: plan.mode, subtasks: plan.subtasks }
4120
+ run.plan = {
4121
+ mode: plan.mode,
4122
+ subtasks: plan.subtasks,
4123
+ ...(plan.needsInput?.length > 0 ? { needsInput: plan.needsInput } : {}),
4124
+ ...(plan.ambiguities?.length > 0 ? { ambiguities: plan.ambiguities } : {}),
4125
+ ...(plan.repaired ? { repaired: plan.repaired } : {}),
4126
+ ...(plan.mode === 'invalid' ? { attempts: plan.attempts ?? 1 } : {}),
4127
+ ...(plan.mode === 'invalid' && plan.reason ? { invalidReason: plan.reason } : {}),
4128
+ }
4129
+ if (plan.mode === 'invalid') {
4130
+ // The host going away is not the planner's fault; leave the run
4131
+ // resumable instead of recording an unusable plan.
4132
+ if (rt.abortCause === 'host-gone') {
4133
+ await save(run)
4134
+ return
4135
+ }
4136
+ run.plan.invalidReply = plan.reply ? capChars(plan.reply, 600) : null
4137
+ run.report = invalidPlanReport(run)
4138
+ run.error = `planner did not return a usable plan after ${plan.attempts ?? 1} attempt(s); `
4139
+ + 'no worker was started'
4140
+ + (plan.reason ? ` (${plan.reason})` : '')
4141
+ addMilestone(run, 'plan_invalid')
4142
+ await save(run)
4143
+ log(`${run.error}; the goal was not handed to a fallback worker`)
4144
+ return
4145
+ }
4146
+ // Replanning after an answer must not pile up the same questions.
4147
+ if (Array.isArray(run.attention?.items)) {
4148
+ run.attention.items = run.attention.items.filter(item => item.source !== 'planner')
4149
+ }
4150
+ // A question the planner would not answer by guessing is a question for
4151
+ // the user, not something the workers may quietly decide.
4152
+ for (const item of plan.needsInput ?? []) {
4153
+ recordAttention(run, 'planner', {
4154
+ question: item.question,
4155
+ options: item.options ?? [],
4156
+ reason: item.reason ?? 'the planner could not resolve this from the goal without guessing',
4157
+ })
4158
+ }
2909
4159
  const entries = plan.subtasks.map((entry, index) => ({
2910
4160
  key: entry.id ?? `w${index + 1}`,
2911
4161
  title: entry.title,
@@ -2947,6 +4197,30 @@ export function createOrchestrator(deps) {
2947
4197
  await save(run)
2948
4198
  }
2949
4199
 
4200
+ if (run.subtasks.length === 0 && (run.plan?.needsInput?.length ?? 0) > 0) {
4201
+ run.report = needsInputReport(run)
4202
+ run.error = `planner needs input before it can plan: ${run.plan.needsInput[0].question}`
4203
+ addMilestone(run, 'needs_input')
4204
+ await save(run)
4205
+ log(`planner stopped before any worker started: ${run.error}`)
4206
+ return
4207
+ }
4208
+
4209
+ // Check declared capabilities against the tools this session really has
4210
+ // before spending a single worker token on work that cannot run.
4211
+ await preflightCapabilities(run, parent)
4212
+ const blockedNow = run.subtasks.filter(subtask => subtask.status === 'blocked')
4213
+ const openNow = run.subtasks.filter(subtask => subtask.status !== 'completed')
4214
+ if (blockedNow.length > 0 && openNow.length === blockedNow.length) {
4215
+ run.report = capabilityGapReport(run)
4216
+ run.error = `no worker started: every planned subtask needs a capability this session lacks `
4217
+ + `(${[...new Set(blockedNow.flatMap(subtask => subtask.missingCapabilities ?? []))].join(', ')})`
4218
+ addMilestone(run, 'preflight_blocked')
4219
+ await save(run)
4220
+ log(`capability preflight stopped the run before any worker started: ${run.error}`)
4221
+ return
4222
+ }
4223
+
2950
4224
  const open = run.subtasks.filter(subtask => subtask.status !== 'completed')
2951
4225
  if (open.length > 0) {
2952
4226
  run.status = 'running'
@@ -3035,6 +4309,221 @@ export function createOrchestrator(deps) {
3035
4309
  else if (!run.report) run.report = deterministicJoin(run)
3036
4310
  }
3037
4311
 
4312
+ /**
4313
+ * A limit that can be read between rounds. `needs-decision` comes first:
4314
+ * spending another round while a question is open would ask the model to guess
4315
+ * the answer the human was asked for. A stall is checked before the round
4316
+ * count so the report names the more specific reason.
4317
+ */
4318
+ function goalHardStop(run, { assessment = null, failures = [] } = {}) {
4319
+ const goalMode = run.goalMode
4320
+ const open = (run.attention?.items ?? []).filter(item => !item.answer)
4321
+ if (open.length > 0) {
4322
+ return { reason: 'needs-decision', detail: oneLine(open[0].question, 200) }
4323
+ }
4324
+ const blocked = budgetStop(run)
4325
+ if (blocked) return { reason: 'budget', detail: blocked }
4326
+ const started = Date.parse(goalMode.startedAt ?? '')
4327
+ const elapsed = Number.isFinite(started) ? now() - started : 0
4328
+ if (elapsed >= goalMode.maxWallClockMinutes * 60000) {
4329
+ return {
4330
+ reason: 'wall-clock',
4331
+ detail: `${Math.round(elapsed / 60000)} of ${goalMode.maxWallClockMinutes} minute(s) used`,
4332
+ }
4333
+ }
4334
+ if (assessment?.stalled) {
4335
+ return {
4336
+ reason: assessment.stalled,
4337
+ detail: assessment.stalled === 'no-changes'
4338
+ ? 'the round left the workspace unchanged'
4339
+ : `${failures.map(item => item.id).join(', ')} failed ${assessment.streak} round(s) in a row`,
4340
+ }
4341
+ }
4342
+ if ((goalMode.rounds ?? []).length - (goalMode.roundBase ?? 0) >= goalMode.maxRounds) {
4343
+ return { reason: 'rounds', detail: `maxRounds is ${goalMode.maxRounds}` }
4344
+ }
4345
+ return null
4346
+ }
4347
+
4348
+ /**
4349
+ * Execute one round: plan or run direct, then judge the acceptance conditions.
4350
+ *
4351
+ * A round starts from an empty subtask list, so the planner sees the previous
4352
+ * failure and can choose a different decomposition instead of replaying the
4353
+ * old plan. `roundGoal` puts that feedback in the planner, worker, direct, and
4354
+ * aggregator prompts.
4355
+ */
4356
+ async function runGoalRound(run, parent, rt) {
4357
+ const goalMode = run.goalMode
4358
+ const roundNumber = goalMode.rounds.length + 1
4359
+ const startedAt = new Date(now()).toISOString()
4360
+ const machineChecked = hasMachineChecks(goalMode)
4361
+ const before = machineChecked ? await fingerprintWorkspace(goalMode.cwd).catch(() => null) : null
4362
+
4363
+ run.subtasks = []
4364
+ run.plan = null
4365
+ run.selfHeal = null
4366
+ run.report = null
4367
+ run.status = 'running'
4368
+ addMilestone(run, `goal_round_${roundNumber}`)
4369
+ await save(run)
4370
+
4371
+ if (run.mode === 'direct') await runDirect(run, parent, rt)
4372
+ else await runPlanned(run, parent, rt)
4373
+
4374
+ const roundReport = run.report
4375
+ const subtasks = run.subtasks ?? []
4376
+ const completed = subtasks.filter(subtask => subtask.status === 'completed').length
4377
+ if (rt.controller.signal.aborted) {
4378
+ goalMode.stop = {
4379
+ reason: 'aborted',
4380
+ detail: `the run stopped during round ${roundNumber} (${rt.abortCause ?? 'cancelled'})`,
4381
+ at: new Date(now()).toISOString(),
4382
+ round: roundNumber,
4383
+ }
4384
+ return
4385
+ }
4386
+
4387
+ // The machine part runs whatever the judge will say, so the verdict rests on
4388
+ // exit codes even when the model also has to answer for other conditions.
4389
+ const checks = await runChecks(goalMode, { signal: rt.controller.signal })
4390
+ const failedChecks = () => checks.filter(check => check.ok === false).map(check => ({
4391
+ id: check.id,
4392
+ text: check.text,
4393
+ source: check.source,
4394
+ why: check.detail ?? 'the condition did not hold',
4395
+ }))
4396
+
4397
+ let verdictNext = null
4398
+ const open = (run.attention?.items ?? []).filter(item => !item.answer)
4399
+ if (open.length === 0) {
4400
+ const judged = checks.filter(check => check.source === 'model')
4401
+ if (judged.length > 0) {
4402
+ const round = { round: roundNumber, report: roundReport, checks }
4403
+ let verdict = null
4404
+ try {
4405
+ const handle = await spawn(run, rt, {
4406
+ label: 'superagent-accept',
4407
+ prompt: verifierPrompt(run, round, checks),
4408
+ parent,
4409
+ })
4410
+ rt.activations.add(handle)
4411
+ run.steps.goalAcceptance = { round: roundNumber, childId: handle.childId }
4412
+ try {
4413
+ const result = await abortable(handle.result, rt.controller.signal)
4414
+ verdict = parseVerdict(textOf(result.output))
4415
+ } finally {
4416
+ await recordUsage(run, handle.childId)
4417
+ rt.activations.delete(handle)
4418
+ await disposeQuietly(handle)
4419
+ }
4420
+ } catch (error) {
4421
+ verdict = { verdict: null, error: `the acceptance judge failed: ${error?.message ?? error}` }
4422
+ }
4423
+ if (verdict.error) {
4424
+ // The judge failing is not the work failing, but the loop cannot call
4425
+ // an unjudged condition met either. The report says which happened.
4426
+ for (const check of judged) {
4427
+ check.ok = false
4428
+ check.detail = verdict.error
4429
+ }
4430
+ } else if (verdict.verdict.achieved) {
4431
+ for (const check of judged) {
4432
+ check.ok = true
4433
+ check.detail = 'met, judged from the round report'
4434
+ }
4435
+ verdictNext = verdict.verdict.next
4436
+ } else {
4437
+ const byId = new Map(verdict.verdict.failed.map(entry => [entry.id, entry.why]))
4438
+ for (const check of judged) {
4439
+ check.ok = false
4440
+ check.detail = byId.get(check.id)
4441
+ ?? verdict.verdict.next
4442
+ ?? 'judged not met from the round report'
4443
+ }
4444
+ verdictNext = verdict.verdict.next
4445
+ }
4446
+ }
4447
+ }
4448
+
4449
+ const failures = failedChecks()
4450
+ const achieved = failures.length === 0 && checks.length > 0
4451
+ const after = machineChecked ? await fingerprintWorkspace(goalMode.cwd).catch(() => null) : null
4452
+ const changed = before === null || after === null ? null : before !== after
4453
+ const assessment = assessRound({
4454
+ previous: goalMode.rounds.at(-1) ?? null,
4455
+ failed: failures,
4456
+ changed,
4457
+ machineChecked,
4458
+ noProgressRounds: goalMode.noProgressRounds,
4459
+ })
4460
+ goalMode.rounds.push({
4461
+ round: roundNumber,
4462
+ startedAt,
4463
+ finishedAt: new Date(now()).toISOString(),
4464
+ subtasks: { total: subtasks.length, completed },
4465
+ checks,
4466
+ changed,
4467
+ failed: failures,
4468
+ failedSignature: assessment.signature,
4469
+ streak: assessment.streak,
4470
+ achieved,
4471
+ next: verdictNext,
4472
+ report: capText(roundReport ?? '', 4000),
4473
+ })
4474
+ run.recovery = null
4475
+
4476
+ if (achieved) {
4477
+ goalMode.achieved = true
4478
+ goalMode.nextInstruction = null
4479
+ await save(run)
4480
+ return
4481
+ }
4482
+ const stop = goalHardStop(run, { assessment, failures })
4483
+ if (stop) {
4484
+ goalMode.stop = { ...stop, at: new Date(now()).toISOString(), round: roundNumber }
4485
+ await save(run)
4486
+ return
4487
+ }
4488
+ goalMode.nextInstruction = buildRoundInstruction(roundNumber, failures, verdictNext)
4489
+ await save(run)
4490
+ }
4491
+
4492
+ /**
4493
+ * Goal mode: run rounds until the acceptance conditions hold or a hard stop
4494
+ * decides a human is needed. Only the final settle notifies, so every round
4495
+ * between the first and the last is silent by construction.
4496
+ */
4497
+ async function runGoalLoop(run, parent, rt) {
4498
+ const goalMode = run.goalMode
4499
+ goalMode.rounds = Array.isArray(goalMode.rounds) ? goalMode.rounds : []
4500
+ goalMode.stop = null
4501
+ goalMode.achieved = false
4502
+ goalMode.startedAt = new Date(now()).toISOString()
4503
+ goalMode.cwd = goalMode.cwd ?? process.cwd()
4504
+ goalMode.roundBase = Number.isFinite(goalMode.roundBase) ? goalMode.roundBase : 0
4505
+ while (!rt.controller.signal.aborted) {
4506
+ const stop = goalHardStop(run)
4507
+ if (stop) {
4508
+ goalMode.stop = { ...stop, at: new Date(now()).toISOString(), round: goalMode.rounds.length }
4509
+ break
4510
+ }
4511
+ await runGoalRound(run, parent, rt)
4512
+ if (goalMode.achieved || goalMode.stop) break
4513
+ }
4514
+ if (!goalMode.stop && !goalMode.achieved && rt.controller.signal.aborted) {
4515
+ goalMode.stop = {
4516
+ reason: 'aborted',
4517
+ detail: `the run stopped before the goal was reached (${rt.abortCause ?? 'cancelled'})`,
4518
+ at: new Date(now()).toISOString(),
4519
+ round: goalMode.rounds.length,
4520
+ }
4521
+ }
4522
+ goalMode.nextInstruction = null
4523
+ run.report = composeGoalReport(run)
4524
+ await save(run)
4525
+ }
4526
+
3038
4527
  async function execute(run, parent, rt) {
3039
4528
  rt.activeStart = now()
3040
4529
  const remaining = Math.max(0, Date.parse(run.deadlineAt) - now())
@@ -3057,8 +4546,25 @@ export function createOrchestrator(deps) {
3057
4546
  ensureCounters(run)
3058
4547
  // Decided once, before any child runs, so the whole plan uses one mode and
3059
4548
  // status can already say whether isolation is on.
3060
- await ensureWorkspace(run)
3061
- if (run.mode === 'direct') await runDirect(run, parent, rt)
4549
+ await ensureWorkspace(run, parent)
4550
+ if (run.goalMode) {
4551
+ try {
4552
+ await runGoalLoop(run, parent, rt)
4553
+ } catch (error) {
4554
+ // Hitting the model-call or token budget aborts the controller inside
4555
+ // `spawn`. A goal run reports that as its stop reason instead of
4556
+ // turning a cap the caller set into an unexplained failure.
4557
+ if (rt.abortCause !== 'budget') throw error
4558
+ run.goalMode.stop = {
4559
+ reason: 'budget',
4560
+ detail: run.error ?? oneLine(error?.message, 300),
4561
+ at: new Date(now()).toISOString(),
4562
+ round: run.goalMode.rounds?.length ?? 0,
4563
+ }
4564
+ run.report = composeGoalReport(run)
4565
+ await save(run)
4566
+ }
4567
+ } else if (run.mode === 'direct') await runDirect(run, parent, rt)
3062
4568
  else await runPlanned(run, parent, rt)
3063
4569
 
3064
4570
  // Merge before the report: a conflict is part of what happened, and the
@@ -3164,19 +4670,37 @@ export function createOrchestrator(deps) {
3164
4670
  queue: wantsQueue = false,
3165
4671
  mode: requestedMode,
3166
4672
  approvePolicy = false,
4673
+ goalMode: requestedGoalMode = null,
4674
+ origin = null,
4675
+ reserveSlot = false,
4676
+ muted = false,
3167
4677
  }) {
3168
4678
  const trimmed = typeof goal === 'string' ? goal.trim() : ''
3169
4679
  if (!trimmed) throw new Error('goal is required')
3170
4680
  if (!parent || typeof parent !== 'object') throw new Error('superagent requires a live parent agent')
3171
4681
  const mode = normalizeMode(requestedMode)
4682
+ // Off unless the caller asks for it: a start with no goal spec behaves
4683
+ // exactly as it did before goal mode existed.
4684
+ const goalSpec = requestedGoalMode === null || requestedGoalMode === undefined
4685
+ ? null
4686
+ : normalizeGoalSpec(requestedGoalMode)
4687
+ // A goal budget can only narrow the operator's cap, exactly like the other
4688
+ // overrides, and it is kept so a resume spends against the same ceiling.
4689
+ const goalBudget = goalSpec?.budget
4690
+ ? {
4691
+ ...(goalSpec.budget.maxModelCalls === null ? {} : { maxModelCalls: goalSpec.budget.maxModelCalls }),
4692
+ ...(goalSpec.budget.maxTokens === null ? {} : { maxTokens: goalSpec.budget.maxTokens }),
4693
+ }
4694
+ : {}
3172
4695
 
3173
- const limits = buildLimits(overrides)
4696
+ const limits = buildLimits({ ...overrides, ...goalBudget })
3174
4697
  // Kept so a resume can rebuild the limits from the *current* config
3175
4698
  // instead of freezing whatever was set when the run first started.
3176
4699
  const keptOverrides = {}
3177
4700
  for (const key of ['maxSubtasks', 'maxParallel', 'deadlineMinutes']) {
3178
4701
  if (overrides[key] !== undefined && overrides[key] !== null) keptOverrides[key] = overrides[key]
3179
4702
  }
4703
+ for (const [key, value] of Object.entries(goalBudget)) keptOverrides[key] = value
3180
4704
  const dedupeKey = dedupeKeyOf(trimmed)
3181
4705
  // The goal claim is held across "list, check, write" so two processes
3182
4706
  // sharing a state directory cannot both conclude that nothing is running.
@@ -3194,8 +4718,39 @@ export function createOrchestrator(deps) {
3194
4718
  }
3195
4719
  }
3196
4720
  const waiting = queue.length
4721
+ const scheduled = origin?.kind === 'scheduled'
4722
+ if (scheduled) {
4723
+ const peer = await activePeerForScheduled(null, origin)
4724
+ if (peer) {
4725
+ // One plan, one active run. The scheduler turns this into a skipped
4726
+ // window; any other caller is told which run is in the way.
4727
+ const error = new Error(
4728
+ `schedule ${origin.scheduleId} already has an active run (${peer.id}); `
4729
+ + 'a plan runs one thing at a time',
4730
+ )
4731
+ error.code = 'schedule-busy'
4732
+ error.runId = peer.id
4733
+ throw error
4734
+ }
4735
+ }
3197
4736
  // A run already in line is first in line: a new start must not jump it.
3198
- const atCapacity = active >= maxActiveRuns() || waiting > 0
4737
+ // A scheduled start never queues and, when the plan asks for human
4738
+ // priority, never takes the last slot: a manual start must still find a
4739
+ // free slot even if the timer fired first. The check lives here, inside
4740
+ // the start gate, so a manual start cannot slip in between a scheduler
4741
+ // check and its spawn.
4742
+ const cap = scheduled && reserveSlot ? Math.max(1, maxActiveRuns() - 1) : maxActiveRuns()
4743
+ const atCapacity = scheduled
4744
+ ? active >= cap || waiting > 0
4745
+ : active >= maxActiveRuns() || waiting > 0
4746
+ if (scheduled && atCapacity) {
4747
+ const error = new Error(
4748
+ `scheduled start deferred: ${active} active run(s), ${waiting} waiting, and a scheduled run may use `
4749
+ + `${cap} of ${maxActiveRuns()} slot(s)${reserveSlot ? ' (one slot is reserved for manual runs)' : ''}`,
4750
+ )
4751
+ error.code = 'scheduled-deferred'
4752
+ throw error
4753
+ }
3199
4754
  if (atCapacity) {
3200
4755
  if (!queueEnabled(wantsQueue)) throw new Error(quotaMessage(active, waiting))
3201
4756
  if (waiting >= maxQueuedRuns()) {
@@ -3249,7 +4804,29 @@ export function createOrchestrator(deps) {
3249
4804
  dedupeKey,
3250
4805
  status: 'queued',
3251
4806
  mode,
4807
+ goalMode: goalSpec
4808
+ ? {
4809
+ enabled: true,
4810
+ acceptance: goalSpec.acceptance,
4811
+ maxRounds: goalSpec.maxRounds,
4812
+ maxWallClockMinutes: goalSpec.maxWallClockMinutes,
4813
+ noProgressRounds: goalSpec.noProgressRounds,
4814
+ budget: goalSpec.budget,
4815
+ cwd: goalSpec.cwd ?? process.cwd(),
4816
+ // Stamped when the loop actually starts, so a queued run is not
4817
+ // charged for the time it waited for a free slot.
4818
+ startedAt: null,
4819
+ rounds: [],
4820
+ stop: null,
4821
+ achieved: false,
4822
+ nextInstruction: null,
4823
+ }
4824
+ : null,
3252
4825
  queue: null,
4826
+ // Where this run came from. Null is a manual start, which is the shape
4827
+ // every existing run had, so old records and readers are unchanged.
4828
+ origin: origin ?? null,
4829
+ notifyMuted: muted === true,
3253
4830
  parentSessionId,
3254
4831
  clientTimeZone: clientTimeZone ?? null,
3255
4832
  createdAt: new Date(now()).toISOString(),
@@ -3370,6 +4947,17 @@ export function createOrchestrator(deps) {
3370
4947
  assertResumeOwner(run, parent)
3371
4948
  reopenCompleted = reopen || hasUnappliedAnswer(run)
3372
4949
  if (run.status === 'completed' && !reopenCompleted) return run
4950
+ // Resuming puts this run back to work, so it obeys the same one-active-
4951
+ // run-per-plan rule the timer does, under the same start gate. A plan
4952
+ // that already has a live run must be waited for or cancelled, not run
4953
+ // beside: two active runs are what made every later window skip.
4954
+ const peer = await activePeerForScheduled(run.id, run.origin)
4955
+ if (peer) {
4956
+ throw new Error(
4957
+ `run ${id} belongs to schedule ${run.origin.scheduleId}, which already has an active run `
4958
+ + `(${peer.id}); wait for it or cancel it before resuming this run`,
4959
+ )
4960
+ }
3373
4961
  // A resume spends the remaining budget again, so a per-run deny applies
3374
4962
  // to it as well; otherwise a policy added mid-run could be bypassed by
3375
4963
  // resuming the run instead of starting a new one.
@@ -3486,6 +5074,15 @@ export function createOrchestrator(deps) {
3486
5074
  // resume" work. Without this the old caps stayed in force forever.
3487
5075
  run.limits = buildLimits(run.overrides ?? {})
3488
5076
  run.deadlineAt = new Date(now() + run.limits.deadlineMinutes * 60000).toISOString()
5077
+ if (run.goalMode) {
5078
+ // A resume is a person asking the loop for another attempt: the round
5079
+ // and wall-clock allowances restart, while `rounds` keeps the history
5080
+ // the report and the next prompt still need.
5081
+ run.goalMode.roundBase = run.goalMode.rounds?.length ?? 0
5082
+ run.goalMode.startedAt = new Date(now()).toISOString()
5083
+ run.goalMode.stop = null
5084
+ run.goalMode.achieved = false
5085
+ }
3489
5086
  ensureCounters(run)
3490
5087
  await save(run)
3491
5088
  schedule(run, parent)
@@ -3829,6 +5426,37 @@ export function createOrchestrator(deps) {
3829
5426
  * Resolve once every run started by this process has finished. Used by tests
3830
5427
  * instead of sleeping, and by embedders that need a quiescent state.
3831
5428
  */
5429
+ /**
5430
+ * The quota as it stands, split by who started each run.
5431
+ *
5432
+ * The scheduler uses this for its report and to explain a deferral; the
5433
+ * reservation itself is enforced in `start()`, because only that path is
5434
+ * serialized with the quota check.
5435
+ */
5436
+ async function activeSnapshot() {
5437
+ try {
5438
+ await sweepOrphans()
5439
+ } catch (error) {
5440
+ log(`cannot check for orphaned runs: ${error?.message ?? error}`)
5441
+ }
5442
+ const runs = new Map()
5443
+ for (const run of await store.list()) runs.set(run.id, run)
5444
+ for (const [id, rt] of runtime) runs.set(id, rt.run)
5445
+ const active = [...runs.values()].filter(run => ACTIVE_STATUSES.has(run.status) && !isWaiting(run))
5446
+ const waiting = queue.map(entry => entry.run)
5447
+ const scheduled = run => run.origin?.kind === 'scheduled'
5448
+ return {
5449
+ active: active.length,
5450
+ scheduledActive: active.filter(scheduled).length,
5451
+ manualActive: active.filter(run => !scheduled(run)).length,
5452
+ waiting: waiting.length,
5453
+ scheduledWaiting: waiting.filter(scheduled).length,
5454
+ manualWaiting: waiting.filter(run => !scheduled(run)).length,
5455
+ maxActiveRuns: maxActiveRuns(),
5456
+ maxQueuedRuns: maxQueuedRuns(),
5457
+ }
5458
+ }
5459
+
3832
5460
  async function idle() {
3833
5461
  await Promise.all([...runtime.values()].map(rt => rt.promise?.catch(() => {})))
3834
5462
  }
@@ -3846,6 +5474,7 @@ export function createOrchestrator(deps) {
3846
5474
  list,
3847
5475
  idle,
3848
5476
  activeCount,
5477
+ activeSnapshot,
3849
5478
  liveRun,
3850
5479
  }
3851
5480
  }