dev-flow-deepseek 0.1.0 → 0.5.1

package/README.md

@@ -1,129 +1,44 @@
 # dev-flow-deepseek
 
-`dev-flow-deepseek` is a prebuilt DeepSeek Harness bundle that connects
-the official DSH MCP client to an independently installed Dev Flow Orchestrator
-runtime. Its local STDIO projection proxy exposes exactly six tools and renders
-each complete Dev Flow result envelope as deterministic canonical JSON while
-preserving valid upstream success and domain-error semantics. The external
-Python Controller remains the only workflow and task-state authority.
+`dev-flow-deepseek` is the independently versioned DeepSeek Harness adapter to Dev Flow's current
+process graph. Its package metadata is public-release capable; actual support begins only after the
+selected release command and registry lifecycle gate complete.
 
-## Exact compatibility
+Its product version comes only from `package.json`. The packaged Core reports its own independently
+maintained version; the adapter validates the actual executable, six-tool catalog, live schemas,
+server information, process definition, and behavior without comparing the two product versions.
 
-| Component | Supported baseline |
-|---|---|
-| This package | `0.1.0` |
-| DeepSeek Harness | `@deepseek-ai/dsh@0.1.0-rc.6`, npm SHA-1 `de9fbf39056c7f4e658a3e284cb1d66ebc86d040`, public source baseline `47f943859bef60e4160492346772ded9b24f765a` |
-| Dev Flow Orchestrator | release `0.6.12`, commit `7edd4fa12fe6787aac57f16246cbab00b8d79272` |
-| Dev Flow MCP interface | `dev-flow-mcp/1.0.0` |
-| Dev Flow result schema | `dev-flow-mcp-result/1.0.0` |
-| Dev Flow model namespace | `0.4.0` |
-| Node.js | `^22.19.0 || >=24.0.0` |
-| MCP SDK | `1.12.0` |
+The package targets macOS arm64 with Node.js 24 or newer and declares compatibility with the DSH
+`>=0.1.0-rc.6` service family. Compatibility uses this minimum version without an upper bound;
+release evidence records the actual DSH version used by the final registry lifecycle.
 
-Compatibility is exact. Later DSH or Dev Flow releases are not inferred to be
-compatible.
+## Profile lifecycle
 
-## Prerequisites and installation
+DSH owns installation and profile reconciliation. Add a reviewed local artifact with:
 
-Install DeepSeek Harness `0.1.0-rc.6` and the separate `dev-flow-mcp` executable
-from Dev Flow Orchestrator `0.6.12` before using this bundle. The executable may
-be on `PATH` or selected with an absolute `DEV_FLOW_MCP_COMMAND` value. This npm
-package does not install, update, repair, migrate, or remove Python, `uv`, or the
-Dev Flow runtime.
-
-Install the stable release into an isolated DSH profile:
-
-```sh
-dsh plugin --profile web add dev-flow-deepseek@latest
-```
-
-Alternatively, build and pack locally with the pinned package manager:
-
-```sh
-corepack pnpm@11.7.0 install --frozen-lockfile
-corepack pnpm@11.7.0 run build
-corepack pnpm@11.7.0 pack
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dev-flow-deepseek-<version>.tgz
 ```
 
-Add the resulting tarball to an isolated DSH profile, for example the `web`
-profile, then remove it by package name when no longer needed:
+Stop and restart that DSH profile before validating the resolved bundle. Remove the package with:
 
