@try-works/dsh-recursive-mode 0.1.0

package/src/recursive_closeout.tool.ts

@@ -0,0 +1,35 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { RecursiveRuntime } from './runtime.ts'
+
+/**
+ * `recursive_closeout` — scaffold a Phase 4/5/6/7/8 closeout receipt under the
+ * SESSION's workspace only (R1 workspace-scoping invariant). The run is resolved
+ * via the session agent's cwd -> workspace registry; a runId outside the current
+ * workspace is rejected.
+ */
+export function createRecursiveCloseoutTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_closeout',
+    description: 'Scaffold a closeout receipt stub (Phase 4/5/6/7/8 delta receipt) for a run in the CURRENT session workspace only. Workspace-scoped: refuses runIds outside the session\'s workspace. Delegates to the RecursiveRuntime service.',
+    parameters: {
+      phase: { type: 'string', description: 'Closeout phase to scaffold: 04, 05, 06, 07, or 08 (e.g. \'06\' for 06-decisions-update.md). Required.' },
+      runId: { type: 'string', description: 'Run id (e.g. 03-something). Required. Must resolve inside the current workspace.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { phase?: string; runId?: string }, exec) {
+      if (!args.phase || !args.runId || args.runId.trim() === '') {
+        return { error: 'phase and runId are required' } as const
+      }
+      const root = await recursive.resolveWorkspaceRoot(exec.agent)
+      if (!root) {
+        return { error: 'session is not attached to a registered workspace (cannot resolve control-plane root)' } as const
+      }
+      const result = recursive.closeoutRun(root, args.runId.trim(), args.phase.trim())
+      return result as unknown as JsonValue
+    },
+  })
+}

package/src/recursive_init.tool.ts

@@ -0,0 +1,28 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { RecursiveRuntime } from './runtime.ts'
+
+export function createRecursiveInitTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_init',
+    description: 'Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic).',
+    parameters: {
+      runId: { type: 'string', description: 'Run id (e.g. 03-something). Required.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { runId?: string }, exec) {
+      if (!args.runId || args.runId.trim() === '') {
+        return { error: 'runId is required' } as const
+      }
+      try {
+        const result = await recursive.initRun(args.runId.trim(), exec.agent as { session?: { header?: { cwd?: string } } } | null)
+        return result as unknown as JsonValue
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) } as const
+      }
+    },
+  })
+}

package/src/recursive_lint.tool.ts

@@ -0,0 +1,29 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { RecursiveRuntime } from './runtime.ts'
+
+export function createRecursiveLintTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_lint',
+    description: 'Lint a recursive-mode run artifact for phase-specific issues (gates, TODO, traceability, diff audit). Delegates to the RecursiveRuntime service.',
+    parameters: {
+      runId: { type: 'string', description: 'Run id. Required.' },
+      artifact: { type: 'string', description: 'Optional artifact file name; defaults to the current phase.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { runId?: string; artifact?: string }, exec) {
+      if (!args.runId || args.runId.trim() === '') {
+        return { error: 'runId is required' } as const
+      }
+      try {
+        const result = await recursive.lintArtifact(args.runId.trim(), args.artifact?.trim(), exec.agent as { session?: { header?: { cwd?: string } } } | null)
+        return result as unknown as JsonValue
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) } as const
+      }
+    },
+  })
+}

package/src/recursive_lock.tool.ts

@@ -0,0 +1,33 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { RecursiveRuntime } from './runtime.ts'
+
+export function createRecursiveLockTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_lock',
+    description: 'Lock a DRAFT recursive-mode artifact: writes Status: LOCKED, LockedAt, LockHash and validates prerequisites (monotonic phase gating). Delegates to the RecursiveRuntime service.',
+    parameters: {
+      runId: { type: 'string', description: 'Run id. Required.' },
+      artifact: { type: 'string', description: 'Artifact file name, e.g. 03-implementation-summary.md. Required.' },
+      reopen: { type: 'boolean', description: 'If true, reopen a locked artifact back to DRAFT (invalidates downstream receipts).' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { runId?: string; artifact?: string; reopen?: boolean }, exec) {
+      if (!args.runId || args.runId.trim() === '') {
+        return { error: 'runId is required' } as const
+      }
+      if (!args.artifact || args.artifact.trim() === '') {
+        return { error: 'artifact is required' } as const
+      }
+      try {
+        const result = await recursive.lockArtifact(args.runId.trim(), args.artifact.trim(), args.reopen === true, exec.agent as { session?: { header?: { cwd?: string } } } | null)
+        return result as unknown as JsonValue
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) } as const
+      }
+    },
+  })
+}

