dev-flow-codex 0.1.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "dev-flow-local",
+  "interface": {
+    "displayName": "Dev Flow Local"
+  },
+  "plugins": [
+    {
+      "name": "dev-flow-codex",
+      "source": {
+        "source": "local",
+        "path": "./plugin"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,243 @@
+# dev-flow-codex
+
+`dev-flow-codex` is the public-package contract for the Codex CLI product. It packages one Codex
+plugin, one explicitly selected `dev-flow` Skill, one bundled STDIO MCP server definition, and one
+`darwin-arm64` Dev Flow Core executable.
+
+Feature 006 has not published this version yet. After an explicitly authorized release, the user
+interface is:
+
+```bash
+npm install -g dev-flow-codex
+dev-flow-codex setup
+```
+
+The supported product is limited to native macOS arm64, Node.js `>=24`, and Codex
+`>=0.147.0 <0.148.0`; the exact merged host acceptance used Codex `0.147.0`. npm `os`/`cpu`
+metadata rejects unsupported package installation, and setup repeats the platform preflight before
+any Codex mutation. No Linux, Windows, Intel Mac, or DeepSeek support is claimed.
+
+npm installation only places package-manager-owned files. Explicit `setup` registers Codex, and
+explicit `remove` removes only proven product-owned registration. npm uninstall remains a separate
+file-removal operation. Task data and unknown adjacent files are retained by default. The package
+contains its Core and requires no Go toolchain, source checkout, first-run download, or separate
+backend.
+
+The production source layout is deliberately closed:
+
+```text
+packages/codex/
+├── .agents/plugins/marketplace.json
+├── LICENSE
+├── bin/dev-flow-codex.mjs
+├── lib/{lifecycle,paths}.mjs
+├── plugin/.codex-plugin/plugin.json
+├── plugin/.mcp.json
+├── plugin/skills/dev-flow/SKILL.md
+├── plugin/skills/dev-flow/agents/openai.yaml
+└── runtime/darwin-arm64/dev-flow       # temporary build staging only
+```
+
+The implementation baseline is Codex CLI `0.147.x` on macOS arm64. Sanitized fixtures and the
+development smoke target that host contract. The final pre-merge acceptance report records the
+actual Codex, package, and Core versions exercised; it is a product acceptance record, not an
+indefinite compatibility promise or public-registry evidence.
+
+Development requires Node.js `>=24`, pnpm `>=11 <12`, and the repository-pinned Go toolchain. The
+package has no production npm dependency and no install, download, or host-mutation lifecycle hook.
+Installation and explicit Codex registration are separate operations, and neither setup nor removal
+may edit the current repository or delete Core-owned task data.
+
+## Local artifact and explicit setup
+
+Create a temporary, non-final development artifact and install it with lifecycle scripts disabled:
+
+```bash
+CODEX_ARTIFACT_DIR="$(mktemp -d -t dev-flow-codex-local.XXXXXX)"
+./scripts/build-codex-local.sh --output "$CODEX_ARTIFACT_DIR"
+
+CODEX_INSTALL_PREFIX="$(mktemp -d -t dev-flow-codex-install.XXXXXX)"
+npm install --ignore-scripts --no-audit --no-fund \
+  --prefix "$CODEX_INSTALL_PREFIX" \
+  "$CODEX_ARTIFACT_DIR/dev-flow-codex-0.1.0.tgz"
+export PATH="$CODEX_INSTALL_PREFIX/node_modules/.bin:$PATH"
+```
+
+Installation alone makes no Codex registration and runs no product lifecycle hook. Verify the
+detached package/Core identity, then perform the separately authorized setup:
+
+```bash
+dev-flow-codex --version
+dev-flow-codex setup --json
+codex plugin marketplace list --json
+codex plugin list --json
+```
+
+Setup supports only macOS arm64 in this feature. It verifies the installed Codex version against
+the selected bounded range, the package/plugin/Core version identity, the package-local executable,
+the one Skill, its explicit-only `agents/openai.yaml` policy, the typed MCP resource, and
+`dev-flow-codex` discovery on `PATH` before its first registry write. It registers
+`dev-flow-local` and `dev-flow-codex@dev-flow-local` through Codex JSON commands, validates the
+official camelCase mutation results, and requires exact `{marketplaces: [...]}` plus
+`{installed: [...], available: [...]}` readback before writing the ownership receipt at
+`~/Library/Application Support/dev-flow/registrations/codex.json`. Matching repeated setup is a
+no-op; malformed, incomplete, or conflicting state fails closed. Restart or open a fresh Codex
+session after setup so the host refreshes plugin, Skill, and MCP discovery.
+
+Without `DEV_FLOW_DATA_DIR`, `dev-flow-codex mcp` creates only
+`~/Library/Application Support/dev-flow/data` with restrictive permissions. A nonempty override
+must already be an absolute, canonical, usable directory. Runtime selection is always relative to
+the installed package; it never falls back to a Core binary in the current repository.
+
+## Explicit invocation boundary
+
+The official Skill metadata sets `policy.allow_implicit_invocation: false`. The Skill resource/base name is `dev-flow`;
+the installed Skill full name is `dev-flow-codex:dev-flow`. The only exact explicit selector is `$dev-flow-codex:dev-flow`.
+Bare `$dev-flow` is not an alias and does not select this installed Skill. A wrong plugin namespace,
+a wrong Skill base name, or a missing selector also does not select it.
+Codex 0.147 registers plugin MCP tools independently from Skill injection, so this package does not
+claim selector-bound MCP visibility or authorization. An ordinary prompt must make zero Dev Flow
+calls. Other non-exact selectors must not complete a task-bearing operation or change task, event,
+or claim state; host-exposed read-only and Core-rejected calls remain observable. Non-exact Skill
+selection does not disable ordinary Codex repository tools or revoke work independently authorized
+by the rest of the prompt. Final acceptance therefore uses a non-mutating bare-selector probe and
+verifies that controlled probe leaves the repository unchanged.
+`$dev-flow-codex:dev-flow` with no substantive requirement, a conversational request, a non-Git
+directory, or work spanning more than one repository stops before Skill-owned task discovery.
+For an admitted request, the Skill resolves one canonical current worktree and calls
+`dev_flow_server_info({})` first; an incomplete or incompatible six-tool catalog stops the request.
+
+## Core-governed create and resume
+
+After the handshake, a new invocation opens one `host=codex` task using only the bounded user
+request, repository instructions, acceptance criteria, exclusions, and verification authority. An
+explicit resume omits `new_task`; Core must return the compatible active task. A restart/resume must
+preserve the same task ID and continue its advancing revision lineage. An ownership or contract
+conflict stops the invocation without choosing, merging, or replacing task records.
+
+Every iteration consumes one complete fresh Core action. Its task/revision/action identity,
+repository binding, allowed effects, required evidence, payload schema, blocker, and outcome stay
+together. Codex performs only the allowed effect, constructs the returned closed payload, retains a
+request ID, and submits exactly one mutation. A complete success continues only from the returned
+next action or a fresh Core read; Codex does not infer transitions or completion.
+
+If a mutation result is missing, cancelled, malformed, truncated, or otherwise uncertain, read
+before retry: retain the exact original operation, call `dev_flow_get_task` and
+`dev_flow_get_next_action`, and follow only Core's recovery assessment. Never reconstruct a missing
+operation probe or repeat a mutation because its response was lost.
+
+Every completed host command event is retained only as role-scoped status, exit code, and safe
+command/output hashes. Ambient commands in the ordinary or invalid sessions and repository
+inspection or implementation commands in active sessions are non-verification facts. Only the one
+Core-submitted and retained logical proof, rendered by Codex 0.147 on macOS as the closed supported
+command, counts against the verification budget. An unbound or duplicate proof and any known test
+or full-suite command fail closed. Do not run a forbidden full suite; when automatic capacity is
+exhausted, report an honest manual handoff.
+Static, simulated, user-performed, and native evidence keep distinct labels. A Core blocker,
+ownership/contract conflict, `CANCELLED`, or Core-owned `DONE` outcome stops repository work and is
+reported without reinterpretation.
+
+## Explicit removal and retained task data
+
+Deregister before running npm uninstall:
+
+```bash
+dev-flow-codex remove --json
+npm uninstall -g --ignore-scripts dev-flow-codex
+```
+
+Removal is receipt-first. It reads and validates the exact ownership receipt, reads current Codex
+marketplace/plugin state, and fails closed on an identity, root, or readback conflict before any
+mutation. It removes the matching plugin, verifies absence, removes the matching marketplace,
+verifies absence again, and deletes only the exact receipt. An interrupted removal keeps the
+receipt, so the next explicit call can resume from fresh readback. Repeated removal after complete
+absence is an idempotent no-op.
+
+The command does not delete the npm package, Core task data, repository, Codex config/cache, receipt
+parents, or unknown adjacent resources. Stop Core before comparing task-data manifests; after
+deregistration, directly reopen the recorded task with Core to prove retention. Perform npm
+uninstall separately only after successful absence readback. A later artifact within the selected
+compatible range may be installed and explicitly set up again against the retained data.
+
+Setup, version reporting, and removal are package/user-state operations and behave the same from
+any working directory. They do not add configuration, databases, instructions, or generated files
+to the target repository and never mutate Git.
+
+The `>=0.147.0 <0.148.0` line and exact `0.147.0` host were selected on 2026-08-15, not promised
+indefinitely. The selected MCP file uses Agent Plugins v1 `$schema`, camelCase `mcpServers`, and one
+`type: stdio` entry, a shape accepted by both 0.147 plugin parsers. A future changed official
+contract requires every compatibility-bearing contract, test, and guide to be updated before a
+final artifact is built.
+
+## Deterministic validation
+
+Run the product-bearing package layers directly:
+
+```bash
+pnpm --dir packages/codex test:package
+pnpm --dir packages/codex test:lifecycle
+pnpm --dir packages/codex test:parser
+pnpm --dir packages/codex test:native-smoke
+pnpm --dir packages/codex pack:dry
+```
+
+The checked-in Codex 0.147 fixtures cover three mutually exclusive terminal shapes without starting
+Codex: completed success with text/structured parity, failed Core-domain result with the same parity,
+and failed transport with no complete Core result. They contain no prompt, source, user path,
+environment, token, or secret.
+
+```bash
+./scripts/run-codex-real-journey.sh --fixture success
+./scripts/run-codex-real-journey.sh --fixture core-domain-error
+./scripts/run-codex-real-journey.sh --fixture transport-error
+```
+
+## Repeatable development smoke
+
+After deterministic checks are green, run the full isolated chain twice with fresh empty result
+directories and labels `A` then `B`:
+
+```bash
+./scripts/run-codex-real-journey.sh \
+  --development-smoke \
+  --run-label A \
+  --codex-executable "$CODEX_EXECUTABLE" \
+  --result-directory "$CODEX_SMOKE_RESULT_DIRECTORY"
+```
+
+Each invocation builds and installs a non-final package in one new temporary root, performs setup,
+four fresh Codex 0.147 sessions, removal, and a direct packaged-Core retention read, then deletes the
+temporary root. The external `smoke-result.json` is a development result, not final acceptance or a
+formal support statement; failures add only a bounded, hashed diagnostic.
+
+## Final pre-merge acceptance
+
+The four native HIGH regressions are closed, and two fresh isolated Codex 0.147 development-smoke
+runs passed with distinct tasks. Those runs establish repeatability but do not replace acceptance.
+Run one final real-host acceptance against the reviewed commit immediately before merge approval.
+The real-host entry point records ephemeral session observations:
+
+```bash
+./scripts/run-codex-real-journey.sh \
+  --acceptance \
+  --codex-executable "$CODEX_EXECUTABLE" \
+  --workspace "$CODEX_ACCEPTANCE_WORKTREE"
+```
+
+The observation itself does not claim acceptance. A single simplified JSON report must then record
+the reviewed source and artifact identities, Codex/package/Core versions, setup readback, zero Core
+calls for the ordinary prompt, unchanged Core/repository state around the non-mutating bare-selector
+probe, the exact selector, the same task ID across restart, at least two
+committed actions, Core `DONE`, successful removal readback, retained and reopened task data, and an
+empty unexpected-repository-path list. Package and Core versions must match. Validate that closed
+object without creating any additional report files:
+
+```bash
+node scripts/write-codex-journey-evidence.mjs \
+  acceptance-report \
+  --report "$CODEX_ACCEPTANCE_REPORT"
+```
+
+Feature 003 uses this one acceptance report only as a pre-merge product gate. It does not implement
+a release or supply-chain proof system. Public npm publication, GitHub releases, tags,
+Windows/Linux claims, IDE support, and additional Codex surfaces remain out of scope.

package/bin/dev-flow-codex.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { constants as fsConstants, realpathSync } from "node:fs";
+import { access, readFile, stat } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+import {
+  inspectCoreVersion,
+  removeRegistration,
+  setupRegistration,
+} from "../lib/lifecycle.mjs";
+import {
+  ensureDefaultDataDirectory,
+  resolveProductPaths,
+} from "../lib/paths.mjs";
+
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const NPM_UNINSTALL_HANDOFF = "Run npm uninstall dev-flow-codex separately after deregistration.";
+const CODEX_MCP_INSTRUCTIONS_ENVIRONMENT = "DEV_FLOW_CODEX_MCP_INSTRUCTIONS";
+const CODEX_MCP_INSTRUCTIONS = [
+  "Dev Flow for Codex is explicit-only.",
+  "Do not call tools from this server unless the current user turn contains the exact selector `$dev-flow-codex:dev-flow`.",
+  "Bare `$dev-flow`, wrong or missing selectors, and implicit matches are not activation.",
+  "After valid selection, `dev_flow_server_info` must be the first Dev Flow call.",
+  "Call `dev_flow_open_task` only after exact `$dev-flow-codex:dev-flow` selection and a successful `dev_flow_server_info` handshake.",
+].join(" ");
+
+export async function runCLI(arguments_, dependencies = {}) {
+  const stdout = dependencies.stdout ?? process.stdout;
+  const stderr = dependencies.stderr ?? process.stderr;
+  const environment = dependencies.environment ?? process.env;
+  const resolvePaths = dependencies.resolvePaths ?? (() => resolveProductPaths({ environment }));
+  const readPackageVersion = dependencies.readPackageVersion ?? readInstalledPackageVersion;
+  const inspectVersion = dependencies.inspectCoreVersion ?? inspectCoreVersion;
+  const ensureDataDirectory = dependencies.ensureDefaultDataDirectory ?? ensureDefaultDataDirectory;
+  const setup = dependencies.setupRegistration ?? setupRegistration;
+
+  if (!isProductionCommand(arguments_)) {
+    stderr.write("dev-flow-codex: invalid arguments; expected setup [--json], remove [--json], mcp, or --version\n");
+    return { code: 2, signal: null };
+  }
+
+  try {
+    const paths = await resolvePaths();
+    if (arguments_.length === 1 && arguments_[0] === "mcp") {
+      if (paths.usesDefaultDataDirectory) await ensureDataDirectory(paths);
+      return await launchPackagedCore(paths, ["mcp", "--stdio"], {
+        environment,
+        spawnImpl: dependencies.spawnImpl ?? spawn,
+        signalSource: dependencies.signalSource ?? process,
+      });
+    }
+
+    const packageVersion = await readPackageVersion(paths.packageRoot);
+    if (arguments_.length === 1 && arguments_[0] === "--version") {
+      const coreVersion = await inspectVersion(paths.runtimePath, {
+        environment,
+        currentDirectory: paths.packageRoot,
+      });
+      if (coreVersion !== packageVersion) {
+        throw new Error(`package version ${packageVersion} does not match Core version ${coreVersion}`);
+      }
+      stdout.write(`dev-flow-codex ${packageVersion} (core ${coreVersion})\n`);
+      return { code: 0, signal: null };
+    }
+
+    const json = arguments_.at(-1) === "--json";
+    if (arguments_[0] === "setup") {
+      const result = await setup({
+        paths,
+        packageVersion,
+        codexExecutable: dependencies.codexExecutable ?? "codex",
+        environment,
+        now: dependencies.now,
+      });
+      writeLifecycleSuccess(stdout, "setup", result, paths.receiptPath, json);
+      return { code: 0, signal: null };
+    }
+
+    const remove = dependencies.removeRegistration ?? removeRegistration;
+    const result = await remove({
+      paths,
+      packageVersion,
+      codexExecutable: dependencies.codexExecutable ?? "codex",
+      environment,
+    });
+    writeLifecycleSuccess(stdout, "remove", result, paths.receiptPath, json);
+    return { code: 0, signal: null };
+  } catch (error) {
+    stderr.write(`dev-flow-codex: ${error.message}\n`);
+    return { code: 1, signal: null };
+  }
+}
+
+export async function launchPackagedCore(
+  paths,
+  arguments_,
+  {
+    environment = process.env,
+    spawnImpl = spawn,
+    signalSource = process,
+  } = {},
+) {
+  await assertExecutableRuntime(paths.runtimePath);
+  let child;
+  try {
+    child = spawnImpl(paths.runtimePath, arguments_, {
+      cwd: paths.packageRoot,
+      env: {
+        ...environment,
+        DEV_FLOW_DATA_DIR: paths.dataDirectory,
+        [CODEX_MCP_INSTRUCTIONS_ENVIRONMENT]: CODEX_MCP_INSTRUCTIONS,
+      },
+      stdio: "inherit",
+      shell: false,
+      windowsHide: true,
+    });
+  } catch (error) {
+    throw new Error("start packaged Core", { cause: error });
+  }
+
+  const handlers = new Map();
+  for (const signal of FORWARDED_SIGNALS) {
+    const handler = () => child.kill(signal);
+    handlers.set(signal, handler);
+    signalSource.on(signal, handler);
+  }
+  const cleanup = () => {
+    for (const [signal, handler] of handlers) signalSource.off(signal, handler);
+  };
+
+  return await new Promise((resolve, reject) => {
+    child.once("error", (error) => {
+      cleanup();
+      reject(new Error("packaged Core process failed to start", { cause: error }));
+    });
+    child.once("exit", (code, signal) => {
+      cleanup();
+      resolve({ code, signal });
+    });
+  });
+}
+
+async function readInstalledPackageVersion(packageRoot) {
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(new URL("../package.json", pathToFileURL(`${packageRoot}/bin/`)), "utf8"));
+  } catch (error) {
+    throw new Error("read installed package identity", { cause: error });
+  }
+  if (manifest.name !== "dev-flow-codex" || typeof manifest.version !== "string") {
+    throw new Error("installed package identity is invalid");
+  }
+  return manifest.version;
+}
+
+async function assertExecutableRuntime(runtimePath) {
+  let info;
+  try {
+    info = await stat(runtimePath);
+    await access(runtimePath, fsConstants.X_OK);
+  } catch (error) {
+    throw new Error("packaged Core must exist and be executable", { cause: error });
+  }
+  if (!info.isFile() || (info.mode & 0o111) === 0) {
+    throw new Error("packaged Core must exist and be executable");
+  }
+}
+
+function writeLifecycleSuccess(stdout, operation, result, receiptPath, json) {
+  if (json) {
+    const output = {
+      operation,
+      status: result.status,
+      changed: result.changed,
+      receipt_path: receiptPath,
+    };
+    if (operation === "remove") output.next_step = NPM_UNINSTALL_HANDOFF;
+    stdout.write(`${JSON.stringify(output)}\n`);
+    return;
+  }
+  stdout.write(`dev-flow-codex ${operation}: ${result.status}\n`);
+  if (operation === "remove") stdout.write(`${NPM_UNINSTALL_HANDOFF}\n`);
+}
+
+function isProductionCommand(arguments_) {
+  if (!Array.isArray(arguments_)) return false;
+  if (arguments_.length === 1 && ["mcp", "--version"].includes(arguments_[0])) return true;
+  return (
+    (arguments_.length === 1 || arguments_.length === 2 && arguments_[1] === "--json") &&
+    ["setup", "remove"].includes(arguments_[0])
+  );
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  const result = await runCLI(process.argv.slice(2));
+  if (result.signal) {
+    try {
+      process.kill(process.pid, result.signal);
+    } catch {
+      process.exitCode = 1;
+    }
+  } else {
+    process.exitCode = result.code ?? 1;
+  }
+}