@try-works/dsh-recursive-mode 0.1.5 → 0.1.7

package/src/index.ts

@@ -1,228 +1,238 @@
-import { type Context } from '@deepseek-ai/cordis'
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { RecursiveRuntime } from './runtime.ts'
-import { createRecursiveStatusTool } from './recursive_status.tool.ts'
-import { createRecursiveInitTool } from './recursive_init.tool.ts'
-import { createRecursiveLockTool } from './recursive_lock.tool.ts'
-import { createRecursiveLintTool } from './recursive_lint.tool.ts'
-import { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
-import { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
-import { registerRecursiveCommand } from './commands.ts'
-import { evaluateToolGuard } from './enforcement.ts'
-import { renderRecursivePolicy } from './policy.ts'
-import { fsPolicyIntent } from './fs-intent.ts'
-import { snapshotWorkspace } from './snapshot.ts'
-import { mountRecursiveRoutesOnce, makeRecursiveRoutes, type RecursiveRouteHost } from './live-route.ts'
-import { enumerateRuns } from './bootstrap.ts'
-import { getNextLegalPhase, getLockStatus } from './lock.ts'
-import { phaseLintRulesMessage } from './phase-rules.ts'
-
-export const name = '@try-works/dsh-recursive-mode'
-
-export { RecursiveRuntime } from './runtime.ts'
-export { createRecursiveStatusTool } from './recursive_status.tool.ts'
-export { createRecursiveInitTool } from './recursive_init.tool.ts'
-export { createRecursiveLockTool } from './recursive_lock.tool.ts'
-export { createRecursiveLintTool } from './recursive_lint.tool.ts'
-export { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
-export { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
-export * from './status.ts'
-export {
-  PHASE_SEQUENCE,
-  OPTIONAL_PHASES,
-  normalizeForLockHash,
-  lockHashFromContent,
-  phaseIndex,
-  isCoreArtifact,
-  getPrerequisites,
-  getLockStatus,
-  getPrerequisiteBlockers,
-  receiptPath,
-  readReceipt,
-  writeReceipt,
-  invalidateReceipt,
-  getStaleDownstreamPhases,
-  getNextLegalPhase,
-  getAllStaleReceipts,
-  validateChain,
-} from './lock.ts'
-export type {
-  LockReceipt,
-  LockStatus,
-  PrerequisiteBlocker,
-  StaleDownstream,
-  ChainPhaseResult,
-  LockChainResult,
-} from './lock.ts'
-export * from './run.ts'
-export * from './review.ts'
-export * from './handoff.ts'
-export * from './router.ts'
-export * from './delegation.ts'
-export * from './lifecycle.ts'
-export * from './enforcement.ts'
-export * from './policy.ts'
-export * from './snapshot.ts'
-export * from './live-route.ts'
-
-/**
- * Bundle plugin entry. The Loader activates this row once `tools` is available
- * (`inject` below); the RecursiveRuntime service is constructed directly so it
- * is provided on `ctx.recursive` for the lifetime of this fiber, and the
- * read-path tools (status/init/lock/lint) are registered through it (R2/R4).
- */
-export const inject = ['tools']
-
-/**
- * Plugin entry (SP2 R1). Stage A (mount-time, this apply): register the
- * isolated ctx.recursive service + the recursive_* tools + the /recursive
- * command + the recursive:policy prompt section + the LIVE board/strip route
- * (HTTP state + SSE), served per-workspace from the filesystem fold. No
- * 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 }) {
-  // 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
-  // NOTHING on the server root — no tools, no /recursive command, no
-  // recursive:policy, no projection (BUG 4 always-on leak). The full server
-  // surface is mounted ONLY by the recursive preset's isolated recursive-realm,
-  // whose rows carry no config (shellOnly undefined).
-  if (config?.shellOnly) return
-  ctx.effect(function* () {
-    // Workspace registry: optional host service (durable). Access via ctx.get —
-    // property access requires inject and would fail boot when undeclared.
-    // Resolve the control-plane root strictly from the session agent's cwd.
-    const workspaceRegistry = ctx.get('workspaceRegistry') as never
-    const recursive = new RecursiveRuntime(ctx, { repoRoot: config?.repoRoot ?? process.cwd(), workspaceRegistry })
-
-    const disposers = [
-      ctx.tools.register(createRecursiveStatusTool(recursive)),
-      ctx.tools.register(createRecursiveInitTool(recursive)),
-      ctx.tools.register(createRecursiveLockTool(recursive)),
-      ctx.tools.register(createRecursiveLintTool(recursive)),
-      ctx.tools.register(createRecursiveCloseoutTool(recursive)),
-      ctx.tools.register(createRecursiveScratchTool(recursive)),
-    ]
-
-    // /recursive command (R4): preset-scoped registration, workspace-scoped dispatch.
-    const commands = ctx.get('commands') as { register: (def: unknown) => () => void } | undefined
-    if (commands) {
-      disposers.push(registerRecursiveCommand({ commands } as never, recursive))
-    }
-
-    // recursive:policy prompt section (Phase C R5): workspace-scoped behavior +
-    // current-phase contract rendered from folded state + enforcement config.
-    const systemPrompt = ctx.get('systemPrompt') as { section: (def: unknown) => () => void } | undefined
-    if (systemPrompt) {
-      disposers.push(systemPrompt.section({
-        name: 'recursive:policy',
-        order: 55,
-        text: (context: unknown) => {
-          const agent = (context as { agent?: { session?: { header?: { cwd?: string } } } } | undefined)?.agent
-          if (!agent) return ''
-          // SP3 R5 policy-render fix: derive intent from the FILESYSTEM, not the
-          // retired recursive/phase-intent session event (zero-emission removed
-          // the emitter, so detectTransitionIntent was ALWAYS null and this
-          // section rendered ''). Pure read-only fs folding; no recursive/*
-          // events are appended.
-          const intent = fsPolicyIntent(agent, workspaceRegistry as never)
-          if (!intent) return ''
-          return renderRecursivePolicy({ worktreeRoot: intent.worktreeRoot, runId: intent.runId, config: recursive.enforcementConfig })
-        },
-      }))
-    }
-
-    // Phase C R3 (Layer 1, agent/pre-step proactive intent gate) is RETIRED
-    // under zero-emission (SP2 R1): its only signal was the recursive/phase-intent
-    // session event, whose emitter is now deleted, and it was ADVISORY by default
-    // (it never rejected; its sole side effect was the now-removed emission).
-    // Enforcement is preserved where it actually bites: Layer 2 (tools/pre-execute
-    // inspects the REAL tool call args below) plus the recursive_lock tool's own
-    // prerequisite validation in lockArtifact — strictly more reliable than the
-    // heuristic intent scan. See 03-implementation-summary.addendum-r1-*.md.
-
-    // Phase C R4: tools/pre-execute surgical guards (Layer 2, caller of the
-    // transition set). Scope-filtered to the active run's worktree.
-    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) => {
-        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
-        // ask -> in advisory we let it through with a warn (the approval seam is Phase D)
-      }))
-    }
-
-    // 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
-    // control-plane root has an active recursive run whose current phase doc is
-    // DRAFT, prepend a compact system-reminder with THAT phase's required sections +
-    // gates. Pure fs read (zero-emission): never appends recursive/* events.
-    const agentRuntime = ctx as unknown as { on?: (event: string, listener: (payload: unknown, next?: unknown) => unknown) => () => void }
-    if (agentRuntime.on) {
-      disposers.push(agentRuntime.on('agent/pre-step', async (payload, next) => {
-        const p = payload as {
-          messages?: Array<{ content: Array<{ type: string; text?: string }> }>,
-          agent?: { session?: { header?: { cwd?: string } } } | null,
-        } | null
-        const messages = p?.messages ?? []
-        const agent = p?.agent ?? null
-        const cwd = agent?.session?.header?.cwd ?? ''
-        // delegate first so later listeners keep veto power, then fold ours on
-        if (typeof next === 'function') await next()
-        if (!cwd) return { kind: 'enter', messages } as const
-        const root = await recursive.resolveRootForRoute(undefined, cwd, undefined)
-        if (!root) return { kind: 'enter', messages } as const
-        const runs = enumerateRuns(root)
-        if (runs.length === 0) return { kind: 'enter', messages } as const
-        const runId = runs[runs.length - 1]
-        const runDir = join(root, '.recursive', 'run', runId)
-        if (!existsSync(runDir)) return { kind: 'enter', messages } as const
-        const phase = getNextLegalPhase(runDir)
-        if (!phase) return { kind: 'enter', messages } as const
-        // only inject when the phase doc is DRAFT (not locked/missing).
-        const phasePath = join(runDir, phase)
-        const status = existsSync(phasePath) ? getLockStatus(phasePath) : null
-        if (status !== 'DRAFT') return { kind: 'enter', messages } as const
-        const reminder = phaseLintRulesMessage(phase)
-        return {
-          kind: 'enter',
-          messages: [...messages, createUserMessage({ content: [{ type: 'text', text: reminder }], source: { kind: 'plugin', plugin: '@try-works/dsh-recursive-mode' } })],
-        } as const
-      }))
-    }
-
-    // Phase C R8: fs/observed lock-tamper WARNINGS are served to the board via the
-    // 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).
-    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;
-        // the client-passed cwd is a fallback hint (hydration / headless).
-        resolveRoot: async (sessionId: string | undefined, cwd: string) => recursive.resolveRootForRoute(sessionId, cwd, sessionsStore),
-        snapshot: async (root: string) => snapshotWorkspace(root),
-        revision: () => 1,
-      }
-      disposers.push(mountRecursiveRoutesOnce('@try-works/dsh-recursive-mode', () => makeRecursiveRoutes(host), webServer))
-    }
-
-    yield () => { for (const d of disposers) d() }
-  })
-}
+import { type Context } from '@deepseek-ai/cordis'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { RecursiveRuntime } from './runtime.ts'
+import { createRecursiveStatusTool } from './recursive_status.tool.ts'
+import { createRecursiveInitTool } from './recursive_init.tool.ts'
+import { createRecursiveLockTool } from './recursive_lock.tool.ts'
+import { createRecursiveLintTool } from './recursive_lint.tool.ts'
+import { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
+import { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
+import { registerRecursiveCommand } from './commands.ts'
+import { evaluateToolGuard } from './enforcement.ts'
+import { renderRecursivePolicy } from './policy.ts'
+import { fsPolicyIntent } from './fs-intent.ts'
+import { snapshotWorkspace } from './snapshot.ts'
+import { mountRecursiveRoutesOnce, makeRecursiveRoutes, type RecursiveRouteHost } from './live-route.ts'
+import { enumerateRuns, stageBWorkflowInit } from './bootstrap.ts'
+import { getNextLegalPhase, getLockStatus } from './lock.ts'
+import { phaseLintRulesMessage } from './phase-rules.ts'
+
+export const name = '@try-works/dsh-recursive-mode'
+
+export { RecursiveRuntime } from './runtime.ts'
+export { createRecursiveStatusTool } from './recursive_status.tool.ts'
+export { createRecursiveInitTool } from './recursive_init.tool.ts'
+export { createRecursiveLockTool } from './recursive_lock.tool.ts'
+export { createRecursiveLintTool } from './recursive_lint.tool.ts'
+export { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
+export { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
+export * from './status.ts'
+export {
+  PHASE_SEQUENCE,
+  OPTIONAL_PHASES,
+  normalizeForLockHash,
+  lockHashFromContent,
+  phaseIndex,
+  isCoreArtifact,
+  getPrerequisites,
+  getLockStatus,
+  getPrerequisiteBlockers,
+  receiptPath,
+  readReceipt,
+  writeReceipt,
+  invalidateReceipt,
+  getStaleDownstreamPhases,
+  getNextLegalPhase,
+  getAllStaleReceipts,
+  validateChain,
+} from './lock.ts'
+export type {
+  LockReceipt,
+  LockStatus,
+  PrerequisiteBlocker,
+  StaleDownstream,
+  ChainPhaseResult,
+  LockChainResult,
+} from './lock.ts'
+export * from './run.ts'
+export * from './review.ts'
+export * from './handoff.ts'
+export * from './router.ts'
+export * from './delegation.ts'
+export * from './lifecycle.ts'
+export * from './enforcement.ts'
+export * from './policy.ts'
+export * from './snapshot.ts'
+export * from './live-route.ts'
+
+/**
+ * Bundle plugin entry. The Loader activates this row once `tools` is available
+ * (`inject` below); the RecursiveRuntime service is constructed directly so it
+ * is provided on `ctx.recursive` for the lifetime of this fiber, and the
+ * read-path tools (status/init/lock/lint) are registered through it (R2/R4).
+ */
+export const inject = ['tools']
+
+/**
+ * Plugin entry (SP2 R1). Stage A (mount-time, this apply): register the
+ * isolated ctx.recursive service + the recursive_* tools + the /recursive
+ * command + the recursive:policy prompt section + the LIVE board/strip route
+ * (HTTP state + SSE), served per-workspace from the filesystem fold. No
+ * 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 }) {
+  // 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
+  // NOTHING on the server root — no tools, no /recursive command, no
+  // recursive:policy, no projection (BUG 4 always-on leak). The full server
+  // surface is mounted ONLY by the recursive preset's isolated recursive-realm,
+  // whose rows carry no config (shellOnly undefined).
+  if (config?.shellOnly) return
+  ctx.effect(function* () {
+    // Workspace registry: optional host service (durable). Access via ctx.get —
+    // property access requires inject and would fail boot when undeclared.
+    // Resolve the control-plane root strictly from the session agent's cwd.
+    const workspaceRegistry = ctx.get('workspaceRegistry') as never
+    const recursive = new RecursiveRuntime(ctx, { repoRoot: config?.repoRoot ?? process.cwd(), workspaceRegistry })
+
+    const repairedRoots = new Set<string>()
+    const disposers = [
+      ctx.tools.register(createRecursiveStatusTool(recursive)),
+      ctx.tools.register(createRecursiveInitTool(recursive)),
+      ctx.tools.register(createRecursiveLockTool(recursive)),
+      ctx.tools.register(createRecursiveLintTool(recursive)),
+      ctx.tools.register(createRecursiveCloseoutTool(recursive)),
+      ctx.tools.register(createRecursiveScratchTool(recursive)),
+    ]
+
+    // /recursive command (R4): preset-scoped registration, workspace-scoped dispatch.
+    const commands = ctx.get('commands') as { register: (def: unknown) => () => void } | undefined
+    if (commands) {
+      disposers.push(registerRecursiveCommand({ commands } as never, recursive))
+    }
+
+    // recursive:policy prompt section (Phase C R5): workspace-scoped behavior +
+    // current-phase contract rendered from folded state + enforcement config.
+    const systemPrompt = ctx.get('systemPrompt') as { section: (def: unknown) => () => void } | undefined
+    if (systemPrompt) {
+      disposers.push(systemPrompt.section({
+        name: 'recursive:policy',
+        order: 55,
+        text: (context: unknown) => {
+          const agent = (context as { agent?: { session?: { header?: { cwd?: string } } } } | undefined)?.agent
+          if (!agent) return ''
+          // SP3 R5 policy-render fix: derive intent from the FILESYSTEM, not the
+          // retired recursive/phase-intent session event (zero-emission removed
+          // the emitter, so detectTransitionIntent was ALWAYS null and this
+          // section rendered ''). Pure read-only fs folding; no recursive/*
+          // events are appended.
+          const intent = fsPolicyIntent(agent, workspaceRegistry as never)
+          if (!intent) return ''
+          return renderRecursivePolicy({ worktreeRoot: intent.worktreeRoot, runId: intent.runId, config: recursive.enforcementConfig })
+        },
+      }))
+    }
+
+    // Phase C R3 (Layer 1, agent/pre-step proactive intent gate) is RETIRED
+    // under zero-emission (SP2 R1): its only signal was the recursive/phase-intent
+    // session event, whose emitter is now deleted, and it was ADVISORY by default
+    // (it never rejected; its sole side effect was the now-removed emission).
+    // Enforcement is preserved where it actually bites: Layer 2 (tools/pre-execute
+    // inspects the REAL tool call args below) plus the recursive_lock tool's own
+    // prerequisite validation in lockArtifact — strictly more reliable than the
+    // heuristic intent scan. See 03-implementation-summary.addendum-r1-*.md.
+
+    // Phase C R4: tools/pre-execute surgical guards (Layer 2, caller of the
+    // transition set). Scope-filtered to the active run's worktree.
+    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) => {
+        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
+        // ask -> in advisory we let it through with a warn (the approval seam is Phase D)
+      }))
+    }
+
+    // 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
+    // control-plane root has an active recursive run whose current phase doc is
+    // DRAFT, prepend a compact system-reminder with THAT phase's required sections +
+    // gates. Pure fs read (zero-emission): never appends recursive/* events.
+    const agentRuntime = ctx as unknown as { on?: (event: string, listener: (payload: unknown, next?: unknown) => unknown) => () => void }
+    if (agentRuntime.on) {
+      disposers.push(agentRuntime.on('agent/pre-step', async (payload, next) => {
+        const p = payload as {
+          messages?: Array<{ content: Array<{ type: string; text?: string }> }>,
+          agent?: { session?: { header?: { cwd?: string } } } | null,
+        } | null
+        const messages = p?.messages ?? []
+        const agent = p?.agent ?? null
+        const cwd = agent?.session?.header?.cwd ?? ''
+        // delegate first so later listeners keep veto power, then fold ours on
+        if (typeof next === 'function') await next()
+        if (!cwd) return { kind: 'enter', messages } as const
+        const root = await recursive.resolveRootForRoute(undefined, cwd, undefined)
+        if (!root) return { kind: 'enter', messages } as const
+        // R3/R6 (run 09): idempotent scaffold REPAIR on session-start (new AND
+        // resume). bootstrapScaffold is upsert-only: it adds missing control-plane
+        // files/dirs + re-upserts marked blocks, NEVER overwriting user content or
+        // touching run/ artifacts (in-flight 02-to-be-plan etc. are preserved).
+        // Guarded once per root so repeated pre-steps are cheap no-ops.
+        if (!repairedRoots.has(root)) {
+          repairedRoots.add(root)
+          stageBWorkflowInit({ root, source: 'resume' })
+        }
+        const runs = enumerateRuns(root)
+        if (runs.length === 0) return { kind: 'enter', messages } as const
+        const runId = runs[runs.length - 1]
+        const runDir = join(root, '.recursive', 'run', runId)
+        if (!existsSync(runDir)) return { kind: 'enter', messages } as const
+        const phase = getNextLegalPhase(runDir)
+        if (!phase) return { kind: 'enter', messages } as const
+        // only inject when the phase doc is DRAFT (not locked/missing).
+        const phasePath = join(runDir, phase)
+        const status = existsSync(phasePath) ? getLockStatus(phasePath) : null
+        if (status !== 'DRAFT') return { kind: 'enter', messages } as const
+        const reminder = phaseLintRulesMessage(phase)
+        return {
+          kind: 'enter',
+          messages: [...messages, createUserMessage({ content: [{ type: 'text', text: reminder }], source: { kind: 'plugin', plugin: '@try-works/dsh-recursive-mode' } })],
+        } as const
+      }))
+    }
+
+    // Phase C R8: fs/observed lock-tamper WARNINGS are served to the board via the
+    // 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).
+    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;
+        // the client-passed cwd is a fallback hint (hydration / headless).
+        resolveRoot: async (sessionId: string | undefined, cwd: string) => recursive.resolveRootForRoute(sessionId, cwd, sessionsStore),
+        snapshot: async (root: string) => snapshotWorkspace(root),
+        revision: () => 1,
+      }
+      disposers.push(mountRecursiveRoutesOnce('@try-works/dsh-recursive-mode', () => makeRecursiveRoutes(host), webServer))
+    }
+
+    yield () => { for (const d of disposers) d() }
+  })
+}

package/src/runtime.ts

@@ -1,8 +1,7 @@
 import { Service, type Context } from '@deepseek-ai/cordis'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { execFileSync } from 'node:child_process'
 import { join } from 'node:path'
-import { referencesRoot } from './bootstrap.ts'
+import { lintRun } from './ts-lint.ts'
 import { requirementsContent, worktreeContent, laterPhaseContent, detectGitContext, RUN_SCAFFOLD_DIRS, type GitContext } from './init-templates.ts'
 import { foldRun, resolveRunDir } from './status.ts'
 import {
@@ -464,12 +463,11 @@ export class RecursiveRuntime extends Service {
   }
 
   /**
-   * Lint an artifact with FULL canonical parity: shells out to the vendored
-   * lint-recursive-run.py (byte-identical to canonical) and parses its
-   * [FAIL]/[WARN] lines + Summary counts. `errors` = FAIL lines, `warnings` =
+   * Lint an artifact with FULL canonical parity: runs the in-process ts-lint
+   * port (ts-lint.ts `lintRun`) against the whole run and filters the verdict
+   * lines to the requested artifact. `errors` = FAIL lines, `warnings` =
    * WARN lines, `passed` = no FAIL (WARN-only passes, matching the canonical
-   * non-strict verdict). Falls back to the structural check only if the vendored
-   * script is unavailable (e.g. bundled lib without references/).
+   * non-strict verdict).
    */
   async lintArtifact(runId: string, artifact?: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<LintArtifactResult> {
     const root = await this.resolveRootFor(agent)
@@ -480,22 +478,20 @@ export class RecursiveRuntime extends Service {
     if (!existsSync(artifactPath)) {
       return { artifact: target, runId, errors: ['Artifact not found'], warnings: [], passed: false }
     }
-    const lintScript = join(referencesRoot(), 'scripts', 'lint-recursive-run.py')
-    if (existsSync(lintScript)) {
-      try {
-        const stdout = execFileSync('python', [lintScript, '--repo-root', root, '--run-id', runId], {
-          encoding: 'utf8',
-          stdio: ['ignore', 'pipe', 'ignore'],
-          timeout: 60000,
-        })
-        return parseLintOutput(stdout, target, runId)
-      } catch (err) {
-        const stdout = (err as { stdout?: string })?.stdout ?? ''
-        if (stdout.includes('Summary')) {
-          return parseLintOutput(stdout, target, runId)
-        }
-        // script failed to run entirely — fall through to structural check
-      }
+    const result = lintRun(root, runId)
+    const stdout = [...result.errors, ...result.warnings].join('\n')
+    return parseLintOutput(stdout, target, runId)
+  }
+
+  /** Legacy structural fallback (kept for type reference; lintArtifact uses lintRun). */
+  async lintArtifactStructuralFallback(runId: string, artifact: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<LintArtifactResult> {
+    const root = await this.resolveRootFor(agent)
+    if (!root) throw new Error('cannot resolve workspace control-plane root for this session')
+    const runDir = join(root, '.recursive', 'run', runId)
+    const target = artifact ?? getNextLegalPhase(runDir) ?? '00-requirements.md'
+    const artifactPath = join(runDir, target)
+    if (!existsSync(artifactPath)) {
+      return { artifact: target, runId, errors: ['Artifact not found'], warnings: [], passed: false }
     }
     // Structural fallback (no vendored script available).
     const content = readFileSync(artifactPath, 'utf8')