package/src/recursive_scratch.tool.ts

@@ -0,0 +1,42 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { RecursiveRuntime } from './runtime.ts'
+
+/**
+ * `recursive_scratch` — read/write/append the run-scoped disposable scratchpad
+ * (R5) under the CURRENT session workspace only (R1). Scratch is git-ignored
+ * and never citable as an Input.
+ */
+export function createRecursiveScratchTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_scratch',
+    description: 'Read, write, or append the run-scoped disposable scratchpad (scratch/scratch.md or scratch/scratch.ts) for a run in the CURRENT session workspace. Workspace-scoped; scratch is git-ignored and never citable as an Input.',
+    parameters: {
+      action: { type: 'string', description: 'read | write | append. Required.' },
+      runId: { type: 'string', description: 'Run id (e.g. 03-something). Required; must resolve inside the current workspace.' },
+      target: { type: 'string', description: 'md | ts. Required.' },
+      content: { type: 'string', description: 'Content for write/append. Optional for read.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { action?: string; runId?: string; target?: string; content?: string }, exec) {
+      const action = args.action ?? ''
+      const runId = args.runId?.trim() ?? ''
+      const target = args.target ?? ''
+      if (!action || !runId || !target) {
+        return { error: 'action, runId, and target are required' } as const
+      }
+      if (target !== 'md' && target !== 'ts') {
+        return { error: 'target must be md or ts' } as const
+      }
+      const root = await recursive.resolveWorkspaceRoot(exec.agent)
+      if (!root) {
+        return { error: 'session is not attached to a registered workspace (cannot resolve control-plane root)' } as const
+      }
+      const result = recursive.scratchRun(root, runId, action, target as 'md' | 'ts', args.content)
+      return result as unknown as JsonValue
+    },
+  })
+}

package/src/recursive_status.tool.ts

@@ -0,0 +1,24 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { RecursiveRuntime } from './runtime.ts'
+
+export function createRecursiveStatusTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_status',
+    description: 'Show the folded status of a recursive-mode run: phase table, current phase, lock validity. Reads through the RecursiveRuntime service (no duplicated parsing logic).',
+    parameters: {
+      runId: { type: 'string', description: 'Optional run id (defaults to the latest run by mtime)' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { runId?: string }, exec) {
+      // B3: per-call workspace root via exec.agent.session.header.cwd (registry
+      // first, cwd fallback) — never the host checkout process.cwd().
+      const result = await recursive.status(args.runId, exec.agent as { session?: { header?: { cwd?: string } } } | null)
+      if (!result) return { error: 'no recursive run found' } as const
+      return result as unknown as JsonValue
+    },
+  })
+}

package/src/review.ts

