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

package/src/recursive_audit_team.tool.ts

@@ -0,0 +1,141 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type {
+  TeamRuntimeLike,
+  TeamCallerHandle,
+  TeamTaskActionLike,
+  TeamTaskViewLike,
+  CreateTeamTaskRequestLike,
+  UpdateTeamTaskRequestLike,
+} from './teams-loop.ts'
+
+/**
+ * `recursive_audit_team` — the T3 entry path: a turn-driven adapter over the
+ * live `agentTeams` task board. ONE call advances the audit→repair→re-audit
+ * state machine by one transition, so the agent drives the loop across turns
+ * as continuable-child settlement notices arrive in its inbox.
+ *
+ * Why one step per call: the live subagents service has no public parent-side
+ * "await settlement" promise — a continuable child's verdict arrives as a
+ * `subagent-settled` message on a LATER turn. The pure whole-loop driver
+ * (`auditToPass` in teams-loop.ts) models the full state machine and is the
+ * tested reference; this tool is its honest turn-driven shell.
+ */
+
+/** Project one live task view to an owned, lossless-JSON-safe record. */
+function taskViewToJson(view: TeamTaskViewLike): JsonValue {
+  // Read only leaf fields; never pass the live service object into the model
+  // context (the tool boundary is where a live view becomes owned JSON).
+  return {
+    id: view.id,
+    revision: view.revision,
+    subject: view.subject,
+    description: view.description,
+    status: view.status,
+    blockedBy: [...view.blockedBy],
+    writeScopes: [...view.writeScopes],
+    ownerName: view.ownerName ?? null,
+    ready: view.ready,
+    writeScopeWarnings: [...view.writeScopeWarnings],
+  }
+}
+
+/** Wrap a non-JSON-pure value in the standard error envelope. */
+function errorJson(message: string): JsonValue {
+  return { error: message }
+}
+
+export function createRecursiveAuditTeamTool(teams: TeamRuntimeLike | null) {
+  return defineTool({
+    name: 'recursive_audit_team',
+    description: 'Advance one agentTeams Task-board transition for the recursive audit loop (create → claim → edit(REVISE) → complete(APPROVE) → release/interrupt). Drive one step per turn as continuable-child settlement notices arrive; complete the task (and lock the phase) ONLY after an APPROVE verdict.',
+    parameters: {
+      action: { type: 'string', description: 'create | claim | edit | complete | release | interrupt | get | list. Required.' },
+      taskId: { type: 'string', description: 'Task id for claim/edit/complete/release/interrupt/get.' },
+      expectedRevision: { type: 'number', description: 'CAS revision for claim/edit/complete/release.' },
+      subject: { type: 'string', description: 'Task subject (create).' },
+      description: { type: 'string', description: 'Task description (create) or appended repair note (edit).' },
+      blockedBy: { type: 'array', items: { type: 'string' }, description: 'Task blockers (create).' },
+      writeScopes: { type: 'array', items: { type: 'string' }, description: 'Advisory write scopes (create).' },
+      targetName: { type: 'string', description: 'Teammate name to interrupt (interrupt).' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: {
+      action?: string
+      taskId?: string
+      expectedRevision?: number
+      subject?: string
+      description?: string
+      blockedBy?: string[]
+      writeScopes?: string[]
+      targetName?: string
+    }, exec) {
+      const action = args.action ?? ''
+      if (!teams) return errorJson('agentTeams service is not available in this composition')
+      // SAFETY: exec.agent is the live Team member Agent (a superset of the
+      // named opaque handle); the seam reads only id/session identity and never
+      // serializes it. When no agent owns the call, an empty handle degrades to
+      // an anonymous caller (the service admits/denies by its own authority).
+      const caller: TeamCallerHandle = exec.agent ?? {}
+
+      try {
+        switch (action) {
+          case 'create': {
+            if (!args.subject || !args.description) return errorJson('create requires subject and description')
+            const createRequest: CreateTeamTaskRequestLike = {
+              subject: args.subject,
+              description: args.description,
+            }
+            if (args.blockedBy !== undefined) createRequest.blockedBy = args.blockedBy
+            if (args.writeScopes !== undefined) createRequest.writeScopes = args.writeScopes
+            const view = await teams.createTask(caller, createRequest)
+            return taskViewToJson(view)
+          }
+          case 'claim':
+          case 'edit':
+          case 'complete':
+          case 'release': {
+            if (!args.taskId || args.expectedRevision === undefined) {
+              return errorJson(action + ' requires taskId and expectedRevision')
+            }
+            // SAFETY: this case arm is reachable only for action 'claim' | 'edit' |
+            // 'complete' | 'release' (the switch discriminates on the same string),
+            // each a member of TeamTaskActionLike's subset; the cast re-asserts that
+            // narrowing across the four fall-through labels without widening scope.
+            const updateAction = action as TeamTaskActionLike
+            const updateRequest: UpdateTeamTaskRequestLike = {
+              taskId: args.taskId,
+              expectedRevision: args.expectedRevision,
+              action: updateAction,
+            }
+            if (action === 'edit' && args.description !== undefined) updateRequest.description = args.description
+            const view = await teams.updateTask(caller, updateRequest)
+            return taskViewToJson(view)
+          }
+          case 'interrupt': {
+            if (!args.targetName) return errorJson('interrupt requires targetName')
+            if (!teams.interrupt) return errorJson('no interrupt seam')
+            const outcome = teams.interrupt(caller, args.targetName)
+            return { previousStatus: outcome.previousStatus }
+          }
+          case 'get': {
+            if (!args.taskId) return errorJson('get requires taskId')
+            if (!teams.getTask) return errorJson('no getTask seam')
+            return taskViewToJson(teams.getTask(caller, args.taskId))
+          }
+          case 'list': {
+            if (!teams.listTasks) return errorJson('no listTasks seam')
+            return teams.listTasks(caller).map(taskViewToJson)
+          }
+          default:
+            return errorJson('unsupported action: ' + action + ' (create|claim|edit|complete|release|interrupt|get|list)')
+        }
+      } catch (err) {
+        return errorJson(err instanceof Error ? err.message : String(err))
+      }
+    },
+  })
+}

package/src/runtime.ts

@@ -21,7 +21,7 @@ import { readScratch, writeScratch, appendScratch, type ScratchTarget } from './
 import { buildReviewBundle, type ReviewBundleInput } from './review.ts'
 import { createHandoff, createChildBrief, replyPath, childScratchPath, buildDelegationPrompt, type HandoffInput, type ChildBriefInput } from './handoff.ts'
 import { loadRouterPolicy, routerPolicyPath, resolveRole, capabilityProbe, delegationDecisionBasis, type RouterPolicy, type SubagentProviderLike, type RouteDecision, type CapabilityProbe } from './router.ts'
-import { delegate, validateReferences, writeActionRecord, evaluateDelegationResult, reviewOutputSchema, defaultReviewToolFilter, type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference, type ActionRecordInput } from './delegation.ts'
+import { delegate, delegateContinuable, validateReferences, writeActionRecord, evaluateDelegationResult, reviewOutputSchema, defaultReviewToolFilter, type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference, type ActionRecordInput, type ContinuableDelegationLike, type SubagentParentHandle } from './delegation.ts'
 import { validateTransition, coupleGateBlockToGoal, type PhaseTransitionIntent, type RecursivePhaseState, type GateCheckResult } from './lifecycle.ts'
 import { resolveEnforcementConfig, DEFAULT_ENFORCEMENT, evaluateToolGuard, detectTamper, type EnforcementConfig, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts'
 import type { Session } from '@deepseek-ai/dsh-session'
@@ -29,6 +29,9 @@ import { renderRecursivePolicy, type PolicyContext } from './policy.ts'
 import { snapshotWorkspace } from './snapshot.ts'
 import { createLinkedWorktree, promoteBranch, listWorktrees, defaultWorktreeBranch, type CreateWorktreeResult, type PromoteBranchResult } from './worktree.ts'
 import { gitFacts } from './git-context.ts'
+import { syncRunGoal, blockRunGoal, resumeRunGoal, type GoalServiceLike } from './goals-projection.ts'
+import { auditToPass, renderTaskHistory, type TeamRuntimeLike, type AuditToPassResult, type TeamCallerHandle, type TeamTaskViewLike, type AuditRoundOutcome } from './teams-loop.ts'
+import type { ContinuableChildId, ContinuableMessageId } from './delegation.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -70,16 +73,86 @@ const ARTIFACT_STUB = {
 export class RecursiveRuntime extends Service {
   /** Recursive-mode runtime service. Owns run-state reads + lock/init/lint operations. */
 
-  constructor(ctx: Context, config: { repoRoot?: string; workspaceRegistry?: WorkspaceRegistryLike } = {}) {
+  constructor(ctx: Context, config: { repoRoot?: string; workspaceRegistry?: WorkspaceRegistryLike; goals?: GoalServiceLike | null } = {}) {
     super(ctx, 'recursive')
     this.repoRoot = config.repoRoot ?? process.cwd()
     this.workspaceRegistry = config.workspaceRegistry ?? null
+    this.goalsService = config.goals ?? null
   }
 
   private readonly repoRoot: string
   private readonly workspaceRegistry: WorkspaceRegistryLike | null
+  private readonly goalsService: GoalServiceLike | null
   private _enforcementConfig: EnforcementConfig | null = null
 
+  /**
+   * T3 (agentTeams task loop): run the audit→repair→re-audit state machine on
+   * ONE durable team task. The `teams` seam (live `ctx.agentTeams`) is injected
+   * per-call so the loop stays unit-testable; `runAuditRound` is the caller's
+   * round executor (live usage wires T4's continuable delegation). Locking the
+   * phase artifact is `lockPhase` — the loop NEVER locks before an APPROVE.
+   */
+  async auditToPass(input: {
+    teams: TeamRuntimeLike
+    caller: TeamCallerHandle
+    root: string
+    runId: string
+    phase: string
+    artifact: string
+    agent?: { session?: { header?: { cwd?: string } } } | null
+    runAuditRound: (round: number, task: TeamTaskViewLike) => Promise<AuditRoundOutcome>
+    blockedBy?: readonly string[]
+    writeScopes?: readonly string[]
+    reviewerName?: string
+    maxRounds?: number
+    waitTimeoutMs?: number
+  }): Promise<AuditToPassResult & { history?: string; lock?: LockArtifactResult }> {
+    const { teams, caller, runId, phase, artifact, runAuditRound, agent } = input
+    let lockResult: LockArtifactResult | undefined
+    const lockPhase = async () => { lockResult = await this.lockArtifact(runId, artifact, false, agent) }
+    const result = await auditToPass({
+      teams,
+      caller,
+      runId,
+      phase,
+      blockedBy: input.blockedBy,
+      writeScopes: input.writeScopes,
+      reviewerName: input.reviewerName,
+      maxRounds: input.maxRounds,
+      waitTimeoutMs: input.waitTimeoutMs,
+      runAuditRound,
+      lockPhase,
+    })
+    const report: AuditToPassResult & { history?: string; lock?: LockArtifactResult } = {
+      ...result,
+      history: renderTaskHistory(result.taskView, result.rounds),
+    }
+    if (lockResult !== undefined) report.lock = lockResult
+    return report
+  }
+
+  /**
+   * T1 (goals projection): project the run into the native goals service so it is
+   * a first-class durable, resumable, blockable object. Best-effort — the run's
+   * filesystem state is the source of truth; a goal is the durable projection.
+   */
+  projectRunToGoal(agent: { session?: { header?: { cwd?: string } } } | null | undefined, runId: string, state: Parameters<typeof syncRunGoal>[3] = 'active') {
+    if (!agent) return { ok: false, reason: 'no agent' }
+    return syncRunGoal(this.goalsService, agent, runId, state)
+  }
+
+  /** T1: block the run's goal on a gate-block (durable + UI-visible). */
+  blockRunToGoal(agent: { session?: { header?: { cwd?: string } } } | null | undefined, runId: string, reason: { code: string; message: string }) {
+    if (!agent) return { ok: false, reason: 'no agent' }
+    return blockRunGoal(this.goalsService, agent, runId, reason)
+  }
+
+  /** T1: re-arm the run's goal on a reopen (blocked/paused -> active). */
+  resumeRunToGoal(agent: { session?: { header?: { cwd?: string } } } | null | undefined, runId: string) {
+    if (!agent) return { ok: false, reason: 'no agent' }
+    return resumeRunGoal(this.goalsService, agent, runId)
+  }
+
   /**
    * Workspace-scoped control-plane root (R1 binding invariant).
    * Resolves the session agent's canonical cwd -> workspace path via the
@@ -138,8 +211,16 @@ export class RecursiveRuntime extends Service {
   /**
    * Phase B (native delegation): build a review bundle (R1) + file-backed
    * handoff docs (R2), resolve the role via the router policy (R3), and call
-   * ctx.subagents.start() with the full request (R4). Workspace-scoped: every
-   * path resolves under the session's control-plane root.
+   * ctx.subagents with the full request (R4). Workspace-scoped: every path
+   * resolves under the session's control-plane root.
+   *
+   * `mode: 'continuable'` (T4) runs the audit→repair→re-audit loop on ONE
+   * durable continuable child (startContinuable → followup with the repair
+   * instruction → settle) and drains the child on closeout. It requires an
+   * `awaitRoundResult` observer (the parent-side settlement seam) AND the exact
+   * live `parent` Agent (continuable followup is object-identity authority);
+   * when either is absent it falls back to one-shot `delegate()` with a flag —
+   * never silently. One-shot `start()` is never called on the continuable path.
    */
   async delegateReview(input: {
     root: string
@@ -160,6 +241,11 @@ export class RecursiveRuntime extends Service {
     subagents?: SubagentsRuntimeLike
     maxDepth?: number
     toolFilter?: unknown
+    mode?: 'one-shot' | 'continuable'
+    awaitRoundResult?: (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null>
+    maxRounds?: number
+    /** T4: the exact live direct-parent Agent (object-identity authority). */
+    parent?: SubagentParentHandle
   }) {
     const policy = loadRouterPolicy(input.policyPath ?? routerPolicyPath(input.root))
     const providers = input.providers ?? {}
@@ -213,7 +299,9 @@ export class RecursiveRuntime extends Service {
       briefPath,
     })
 
-    // R4: plugin-driven delegation with the full request shape.
+    // R4: plugin-driven delegation with the full request shape. `parent` is the
+    // exact live direct-parent Agent (object-identity authority in the live
+    // subagent service); absent it, the live start() rejects the request.
     const request: SubagentStartRequestLike = {
       prompt: [{ type: 'text', text: prompt }],
       label: input.delegationId + '/' + input.childId,
@@ -221,12 +309,38 @@ export class RecursiveRuntime extends Service {
       toolFilter: input.toolFilter ?? defaultReviewToolFilter(),
       maxDepth: input.maxDepth ?? 2,
     }
+    if (input.parent !== undefined) request.parent = input.parent
 
     let result: SubagentResultLike | null = null
     let error: string | null = null
+    let continuable: ContinuableDelegationLike | null = null
     if (decision.tier === 'native' || decision.tier === 'external-cli') {
       if (!input.subagents) {
         error = 'no ctx.subagents runtime available (self-audit fallback)'
+      } else if (input.mode === 'continuable') {
+        // T4: one durable child carries every round; start() is never called.
+        continuable = await delegateContinuable({
+          subagents: input.subagents,
+          provider: decision.provider as string,
+          label: input.delegationId + '/' + input.childId,
+          prompt,
+          childId: input.childId,
+          maxDepth: input.maxDepth ?? 2,
+          toolFilter: input.toolFilter ?? defaultReviewToolFilter(),
+          maxRounds: input.maxRounds ?? 3,
+          awaitRoundResult: input.awaitRoundResult,
+          parent: input.parent,
+        })
+        if (continuable.fellBackToOneShot) {
+          // The seam has no continuable capability — keep the one-shot result.
+          result = continuable.rounds[0]?.result ?? null
+          if (!result) error = 'continuable fallback produced no result'
+        } else if (continuable.ok && continuable.rounds.length > 0) {
+          result = continuable.rounds[continuable.rounds.length - 1].result ?? null
+          if (!result) error = 'continuable child produced no final result'
+        } else {
+          error = continuable.reason ?? 'continuable delegation failed'
+        }
       } else {
         try {
           result = await delegate({
@@ -251,7 +365,7 @@ export class RecursiveRuntime extends Service {
       subagentId: input.childId,
       phase: input.phase,
       purpose: input.role + ' for run ' + input.runId,
-      executionMode: decision.tier,
+      executionMode: decision.tier + (input.mode === 'continuable' ? ' (continuable)' : ''),
       artifactPath: input.artifactPath,
       upstreamArtifacts: input.upstreamArtifacts,
       reviewBundle: bundle.repoRelativePath,
@@ -263,6 +377,10 @@ export class RecursiveRuntime extends Service {
       stopReason: result?.stopReason,
     })
 
+    // T4: the durable child id is reported for the caller (a tool/closeout that
+    // holds the live parent Agent may drain it explicitly); the HOST owns the
+    // teardown drain (drainContinuableDescendants) at session close — this loop
+    // never forces a drain with a wrong authority credential (childId ≠ parent).
     return {
       decision,
       probe,
@@ -277,6 +395,7 @@ export class RecursiveRuntime extends Service {
       evaluation,
       actionRecordPath,
       error,
+      continuable: continuable ? { rounds: continuable.rounds, childId: continuable.childId, fellBackToOneShot: continuable.fellBackToOneShot } : null,
     }
   }
 
@@ -431,6 +550,9 @@ export class RecursiveRuntime extends Service {
 
     const result: { runDir: string; runId: string; created: string[]; existing: string[]; worktree?: CreateWorktreeResult } = { runDir, runId, created, existing }
     if (worktree) result.worktree = worktree
+    // T1 (goals projection): arm a durable run goal for the driving session.
+    // Best-effort — never fails a run init if the goals service is absent/odd.
+    try { this.projectRunToGoal(agent, runId, 'active') } catch { /* goal projection is best-effort */ }
     return result
   }
 
@@ -486,6 +608,10 @@ export class RecursiveRuntime extends Service {
     // durable commit below is what the live fs route folds. No phase-intent event.
     const blockers = getPrerequisiteBlockers(runDir, artifact)
     if (blockers.length > 0) {
+      // T1 (goals projection): a gate-block becomes a durable, UI-visible goal
+      // block rather than a one-line advisory. Best-effort before the throw.
+      const message = 'monotonic lock-order: ' + blockers.map(b => b.artifact + ' (' + b.status + ')').join(', ')
+      try { this.blockRunToGoal(agent, runId, { code: 'prerequisite-blockers', message }) } catch { /* best-effort */ }
       throw new Error('Prerequisite blockers: ' + blockers.map(b => b.artifact + ' (' + b.status + ')').join(', '))
     }
     let content = readFileSync(artifactPath, 'utf8')
@@ -521,6 +647,8 @@ export class RecursiveRuntime extends Service {
     const stale = getStaleDownstreamPhases(runDir, artifact)
     for (const entry of stale) invalidateReceipt(runDir, entry.artifact)
     // B2: reopen reverts to DRAFT — the live fs route folds the reverted state.
+    // T1 (goals projection): re-arm the durable run goal (reopen un-blocks).
+    try { this.resumeRunToGoal(agent, runId) } catch { /* best-effort */ }
     return {
       artifact,
       runId,

package/src/skills.ts

@@ -0,0 +1,151 @@
+/**
+ * Packaged `recursive-mode` skill (dsh plugin standard).
+ *
+ * Ships the workflow's operating contract as a bundled skill through
+ * `ctx.skills.registerProvider(...)` — the same shape as the shipped
+ * `dsh-skill-badge` provider: a `bundled` candidate at `BUNDLED_SKILL_RANK`
+ * (600), body read from the package's shipped `skills/recursive-mode/SKILL.md`
+ * (never an inlined TS string literal), with a directory resource base so the
+ * skill can resolve its own assets. Skills are optional instructions, not
+ * session events: this emits nothing and never appends a recursive/* event.
+ *
+ * Optionality: `skills` is a host-plane registry; when the composition has
+ * none, this is a no-op (returns undefined) rather than failing boot.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Package root: <package>/src/.. — skills/ sits next to src/. */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = join(MODULE_DIR, '..')
+
+/** Precedence rank for packaged/bundled skills (mirrors `BUNDLED_SKILL_RANK`). */
+const BUNDLED_SKILL_RANK = 600
+const SKILL_NAME = 'recursive-mode'
+const PROVIDER_NAME = 'recursive-mode'
+const SKILL_BODY_PATH = join(PACKAGE_ROOT, 'skills', SKILL_NAME, 'SKILL.md')
+const SKILL_RESOURCE_BASE = join(PACKAGE_ROOT, 'skills', SKILL_NAME)
+const SKILL_DESCRIPTION =
+  'Drive the recursive-mode workflow: an audit-gated, phase-disciplined loop that carries one requirement from AS-IS through TO-BE plan, implementation, test, and manual QA to locked control-plane state and durable memory. Use whenever the user asks to implement, resume, or advance a recursive run, or when a repo carries a /.recursive/ control plane.'
+
+/** Invocation policy: both the model catalog and user `/name` surfaces may load it. */
+const INVOCATION = { modelInvocable: true, userInvocable: true } as const
+
+/** One skill contribution, mirrored from the `dsh-skill` registry contract. */
+export interface SkillInvocationPolicyLike {
+  readonly modelInvocable: boolean
+  readonly userInvocable: boolean
+}
+
+/** Provider-owned base for relative resource resolution. */
+export type SkillResourceBaseLike =
+  | { readonly kind: 'directory'; readonly path: string }
+  | { readonly kind: 'url'; readonly url: string }
+  | { readonly kind: 'opaque'; readonly description: string }
+
+/** Invocation-neutral summary fields shared by candidates and definitions. */
+export interface SkillSummaryLike {
+  readonly name: string
+  readonly description: string
+  readonly whenToUse?: string
+  readonly invocation: SkillInvocationPolicyLike
+  readonly source: string
+  readonly provider: string
+  readonly resourceBase?: SkillResourceBaseLike
+}
+
+/** Provider catalog entry: a summary plus rank and an opaque locator. */
+export interface SkillCandidateLike extends SkillSummaryLike {
+  readonly rank: number
+  readonly locator: unknown
+  readonly path?: string
+}
+
+/** Complete loaded skill: a summary plus the markdown instruction body. */
+export interface SkillDefinitionLike extends SkillSummaryLike {
+  readonly content: string
+  readonly path?: string
+}
+
+/** Lookup options passed to provider `list`/`get`. */
+export interface SkillLookupOptionsLike {
+  readonly cwd?: string | undefined
+  readonly signal?: AbortSignal | undefined
+}
+
+/** Registration-scoped control borrowed by one provider. */
+export interface SkillProviderControlLike {
+  readonly signal: AbortSignal
+  readonly invalidate: () => void
+}
+
+/** One source of skills, mirrored from the `dsh-skill` SkillProvider contract. */
+export interface SkillProviderLike {
+  readonly name: string
+  readonly list: (options: SkillLookupOptionsLike) => Promise<readonly SkillCandidateLike[] | { readonly candidates: readonly SkillCandidateLike[]; readonly complete: boolean }>
+  readonly get: (candidate: SkillCandidateLike, options: SkillLookupOptionsLike) => Promise<SkillDefinitionLike | undefined>
+}
+
+/** Minimal host-realm contract for ctx.skills (the seam we call). */
+export interface SkillsRuntimeLike {
+  registerProvider(create: (control: SkillProviderControlLike) => SkillProviderLike): () => void
+}
+
+/** The bundled candidate, stable across every `list()` call. */
+function candidate(): SkillCandidateLike {
+  return {
+    name: SKILL_NAME,
+    description: SKILL_DESCRIPTION,
+    invocation: INVOCATION,
+    provider: PROVIDER_NAME,
+    source: 'bundled',
+    resourceBase: { kind: 'directory', path: SKILL_RESOURCE_BASE },
+    rank: BUNDLED_SKILL_RANK,
+    locator: SKILL_BODY_PATH,
+    path: SKILL_BODY_PATH,
+  }
+}
+
+/** Read the shipped operating-contract body (fail loud if the package lost it). */
+function readBody(): string {
+  return readFileSync(SKILL_BODY_PATH, 'utf8').replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+}
+
+/** The one bundled provider this plugin contributes. */
+function provider(): SkillProviderLike {
+  return {
+    name: PROVIDER_NAME,
+    list: () => Promise.resolve([candidate()]),
+    get: async () => ({
+      name: SKILL_NAME,
+      description: SKILL_DESCRIPTION,
+      invocation: INVOCATION,
+      provider: PROVIDER_NAME,
+      source: 'bundled',
+      resourceBase: { kind: 'directory', path: SKILL_RESOURCE_BASE },
+      content: readBody(),
+      path: SKILL_BODY_PATH,
+    }),
+  }
+}
+
+/**
+ * Register the packaged `recursive-mode` skill into the host `skills` registry.
+ *
+ * Reads `ctx.get('skills')` optionally (the registry is host-plane; a
+ * composition without it is valid). On success returns the exact disposer that
+ * unregisters the provider; on absence returns undefined (a no-op, never a boot
+ * failure).
+ */
+export function registerRecursiveSkill(ctx: Context): (() => void) | undefined {
+  const skills = ctx.get('skills')
+  if (skills === undefined || skills === null) return undefined
+  // SAFETY: the single boundary cast asserts the live ctx.skills satisfies the
+  // structural SkillsRuntimeLike seam (registerProvider). The live registry's
+  // method is a superset of this seam; the provider we return is a plain owned
+  // object read through its own leaf fields, never serialized.
+  const registry = skills as SkillsRuntimeLike
+  return registry.registerProvider(() => provider())
+}