refactor(packages): merge timeout/ into guard/, rename cordis/ to self-modification/

git mv timeout-policy beside repeat-tool-guard (both are loop-hygiene
policies on the tool-execution pipeline, and the timeout/ group name
collided with util/timeout) and tool-cordis into self-modification/
(naming the role the framework name obscured). Merged/renamed group
README triplets, tsconfig globs, generator sources, hierarchy tables,
catalogs, and the timeout-policy design note's group references
follow. Adds the fifth FIXME marker (dsh-timeout-guard, recorded as a
suggestion to settle at resolution time).

guard + self-modification suites: 197 passed.

packages/self-modification/repository-plugin/src/bin.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+/** Command-line entry that prepares the current `.dsh-plugin` package. @module */
+
+import { prepareDshPlugin } from './format.ts'
+
+try {
+  await prepareDshPlugin()
+} catch (error) {
+  process.stderr.write(`dsh-plugin-prepare: ${error instanceof Error ? error.message : String(error)}\n`)
+  process.exitCode = 1
+}

packages/self-modification/repository-plugin/src/format.ts

@@ -0,0 +1,193 @@
+/**
+ * Static repository-plugin preparation and prepared-manifest validation.
+ * @module
+ */
+
+import { cp, copyFile, mkdir, mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { z } from 'zod'
+import { parseMcpDocument } from './mcp.ts'
+
+/** Fixed module filename loaded from an installed prepared plugin package. */
+export const PREPARED_ENTRY_FILENAME = 'dsh-plugin.mjs'
+/** Fixed directory containing copied static plugin assets. */
+export const PREPARED_ASSET_DIRECTORY = 'dsh-plugin-assets'
+/** Loader builtin used by every generated import-free wrapper. */
+export const REPOSITORY_PLUGIN_BUILTIN = 'dsh-repository-plugin'
+
+const sourceMetadataSchema = z.object({
+  skills: z.array(z.string().min(1)).default([]),
+  mcpServers: z.string().min(1).optional(),
+}).strict().refine(value => value.skills.length > 0 || value.mcpServers !== undefined, {
+  message: 'declare at least one skill root or mcpServers file',
+})
+const sourcePackageSchema = z.looseObject({
+  name: z.string().min(1),
+  dsh: sourceMetadataSchema,
+})
+const preparedManifestSchema = z.object({
+  name: z.string().min(1),
+  skills: z.array(z.string().min(1)),
+  mcpServers: z.string().min(1).optional(),
+}).strict()
+const preparedConfigSchema = z.object({
+  // Wrappers pass import.meta.url, which is always file: for an installed
+  // package; any other scheme would only fail later inside fileURLToPath with
+  // an uncontextualized TypeError, so reject it at this validation boundary.
+  baseUrl: z.url({ protocol: /^file$/ }),
+  manifest: preparedManifestSchema,
+}).strict()
+
+/** Static manifest embedded in the generated wrapper. */
+export interface PreparedPluginManifest {
+  name: string
+  skills: string[]
+  mcpServers?: string
+}
+
+/** Untrusted generated-wrapper config accepted by the DSH-owned runtime builtin. */
+export interface PreparedPluginConfig {
+  baseUrl: string
+  manifest: PreparedPluginManifest
+}
+
+function formatZodError(label: string, error: z.ZodError): Error {
+  return new Error(`${label}:\n${z.prettifyError(error)}`)
+}
+
+/**
+ * Validate the config passed by an installed prepared wrapper.
+ * @param value - wrapper-provided value crossing the file/module boundary.
+ * @returns a detached typed config.
+ */
+export function parsePreparedPluginConfig(value: unknown): PreparedPluginConfig {
+  const result = preparedConfigSchema.safeParse(value)
+  if (!result.success) throw formatZodError('invalid prepared DSH plugin', result.error)
+  return {
+    baseUrl: result.data.baseUrl,
+    manifest: {
+      name: result.data.manifest.name,
+      skills: result.data.manifest.skills,
+      ...result.data.manifest.mcpServers === undefined ? {} : { mcpServers: result.data.manifest.mcpServers },
+    },
+  }
+}
+
+/**
+ * Whether `candidate` resolves outside `root` — the containment check shared
+ * by prepare-time asset copying and runtime prepared-path resolution.
+ * @param root - directory that must contain the candidate.
+ * @param candidate - absolute path to test.
+ * @returns true when the candidate escapes the root.
+ */
+export function isOutside(root: string, candidate: string): boolean {
+  const path = relative(root, candidate)
+  /* v8 ignore next -- Different-drive Windows relative paths cannot be produced on POSIX coverage hosts. */
+  return path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)
+}
+
+async function sourcePath(pluginDirectory: string, sourceRoot: string, configured: string, kind: 'directory' | 'file'): Promise<string> {
+  if (isAbsolute(configured)) throw new Error(`DSH plugin asset path must be relative: ${JSON.stringify(configured)}`)
+  let path: string
+  try {
+    path = await realpath(resolve(pluginDirectory, configured))
+  } catch (cause) {
+    throw new Error(`DSH plugin asset does not exist: ${JSON.stringify(configured)}`, { cause })
+  }
+  if (isOutside(sourceRoot, path)) {
+    throw new Error(`DSH plugin asset escapes its plugin source root: ${JSON.stringify(configured)}`)
+  }
+  const info = await stat(path)
+  if (kind === 'directory' ? !info.isDirectory() : !info.isFile()) {
+    throw new Error(`DSH plugin asset is not a ${kind}: ${JSON.stringify(configured)}`)
+  }
+  return path
+}
+
+function wrapperSource(manifest: PreparedPluginManifest): string {
+  // The manifest is static, so the wrapper's service dependencies are too:
+  // declaring them gates the wrapper fiber until the composition provides
+  // them, which means the runtime's SkillLocal/McpClient children activate
+  // within the wrapper's own load epoch and their failures (duplicate
+  // provider names, damaged packages) reject the wrapper's Loader
+  // transaction instead of leaving a silently PENDING or FAILED child.
+  const inject = [
+    'loader',
+    ...manifest.skills.length > 0 ? ['skills'] : [],
+    ...manifest.mcpServers === undefined ? [] : ['tools'],
+  ]
+  return [
+    '// Generated by dsh-plugin-prepare. Do not edit.',
+    `const manifest = ${JSON.stringify(manifest)}`,
+    `export const name = ${JSON.stringify(manifest.name)}`,
+    `export const inject = ${JSON.stringify(inject)}`,
+    'export async function apply(ctx) {',
+    `  const runtime = ctx.loader.builtins[${JSON.stringify(REPOSITORY_PLUGIN_BUILTIN)}]`,
+    `  if (runtime === undefined) throw new Error(${JSON.stringify(`missing Cordis builtin ${REPOSITORY_PLUGIN_BUILTIN}`)})`,
+    '  await ctx.plugin(runtime, { baseUrl: import.meta.url, manifest })',
+    '}',
+    '',
+  ].join('\n')
+}
+
+/**
+ * Validate and package one `.dsh-plugin` directory into static assets plus a fixed wrapper.
+ * Outputs are staged and committed by rename, but the final publish (remove
+ * old outputs, rename assets, rename entry) is not one atomic step: a crash
+ * mid-publish can leave assets without an entry or neither. Rerunning prepare
+ * repairs the package; partial outputs are never importable as a plugin.
+ * @param directory - `.dsh-plugin` package directory; defaults to the prepare process cwd.
+ * @returns the generated static manifest.
+ */
+export async function prepareDshPlugin(directory: string = process.cwd()): Promise<PreparedPluginManifest> {
+  const pluginDirectory = await realpath(resolve(directory))
+  let packageValue: unknown
+  try {
+    packageValue = JSON.parse(await readFile(join(pluginDirectory, 'package.json'), 'utf8')) as unknown
+  } catch (cause) {
+    throw new Error(`failed to read DSH plugin package metadata in ${pluginDirectory}`, { cause })
+  }
+  const parsed = sourcePackageSchema.safeParse(packageValue)
+  if (!parsed.success) throw formatZodError('invalid package.json#dsh', parsed.error)
+
+  const sourceRoot = await realpath(dirname(pluginDirectory))
+  const skillSources: string[] = []
+  for (const configured of parsed.data.dsh.skills) {
+    const source = await sourcePath(pluginDirectory, sourceRoot, configured, 'directory')
+    if (!isOutside(source, pluginDirectory)) {
+      throw new Error(`DSH skill root cannot contain the .dsh-plugin package: ${JSON.stringify(configured)}`)
+    }
+    skillSources.push(source)
+  }
+  let mcpSource: string | undefined
+  if (parsed.data.dsh.mcpServers !== undefined) {
+    mcpSource = await sourcePath(pluginDirectory, sourceRoot, parsed.data.dsh.mcpServers, 'file')
+    parseMcpDocument(await readFile(mcpSource, 'utf8'))
+  }
+
+  const manifest: PreparedPluginManifest = {
+    name: parsed.data.name,
+    skills: skillSources.map((_, index) => `${PREPARED_ASSET_DIRECTORY}/skills/${index}`),
+    ...mcpSource === undefined ? {} : { mcpServers: `${PREPARED_ASSET_DIRECTORY}/.mcp.json` },
+  }
+  const staging = await mkdtemp(join(pluginDirectory, '.dsh-plugin-prepare-'))
+  try {
+    const stagedAssets = join(staging, PREPARED_ASSET_DIRECTORY)
+    await mkdir(join(stagedAssets, 'skills'), { recursive: true })
+    await Promise.all(skillSources.map((source, index) => cp(source, join(stagedAssets, 'skills', String(index)), {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+    })))
+    if (mcpSource !== undefined) await copyFile(mcpSource, join(stagedAssets, '.mcp.json'))
+    await writeFile(join(staging, PREPARED_ENTRY_FILENAME), wrapperSource(manifest))
+
+    await rm(join(pluginDirectory, PREPARED_ASSET_DIRECTORY), { recursive: true, force: true })
+    await rm(join(pluginDirectory, PREPARED_ENTRY_FILENAME), { force: true })
+    await rename(stagedAssets, join(pluginDirectory, PREPARED_ASSET_DIRECTORY))
+    await rename(join(staging, PREPARED_ENTRY_FILENAME), join(pluginDirectory, PREPARED_ENTRY_FILENAME))
+  } finally {
+    await rm(staging, { recursive: true, force: true })
+  }
+  return manifest
+}

