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

package/src/index.ts

@@ -1,8 +1,14 @@
 import { type Context } from '@deepseek-ai/cordis'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { ContextFormed } from '@deepseek-ai/dsh-llm'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { RecursiveRuntime } from './runtime.ts'
+import type { JobsRegistryLike } from './jobs-runner.ts'
+import { planGateForExit } from './plan-gate.ts'
+import { registerPhaseSkills, type SkillRegistryLike } from './skills-phase.ts'
+import type { WorkflowEngineLike } from './workflow-audit.ts'
+import type { RecursiveModeConfig } from './config.ts'
 import { createRecursiveStatusTool } from './recursive_status.tool.ts'
 import { createRecursiveInitTool } from './recursive_init.tool.ts'
 import { createRecursiveLockTool } from './recursive_lock.tool.ts'
@@ -12,8 +18,14 @@ import { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
 import { createRecursiveWorktreeTool } from './recursive_worktree.tool.ts'
 import { createRecursivePhaseTool } from './recursive_phase.tool.ts'
 import { createRecursiveAuditTeamTool } from './recursive_audit_team.tool.ts'
+import { createRecursiveReviewTool } from './recursive_review.tool.ts'
+import { createRecursiveDelegateTool } from './recursive_delegate.tool.ts'
+import { createRecursiveAskTool } from './recursive_ask.tool.ts'
+import { createRecursivePreviewTool } from './recursive_preview.tool.ts'
+import type { SubagentsRuntimeLike } from './delegation.ts'
 import { registerRecursiveCommand } from './commands.ts'
-import { evaluateToolGuard, coerceAskToDecision } from './enforcement.ts'
+import { evaluateToolGuard, coerceAskToDecision, type ToolGuardDecision } from './enforcement.ts'
+import { appendGuardDecision, appendObservedTamper, type GuardDecisionRecord } from './guard-log.ts'
 import type { GoalServiceLike } from './goals-projection.ts'
 import type { TeamRuntimeLike } from './teams-loop.ts'
 import { renderRecursivePolicy } from './policy.ts'
@@ -22,11 +34,47 @@ import { snapshotWorkspace } from './snapshot.ts'
 import { mountRecursiveRoutesOnce, makeRecursiveRoutes, type RecursiveRouteHost } from './live-route.ts'
 import { registerRecursiveSkill } from './skills.ts'
 import { enumerateRuns, stageBWorkflowInit } from './bootstrap.ts'
-import { getNextLegalPhase, getLockStatus } from './lock.ts'
+import { getNextLegalPhase, getLockStatus, PHASE_SEQUENCE } from './lock.ts'
+import { adoptSettlement } from './settlement.ts'
+import type { LlmInventoryLike } from './model-inventory.ts'
+import { resolveRunDir } from './run.ts'
 import { phaseLintRulesMessage, ReminderOnceGate } from './phase-rules.ts'
+import { settlementFromEvent, runDirForChild, recordSettlement } from './settlement.ts'
+
+/**
+ * rc.2 rebase (T31a) — the message-source vocabulary changed under us.
+ *
+ * At `dsh-v0.1.1-rc.2` `MessageSourceMap` carried a shared catch-all
+ * `plugin: { kind: 'plugin'; plugin: string }` entry, which this file used for
+ * its injected phase-lint reminder. At `dsh-v0.2.0-rc.2` that entry is GONE:
+ * the map is merge-extensible and, in its own words, "each producer declares
+ * its own `kind` in its own module; there is no shared catch-all `plugin`
+ * kind". This was invisible in the old checkout because its `node_modules`
+ * still held a stale `dsh-llm`.
+ *
+ * The idiom below is copied from the shipped `@deepseek-ai/dsh-repeat-tool-reminder`,
+ * whose pre-step reminder is the closest analogue to ours: a user-role message
+ * whose source declares its own kind and a `form: 'notice'` one-line account.
+ */
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'recursive-mode': { kind: 'recursive-mode' } & ContextFormed
+  }
+}
+
+/** Producer source stamped on every injected phase-lint reminder. */
+const REMINDER_SOURCE = { kind: 'recursive-mode' } as const
 
 export const name = '@try-works/dsh-recursive-mode'
 
