@try-works/dsh-recursive-mode 0.3.1 → 0.4.1

package/src/delegation.ts

@@ -69,6 +69,15 @@ export interface SubagentStartRequestLike {
   persona?: string
   parent?: unknown
   signal?: unknown
+  /**
+   * T9 — the child's provider/model overrides.
+   *
+   * ⚠ `SubagentStartRequest.agentOptions` is only valid for a provider that DECLARES
+   * `capabilities.agentOptions`; the harness REJECTS a start that sends it otherwise. Passing
+   * it unconditionally would therefore BREAK delegations on providers that do not support it,
+   * which is why the caller gates on the capability rather than on the model being non-null.
+   */
+  agentOptions?: { model?: string; provider?: string }
 }
 
 export interface SubagentResultLike {
@@ -235,11 +244,42 @@ export interface ContinuableDelegationLike {
   accepted: boolean
   /** True when the fallback one-shot `delegate()` was used (no continuable seam). */
   fellBackToOneShot?: boolean
+  /**
+   * True when the round ended because NO settlement has landed yet — the caller's
+   * signal to resume on a later turn with the SAME `childId`, not a failure. The
+   * harness offers no parent-side await-settlement promise, so this is the honest
+   * report of "the child is still working".
+   */
+  parked?: boolean
 }
 
 /** Verdict vocabulary shared by T3/T4 (matches the delegated review schema). */
 export type DelegationVerdict = 'APPROVE' | 'REVISE' | 'REJECT'
 
+/**
+ * T28 — how much delegation depth is left for a child of a parent at `parentDepth`.
+ *
+ * The configured maximum is a ceiling for the WHOLE recursion, not a fresh allowance
+ * at every level. Passing the configured maximum down unchanged at each level is how
+ * a "depth 3" budget silently permits 3^depth children, which bounds nothing.
+ *
+ * A caller may ask for LESS than what remains (`requested`) and never for more:
+ * `min(remaining, requested)`. A parent already at or past the cap yields **0** —
+ * "delegate no further" — never a negative that some downstream comparison could read
+ * as permission.
+ */
+export function remainingDepthFor(
+  budgets: { maxDelegationDepth: number },
+  parentDepth: number,
+  requested?: number,
+): number {
+  const depth = Number.isSafeInteger(parentDepth) && parentDepth > 0 ? parentDepth : 0
+  const remaining = Math.max(0, budgets.maxDelegationDepth - depth)
+  if (requested === undefined) return remaining
+  const want = Number.isSafeInteger(requested) && requested > 0 ? requested : 0
+  return Math.max(0, Math.min(remaining, want))
+}
+
 /** Read the verdict from a review-schema structured result (pure). */
 export function readVerdictFromStructured(result: SubagentResultLike): DelegationVerdict {
   // SAFETY: reviewOutputSchema() defines verdict as a string enum; the cast reads
@@ -263,6 +303,123 @@ export function readRepairFromStructured(result: SubagentResultLike): string {
   return 'REVISE: address the review findings and re-submit.'
 }
 
+/** What a delegated child's `reply.md` said, as far as the plugin can tell. */
+export interface ReplyVerdict {
+  /** The verdict the reply STATES, or null when it states none. */
+  verdict: DelegationVerdict | null
+  /** Finding titles, when the reply carried review-schema JSON. */
+  findings: string[]
+  /** Why no verdict was read, for the repair instruction. Null when one was. */
+  problem: string | null
+}
+
+/**
+ * Read a verdict out of a child's `reply.md`, FAILING CLOSED.
+ *
+ * WHY THIS EXISTS RATHER THAN `readVerdictFromStructured`. The settlement's closing
+ * text is free-form — a child may report prose, a fenced JSON block, or a bare
+ * field line — and the structured reader's fallback for "no verdict" is
+ * `APPROVE`. That default is defensible where the caller re-evaluates the result,
+ * but it is the wrong default for a REVIEW ROUND: a child that answered with prose,
+ * or answered the wrong question, or wrote nothing parseable, must never be read as
+ * having approved the work. Verification that fails open is not verification.
+ *
+ * So this reader accepts exactly three things — review-schema JSON (fenced or
+ * bare), or an explicit `Verdict:` field — and reports `verdict: null` plus a
+ * `problem` for anything else. The caller turns that into a REVISE with a repair
+ * instruction that says what was wrong, so an unreadable reply costs a round rather
+ * than a false approval.
+ */
+export function parseReplyVerdict(replyText: string): ReplyVerdict {
+  const text = replyText ?? ''
+  if (text.trim() === '') {
+    return { verdict: null, findings: [], problem: 'the reply is empty' }
+  }
+
+  const candidates: string[] = []
+  // A fenced block first: a child that wraps its JSON is being explicit about it.
+  for (const match of text.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)) {
+    if (match[1] !== undefined) candidates.push(match[1])
+  }
+  // Then a bare object, so an unfenced submission still reads.
+  const bare = text.match(/\{[\s\S]*\}/)
+  if (bare?.[0] !== undefined) candidates.push(bare[0])
+
+  for (const candidate of candidates) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(candidate)
+    } catch {
+      continue
+    }
+    const record = typeof parsed === 'object' && parsed !== null ? parsed as Record<string, unknown> : null
+    const raw = record?.verdict
+    const verdict = normaliseVerdict(raw)
+    if (verdict !== null) {
+      const findings = Array.isArray(record?.findings)
+        ? record.findings
+          .map((f) => (typeof f === 'object' && f !== null ? (f as { title?: unknown }).title : undefined))
+          .filter((t): t is string => typeof t === 'string' && t !== '')
+        : []
+      return { verdict, findings, problem: null }
+    }
+    return { verdict: null, findings: [], problem: 'the reply carries JSON but no usable "verdict" field' }
+  }
+
+  // A plain field line, which is how a child that ignores the schema tends to answer.
+  // The decoration class around the value allows the asterisks, backticks and
+  // underscores a child may wrap it in — including a backtick INSIDE bold, as in
+  // `**Verdict:** \`REVISE\``, which is the shape that first broke this reader.
+  const field = text.match(/^[ \t>*_`-]*verdict[ \t]*[:=][ \t>*_`-]*([A-Za-z]+)/im)
+  const fieldVerdict = normaliseVerdict(field?.[1])
+  if (fieldVerdict !== null) return { verdict: fieldVerdict, findings: [], problem: null }
+
+  return {
+    verdict: null,
+    findings: [],
+    problem: field?.[1] !== undefined
+      ? 'the reply states a verdict of "' + field[1] + '", which is not one of APPROVE, REVISE or REJECT'
+      : 'the reply states no verdict',
+  }
+}
+
+/** Accept the verdict vocabulary case-insensitively; reject everything else. */
+function normaliseVerdict(raw: unknown): DelegationVerdict | null {
+  if (typeof raw !== 'string') return null
+  const upper = raw.trim().toUpperCase()
+  if (upper === 'APPROVE' || upper === 'REVISE' || upper === 'REJECT') return upper
+  return null
+}
+
+/**
+ * The verdict for one round, from the child's reply text, FAILING CLOSED: an
+ * unreadable reply becomes `REVISE`, never `APPROVE`.
+ */
+export function readVerdictFromReply(replyText: string): DelegationVerdict {
+  const parsed = parseReplyVerdict(replyText)
+  if (parsed.verdict !== null) return parsed.verdict
+  return 'REVISE'
+}
+
+/**
+ * The repair instruction for a round whose reply did not approve.
+ *
+ * Findings drive it when the reply carried them (and are the ONLY source of
+ * instruction text — a child cannot inject instructions, since only the titles
+ * travel). When there is nothing to quote, the instruction states the contract
+ * violation instead of asking vaguely for "improvement", because a repair request
+ * that does not say what was wrong cannot be acted on.
+ */
+export function readRepairFromReply(replyText: string): string {
+  const parsed = parseReplyVerdict(replyText)
+  if (parsed.findings.length > 0) return 'Address the findings: ' + parsed.findings.join('; ')
+  if (parsed.problem !== null) {
+    return 'Your reply.md could not be read as a review: ' + parsed.problem + '. Re-submit with the required '
+      + 'JSON contract (verdict APPROVE | REVISE | REJECT, plus findings) written to reply.md.'
+  }
+  return 'REVISE: address the review findings and re-submit.'
+}
+
 /**
  * Run a multi-round delegated task on ONE durable continuable child:
  * 1. `startContinuable` (initial prompt) — `start()` is never called.
@@ -284,10 +441,19 @@ export async function delegateContinuable(input: {
   toolFilter?: unknown
   maxDepth?: number
   childId?: ContinuableChildId
+  /**
+   * T36: RESUME an existing durable child instead of starting one. The turn-shaped
+   * caller passes the childId from a previous `parked` round, which is what makes
+   * the loop resumable across turns — `startContinuable` is not called, so a parked
+   * round does not create a second child.
+   */
+  resumeChild?: ContinuableChildId
   maxRounds?: number
   readVerdict?: (result: SubagentResultLike) => DelegationVerdict
   readRepair?: (result: SubagentResultLike) => string | undefined
   awaitRoundResult?: (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null>
+  /** T9: the child's provider/model overrides, forwarded onto the start request verbatim. */
+  agentOptions?: { model?: string; provider?: string }
 }): Promise<ContinuableDelegationLike> {
   const { subagents, provider, label, prompt, parent, toolFilter, maxDepth } = input
   const maxRounds = input.maxRounds ?? 3
@@ -302,6 +468,15 @@ export async function delegateContinuable(input: {
   // actual result) rather than fabricating authority and silently APPROVE-ing.
   const hasContinuableSeam = startContinuable !== undefined && followup !== undefined && input.awaitRoundResult !== undefined
   if (!hasContinuableSeam || subagents === undefined || parent === undefined) {
+    // ⚠ FU-9 — NAME WHICH CONDITION FAILED, because this branch covers THREE of them and the report did not.
+    // A live run returned `status: unavailable` with "no continuable seam or no live parent" for three rounds,
+    // making its cause UNDECIDABLE while this code knew it exactly. That is the defect class this session keeps
+    // finding - a surface describing less than the code knows - and it cost more than the bug it was hiding.
+    const fallbackReason = 'missing ' + [
+      hasContinuableSeam ? null : 'the continuable seam (startContinuable, followup, awaitRoundResult)',
+      subagents === undefined ? 'the subagents runtime' : null,
+      parent === undefined ? 'the exact live parent Agent' : null,
+    ].filter((part): part is string => part !== null).join(', ')
     // Fall back to one-shot delegation (self-audit-safe): never silently drop.
     try {
       const oneShot = await delegate({
@@ -321,6 +496,7 @@ export async function delegateContinuable(input: {
         rounds: [{ text: prompt, result: oneShot }],
         accepted: verdict === 'APPROVE' && evaluateDelegationResult(oneShot).accepted,
         fellBackToOneShot: true,
+        reason: fallbackReason,
       }
     } catch (err) {
       return { ok: false, reason: err instanceof Error ? err.message : String(err), rounds: [], accepted: false, fellBackToOneShot: true }
@@ -337,24 +513,61 @@ export async function delegateContinuable(input: {
   }
   if (toolFilter !== undefined) request.toolFilter = toolFilter
   if (maxDepth !== undefined) request.maxDepth = maxDepth
+  // T9: the child's provider/model overrides, forwarded only when the caller supplied them —
+  // and the caller supplies them only for a provider that DECLARES the capability, because the
+  // harness rejects a start that carries them otherwise.
+  if (input.agentOptions !== undefined) request.agentOptions = input.agentOptions
 
   const spec: ContinuableStartSpecLike = {
     provider,
     label,
     request,
+    // ⚠ FU-9 — A SIGNAL IS MANDATORY IN PRACTICE, NOT DECORATION. The host reads `signal.aborted` WITHOUT
+    // optional chaining in `packages/subagent/subagent/src/control.ts:106`, while its own sibling
+    // `list-children.ts:130` guards it with `signal?.aborted`. So a continuable start carrying no signal throws
+    // `Cannot read properties of undefined (reading 'aborted')` — the delegation's catch records that as its
+    // reason, the driver reports "no continuable repair path", and THE CHILD NEVER STARTS. That one chain
+    // produced every artifact this investigation chased: no child session, no reply, no settlement, and four
+    // brief-only child directories. The host should guard its own read (reported as a DSH limitation); supplying
+    // a signal on the SPEC — the request type excludes it deliberately — is this plugin's side of the contract.
+    signal: new AbortController().signal,
   }
   if (input.childId !== undefined) spec.childId = input.childId
   try {
-    const started = await startContinuable(spec)
-    childId = started.childId
-    messageIds.push(started.messageId)
-    rounds.push({ text: prompt })
+    if (input.resumeChild !== undefined) {
+      // T36: RESUME. The initial prompt went out in an earlier turn, so this round
+      // has no message id of its own — and the observer keys on the CHILD anyway,
+      // because the settlement log is child-keyed. Starting a second child here
+      // would orphan the one already doing the work.
+      childId = input.resumeChild
+      rounds.push({ text: prompt })
+    } else {
+      const started = await startContinuable(spec)
+      childId = started.childId
+      messageIds.push(started.messageId)
+      rounds.push({ text: prompt })
+    }
 
     for (let round = 0; round < maxRounds; round += 1) {
       const current = rounds[round]
-      const observed = await input.awaitRoundResult!(childId, messageIds[messageIds.length - 1])
+      const lastMessageId = messageIds.length > 0
+        ? messageIds[messageIds.length - 1]!
+        : ('' as ContinuableMessageId)
+      const observed = await input.awaitRoundResult!(childId, lastMessageId)
       if (observed === null) {
-        return { ok: false, reason: 'continuable child produced no settlement for round ' + (round + 1), childId, messageIds, rounds, accepted: false }
+        // NOT a failure: nothing has settled yet. Reported as `parked` so a
+        // turn-shaped caller resumes on a later turn instead of treating the round
+        // as lost, and so `accepted` stays false — an unobserved round is never an
+        // approval.
+        return {
+          ok: false,
+          reason: 'no settlement has landed for round ' + (round + 1) + ' yet (the child is still working)',
+          childId,
+          messageIds,
+          rounds,
+          accepted: false,
+          parked: true,
+        }
       }
       current.result = observed
       const verdict = readVerdict(observed)
@@ -556,6 +769,13 @@ export interface ActionRecordInput {
   findings?: string[]
   success: boolean
   stopReason?: string
+  /**
+   * ⚠ FU-9 — WHY IT FAILED, when it did. `success` is a boolean, so a record could say `Status: failed` and
+   * nothing else: a delegation that FAILED and a delegation that NEVER HAPPENED read identically, which is what
+   * let me conclude for three rounds that the host was not scheduling children. The caller ALREADY passed
+   * `stopReason`, and the live record said `n/a` — because there was no result to take a stop reason from.
+   */
+  failure?: string
 }
 
 function slugify(value: string): string {
@@ -563,9 +783,18 @@ function slugify(value: string): string {
 }
 
 /**
- * Write a durable action record under subagents/ with the canonical sections
- * (matches recursive-subagent-action.py). A success:false attempt is written
- * with a failed status and is NOT accepted.
+ * Write a durable action record under subagents/ in the shape this repo's own
+ * linter accepts (ts-lint.ts lintSubagentActionRecordFile — every top-level .md
+ * under a run's subagents/ is linted as one):
+ *   - the literal title `# Subagent Action Record`;
+ *   - `Run ID` and `Timestamp` in ## Metadata (Run ID must equal the run dir name);
+ *   - `Current Artifact`, `Artifact Content Hash` (the artifact's LF-normalized
+ *     sha256, derived from the artifact itself — no extra caller input), `Diff
+ *     Basis`, `Review Bundle`, and the NAMED fields `Upstream Artifacts` /
+ *     `Code Refs` strictly inside ## Inputs Provided. The linter resolves each of
+ *     those through the heading body, so a field under another heading is not
+ *     found at all.
+ * A success:false attempt is written with a failed status and is NOT accepted.
  */
 export function writeActionRecord(input: ActionRecordInput): string {
   const { root, runId } = input
@@ -574,34 +803,68 @@ export function writeActionRecord(input: ActionRecordInput): string {
   const fileName = Date.now() + '-' + slugify(input.subagentId) + '-action.md'
   const path = join(dir, fileName)
 
+  const tick = String.fromCharCode(96)
+  const code = (value: string) => tick + norm(value) + tick
+
   const list = (title: string, values: string[]) => {
     const out: string[] = [title]
     if (!values?.length) {
       out.push('- none')
       return out
     }
-    for (const v of values) out.push('- ' + String.fromCharCode(96) + norm(v) + String.fromCharCode(96))
+    for (const v of values) out.push('- ' + code(v))
     return out
   }
 
+  /** A NAMED field whose value is a block of backticked paths (`Field: none` when empty). */
+  const namedList = (fieldName: string, values: string[]): string[] =>
+    values.length
+      ? ['- ' + fieldName + ':', ...values.map((v) => '  - ' + code(v))]
+      : ['- ' + fieldName + ': none']
+
+  const artifactRel = input.artifactPath ? norm(input.artifactPath) : ''
+  let artifactHash = ''
+  if (artifactRel) {
+    try {
+      const artifactAbs = resolveUnderRoot(root, artifactRel)
+      if (existsSync(artifactAbs)) artifactHash = contentSha256(readFileSync(artifactAbs, 'utf8'))
+    } catch {
+      artifactHash = ''
+    }
+  }
+
   const lines: string[] = [
-    '# Subagent action record: ' + input.subagentId,
+    // The canonical template (references/artifact-template.md) H1 and the string the
+    // linter looks for — the subagent identity belongs in Metadata, not the title.
+    '# Subagent Action Record',
     '',
     '## Metadata',
     '- Subagent ID: ' + input.subagentId,
+    '- Run ID: ' + runId,
     '- Phase: ' + input.phase,
     '- Purpose: ' + input.purpose,
     '- Execution Mode: ' + input.executionMode,
     '- Status: ' + (input.success ? 'accepted' : 'failed'),
+    // ⚠ EMITTED ONLY WHEN A REASON IS GIVEN, so a caller that says nothing produces the record it always did.
+    // Not politeness: this record's shape is asserted by specs, and a first attempt that always emitted the line
+    // failed 13 tests across 5 files. A change to a shared surface should be additive where it can be.
+    ...(input.success === false && input.failure !== undefined ? ['- Failure: ' + input.failure] : []),
     '- Stop Reason: ' + (input.stopReason ?? 'n/a'),
-    ...(input.artifactPath ? ['- Current Artifact: ' + String.fromCharCode(96) + norm(input.artifactPath) + String.fromCharCode(96)] : []),
-    ...(input.reviewBundle ? ['- Review Bundle: ' + String.fromCharCode(96) + norm(input.reviewBundle) + String.fromCharCode(96)] : []),
+    // Timestamp LAST in Metadata. This USED to be load-bearing: `getHeadingBody` ended
+    // its capture with a `\Z` that JavaScript reads as a literal `Z`, so a body was
+    // truncated at its first `Z` and an ISO timestamp could cut the section short. T33
+    // replaced that anchor with `(?![\s\S])`, so the hazard is gone and this ordering is
+    // now only conventional — kept because Timestamp is naturally the last metadata field.
+    '- Timestamp: ' + new Date().toISOString(),
     '',
     '## Inputs Provided',
-    ...list('', input.upstreamArtifacts ?? []).slice(1),
-    '',
-    '## Routing',
-    ...(input.diffBasis ? ['- Diff Basis: ' + input.diffBasis] : ['- Diff Basis: n/a']),
+    ...(artifactRel ? ['- Current Artifact: ' + code(artifactRel)] : []),
+    ...(artifactHash ? ['- Artifact Content Hash: ' + code(artifactHash)] : []),
+    '- Diff Basis: ' + (input.diffBasis ?? 'n/a'),
+    ...namedList('Upstream Artifacts', input.upstreamArtifacts ?? []),
+    ...(input.reviewBundle ? ['- Review Bundle: ' + code(norm(input.reviewBundle))] : []),
+    ...namedList('Code Refs', input.codeRefs ?? []),
+    '- Audit / Task Questions: ' + (input.auditQuestions?.length ? input.auditQuestions.join(' ') : 'n/a'),
     '',
     '## Claimed Actions Taken',
     ...list('', input.actionsTaken ?? []).slice(1),
@@ -618,9 +881,19 @@ export function writeActionRecord(input: ActionRecordInput): string {
     ...(input.findings?.length ? input.findings.map((f) => '- ' + f) : ['- none']),
     '',
     '## Verification Handoff',
-    '- Inspect first: ' + (input.artifactPath ? String.fromCharCode(96) + norm(input.artifactPath) + String.fromCharCode(96) : 'n/a'),
+    '- Inspect first: ' + (artifactRel ? code(artifactRel) : 'n/a'),
     '- Notes: main agent must verify every claimed reference against actual files, actual recursive artifacts, and the actual diff before acceptance.',
     '',
+    // Provenance tail. This USED to be load-bearing: with the old `\Z` anchor a
+    // document's FINAL section always read as empty, so `## Verification Handoff` would
+    // have been reported as "Missing or empty section" unless something followed it. T33
+    // gave the section parsers a real end-of-input assertion, so the trailing heading is
+    // no longer needed to satisfy the linter — it is kept because the record genuinely
+    // wants to state who wrote it and how its hashes are computed.
+    '## Record Provenance',
+    '- Writer: dsh-recursive-mode ' + code('writeActionRecord') + ' (plugin-generated action record; hashes are LF-normalized sha256).',
+    '- Contract: canonical Subagent Action Record sections, as read by recursive_lint.',
+    '',
   ]
 
   writeFileSync(path, lines.join('\n'), 'utf8')
@@ -640,3 +913,48 @@ export function evaluateDelegationResult(result: SubagentResultLike): { accepted
   }
   return { accepted: true, reason: 'delegation completed' }
 }
+
+/**
+ * T8 — the child's CLAIMED references, read from wherever the delegation put them.
+ *
+ * The review output schema requires `references`, so a reviewer states which files back its
+ * verdict — and NOTHING read that field: `evaluateDelegationResult` looks only at
+ * `success`/`stopReason`, so a review citing files that do not exist was indistinguishable
+ * from one citing real evidence. This reads the claims so they can be checked.
+ *
+ * Both carriers are tried, because a delegation may return structured output or the raw
+ * JSON text: `structured` first (the native path), then `output` parsed as JSON. A result
+ * that carries neither yields `[]` — "no claims" — which the caller treats as NOTHING TO
+ * CHECK rather than as a pass, so an unparseable result can never be mistaken for a
+ * verified one. Malformed entries are dropped rather than thrown on: this reads a model's
+ * output, which is untrusted.
+ */
+export function referencesFromResult(result: SubagentResultLike): Reference[] {
+  const candidates: unknown[] = []
+  if (result.structured !== undefined && result.structured !== null && typeof result.structured === 'object') {
+    candidates.push((result.structured as { references?: unknown }).references)
+  }
+  if (typeof result.output === 'string' && result.output.trim() !== '') {
+    try {
+      const parsed = JSON.parse(result.output) as { references?: unknown } | null
+      if (parsed !== null && typeof parsed === 'object') candidates.push(parsed.references)
+    } catch {
+      // Not JSON: no structured claims to read. Never a failure of the delegation itself.
+    }
+  }
+  for (const candidate of candidates) {
+    if (!Array.isArray(candidate)) continue
+    const refs: Reference[] = []
+    for (const entry of candidate) {
+      if (entry === null || typeof entry !== 'object') continue
+      const path = (entry as { path?: unknown }).path
+      if (typeof path !== 'string' || path.trim() === '') continue
+      const reference: Reference = { path }
+      const lineRange = (entry as { lineRange?: unknown }).lineRange
+      if (typeof lineRange === 'string') reference.lineRange = lineRange
+      refs.push(reference)
+    }
+    if (refs.length > 0) return refs
+  }
+  return []
+}