@@ -0,0 +1,178 @@
+/**
+ * Review-bundle builder (Phase B R1). TS port of the canonical
+ * recursive-review-bundle minimum-input contract (PROPOSAL 10.4/10.6):
+ * gathers the context-in bundle a delegated reviewer needs and materializes it
+ * as a durable markdown bundle under evidence/review-bundles/ with an
+ * Artifact Path + Artifact Content Hash (LF-normalized sha256) header.
+ *
+ * Workspace-scoped (run 03 R1): every path resolves under the given control-
+ * plane root; this module never scans a registry or another workspace.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+import { createHash } from 'node:crypto'
+
+export interface ReviewBundleInput {
+  root: string
+  runId: string
+  phase: string
+  role: string
+  artifactPath: string
+  upstreamArtifacts: string[]
+  auditQuestions: string[]
+  requiredOutput: string
+  diffBasis?: {
+    baselineType: string
+    baselineReference: string
+    comparisonReference: string
+    normalizedBaseline: string
+    normalizedComparison: string
+    normalizedDiffCommand: string
+  }
+  codeRefs?: string[]
+  addenda?: string[]
+  priorEvidence?: string[]
+  memoryRefs?: string[]
+  changedFiles?: string[]
+}
+
+export interface ReviewBundleResult {
+  bundlePath: string
+  repoRelativePath: string
+  artifactContentHash: string
+  markdown: string
+}
+
+/** LF-normalized sha256 (matches recursive-lock.py content_sha256). */
+export function contentSha256(content: string): string {
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+  return createHash('sha256').update(normalized, 'utf8').digest('hex')
+}
+
+function norm(repoRelative: string): string {
+  return repoRelative.replace(/\\/g, '/').replace(/^\/+/, '')
+}
+
+function resolveUnderRoot(root: string, repoRelative: string): string {
+  const normalized = norm(repoRelative)
+  const rootAbs = resolve(root)
+  const abs = resolve(rootAbs, normalized)
+  const rootPrefix = rootAbs.endsWith(sep) ? rootAbs : rootAbs + sep
+  if (abs !== rootAbs && !abs.startsWith(rootPrefix)) {
+    throw new Error('Path escapes the workspace root: ' + repoRelative)
+  }
+  return abs
+}
+
+function pathList(title: string, values: string[]): string[] {
+  const lines: string[] = [title]
+  if (!values.length) {
+    lines.push('- none')
+    return lines
+  }
+  for (const v of values) lines.push('- `' + norm(v) + '`')
+  return lines
+}
+
+/**
+ * Build a canonical review bundle. Throws when the artifact path is missing or
+ * when a path would escape the workspace root (fail loud, never a silent
+ * bundle).
+ */
+export function buildReviewBundle(input: ReviewBundleInput): ReviewBundleResult {
+  const { root, runId, phase, role } = input
+  const runDir = resolveUnderRoot(root, '.recursive/run/' + runId)
+  if (!existsSync(runDir)) {
+    throw new Error('Run directory does not exist: ' + runId)
+  }
+
+  const artifactAbs = resolveUnderRoot(root, input.artifactPath)
+  if (!existsSync(artifactAbs)) {
+    throw new Error('Review-bundle artifact path does not exist: ' + input.artifactPath)
+  }
+  const artifactHash = contentSha256(readFileSync(artifactAbs, 'utf8'))
+
+  const bundlesDir = join(runDir, 'evidence', 'review-bundles')
+  mkdirSync(bundlesDir, { recursive: true })
+  const slug = phase.trim().toLowerCase().replace(/[^a-z0-9.]+/g, '-').replace(/^-+|-+$/g, '')
+  const bundleFileName = (slug || 'review') + '-bundle.md'
+  const bundlePath = join(bundlesDir, bundleFileName)
+  const rootNorm = resolve(root).replace(/\\/g, '/')
+  const repoRelativePath = bundlePath.replace(/\\/g, '/').replace(rootNorm + '/', '')
+
+  const diff = input.diffBasis
+  const diffLines = diff
+    ? [
+        '- Baseline type: ' + diff.baselineType,
+        '- Baseline reference: ' + diff.baselineReference,
+        '- Comparison reference: ' + diff.comparisonReference,
+        '- Normalized baseline: ' + diff.normalizedBaseline,
+        '- Normalized comparison: ' + diff.normalizedComparison,
+        '- Normalized diff command: ' + diff.normalizedDiffCommand,
+      ]
+    : [
+        '- Baseline type: local commit',
+        '- Baseline reference: (see 00-worktree.md)',
+        '- Comparison reference: working-tree',
+        '- Normalized baseline: (see 00-worktree.md)',
+        '- Normalized comparison: working-tree',
+        '- Normalized diff command: git diff --name-only (see 00-worktree.md)',
+      ]
+
+  const changedLines = input.changedFiles?.length
+    ? input.changedFiles.map((f) => '- `' + norm(f) + '`')
+    : ["- (derived from the run's Worktree Diff Audit; see the phase artifact)"]
+
+  const lines: string[] = [
+    '# ' + phase + ' review bundle',
+    '',
+    'Artifact Path: ' + norm(input.artifactPath),
+    'Artifact Content Hash: ' + artifactHash,
+    '',
+    '## Diff Basis',
+    ...diffLines,
+    '',
+    '## Changed Files Reviewed',
+    ...changedLines,
+    '',
+    '## Upstream Artifacts To Re-read',
+    ...pathList('', input.upstreamArtifacts).slice(1),
+    '',
+    '## Relevant Addenda',
+    ...pathList('', input.addenda ?? []).slice(1),
+    '',
+    '## Prior Recursive Evidence',
+    ...pathList('', input.priorEvidence ?? []).slice(1),
+    '',
+    '## Targeted Code References',
+    ...pathList('', input.codeRefs ?? []).slice(1),
+    '',
+    '## Audit Questions',
+    ...(input.auditQuestions.length
+      ? input.auditQuestions.map((q, i) => String(i + 1) + '. ' + q)
+      : ['- none']),
+    '',
+    '## Required Output',
+    '',
+    input.requiredOutput,
+    '',
+    '## Relevant Memory References',
+    ...pathList('', input.memoryRefs ?? []).slice(1),
+    '',
+  ]
+
+  const markdown = lines.join('\n')
+  writeFileSync(bundlePath, markdown, 'utf8')
+
+  return {
+    bundlePath,
+    repoRelativePath,
+    artifactContentHash: artifactHash,
+    markdown,
+  }
+}
+
+/** Canonical bundle dir for a run: .recursive/run/<id>/evidence/review-bundles/. */
+export function reviewBundleDir(root: string, runId: string): string {
+  return join(resolveUnderRoot(root, '.recursive/run/' + runId), 'evidence', 'review-bundles')
+}