packages/self-modification/repository-plugin/src/index.ts

@@ -0,0 +1,145 @@
+/**
+ * Restricted repository-plugin runtime for static skills and common MCP definitions.
+ * @module @deepseek-ai/dsh-repository-plugin
+ */
+
+import { readFile, stat } from 'node:fs/promises'
+import { dirname, isAbsolute, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from 'cordis'
+import type {} from '@cordisjs/plugin-loader'
+import { RepositoryCache } from '@cordisjs/plugin-loader/repository'
+import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
+import * as McpClient from '@deepseek-ai/dsh-mcp-client'
+import { z } from 'zod'
+import {
+  REPOSITORY_PLUGIN_BUILTIN,
+  isOutside,
+  parsePreparedPluginConfig,
+  type PreparedPluginConfig,
+} from './format.ts'
+import { parseMcpDocument, resolveMcpServers } from './mcp.ts'
+import {
+  loadPreparedRepository,
+  resolveRepositoryCacheDirectory,
+  resolveRepositorySpecifier,
+} from './source.ts'
+
+export {
+  PREPARED_ASSET_DIRECTORY,
+  PREPARED_ENTRY_FILENAME,
+  REPOSITORY_PLUGIN_BUILTIN,
+  prepareDshPlugin,
+  type PreparedPluginManifest,
+} from './format.ts'
+
+/** Cordis plugin name used by Loader diagnostics. */
+export const name = 'repository-plugin'
+/** Loader service required to register the fixed prepared-wrapper builtin. */
+export const inject = ['loader']
+
+/** Repository Plugin runtime and source-list configuration. */
+export interface Config {
+  /** GitHub repository sources with explicit refs and optional `.dsh-plugin` subpaths. */
+  repositories?: string[]
+  /** Persistent generation cache; defaults to `$DSH_HOME/cache/repository-plugins`. */
+  cacheDir?: string
+}
+
+export const Config = z.object({
+  repositories: z.array(z.string().min(1)).default([]),
+  cacheDir: z.string().min(1).optional(),
+}).strict().default({ repositories: [] })
+
+function preparedPath(baseUrl: string, configured: string): string {
+  if (isAbsolute(configured)) throw new Error(`prepared DSH plugin path must be relative: ${JSON.stringify(configured)}`)
+  const directory = dirname(fileURLToPath(baseUrl))
+  const path = resolve(directory, configured)
+  if (isOutside(directory, path)) {
+    throw new Error(`prepared DSH plugin path escapes its package: ${JSON.stringify(configured)}`)
+  }
+  return path
+}
+
+async function preparedDirectory(baseUrl: string, configured: string): Promise<string> {
+  const path = preparedPath(baseUrl, configured)
+  // A manifest-declared skill root missing from the installed package (files/
+  // .npmignore dropping generated outputs, a damaged cache entry) must fail
+  // the plugin load: the skill provider treats an absent root as legitimately
+  // empty, which would silently mount a skill-less plugin.
+  let info
+  try {
+    info = await stat(path)
+  } catch (cause) {
+    throw new Error(`prepared DSH plugin skill root is missing from the installed package: ${JSON.stringify(configured)}`, { cause })
+  }
+  if (!info.isDirectory()) {
+    throw new Error(`prepared DSH plugin skill root is not a directory: ${JSON.stringify(configured)}`)
+  }
+  return path
+}
+
+async function applyPrepared(ctx: Context, value: PreparedPluginConfig): Promise<void> {
+  const config = parsePreparedPluginConfig(value)
+  const directory = dirname(fileURLToPath(config.baseUrl))
+  const skillDirectories = await Promise.all(config.manifest.skills.map(path => preparedDirectory(config.baseUrl, path)))
+  const mcpConfigs = config.manifest.mcpServers === undefined
+    ? []
+    : resolveMcpServers(
+      parseMcpDocument(await readFile(preparedPath(config.baseUrl, config.manifest.mcpServers), 'utf8')),
+      process.env,
+      directory,
+      // Schemastery call signatures collapse the parameter to `never` under
+      // NodeNext; ResolvedMcpServer is shaped for the Config union by design.
+    ).map(input => McpClient.Config(input as never))
+
+  await ctx.effect(async function* () {
+    if (skillDirectories.length > 0) {
+      const skills = ctx.plugin(SkillLocal, {
+        providerName: `repository:${config.manifest.name}`,
+        includeDefaultRoots: false,
+        customSkillDirs: skillDirectories,
+        watch: false,
+      })
+      await skills
+      yield skills.dispose
+    }
+    for (const mcpConfig of mcpConfigs) {
+      const mcp = ctx.plugin(McpClient, mcpConfig)
+      await mcp
+      yield mcp.dispose
+    }
+  }, `repository-plugin(${config.manifest.name})`)
+}
+
+const preparedRuntime = {
+  name: 'repository-plugin-runtime',
+  apply: applyPrepared,
+}
+
+/**
+ * Register the DSH-owned runtime as the Loader builtin used by fixed prepared wrappers.
+ * @param ctx - plugin context carrying the Loader service.
+ */
+export async function apply(ctx: Context, config: Config = {}): Promise<void> {
+  if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] !== undefined) {
+    throw new Error(`Loader builtin ${REPOSITORY_PLUGIN_BUILTIN} is already registered`)
+  }
+  const repositories = (config.repositories ?? []).map(resolveRepositorySpecifier)
+  if (new Set(repositories).size !== repositories.length) {
+    throw new Error('repository sources must resolve to unique exact specifiers')
+  }
+  const cache = new RepositoryCache(resolveRepositoryCacheDirectory(config.cacheDir))
+  await ctx.effect(async function* () {
+    ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] = preparedRuntime
+    yield () => {
+      if (ctx.loader.builtins[REPOSITORY_PLUGIN_BUILTIN] === preparedRuntime) {
+        Reflect.deleteProperty(ctx.loader.builtins, REPOSITORY_PLUGIN_BUILTIN)
+      }
+    }
+    for (const repository of repositories) {
+      const plugin = await loadPreparedRepository(ctx, cache, repository)
+      yield plugin.dispose
+    }
+  }, 'repository-plugin runtime and sources')
+}