+/**
+ * T7: the plugin's Config schema, which the settings service DISCOVERS (see `src/config.ts`
+ * for why declaring it is the registration). Re-exported from the entry because the Loader
+ * reads it from the plugin module.
+ */
+export { Config } from './config.ts'
+export type { RecursiveModeConfig } from './config.ts'
+
 export { RecursiveRuntime } from './runtime.ts'
 export { createRecursiveStatusTool } from './recursive_status.tool.ts'
 export { createRecursiveInitTool } from './recursive_init.tool.ts'
@@ -93,7 +141,57 @@ export const inject = ['tools']
  * repo/run work and NO session-event emission here: zero recursive/* events
  * are ever appended (resume-crash fix), and the board reads the live fs route.
  */
-export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: string }) {
+/** T38: the built-in guard's hook name — the chain's identity for "this was the plugin's own". */
+const BUILTIN_GUARD_HOOK_NAME = 'builtin-tool-guard'
+
+/**
+ * T38 — the tool guard, as a function rather than an inline block.
+ *
+ * Extracted so the SAME code can run as a hook on the registry: a built-in and a
+ * sibling then share one chain, one ordering rule and one failure policy, instead of
+ * the built-in being privileged code that always runs first. Every side effect stays
+ * here — the guard-decision log is written by whoever computes the decision, so moving
+ * the call site cannot lose it.
+ *
+ * The `ask` coercion is unchanged and stays key-frozen: `coerceAskToDecision`'s output
+ * is asserted with an exact `toEqual`, so the rebuilt object carries the guard's `rule`
+ * and `transition` forward rather than letting the coercion drop them.
+ */
+function runToolGuard(
+  recursive: RecursiveRuntime,
+  exec: unknown,
+  root: string,
+  runId: string,
+): ToolGuardDecision {
+  const guardMode = recursive.enforcementConfig.toolGuards
+  const decision = evaluateToolGuard(exec as never, root, runId, guardMode)
+  const coerced = coerceAskToDecision(decision, guardMode)
+  const final: ToolGuardDecision = coerced === decision
+    ? decision
+    : { ...coerced, rule: decision.rule, transition: decision.transition }
+  // T15 (C/D): every decision is logged — allows included — so the rolling trace shows
+  // what the guard decided AND why, not only refusals. File-backed evidence in the
+  // control-plane config dir: zero session-event emission.
+  if (root) {
+    const record: GuardDecisionRecord = {
+      at: new Date().toISOString(),
+      runId,
+      tool: (exec as { name?: string } | null)?.name ?? '',
+      kind: final.kind,
+      rule: final.rule ?? 'none',
+    }
+    if (final.kind === 'allow') {
+      if (final.warn) record.reason = final.warn
+    } else if (final.reason) {
+      record.reason = final.reason
+    }
+    if (final.transition) record.transition = final.transition
+    appendGuardDecision(root, record)
+  }
+  return final
+}
+
+export function apply(ctx: Context, config?: RecursiveModeConfig) {
   // R4 shell split (02-to-be-plan.addendum-r4-r2-mount-resolution.md): the
   // global bare-name row in cordis.patch.yml mounts with config.shellOnly=true
   // to expose ONLY the client bundle for client discovery. It must register
@@ -112,7 +210,58 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
     // SAFETY: the goals service is an optional host service (could be absent); the
     // run projection treats null as "no goal backing" and never throws.
     const goals = ctx.get('goals') as GoalServiceLike | null
-    const recursive = new RecursiveRuntime(ctx, { repoRoot: config?.repoRoot ?? process.cwd(), workspaceRegistry, goals })
+    // T10: the native jobs registry, when the composition mounts one. OPTIONAL on purpose —
+    // a long operation must still run, and say it was untracked, rather than fail because no
+    // board is attached.
+    const jobs = ctx.get('jobs') as JobsRegistryLike | undefined
+    // T39: the subagents seam is resolved HERE, at the composition, so the runtime can fall back
+    // to it when a caller passes none. Measured reason: `recursive_review.tool.ts` — the only
+    // production caller of `delegateReview` — passes no seam, and the runtime then reported
+    // "no ctx.subagents runtime available" on a host that had mounted it all along.
+    const subagentsSeamForRuntime = ctx.get('subagents') as SubagentsRuntimeLike | undefined
+    const recursive = new RecursiveRuntime(ctx, { repoRoot: config?.repoRoot ?? process.cwd(), workspaceRegistry, goals, jobs, subagents: subagentsSeamForRuntime ?? null, workflow: ctx.get('workflow') as WorkflowEngineLike | undefined ?? null })
+    // ⚠ FU-9 — AND RESOLVE IT AGAIN WHENEVER THE SERVICE APPEARS, because the one-shot get above is only a
+    // fast path. A live run proved the cost of relying on it: the review fell back to self-audit and reported
+    // `Status: failed` while a child DIRECTORY sat there — written by this plugin's own brief writer, before
+    // any service call — so the artifact looked like a started child and was not. `ctx.inject` is the
+    // harness's own pattern for a service that may be mounted by a later layer, and it fires immediately when
+    // the service is already present, so this is a guarantee rather than a second chance.
+    ctx.inject(['subagents'], (subagentsCtx: Context) => {
+      recursive.attachSubagents((subagentsCtx.get('subagents') as SubagentsRuntimeLike | undefined) ?? null)
+    })
+    // ⚠ FU-19 — AND THE LLM INVENTORY, the same late-attaching way: `ctx.llm` is what the browser model catalog is
+    // built from, so it is the service that knows which providers and models this host actually has. Resolved
+    // optionally — a host without it gets the `unverified` verdict rather than a silent approval.
+    const llmInventory = ctx.get('llm') as LlmInventoryLike | undefined
+    recursive.attachLlmInventory(llmInventory ?? null)
+    ctx.inject(['llm'], (llmCtx: Context) => {
+      recursive.attachLlmInventory((llmCtx.get('llm') as LlmInventoryLike | undefined) ?? null)
+    })
+
+    // T7 — THE SETTINGS NAMESPACE, APPLIED ON EVERY APPLY. The settings service edits the
+    // Loader entry's config and the Loader RE-APPLIES this plugin, so a toggle in the UI
+    // lands on this line: the re-application IS the hot reload, and there is deliberately
+    // no watcher or file poller here to drift out of sync with it.
+    //
+    // Guarded on PRESENCE rather than truthiness: `enforcement: undefined` means "the
+    // caller said nothing", which must leave the runtime's own default alone, while an
+    // explicit object — including one whose fields the schema defaulted — is a decision.
+    // Validation stays in `resolveEnforcementConfig` (strict, fail-loud), so a bad value
+    // from any source is refused rather than coerced.
+    if (config?.enforcement !== undefined) recursive.setEnforcementConfig(config.enforcement)
+
+    // T12 — publish each phase's rules to the native SKILL catalogue, so the agent and its
+    // children can ASK what a phase requires instead of grepping this checkout. The catalogue is
+    // optional; with none mounted this registers nothing and says so, because a composition
+    // without skills should still run the workflow.
+    const phaseSkills = registerPhaseSkills(ctx.get('skills') as SkillRegistryLike | undefined, PHASE_SEQUENCE)
+    // Tied to this plugin's effects: the contribution is withdrawn with the fiber that made it.
+    yield () => { for (const dispose of phaseSkills.disposers) dispose() }
+
+    // T7 part 2 — the ROUTER overrides, on the same terms: present means override, absent
+    // means defer to the workspace's declarative `recursive-router.json`. ONE PATH, NOT
+    // TWO: this does not replace the file, it lays over it (see `loadRouterPolicy`).
+    if (config?.router !== undefined) recursive.setRouterOverrides(config.router)
 
     const repairedRoots = new Set<string>()
     const reminderGate = new ReminderOnceGate()
@@ -126,6 +275,11 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
     // live service's real Agent parameter is a superset of TeamCallerHandle, so
     // the seam passes the exact live Agent the tool extracts from exec.agent.
     const agentTeams = ctx.get('agentTeams') as TeamRuntimeLike | undefined
+    // T36: the continuable-subagent seam the review tool drives. Optional for the
+    // same reason as agentTeams — absent it, `recursive_review` still runs and
+    // reports `unavailable`, naming that the repair path does not exist rather than
+    // pretending the review was a success.
+    const subagentsSeam = subagentsSeamForRuntime
 
     // Packaged skill (dsh plugin standard): register the `recursive-mode` skill
     // into the host skills registry via ctx.skills.registerProvider (the
@@ -143,6 +297,16 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
       ctx.tools.register(createRecursiveScratchTool(recursive)),
       ctx.tools.register(createRecursiveWorktreeTool(recursive)),
       ctx.tools.register(createRecursivePhaseTool(recursive)),
+      ctx.tools.register(createRecursiveReviewTool(recursive, subagentsSeam)),
+    // ⚠ FU-17 — WORK delegation: the main agent hands a phase's actual work to a child, reads it, and sends
+    // feedback to the same child. Registered beside the review tool because they share the round driver, the
+    // settlement observer and the reply contract — the difference is what a settlement MEANS.
+    ctx.tools.register(createRecursiveDelegateTool(recursive, subagentsSeam)),
+    // T23: the three human gates as structured decisions. Registered here so the ask is a TOOL call
+    // — which is what the host renders as a card — rather than prose a person has to interpret.
+    ctx.tools.register(createRecursiveAskTool(recursive)),
+    // T26: the read-only view of what the enforcement contract will do, before it fires.
+    ctx.tools.register(createRecursivePreviewTool(recursive)),
       ...(agentTeams ? [ctx.tools.register(createRecursiveAuditTeamTool(agentTeams))] : []),
     ]
 
@@ -186,30 +350,232 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
 
     // Phase C R4: tools/pre-execute surgical guards (Layer 2, caller of the
     // transition set). Scope-filtered to the active run's worktree.
+    //
+    // T15 — this listener used to hand `evaluateToolGuard` an EMPTY runId, so its
+    // `runDir` resolved to `<root>/.recursive/run` — the directory that holds run
+    // DIRECTORIES, not artifacts. The monotonic lock-order and Phase-3 TDD
+    // branches could therefore never fire; only the locked-write branch worked
+    // (it resolves its target path directly). The REAL active run id is now
+    // resolved per call, the same way recursive_status/phaseRules do it.
+    const sessionsStore = ctx.get('sessions') as
+      | { get?: (id: string) => { header?: { cwd?: string } } | undefined }
+      | undefined
+    // T38 — THE BUILT-IN GUARD IS NOW A HOOK ON THE SAME CHAIN AS EVERYONE ELSE.
+    //
+    // Registered at PRIORITY 0 so a sibling with a higher priority runs FIRST and can
+    // pre-empt it cheaply — which is the point of participation. The guard stays the
+    // baseline that runs when nobody objects.
+    //
+    // `fail_closed` because this is a GATING point: a guard that cannot decide must not
+    // let the call through. The FULL decision rides back as an annotation, so `ask` and
+    // `allow` survive with `warn`/`rule`/`transition` intact — the listener returns that
+    // object VERBATIM, which is what keeps `guard-path` byte-identical.
+    recursive.hooks.register('pre_trigger', {
+      name: BUILTIN_GUARD_HOOK_NAME,
+      priority: 0,
+      onError: 'fail_closed',
+      run: (input) => {
+        const payload = input as { exec?: unknown; root?: string; runId?: string }
+        const decision = runToolGuard(recursive, payload.exec, payload.root ?? '', payload.runId ?? '')
+        return decision.kind === 'deny'
+          ? { decision: 'deny' as const, reason: decision.reason ?? 'denied by the tool guard', annotations: { guardDecision: decision } }
+          : { decision: 'continue' as const, annotations: { guardDecision: decision } }
+      },
+    })
+    // T13 (part 2) — THE PLAN GATE IS LIVE. `exit_plan_mode` is the event that leaves plan mode,
+    // so it is where the gate belongs: a run still waiting on a DISCOVERY phase must not leave
+    // plan mode, because that would start implementing on an unfinished plan. The gate reads the
+    // phase the run is already waiting on rather than keeping its own state, which is why it
+    // cannot drift from the workflow.
+    //
+    // Priority 5, ABOVE the built-in tool guard at 0: this is a workflow-shaped refusal and
+    // should be the reason a caller sees, not something the generic guard has to restate.
+    recursive.hooks.register('pre_trigger', {
+      name: 'exit-plan-mode-gate',
+      priority: 5,
+      onError: 'fail_closed',
+      run: (input) => {
+        const payload = input as { tool?: string; root?: string; runId?: string }
+        if (payload.tool !== 'exit_plan_mode') return { decision: 'continue' as const }
+        const root = payload.root ?? ''
+        const runId = payload.runId ?? ''
+        if (root === '' || runId === '') return { decision: 'continue' as const }
+        const gate = planGateForExit(getNextLegalPhase(join(root, '.recursive', 'run', runId)))
+        return gate.allow
+          ? { decision: 'continue' as const, annotations: { planGate: gate.reason } }
+          : { decision: 'deny' as const, reason: gate.reason }
+      },
+    })
     const toolRuntime = ctx as unknown as { on?: (event: string, listener: (payload: unknown, next?: unknown) => unknown) => () => void }
     if (toolRuntime.on) {
-      disposers.push(toolRuntime.on('tools/pre-execute', (payload, next) => {
+      disposers.push(toolRuntime.on('tools/pre-execute', async (payload, next) => {
         const exec = payload as { name?: string; arguments?: unknown; agent?: { session?: { header?: { cwd?: string } } } | null } | null
         if (!exec?.name) return typeof next === 'function' ? next() : { kind: 'allow' }
         // B3: per-call root is the session cwd (authoritative when the registry is
         // absent), never process.cwd().
-        const root = exec?.agent?.session?.header?.cwd ?? ''
-        const decision = evaluateToolGuard(exec as never, root, '', recursive.enforcementConfig.toolGuards)
-        if (decision.kind === 'allow') return typeof next === 'function' ? next() : { kind: 'allow' }
-        if (decision.kind === 'deny') return decision
-        // T6 (approval ask→policy bridge): an `ask` must never be a silent
-        // allow. Strict coerces to deny; advisory allows but carries a warn that
-        // the caller logs below. The approval seam is the follow-on (Phase D).
-        const coerced = coerceAskToDecision(decision, recursive.enforcementConfig.toolGuards)
-        if (coerced.kind === 'deny') return coerced
-        if (coerced.kind === 'allow' && coerced.warn) {
+        const cwd = exec?.agent?.session?.header?.cwd ?? ''
+        const root = (await recursive.resolveRootForRoute(undefined, cwd, sessionsStore)) ?? cwd
+        // T15 (A): the active run id is resolved from the FILESYSTEM on every call
+        // — `resolveRunDir` is the canonical latest-run-by-mtime used by
+        // recursive_status/phaseRules. Deliberately NO ttl/time cache: a cached run
+        // id would silently reintroduce exactly the empty-runId bug being fixed
+        // here, because a run created moments ago must be visible immediately. If a
+        // cache is ever added it must be provably invalidated on run creation.
+        const runId = root ? resolveRunDir(root)?.runId ?? '' : ''
+
+        // T27 — THE NAMED POINT IS LIVE AT THE ENFORCEMENT SEAM. A sibling hook may
+        // deny here BEFORE the built-in guard runs, so participation is real rather
+        // than a reachable registry that nothing consults.
+        //
+        // With no hooks registered — the ordinary case — the chain returns `continue`
+        // and the guard below runs exactly as it always has, which is what keeps
+        // `guard-path.spec.ts`'s pinned contract byte-identical. That is the point of
+        // putting the chain FIRST: it adds a way in without moving what was there.
+        //
+        // A `hold` is treated as a denial at this seam. `hold` means "stop and wait"
+        // for a point that can resume later; a tool call has nothing to resume, so
+        // pretending to hold would silently proceed. Better to refuse and say so.
+        const preTrigger = await recursive.hooks.run('pre_trigger', {
+          tool: exec.name,
+          args: exec.arguments,
+          exec,
+          root,
+          runId,
+        })
+        const decider = preTrigger.ran[preTrigger.ran.length - 1]
+
+        // A SIBLING stopped the chain. Checked by the DECIDER, not by the built-in's
+        // mere absence: a sibling with a LOWER priority than the guard runs after it, so
+        // "the guard is in the trail" does not mean "the guard decided".
+        if ((preTrigger.decision === 'deny' || preTrigger.decision === 'hold') && decider?.name !== BUILTIN_GUARD_HOOK_NAME) {
+          const by = decider?.name ?? 'a pre_trigger hook'
+          const why = preTrigger.reason ?? 'no reason given'
+          // A `hold` is treated as a refusal at this seam. `hold` means "stop and wait"
+          // for a point that can resume later; a tool call has nothing to resume, so
+          // pretending to hold would silently proceed — worse than refusing, because the
+          // caller would never learn a hook wanted to stop it.
+          return {
+            kind: 'deny',
+            reason: preTrigger.decision === 'hold'
+              ? 'held by pre_trigger hook ' + by + ': ' + why
+              : 'denied by pre_trigger hook ' + by + ': ' + why,
+          }
+        }
+
+        // The guard itself failed: it is fail_closed, so the refusal is reported with
+        // its own error rather than as a silent allow.
+        if (decider?.name === BUILTIN_GUARD_HOOK_NAME && decider.error !== undefined) {
+          return { kind: 'deny', reason: 'the tool guard failed: ' + decider.error }
+        }
+
+        const builtIn = preTrigger.ran.find((entry) => entry.name === BUILTIN_GUARD_HOOK_NAME)
+        const final = builtIn?.annotations?.guardDecision as ToolGuardDecision | undefined
+        if (final === undefined) {
+          // Unreachable while the built-in is registered unconditionally. It fails
+          // CLOSED rather than allowing, because "we could not decide" is not permission.
+          return { kind: 'deny', reason: 'the tool guard produced no decision' }
+        }
+        // The guard's own object, returned VERBATIM — the pinned contract.
+        if (final.kind === 'deny') return final
+        if (final.kind === 'allow' && final.warn) {
           // Package-tagged host logging; never a silent pass under approval=never.
-          console.warn('[recursive] tool guard (advisory): ' + coerced.warn + ' — allowing')
+          console.warn('[recursive] tool guard (advisory): ' + final.warn + ' — allowing')
         }
         return typeof next === 'function' ? next() : { kind: 'allow' }
       }))
     }
 
+    // T15 (E): the fs/observed lock-tamper path. The harness contract is a plain
+    // SYNCHRONOUS emit fired AFTER a successful write, so this listener cannot
+    // veto anything and contractually must not throw — it only RECORDS. Before
+    // T15 the plugin had no fs/observed listener at all (the string appeared in
+    // comments only), so `detectTamper` was exported and unit-tested with no live
+    // caller and a tampered lock surfaced nowhere but prompt text.
+    const observationRuntime = ctx as unknown as { on?: (event: string, listener: (target: unknown, observation: unknown, actor: unknown) => void) => () => void }
+    if (observationRuntime.on) {
+      disposers.push(observationRuntime.on('fs/observed', (target, observation, actor) => {
+        try {
+          // Only a present observation can be a tamper; absent/unrelated are ignored.
+          if ((observation as { kind?: string } | null)?.kind !== 'present') return
+          const displayPath = (target as { displayPath?: string } | null)?.displayPath ?? ''
+          if (!displayPath) return
+          // Cheap shape test BEFORE any filesystem work: fs/observed fires on reads
+          // too, so enumerating runs for every observation would be a readdir per
+          // file touch. This is EXACTLY detectTamper's own admission test (same
+          // normalized string, same two conditions), so it can never reject a
+          // candidate detectTamper would have accepted.
+          const normalized = displayPath.replace(/\\/g, '/')
+          if (!normalized.endsWith('.md') || !normalized.includes('/.recursive/run/')) return
+          // The actor is the tool execution. This event cannot await, so the root is
+          // the actor's session cwd (the same B4 sync shortcut fsPolicyIntent takes:
+          // the session cwd is authoritative, the registry path is async-only).
+          const cwd = (actor as { agent?: { session?: { header?: { cwd?: string } } } } | null)?.agent?.session?.header?.cwd ?? ''
+          if (!cwd) return
+          const runId = resolveRunDir(cwd)?.runId ?? ''
+          const tamper = recursive.detectTamper(normalized, cwd, runId)
+          if (!tamper) return
+          appendObservedTamper(cwd, {
+            at: new Date().toISOString(),
+            runId: tamper.runId,
+            path: tamper.path,
+            reason: tamper.reason,
+          })
+        } catch {
+          // Observe-only: the fs/observed contract forbids throwing.
+        }
+      }))
+    }
+
+    // T36: capture a delegated child's SETTLEMENT at delivery time.
+    //
+    // WHY DELIVERY AND NOT HISTORY. The obvious implementation of a parent-side
+    // settlement observer is to scan the session log for the `subagent-settled`
+    // notice. That is prohibited: DSH deprecates synchronous reads of arbitrary
+    // session history (`eventAt`/`snapshotEvents`/`ownEvents`) and states that new
+    // production calls are prohibited, enforced by an executable lint check. The
+    // sanctioned replacement is to process the DELIVERED event, which is this
+    // listener — the same `session/event` seam the projection registry subscribes
+    // to. The durable fact then lands in the run's own FILE state, which is where
+    // every other plugin fact lands and keeps the plugin zero-emission.
+    //
+    // The loop needs this because there is NO parent-side promise to await: a
+    // continuable child's settlement arrives as a durable user message on a later
+    // turn, so the round observer must find a recorded settlement or honestly
+    // report that none has landed yet.
+    const sessionRuntime = ctx as unknown as { on?: (event: string, listener: (session: unknown, event: unknown) => void) => () => void }
+    if (sessionRuntime.on) {
+      disposers.push(sessionRuntime.on('session/event', (session, event) => {
+        try {
+          // Cheap shape test FIRST: session/event fires for EVERY committed event
+          // in every session, so a non-settlement must be rejected before any
+          // filesystem work. This is the same ordering the fs/observed listener
+          // uses, for the same reason.
+          const notice = settlementFromEvent(event as never)
+          if (notice === null) return
+          // B3: the session cwd is the authoritative control-plane root per call.
+          const cwd = (session as { header?: { cwd?: string } } | null)?.header?.cwd ?? ''
+          if (cwd === '') return
+          const runDir = runDirForChild(cwd, notice.childId)
+          // No run (or an ambiguous one) means the settlement is not filed rather
+          // than filed wrongly: the loop will report "no settlement yet", which is
+          // recoverable, whereas attaching evidence to the wrong run is not.
+          if (runDir === null) {
+            // ⚠ FU-17 — ADOPT RATHER THAN DROP. The rule above still holds — never guess between runs — but a
+            // settlement for a child nobody filed is evidence of work that really happened, and dropping it
+            // means a phase artifact cannot cite it. `adoptSettlement` files it into the single run when there
+            // is exactly one, and into a root-level adoption log when choosing would mean guessing. Marked as
+            // adopted either way, so a reader can tell an adopted record from a delegation's own.
+            adoptSettlement(cwd, notice)
+            return
+          }
+          recordSettlement(runDir, notice)
+        } catch {
+          // Observe-only. This rides the hot path of every session event and must
+          // never break the session it observes.
+        }
+      }))
+    }
+
     // SP3 R5: agent/pre-step lint-rules injection (pre-step contract verified: the
     // listener returns { kind: 'enter', messages: [...messages, injected] } and the
     // returned array REPLACES the default [...claimed, context]). When the session's
@@ -258,7 +624,7 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
                 const reminder = phaseLintRulesMessage(phase)
         return {
           kind: 'enter',
-          messages: [...messages, createUserMessage({ content: [{ type: 'text', text: reminder }], source: { kind: 'plugin', plugin: '@try-works/dsh-recursive-mode' } })],
+          messages: [...messages, createUserMessage({ content: [{ type: 'text', text: reminder }], source: { ...REMINDER_SOURCE, form: 'notice', summary: 'phase ' + phase + ' lint rules' } })],
         } as const
       }))
     }
@@ -267,12 +633,11 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
     // mountOnce-global: apply() runs per-session, but the route must register
     // exactly once (WebServer.register throws on duplicate kind+path) and serve
     // PER-WORKSPACE state. No-op when the host composes no webServer (headless).
+    // (`sessionsStore` is resolved once, above the pre-execute listener, which now
+    // needs it too.)
     const webServer = ctx.get('webServer') as
       | { register: (route: { kind: string; path: string; handler: unknown }) => () => void }
       | undefined
-    const sessionsStore = ctx.get('sessions') as
-      | { get?: (id: string) => { header?: { cwd?: string } } | undefined }
-      | undefined
     if (webServer) {
       const host: RecursiveRouteHost = {
         // sessionId PRIMARY: the host resolves cwd from the attached session header;

package/src/job-log.ts

@@ -0,0 +1,112 @@
+/**
+ * T39 — surface job runs to the board as a durable, file-backed log.
+ *
+ * WHY A FILE AND NOT AN EVENT BUS. The native registry offers
+ * `jobs.events.subscribe(filter, listener)`, and subscribing was the first thing this looked
+ * like it should do. It is the wrong seam for THIS job: an event carries a job id and a
+ * status, but **not the run a job belongs to** — and the plugin's board reads the RUN LAYER.
+ * Subscribing would therefore mean parsing run ids back out of our own labels, which is a
+ * mapping that breaks silently the day a label changes. The call site already knows the run
+ * it started work for, so the run id is recorded where it is KNOWN and read where it is
+ * NEEDED. That also keeps the zero-emission invariant: a file in the run layer, never a
+ * session event.
+ *
+ * ⚠ BEST-EFFORT BY DESIGN, exactly like the guard log and the settlement log: a failed log
+ * write must never change the outcome of work that already ran. Recording is observability;
+ * letting observability fail a lint would be the tail wagging the dog.
+ *
+ * ⚠ AND IT SAYS WHETHER THE RUN WAS TRACKED. `tracked: false` is recorded rather than left
+ * implicit, because a reader must be able to tell "this job ran without a board" from "the
+ * board lost it" — the same distinction `describeJobRun` makes for a caller.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { JobRunResult } from './jobs-runner.ts'
+
+/** One recorded run, as the board reads it. */
+export interface JobLogRecord {
+  at: string
+  /** The producer kind: `lint`, `worktree`, `delegation`. */
+  kind: string
+  label: string
+  /** False when there was no registry and the work ran inline. */
+  tracked: boolean
+  jobId?: string
+  status: 'completed' | 'killed' | 'failed'
+  detail?: string
+}
+
+/** Where a run's job log lives, beside its other run-layer records. */
+export function jobsLogPath(root: string, runId: string): string {
+  return join(root, '.recursive', 'run', runId, 'jobs', 'jobs.jsonl')
+}
+
+/**
+ * Append one run to the log. Never throws: an unwritable log is not a reason for a completed
+ * lint to be reported as a failure.
+ *
+ * @returns true when the line was written, false when it could not be — so a caller that
+ * cares can say so without this function deciding for it.
+ */
+export function recordJobRun(
+  root: string,
+  runId: string,
+  entry: { kind: string; label: string; result: JobRunResult<unknown> },
+): boolean {
+  if (root === '' || runId === '') return false
+  try {
+    const path = jobsLogPath(root, runId)
+    mkdirSync(dirname(path), { recursive: true })
+    const record: JobLogRecord = {
+      at: new Date().toISOString(),
+      kind: entry.kind,
+      label: entry.label,
+      tracked: entry.result.tracked,
+      status: entry.result.status,
+    }
+    if (entry.result.jobId !== undefined) record.jobId = entry.result.jobId
+    const detail = entry.result.detail ?? entry.result.error
+    if (detail !== undefined) record.detail = detail
+    appendFileSync(path, JSON.stringify(record) + '\n', 'utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Read a run's job log. A missing or damaged file reads as empty — never an error. */
+export function readJobRuns(root: string, runId: string): JobLogRecord[] {
+  const path = jobsLogPath(root, runId)
+  if (!existsSync(path)) return []
+  try {
+    return readFileSync(path, 'utf8')
+      .split('\n')
+      .filter((line) => line.trim() !== '')
+      .flatMap((line) => {
+        try {
+          const parsed = JSON.parse(line) as JobLogRecord
+          return typeof parsed?.kind === 'string' && typeof parsed?.status === 'string' ? [parsed] : []
+        } catch {
+          return []
+        }
+      })
+  } catch {
+    return []
+  }
+}
+
+/**
+ * A board-facing rendering: one line per run, newest last, with the untracked and
+ * non-completed cases called out rather than implied.
+ */
+export function renderJobLog(root: string, runId: string): string {
+  const records = readJobRuns(root, runId)
+  if (records.length === 0) return 'no job runs recorded for this run'
+  return records
+    .map((record) => {
+      const where = record.tracked ? (record.jobId ?? 'job') : 'untracked'
+      const why = record.detail === undefined ? '' : ' — ' + record.detail
+      return record.status + ' [' + record.kind + '] ' + where + ': ' + record.label + why
+    })
+    .join('\n')
+}