package/src/router.ts

@@ -0,0 +1,197 @@
+/**
+ * Native router resolution (Phase B R3, PROPOSAL 10.4/10.10): resolves the
+ * canonical recursive-router.json policy to a NATIVE DSH subagent provider,
+ * keeping the policy file as declarative config and dropping the external-CLI
+ * wrappers. Order per role: native provider -> external-CLI route (codex/
+ * claude) -> self-audit / local-controller fallback.
+ *
+ * Workspace-scoped + optionality-preserving: a missing provider, a missing
+ * policy, or a failed probe resolves to self-audit, never throws and never
+ * scans another workspace.
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface RouterDefaults {
+  when_role_unconfigured: string
+  when_cli_unavailable: string
+  when_model_unknown: string
+  allow_auto_assign_if_single_cli: boolean
+  probe_timeout_ms: number
+  invoke_timeout_ms: number
+}
+
+export interface RoleRoute {
+  enabled: boolean
+  mode: string
+  cli: string | null
+  model: string | null
+  fallback: string
+}
+
+export interface RouterPolicy {
+  version: number
+  defaults: RouterDefaults
+  role_routes: Record<string, RoleRoute>
+  cli_overrides: Record<string, unknown>
+  custom_clis: unknown[]
+}
+
+export type RouteTier = 'native' | 'external-cli' | 'self-audit' | 'local-controller'
+
+export interface RouteDecision {
+  tier: RouteTier
+  provider?: string
+  reason: string
+}
+
+export interface SubagentProviderLike {
+  name: string
+  capabilities?: {
+    outputSchema?: boolean
+    depthLimit?: boolean
+    toolFilter?: boolean
+    persona?: boolean
+  }
+}
+
+export interface CapabilityProbe {
+  available: boolean
+  provider?: string
+  capabilities?: {
+    outputSchema: boolean
+    depthLimit: boolean
+    toolFilter: boolean
+    persona: boolean
+  }
+  reason: string
+}
+
+const DEFAULT_POLICY: RouterPolicy = {
+  version: 1,
+  defaults: {
+    when_role_unconfigured: 'ask',
+    when_cli_unavailable: 'fallback-local',
+    when_model_unknown: 'ask',
+    allow_auto_assign_if_single_cli: false,
+    probe_timeout_ms: 50000,
+    invoke_timeout_ms: 180000,
+  },
+  role_routes: {},
+  cli_overrides: {},
+  custom_clis: [],
+}
+
+/** Parse recursive-router.json. A missing/invalid file yields a default self-audit policy (never throws). */
+export function loadRouterPolicy(path?: string): RouterPolicy {
+  if (!path || !existsSync(path)) return DEFAULT_POLICY
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<RouterPolicy>
+    return {
+      version: typeof raw.version === 'number' ? raw.version : 1,
+      defaults: { ...DEFAULT_POLICY.defaults, ...(raw.defaults ?? {}) },
+      role_routes: raw.role_routes ?? {},
+      cli_overrides: raw.cli_overrides ?? {},
+      custom_clis: raw.custom_clis ?? [],
+    }
+  } catch {
+    return DEFAULT_POLICY
+  }
+}
+
+/** Default router policy path inside a workspace root. */
+export function routerPolicyPath(root: string): string {
+  return join(root, '.recursive', 'config', 'recursive-router.json')
+}
+
+/**
+ * Resolve a role to a tier, preferring a native provider whose name maps to
+ * the role (e.g. role 'code-reviewer' -> provider 'code-reviewer' or the
+ * generic spawn/fork provider). External CLIs ride their provider rows; else
+ * the policy fallback.
+ */
+export function resolveRole(
+  role: string,
+  policy: RouterPolicy,
+  providers: Record<string, SubagentProviderLike>,
+): RouteDecision {
+  const route = policy.role_routes[role]
+  if (!route || !route.enabled) {
+    return { tier: 'self-audit', reason: 'role ' + role + ' is unconfigured or disabled' }
+  }
+
+  // 1. Native provider: role-mapped name, then the generic spawn/fork.
+  const candidates = [role, 'spawn', 'fork', 'dsh-sdk']
+  for (const name of candidates) {
+    if (providers[name]) {
+      return { tier: 'native', provider: name, reason: 'native provider ' + name + ' is registered' }
+    }
+  }
+
+  // 2. External-CLI route (codex/claude provider rows).
+  if (route.mode === 'external-cli' && route.cli) {
+    for (const name of [route.cli, 'codex', 'claude-code']) {
+      if (providers[name]) {
+        return { tier: 'external-cli', provider: name, reason: 'external CLI ' + route.cli + ' resolves to provider ' + name }
+      }
+    }
+    return { tier: 'self-audit', reason: 'external CLI ' + route.cli + ' has no registered provider; falling back' }
+  }
+
+  // 3. Fallback.
+  if (route.fallback === 'local-controller') {
+    return { tier: 'local-controller', reason: 'policy fallback local-controller' }
+  }
+  return { tier: 'self-audit', reason: 'no native or external provider available; policy fallback ' + (route.fallback || 'self-audit') }
+}
+
+/** Probe a single provider and return its advertised capabilities. */
+export function probeCapabilities(provider: SubagentProviderLike | undefined): CapabilityProbe {
+  if (!provider) {
+    return { available: false, reason: 'no provider registered' }
+  }
+  const caps = provider.capabilities
+  return {
+    available: true,
+    provider: provider.name,
+    capabilities: {
+      outputSchema: caps?.outputSchema ?? false,
+      depthLimit: caps?.depthLimit ?? false,
+      toolFilter: caps?.toolFilter ?? false,
+      persona: caps?.persona ?? false,
+    },
+    reason: 'provider ' + provider.name + ' probed',
+  }
+}
+
+/**
+ * Probe the router-relevant capability for a role. No provider -> available
+ * false with a concrete reason (the self-audit fallback trigger).
+ */
+export function capabilityProbe(input: {
+  providers: Record<string, SubagentProviderLike>
+  role: string
+  policy?: RouterPolicy
+}): CapabilityProbe {
+  const policy = input.policy ?? DEFAULT_POLICY
+  const decision = resolveRole(input.role, policy, input.providers)
+  if (decision.tier === 'self-audit' || decision.tier === 'local-controller') {
+    return { available: false, reason: decision.reason }
+  }
+  const provider = input.providers[decision.provider ?? '']
+  return probeCapabilities(provider)
+}
+
+/** Render the Delegation Decision Basis prose the phase doc records. */
+export function delegationDecisionBasis(input: {
+  role: string
+  available: boolean
+  provider?: string
+  fallback: string
+}): string {
+  const { role, available, provider, fallback } = input
+  if (available && provider) {
+    return 'subagents are available (' + provider + '); ' + role + ' work is delegated by default when the context bundle is complete, with ' + fallback + ' as the guaranteed fallback.'
+  }
+  return 'no native subagent provider is available for ' + role + ' (probe failed or timed out); the audit is performed as self-audit per the bridge block, never weakening or skipping it.'
+}