packages/self-modification/repository-plugin/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-repository-plugin`.
+ * @module @deepseek-ai/dsh-repository-plugin/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-repository-plugin'
+
+/** Cordis companion plugin name. */
+export const name = 'repository-plugin-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the package owns no service state; Loader fibers and the existing skill
+ * and MCP owners expose the authoritative lifecycle relationships for its composed children.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/self-modification/repository-plugin/src/mcp.ts

@@ -0,0 +1,152 @@
+/**
+ * Parser for the common `.mcp.json` file consumed by prepared repository plugins.
+ * @module
+ */
+
+import { z } from 'zod'
+
+/**
+ * Restates dsh-mcp-client's `SERVER_NAME_PATTERN` rather than importing it:
+ * the prepare bin must stay a zod-only module graph (no tools seam, no MCP
+ * SDK). Exported so `repository-plugin.spec.ts` pins equality with the
+ * client's exported pattern — prepare-time validation cannot drift from the
+ * registry that enforces uniqueness.
+ */
+export const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/
+const ENVIRONMENT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+const PLACEHOLDER_PATTERN = /\$\{([^}]*)\}/g
+
+const stringMap = z.record(z.string(), z.string())
+const stdioServerSchema = z.object({
+  type: z.literal('stdio').optional(),
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  env: stringMap.optional(),
+}).strict()
+const httpServerSchema = z.object({
+  type: z.literal('http'),
+  url: z.string().min(1),
+  headers: stringMap.optional(),
+}).strict()
+const documentSchema = z.object({
+  mcpServers: z.record(z.string(), z.union([stdioServerSchema, httpServerSchema])),
+}).strict()
+
+/** One supported server entry from the common `.mcp.json` format. */
+export type McpServerDefinition = z.infer<typeof stdioServerSchema> | z.infer<typeof httpServerSchema>
+
+/** Parsed common MCP document before process-environment expansion. */
+export interface McpDocument {
+  mcpServers: Record<string, McpServerDefinition>
+}
+
+/** Resolved input handed to the existing `dsh-mcp-client` Config schema. */
+export type ResolvedMcpServer =
+  | {
+    transport: 'stdio'
+    serverName: string
+    command: string
+    args: string[]
+    env: Record<string, string>
+    cwd: string
+  }
+  | {
+    transport: 'streamable-http'
+    serverName: string
+    url: string
+    headers: Record<string, string>
+  }
+
+function assertTemplate(value: string, location: string): void {
+  for (const match of value.matchAll(PLACEHOLDER_PATTERN)) {
+    const name = match[1] as string
+    if (!ENVIRONMENT_NAME_PATTERN.test(name)) {
+      throw new Error(`${location} contains an unsupported environment placeholder ${JSON.stringify(match[0])}`)
+    }
+  }
+  if (value.replace(PLACEHOLDER_PATTERN, '').includes('${')) {
+    throw new Error(`${location} contains an unterminated environment placeholder`)
+  }
+}
+
+function visitStrings(serverName: string, definition: McpServerDefinition, visit: (value: string, location: string) => void): void {
+  if ('command' in definition) {
+    visit(definition.command, `mcpServers.${serverName}.command`)
+    definition.args?.forEach((value, index) => { visit(value, `mcpServers.${serverName}.args[${index}]`) })
+    Object.entries(definition.env ?? {}).forEach(([name, value]) => { visit(value, `mcpServers.${serverName}.env.${name}`) })
+    return
+  }
+  visit(definition.url, `mcpServers.${serverName}.url`)
+  Object.entries(definition.headers ?? {}).forEach(([name, value]) => { visit(value, `mcpServers.${serverName}.headers.${name}`) })
+}
+
+/**
+ * Parse and validate one common `.mcp.json` document without resolving environment values.
+ * @param content - UTF-8 JSON document.
+ * @returns the supported stdio and Streamable HTTP server definitions.
+ */
+export function parseMcpDocument(content: string): McpDocument {
+  let value: unknown
+  try {
+    value = JSON.parse(content) as unknown
+  } catch (cause) {
+    throw new Error('invalid .mcp.json: expected JSON', { cause })
+  }
+  const result = documentSchema.safeParse(value)
+  if (!result.success) throw new Error(`invalid .mcp.json:\n${z.prettifyError(result.error)}`)
+  for (const [serverName, definition] of Object.entries(result.data.mcpServers)) {
+    if (!SERVER_NAME_PATTERN.test(serverName)) {
+      throw new Error(`invalid .mcp.json: server name ${JSON.stringify(serverName)} must match ${SERVER_NAME_PATTERN.source}`)
+    }
+    visitStrings(serverName, definition, assertTemplate)
+  }
+  return result.data
+}
+
+function expand(value: string, environment: NodeJS.ProcessEnv, location: string): string {
+  return value.replace(PLACEHOLDER_PATTERN, (_placeholder, name: string) => {
+    const replacement = environment[name]
+    if (replacement === undefined) throw new Error(`${location} requires missing environment variable ${name}`)
+    return replacement
+  })
+}
+
+function expandMap(values: Record<string, string> | undefined, environment: NodeJS.ProcessEnv, location: string): Record<string, string> {
+  return Object.fromEntries(Object.entries(values ?? {}).map(([name, value]) => [
+    name,
+    expand(value, environment, `${location}.${name}`),
+  ]))
+}
+
+/**
+ * Resolve supported MCP definitions to inputs for the existing MCP client.
+ * @param document - validated common MCP document.
+ * @param environment - process environment used for exact `${NAME}` expansion.
+ * @param cwd - prepared plugin directory used for stdio child processes.
+ * @returns one existing-client config input per declared server.
+ */
+export function resolveMcpServers(document: McpDocument, environment: NodeJS.ProcessEnv, cwd: string): ResolvedMcpServer[] {
+  return Object.entries(document.mcpServers).map(([serverName, definition]) => {
+    if ('command' in definition) {
+      return {
+        transport: 'stdio',
+        serverName,
+        command: expand(definition.command, environment, `mcpServers.${serverName}.command`),
+        args: (definition.args ?? []).map((value, index) => expand(value, environment, `mcpServers.${serverName}.args[${index}]`)),
+        env: expandMap(definition.env, environment, `mcpServers.${serverName}.env`),
+        cwd,
+      }
+    }
+    const url = expand(definition.url, environment, `mcpServers.${serverName}.url`)
+    const protocol = new URL(url).protocol
+    if (protocol !== 'http:' && protocol !== 'https:') {
+      throw new Error(`mcpServers.${serverName}.url must use http or https`)
+    }
+    return {
+      transport: 'streamable-http',
+      serverName,
+      url,
+      headers: expandMap(definition.headers, environment, `mcpServers.${serverName}.headers`),
+    }
+  })
+}

packages/self-modification/repository-plugin/src/source.ts

@@ -0,0 +1,94 @@
+/**
+ * GitHub repository source validation and prepared-wrapper loading.
+ * @module
+ */
+
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Context, Fiber, FiberState, Plugin } from 'cordis'
+import type { RepositoryCache } from '@cordisjs/plugin-loader/repository'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { PREPARED_ENTRY_FILENAME } from './format.ts'
+
+// Value mirror: Cordis's const enum has no runtime object to import. Keep
+// aligned with `packages/self-modification/tool-cordis/src/fiber-state.ts`.
+const FIBER_ACTIVE = 2 as FiberState.ACTIVE
+
+/** Directory under the Harness home containing immutable repository generations. */
+export const DEFAULT_REPOSITORY_CACHE_DIRECTORY = 'repository-plugins'
+
+// The ref segment excludes `#` so `github:o/r#a#b` fails here — at the config
+// parser, with the syntax the error message promises — instead of inside the
+// cache's pnpm install ('misconfiguration fails loud at the earliest
+// resolvable point').
+const GITHUB_SOURCE_PATTERN = /^github:([^/\s#&]+)\/([^/\s#&]+)#([^\s#&]+)(?:&path:(\/[^\s&]+))?$/
+
+function validPluginPath(path: string): boolean {
+  const segments = path.split('/').slice(1)
+  return segments.length > 0
+    && segments.at(-1) === '.dsh-plugin'
+    && segments.every(segment => segment.length > 0 && segment !== '.' && segment !== '..')
+}
+
+/**
+ * Normalize one user-facing GitHub source to the exact pnpm dependency specifier.
+ * @param configured - `github:owner/repo#ref` with an optional `&path:/.../.dsh-plugin`.
+ * @returns the exact specifier, with the root `.dsh-plugin` subpath added when omitted.
+ * @throws when the GitHub owner, repository, explicit ref, or plugin subpath is invalid.
+ */
+export function resolveRepositorySpecifier(configured: string): string {
+  const match = GITHUB_SOURCE_PATTERN.exec(configured)
+  if (match === null) {
+    throw new Error(`repository source must use github:owner/repo#<ref> with an optional &path:/.../.dsh-plugin: ${JSON.stringify(configured)}`)
+  }
+  const path = match[4]
+  if (path !== undefined && !validPluginPath(path)) {
+    throw new Error(`repository source path must be an absolute repository subpath ending in .dsh-plugin without empty, . or .. segments: ${JSON.stringify(path)}`)
+  }
+  return path === undefined ? `${configured}&path:/.dsh-plugin` : configured
+}
+
+/**
+ * Resolve the persistent repository cache root.
+ * @param configured - explicit cache directory, or undefined for `$DSH_HOME/cache/repository-plugins`.
+ * @returns an absolute cache directory.
+ */
+export function resolveRepositoryCacheDirectory(configured: string | undefined): string {
+  return resolve(configured ?? join(resolveDshHome(), 'cache', DEFAULT_REPOSITORY_CACHE_DIRECTORY))
+}
+
+/**
+ * Load one exact repository generation's generated wrapper as a child Cordis fiber.
+ * @param ctx - repository runtime context that owns the child.
+ * @param cache - package-manager-native immutable repository cache.
+ * @param specifier - normalized exact pnpm dependency specifier.
+ * @returns the settled prepared-wrapper fiber.
+ * @throws when installation, wrapper import, manifest validation, or child registration fails.
+ */
+export async function loadPreparedRepository(
+  ctx: Context,
+  cache: Pick<RepositoryCache, 'resolve'>,
+  specifier: string,
+): Promise<Fiber> {
+  const directory = await cache.resolve(specifier)
+  const filename = join(directory, PREPARED_ENTRY_FILENAME)
+  try {
+    const plugin = await import(/* @vite-ignore */pathToFileURL(filename).href) as Plugin
+    const fiber = ctx.plugin(plugin)
+    await fiber
+    // Awaiting a service-gated fiber returns while it is still PENDING (the
+    // generated wrapper injects `skills`/`tools` per its manifest). This
+    // runtime commits the repository configuration transactionally, so a
+    // composition that never provides a required service must reject the
+    // transaction here — not settle ACTIVE with a silently pending child.
+    if (fiber.state !== FIBER_ACTIVE) {
+      const missing = Object.keys(fiber.inject).filter(service => fiber.ctx.get(service) === undefined)
+      /* v8 ignore next 2 -- the 'unknown' arm needs a service to appear after the state read; not deterministically stageable. */
+      const detail = missing.join(', ') || 'unknown'
+      throw new Error(`prepared wrapper did not activate (waiting for services: ${detail})`)
+    }
+    return await fiber
+  } catch (cause) {
+    throw new Error(`failed to load prepared repository Plugin ${JSON.stringify(specifier)} from ${filename}`, { cause })
+  }
+}