-```sh
-dsh plugin --profile web add /absolute/path/dev-flow-deepseek-0.1.0.tgz
-dsh plugin --profile web remove dev-flow-deepseek
+```bash
+dsh plugin --profile <profile> remove dev-flow-deepseek
 ```
 
-Removal deletes only the profile dependency and bundle layer. It does not
-delete Dev Flow task data.
-
-## Data and use
-
-By default the bundle sets `DEV_FLOW_DATA_DIR` to
-`$DSH_HOME/dev-flow-orchestrator/data`; the compatible backend appends its
-`0.4.0` namespace. This keeps DSH tasks separate from Codex Dev Flow data. An
-explicit `DEV_FLOW_DATA_DIR` set before DSH starts overrides that root.
-
-Inside one existing Git worktree, invoke the Skill explicitly:
-
-```text
-/dev-flow Implement the requested change and verify it.
-```
-
-The Skill validates the exact runtime identity, discovers a compatible active
-task or starts one `lite` task, follows only the Controller's fresh action and
-binding, and stops on the Controller's Delivery Dossier.
-
-The outward raw MCP surface is exactly:
-
-- `dev_flow_server_info`
-- `dev_flow_find_tasks_for_path`
-- `dev_flow_get_task`
-- `dev_flow_get_next_action`
-- `dev_flow_start_task`
-- `dev_flow_apply_action`
-
-## Supported and unsupported scope
-
-The MVP supports explicit `/dev-flow`, one current Git repository, compatible
-active `lite` task resume, new `lite` tasks, local STDIO, safe mutation
-read-after-write recovery, and complete spilled-result retrieval.
-
-It does not support implicit activation, multiple repositories, another
-workflow, task listing or cancellation, governance decisions, finding
-disposition, contract revision, custom DSH UI, runtime installation, a generic
-shell MCP, HTTP/SSE/remote MCP, OAuth, branch or worktree management, commits,
-pushes, pull requests, tags, or releases. Windows is unverified.
-
-## Troubleshooting
+Restart after removal before checking that the bundle contributions are absent. Reinstallation uses
+the same official add command and the exact previously reviewed artifact.
 
-- If no Dev Flow tools appear, confirm that the package layer is installed and
-  that `DEV_FLOW_MCP_COMMAND` resolves directly to the `0.6.12`
-  `dev-flow-mcp` executable. DSH remains usable when startup fails because the
-  bundle sets `failOnStartupError: false`.
-- If `/dev-flow` reports an incompatible identity, use the exact versions in
-  the compatibility table. Do not substitute a newer release.
-- If a mutation response is lost, do not replay it. The Skill rediscovers a
-  possibly created task or reads the task and fresh action before any retry.
-- If DSH reports a spilled, truncated, pruned, or preview result, the Skill
-  must read the complete saved canonical JSON text before using authority
-  fields.
+The official lifecycle owns the DSH dependency entry, bundle layer, integration process, Skill,
+guard, and MCP child. Dev Flow task data, target repositories, and Codex-owned package or
+configuration state remain outside package removal.
 
-## Trust and verification
+## Support boundary
 
-The installed bundle executes its prebuilt Node proxy and the selected local
-Dev Flow executable outside the DSH agent sandbox. Install the package only
-from a publisher you trust. The proxy reduces ambient authority by using no
-shell, passing only a closed child environment, opening no listener, and
-exposing no tool outside the six-tool allowlist; it does not claim code signing,
-provenance attestation, automatic updates, or protection from a compromised
-publisher or runtime.
+The package contains one `dsh.bundle.patch` layer and is designed to contribute one integration row.
+Its final Feature 010 artifact will contain one user-invocable `dev-flow` Skill, a current-turn
+selector guard, the official local STDIO MCP client, and one packaged darwin-arm64 Core.
 
-Deterministic verification consists of 25 bounded unit cases, one local fake
-MCP suite with exactly eight scenarios, one package-contract check, strict
-OpenSpec validation, and the documented default gate. The real-runtime smoke is
-opt-in and requires Dev Flow `0.6.12`. A fake backend or static inspection is not
-evidence of a real DSH GUI journey. The recorded evidence verifies the real DSH
-happy path and restart/resume/removal journey on macOS arm64. The stable
-release artifact was separately revalidated for package installation, composed
-path resolution, and removal. Linux x64 and Windows remain `UNVERIFIED`; see
-`tests/manual/deepseek-harness-journey.md` for the exact evidence boundary.
+Source capability alone is not a public support claim. npm, `deepseek-v*`, GitHub Release assets and
+the registry-installed DSH lifecycle must all be verified by `pnpm run release:deepseek` before the
+support matrix is promoted.

package/cordis.patch.yml

@@ -1,27 +1,3 @@
 - insert:
-    - id: dev-flow-mcp
-      name: '@deepseek-ai/dsh-mcp-client'
-      config:
-        serverName: dev-flow
-        transport: stdio
-        command: !!js process.execPath
-        args:
-          - !!js process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dev-flow-deepseek/lib/proxy.js')
-        env:
-          DEV_FLOW_MCP_COMMAND: !!js process.env.DEV_FLOW_MCP_COMMAND ?? 'dev-flow-mcp'
-          DEV_FLOW_DATA_DIR: !!js process.env.DEV_FLOW_DATA_DIR ?? dshHomePath('dev-flow-orchestrator/data')
-        toolCallTimeoutMs: 120000
-        failOnStartupError: false
-        reconnect:
-          enabled: true
-          initialDelayMs: 500
-          maxDelayMs: 30000
-          maxAttempts: 10
-
-    - id: dev-flow-skill-provider
-      name: '@deepseek-ai/dsh-skill-filesystem'
-      config:
-        providerName: dev-flow-bundle
-        includeDefaultRoots: false
-        customSkillDirs:
-          - !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dev-flow-deepseek/package.json')), 'skills')
+    - id: dev-flow-deepseek
+      name: dev-flow-deepseek

package/lib/authorization.mjs

@@ -0,0 +1,117 @@
+import {
+  isDevFlowNamespaceTool,
+  isExpectedDevFlowTool,
+} from "./tool-names.mjs";
+
+export const DENIAL_CODES = Object.freeze({
+  SELECTOR_REQUIRED: "DEV_FLOW_SELECTOR_REQUIRED",
+  UNEXPECTED_TOOL: "DEV_FLOW_UNEXPECTED_TOOL",
+  NO_AGENT: "DEV_FLOW_NO_AGENT",
+  NO_OPEN_TURN: "DEV_FLOW_NO_OPEN_TURN",
+});
+
+const selectorPattern = /(^|\s)\/dev-flow(?=\s|$)/u;
+const selectorInstruction = "include a whitespace-bounded /dev-flow in the current direct user turn";
+
+export function hasDirectUserSelector(message) {
+  if (message?.source?.kind !== "user" || !Array.isArray(message.content)) return false;
+  return message.content.some(
+    (block) => block?.type === "text"
+      && typeof block.text === "string"
+      && selectorPattern.test(block.text),
+  );
+}
+
+export function deriveCurrentTurn(execution) {
+  try {
+    const agent = execution?.agent;
+    if (agent?.status !== "running" || !Array.isArray(agent.session?.events)) return undefined;
+    const events = agent.session.events;
+    const matchingCalls = events
+      .map((event, index) => ({ event, index }))
+      .filter(({ event }) => event?.type === "tool/call"
+        && String(event.data?.callId) === String(execution.callId));
+
+    if (matchingCalls.length === 1) {
+      return deriveDurableCallTurn(execution, events, matchingCalls[0]);
+    }
+    if (matchingCalls.length > 1 || execution.parent === undefined) return undefined;
+    return deriveNestedTurn(events);
+  } catch {
+    return undefined;
+  }
+}
+
+export function authorizeDevFlowExecution(execution) {
+  if (!isDevFlowNamespaceTool(execution?.name)) return undefined;
+  if (!isExpectedDevFlowTool(execution.name)) {
+    return `${DENIAL_CODES.UNEXPECTED_TOOL}: the Dev Flow namespace permits only the six contracted tools.`;
+  }
+  if (execution.agent === undefined) {
+    return `${DENIAL_CODES.NO_AGENT}: ${selectorInstruction}.`;
+  }
+
+  const turn = deriveCurrentTurn(execution);
+  if (turn === undefined) {
+    return `${DENIAL_CODES.NO_OPEN_TURN}: ${selectorInstruction}.`;
+  }
+  if (!turn.selectorPresent) {
+    return `${DENIAL_CODES.SELECTOR_REQUIRED}: ${selectorInstruction}.`;
+  }
+  return undefined;
+}
+
+export function registerDevFlowGuard(ctx) {
+  return ctx.tools.guard(authorizeDevFlowExecution);
+}
+
+function deriveDurableCallTurn(execution, events, matchingCall) {
+  const { event: callEvent, index: callIndex } = matchingCall;
+  if (callEvent.data?.name !== execution.name) return undefined;
+  const turn = callEvent.data?.turn;
+  if (!Number.isInteger(turn)) return undefined;
+
+  const starts = events
+    .slice(0, callIndex + 1)
+    .map((event, index) => ({ event, index }))
+    .filter(({ event }) => event?.type === "turn/start" && event.data?.turn === turn);
+  if (starts.length !== 1) return undefined;
+  const start = starts[0];
+
+  for (let index = start.index + 1; index < events.length; index += 1) {
+    const event = events[index];
+    if (event?.type === "turn/start") return undefined;
+    if (event?.type === "turn/end" && event.data?.turn === turn) return undefined;
+  }
+  return projectTurn(events, start, callIndex, turn, callEvent.seq);
+}
+
+function deriveNestedTurn(events) {
+  let open;
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (event?.type === "turn/start") {
+      if (open !== undefined || !Number.isInteger(event.data?.turn)) return undefined;
+      open = { event, index };
+    } else if (event?.type === "turn/end") {
+      if (open === undefined || event.data?.turn !== open.event.data?.turn) return undefined;
+      open = undefined;
+    }
+  }
+  if (open === undefined) return undefined;
+  return projectTurn(events, open, events.length, open.event.data.turn, undefined);
+}
+
+function projectTurn(events, start, endIndex, turn, callSeq) {
+  const messages = events
+    .slice(start.index + 1, endIndex)
+    .filter((event) => event?.type === "user/message" && event.data?.source?.kind === "user")
+    .map((event) => event.data);
+  return Object.freeze({
+    turn,
+    startSeq: start.event.seq,
+    ...(callSeq === undefined ? {} : { callSeq }),
+    directUserMessageIds: Object.freeze(messages.map((message) => message.id)),
+    selectorPresent: messages.some(hasDirectUserSelector),
+  });
+}

package/lib/index.mjs

@@ -0,0 +1,114 @@
+import * as mcpClientPlugin from "@deepseek-ai/dsh-mcp-client";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { registerDevFlowGuard } from "./authorization.mjs";
+import {
+  ensureDefaultDataDirectory,
+  packageRootFromModule,
+  resolveDataDirectory,
+} from "./paths.mjs";
+import { preflightPackagedCore, selectPackagedRuntime } from "./runtime.mjs";
+import {
+  DEV_FLOW_SERVER_NAME,
+  assertQualifiedToolCatalog,
+} from "./tool-names.mjs";
+
+export const name = "dev-flow-deepseek";
+export const inject = ["skills", "tools"];
+
+export async function apply(ctx) {
+  await activateDeepSeekIntegration(ctx);
+}
+
+export async function activateDeepSeekIntegration(ctx, {
+  packageRoot = packageRootFromModule(import.meta.url),
+  homeDirectory,
+  environment = process.env,
+  platform = process.platform,
+  arch = process.arch,
+} = {}) {
+  const manifest = await readPackageManifest(packageRoot);
+  const runtimeSelection = await selectPackagedRuntime({ packageRoot, platform, arch });
+  const dataSelection = await resolveDataDirectory({ homeDirectory, environment });
+  if (dataSelection.usesDefaultDataDirectory) {
+    await ensureDefaultDataDirectory(dataSelection);
+  }
+  const runtime = await preflightPackagedCore(runtimeSelection, {
+    environment,
+  });
+
+  const skillDirectory = join(runtime.packageRoot, "skills", "dev-flow");
+  const skillPath = join(skillDirectory, "SKILL.md");
+  const skillContent = await readFile(skillPath, "utf8");
+
+  ctx.skills.register(Object.freeze({
+    name: "dev-flow",
+    description: "Use the Dev Flow graph Core for the current explicit development request.",
+    whenToUse: "Use only for a current direct user turn containing /dev-flow.",
+    invocation: Object.freeze({
+      modelInvocable: false,
+      userInvocable: true,
+    }),
+    source: "bundled",
+    provider: name,
+    resourceBase: Object.freeze({ kind: "directory", path: skillDirectory }),
+    content: skillContent,
+    path: skillPath,
+  }));
+  registerDevFlowGuard(ctx);
+
+  let mcpFiber;
+  let catalogCheckQueued = false;
+  let catalogFailed = false;
+  ctx.on("tools/change", () => {
+    if (catalogCheckQueued || catalogFailed) return;
+    catalogCheckQueued = true;
+    queueMicrotask(() => {
+      catalogCheckQueued = false;
+      if (catalogFailed) return;
+      try {
+        verifyCurrentCatalog(ctx, { allowUnavailable: true });
+      } catch (error) {
+        catalogFailed = true;
+        ctx.logger.error(`${name}: ${error.message}`);
+        if (mcpFiber !== undefined) {
+          void mcpFiber.dispose().catch((disposeError) => {
+            ctx.logger.error(`${name}: failed to dispose incompatible MCP child: ${disposeError.message}`);
+          });
+        }
+      }
+    });
+  });
+
+  mcpFiber = await ctx.plugin(mcpClientPlugin, {
+    transport: "stdio",
+    serverName: DEV_FLOW_SERVER_NAME,
+    command: runtime.runtimePath,
+    args: ["mcp", "--stdio"],
+    env: { DEV_FLOW_DATA_DIR: dataSelection.dataDirectory },
+    cwd: runtime.packageRoot,
+    toolCallTimeoutMs: 60_000,
+    failOnStartupError: false,
+    reconnect: {
+      enabled: true,
+      initialDelayMs: 500,
+      maxDelayMs: 30_000,
+      maxAttempts: 10,
+    },
+  });
+  verifyCurrentCatalog(ctx, { allowUnavailable: true });
+}
+
+function verifyCurrentCatalog(ctx, options) {
+  const toolNames = ctx.tools.schemas().map((schema) => schema.name);
+  return assertQualifiedToolCatalog(toolNames, options);
+}
+
+async function readPackageManifest(packageRoot) {
+  const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+  if (manifest.name !== name || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u.test(manifest.version ?? "")) {
+    throw new Error("DeepSeek package manifest identity is invalid");
+  }
+  return manifest;
+}

package/lib/paths.mjs

@@ -0,0 +1,121 @@
+import { chmod, lstat, mkdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DATA_DIRECTORY_ENVIRONMENT = "DEV_FLOW_DATA_DIR";
+
+export function packageRootFromModule(moduleUrl = import.meta.url) {
+  return dirname(dirname(fileURLToPath(moduleUrl)));
+}
+
+export async function resolveDataDirectory({
+  homeDirectory = homedir(),
+  environment = process.env,
+} = {}) {
+  const canonicalHome = await canonicalExistingDirectory(homeDirectory, "home directory");
+  const productSupportRoot = containedPath(
+    canonicalHome,
+    join(canonicalHome, "Library", "Application Support", "dev-flow"),
+    "product support root",
+  );
+
+  const explicitDataDirectory = environment?.[DATA_DIRECTORY_ENVIRONMENT] ?? "";
+  if (explicitDataDirectory !== "") {
+    const dataDirectory = await canonicalExplicitDataDirectory(explicitDataDirectory);
+    return Object.freeze({
+      dataDirectory,
+      homeDirectory: canonicalHome,
+      productSupportRoot,
+      usesDefaultDataDirectory: false,
+    });
+  }
+
+  await assertNoSymlinkComponents(canonicalHome, productSupportRoot);
+
+  return Object.freeze({
+    dataDirectory: containedPath(
+      productSupportRoot,
+      join(productSupportRoot, "data"),
+      "default data directory",
+    ),
+    homeDirectory: canonicalHome,
+    productSupportRoot,
+    usesDefaultDataDirectory: true,
+  });
+}
+
+export async function ensureDefaultDataDirectory(paths) {
+  if (!paths?.usesDefaultDataDirectory) {
+    throw new Error("refusing to create an explicit data directory");
+  }
+  const expected = containedPath(
+    paths.productSupportRoot,
+    join(paths.productSupportRoot, "data"),
+    "default data directory",
+  );
+  if (paths.dataDirectory !== expected) {
+    throw new Error("default data directory does not match the shared product path");
+  }
+
+  await assertNoSymlinkComponents(paths.homeDirectory, paths.productSupportRoot);
+  await mkdir(paths.dataDirectory, { recursive: true, mode: 0o700 });
+  await assertNoSymlinkComponents(paths.homeDirectory, paths.dataDirectory);
+  await chmod(paths.dataDirectory, 0o700);
+  return paths.dataDirectory;
+}
+
+export function containedPath(root, candidate, label = "path") {
+  const canonicalRoot = resolve(root);
+  const canonicalCandidate = resolve(candidate);
+  const offset = relative(canonicalRoot, canonicalCandidate);
+  if (offset === ".." || offset.startsWith(`..${sep}`) || isAbsolute(offset)) {
+    throw new Error(`${label} escapes its owned root`);
+  }
+  return canonicalCandidate;
+}
+
+async function canonicalExplicitDataDirectory(path) {
+  if (!isAbsolute(path)) {
+    throw new Error(`${DATA_DIRECTORY_ENVIRONMENT} must be an absolute path`);
+  }
+  const normalized = resolve(path);
+  const canonical = await canonicalExistingDirectory(path, DATA_DIRECTORY_ENVIRONMENT);
+  if (canonical !== normalized) {
+    throw new Error(`${DATA_DIRECTORY_ENVIRONMENT} must be canonical and may not use a symbolic link`);
+  }
+  return canonical;
+}
+
+async function canonicalExistingDirectory(path, label) {
+  if (!isAbsolute(path)) {
+    throw new Error(`${label} must be absolute`);
+  }
+  try {
+    const canonical = await realpath(path);
+    const info = await stat(canonical);
+    if (!info.isDirectory()) throw new Error("not a directory");
+    return canonical;
+  } catch (error) {
+    throw new Error(`${label} must name an existing directory`, { cause: error });
+  }
+}
+
+async function assertNoSymlinkComponents(root, candidate) {
+  const canonicalRoot = resolve(root);
+  const canonicalCandidate = containedPath(canonicalRoot, candidate, "product path");
+  const components = relative(canonicalRoot, canonicalCandidate).split(sep).filter(Boolean);
+  let current = canonicalRoot;
+  for (const component of components) {
+    current = join(current, component);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink()) {
+        throw new Error(`product path contains a symbolic link: ${current}`);
+      }
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+  }
+}

package/lib/runtime.mjs

@@ -0,0 +1,103 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { lstat, realpath, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+import { containedPath, packageRootFromModule } from "./paths.mjs";
+
+export const SUPPORTED_RUNTIME_KEY = "darwin-arm64";
+
+const execFile = promisify(execFileCallback);
+const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+
+export async function selectPackagedRuntime({
+  packageRoot = packageRootFromModule(import.meta.url),
+  platform = process.platform,
+  arch = process.arch,
+} = {}) {
+  const runtimeKey = `${platform}-${arch}`;
+  if (runtimeKey !== SUPPORTED_RUNTIME_KEY) {
+    throw new Error(`unsupported platform ${runtimeKey}; dev-flow-deepseek supports ${SUPPORTED_RUNTIME_KEY}`);
+  }
+
+  const canonicalPackageRoot = await canonicalPackageDirectory(packageRoot);
+  return Object.freeze({
+    packageRoot: canonicalPackageRoot,
+    runtimeKey,
+    runtimePath: containedPath(
+      canonicalPackageRoot,
+      join(canonicalPackageRoot, "runtime", runtimeKey, "dev-flow"),
+      "packaged Core runtime",
+    ),
+  });
+}
+
+export async function preflightPackagedCore(
+  selection,
+  {
+    environment = process.env,
+    currentDirectory = dirname(selection?.runtimePath ?? "."),
+  } = {},
+) {
+  if (!selection || selection.runtimeKey !== SUPPORTED_RUNTIME_KEY) {
+    throw new Error("packaged Core selection must use darwin-arm64");
+  }
+  const expectedRuntimePath = containedPath(
+    selection.packageRoot,
+    join(selection.packageRoot, "runtime", SUPPORTED_RUNTIME_KEY, "dev-flow"),
+    "packaged Core runtime",
+  );
+  if (selection.runtimePath !== expectedRuntimePath) {
+    throw new Error("packaged Core must use the exact package-relative runtime path");
+  }
+  await assertRegularExecutableFile(selection.runtimePath);
+
+  let stdout;
+  try {
+    ({ stdout } = await execFile(selection.runtimePath, ["version"], {
+      cwd: currentDirectory,
+      env: environment,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024,
+      windowsHide: true,
+    }));
+  } catch (error) {
+    throw new Error("packaged Core version preflight failed", { cause: error });
+  }
+
+  const match = /^dev-flow (\S+)\n?$/u.exec(stdout);
+  if (!match || !semverPattern.test(match[1])) {
+    throw new Error("packaged Core returned an invalid version line");
+  }
+  return Object.freeze({ ...selection, version: match[1] });
+}
+
+async function canonicalPackageDirectory(path) {
+  try {
+    const canonical = await realpath(path);
+    const info = await stat(canonical);
+    if (!info.isDirectory()) throw new Error("not a directory");
+    return canonical;
+  } catch (error) {
+    throw new Error("package root must name an existing directory", { cause: error });
+  }
+}
+
+async function assertRegularExecutableFile(path) {
+  let info;
+  try {
+    info = await lstat(path);
+  } catch (error) {
+    throw new Error("packaged Core must be a regular executable file", { cause: error });
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new Error("packaged Core must be a regular executable file");
+  }
+  if ((info.mode & 0o111) === 0) {
+    throw new Error("packaged Core must have executable mode");
+  }
+  const canonical = await realpath(path);
+  if (canonical !== path) {
+    throw new Error("packaged Core must use a canonical package-relative runtime path");
+  }
+}