package/src/run.ts

@@ -0,0 +1,85 @@
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Run discovery for recursive-mode runs.
+ *
+ * Ports the discovery subset of recursive-status.py:
+ * - discoverRuns: list run directories under <repoRoot>/.recursive/run/
+ * - resolveRunDir: explicit run id, or the latest run by mtime (stable sort)
+ *
+ * R1 (run 02): dedicated module so tools and status share one discovery path.
+ */
+
+export interface RunDiscoveryResult {
+  runDir: string
+  runId: string
+}
+
+/**
+ * List run ids under <repoRoot>/.recursive/run/, excluding non-directories.
+ * Mirrors: runs = [p for p in run_root.iterdir() if p.is_dir()]
+ */
+export function discoverRuns(repoRoot: string): string[] {
+  const runRoot = join(repoRoot, '.recursive', 'run')
+  let runs: string[] = []
+  try {
+    runs = readdirSync(runRoot, { withFileTypes: true })
+      // B5: accept directories AND junctions/symlinks — Windows junction run
+      // dirs report isDirectory() === false but statSync().isDirectory() ===
+      // true (it follows the link). Deliberate for this repo (keeps the
+      // template /.recursive/ byte-pristine via a junction).
+      .filter(d => {
+        if (d.isDirectory()) return true
+        if (!d.isSymbolicLink()) return false
+        try { return statSync(join(runRoot, d.name)).isDirectory() } catch { return false }
+      })
+      .map(d => d.name)
+  } catch {
+    return []
+  }
+  return runs
+}
+
+/**
+ * Resolve the run directory for an explicit run id, or the latest run by mtime.
+ * Mirrors get_latest_run_directory: sort by st_mtime descending, stable sort
+ * (ties preserve discovery order — no name-based tie-break).
+ */
+export function resolveRunDir(repoRoot: string, runId?: string): RunDiscoveryResult | null {
+  const runRoot = join(repoRoot, '.recursive', 'run')
+  if (runId && runId.trim() !== '') {
+    return { runDir: join(runRoot, runId.trim()), runId: runId.trim() }
+  }
+  const latest = getLatestRunDirectory(runRoot)
+  if (!latest) return null
+  return { runDir: join(runRoot, latest), runId: latest }
+}
+
+/**
+ * Latest run directory by mtime (descending), stable sort preserving
+ * discovery order for exact ties. Returns null when no runs exist.
+ */
+export function getLatestRunDirectory(runRoot: string): string | null {
+  let runs: string[] = []
+  try {
+    runs = readdirSync(runRoot, { withFileTypes: true })
+      .filter(d => {
+        if (d.isDirectory()) return true
+        if (!d.isSymbolicLink()) return false
+        try { return statSync(join(runRoot, d.name)).isDirectory() } catch { return false }
+      })
+      .map(d => d.name)
+  } catch {
+    return null
+  }
+  if (runs.length === 0) return null
+  runs.sort((a, b) => {
+    try {
+      return statSync(join(runRoot, b)).mtimeMs - statSync(join(runRoot, a)).mtimeMs
+    } catch {
+      return 0
+    }
+  })
+  return runs[0]
+}