@open-mercato/cli 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.7",
+  "version": "0.6.8-canary.320.1.bf889f49e4",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,12 +56,13 @@
     "node": "24.x"
   },
   "dependencies": {
-    "@mikro-orm/core": "^7.1.5",
-    "@mikro-orm/decorators": "^7.1.5",
-    "@mikro-orm/migrations": "^7.1.5",
-    "@mikro-orm/postgresql": "^7.1.5",
-    "@open-mercato/queue": "0.6.7",
-    "@open-mercato/shared": "0.6.7",
+    "@mikro-orm/core": "^7.1.8",
+    "@mikro-orm/decorators": "^7.1.8",
+    "@mikro-orm/migrations": "^7.1.8",
+    "@mikro-orm/postgresql": "^7.1.8",
+    "@open-mercato/queue": "0.6.8-canary.320.1.bf889f49e4",
+    "@open-mercato/shared": "0.6.8-canary.320.1.bf889f49e4",
+    "@open-mercato/telemetry": "0.6.8-canary.320.1.bf889f49e4",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -72,13 +73,13 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.7"
+    "@open-mercato/shared": "0.6.8-canary.320.1.bf889f49e4"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.7",
+    "@open-mercato/shared": "0.6.8-canary.320.1.bf889f49e4",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11"
+    "ts-jest": "^29.4.12"
   },
   "publishConfig": {
     "access": "public"
@@ -87,5 +88,6 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/cli"
-  }
+  },
+  "stableVersion": "0.6.7"
 }

package/src/__tests__/mercato.test.ts

@@ -716,6 +716,7 @@ describe('generate post-step structural invalidation', () => {
     consoleErrorSpy.mockRestore()
     consoleLogSpy.mockRestore()
   })
+
 })
 
 describe('server dev managed process exits', () => {
@@ -1263,6 +1264,86 @@ describe('server dev managed process exits', () => {
     consoleLogSpy.mockRestore()
   })
 
+  it('uses lightweight manifest workers instead of handler-bearing CLI modules', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+    process.env.OM_AUTO_SPAWN_WORKERS_LAZY = 'true'
+    process.env.OM_AUTO_SPAWN_WORKERS_LAZY_MODE = 'shared'
+
+    jest.doMock('node:fs', () => {
+      const actual = jest.requireActual('node:fs')
+      return {
+        ...actual,
+        existsSync: jest.fn((candidate: string) =>
+          pathIncludes(candidate, 'next/dist/bin/next') || pathIncludes(candidate, '@open-mercato/cli/bin/mercato'),
+        ),
+        unlinkSync: jest.fn(),
+      }
+    })
+    jest.doMock('../lib/generators', () => ({
+      generateModulePackageSources: jest.fn().mockResolvedValue(undefined),
+    }))
+    jest.doMock('../lib/resolver', () => ({
+      resolveEnvironment: () => ({
+        appDir: '/tmp/test-app',
+        rootDir: '/tmp/test-root',
+      }),
+      createResolver: () => ({}),
+    }))
+
+    const supervisorClose = jest.fn().mockResolvedValue(undefined)
+    const startLazyWorkerSupervisor = jest.fn(() => ({
+      startedQueues: new Set<string>(),
+      getActiveChild: () => undefined,
+      close: supervisorClose,
+      done: Promise.resolve(),
+    }))
+    jest.doMock('../lib/queue-worker-supervisor', () => ({
+      startLazyWorkerSupervisor,
+    }))
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) =>
+        pathIncludes(args[0] ?? '', 'next/dist/bin/next') ? { code: null, signal: 'SIGTERM' } : undefined,
+      ),
+    )
+
+    const manifestRegistry = await import('../lib/dev-supervisor-manifest')
+    manifestRegistry.registerDevSupervisorManifest({
+      version: 1,
+      workers: [
+        {
+          id: 'manifest:worker',
+          moduleId: 'manifest',
+          queue: 'manifest-events',
+          concurrency: 1,
+        },
+      ],
+      schedulerStartStatus: 'missing-module',
+      requiresFullBootstrap: false,
+    })
+    const mercato = await import('../mercato')
+    mercato.registerCliModules([eventsWorkerFixture as Module])
+
+    const exitCode = await mercato.run(['node', 'mercato', 'server', 'dev'])
+
+    expect(exitCode).toBe(0)
+    expect(startLazyWorkerSupervisor).toHaveBeenCalledTimes(1)
+    const workers = startLazyWorkerSupervisor.mock.calls[0][0].workers
+    expect(workers).toEqual([
+      {
+        id: 'manifest:worker',
+        moduleId: 'manifest',
+        queue: 'manifest-events',
+        concurrency: 1,
+      },
+    ])
+    expect(workers[0]).not.toHaveProperty('handler')
+    expect(supervisorClose).toHaveBeenCalled()
+
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
+  })
+
   it('starts the lazy scheduler supervisor instead of the scheduler process when OM_AUTO_SPAWN_SCHEDULER_LAZY=true', async () => {
     const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
     const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
@@ -1328,6 +1409,69 @@ describe('server dev managed process exits', () => {
     consoleErrorSpy.mockRestore()
     consoleLogSpy.mockRestore()
   })
+
+  it('uses the lightweight manifest scheduler status without loading scheduler CLI modules', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+    process.env.AUTO_SPAWN_SCHEDULER = 'true'
+    process.env.AUTO_SPAWN_WORKERS = 'false'
+    process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY = 'true'
+
+    jest.doMock('node:fs', () => {
+      const actual = jest.requireActual('node:fs')
+      return {
+        ...actual,
+        existsSync: jest.fn((candidate: string) =>
+          pathIncludes(candidate, 'next/dist/bin/next') || pathIncludes(candidate, '@open-mercato/cli/bin/mercato'),
+        ),
+        unlinkSync: jest.fn(),
+      }
+    })
+    jest.doMock('../lib/generators', () => ({
+      generateModulePackageSources: jest.fn().mockResolvedValue(undefined),
+    }))
+    jest.doMock('../lib/resolver', () => ({
+      resolveEnvironment: () => ({
+        appDir: '/tmp/test-app',
+        rootDir: '/tmp/test-root',
+      }),
+      createResolver: () => ({}),
+    }))
+
+    const schedulerClose = jest.fn().mockResolvedValue(undefined)
+    const startLazySchedulerSupervisor = jest.fn(() => ({
+      started: false,
+      getActiveChild: () => undefined,
+      close: schedulerClose,
+      done: Promise.resolve(),
+    }))
+    jest.doMock('../lib/scheduler-supervisor', () => ({
+      startLazySchedulerSupervisor,
+    }))
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) =>
+        pathIncludes(args[0] ?? '', 'next/dist/bin/next') ? { code: null, signal: 'SIGTERM' } : undefined,
+      ),
+    )
+
+    const manifestRegistry = await import('../lib/dev-supervisor-manifest')
+    manifestRegistry.registerDevSupervisorManifest({
+      version: 1,
+      workers: [],
+      schedulerStartStatus: 'ok',
+      requiresFullBootstrap: false,
+    })
+    const mercato = await import('../mercato')
+
+    const exitCode = await mercato.run(['node', 'mercato', 'server', 'dev'])
+
+    expect(exitCode).toBe(0)
+    expect(startLazySchedulerSupervisor).toHaveBeenCalledTimes(1)
+    expect(schedulerClose).toHaveBeenCalled()
+
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
+  })
 })
 
 describe('server start managed process exits', () => {

package/src/bin.ts

@@ -4,34 +4,13 @@
  * Called from within a Next.js app directory as: yarn mercato <command>
  * Uses dynamic app resolution to find generated files at .mercato/generated/
  */
-import { run } from './mercato.js'
-
-// Commands that can run without bootstrap (without generated files)
-// - generate: creates the generated files
-// - db: uses resolver directly to find modules and migrations
-// - init: runs yarn commands to set up the app
-// - help: just shows help text
-const BOOTSTRAP_FREE_COMMANDS = [
-  'generate',
-  'module',
-  'deploy',
-  'db',
-  'init',
-  'agentic:init',
-  'eject',
-  'test',
-  'test:integration',
-  'test:integration:coverage',
-  'test:integration:spec-coverage',
-  'test:ephemeral',
-  'test:integration:interactive',
-  'umes:list',
-  'umes:inspect',
-  'umes:check',
-  'help',
-  '--help',
-  '-h',
-]
+import {
+  getTelemetryRuntime,
+  isTelemetryBackendEnabled,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+import { resolveCliBootstrapMode, type CliBootstrapMode } from './lib/cli-bootstrap-mode.js'
+// `run` is imported dynamically inside `main()` so telemetry can initialize
+// before the mercato entry (and its Postgres driver) loads — see main().
 
 function assertNode24Runtime(): void {
   const detectedNodeVersion = process.versions.node
@@ -48,20 +27,30 @@ function assertNode24Runtime(): void {
   )
 }
 
-function needsBootstrap(argv: string[]): boolean {
-  const [, , first] = argv
-  if (!first) return false // help screen
-  return !BOOTSTRAP_FREE_COMMANDS.includes(first)
-}
-
-async function tryBootstrap(): Promise<boolean> {
+async function tryBootstrap(mode: Exclude<CliBootstrapMode, 'none'>): Promise<boolean> {
   try {
-    const { bootstrapFromAppRoot } = await import('@open-mercato/shared/lib/bootstrap/dynamicLoader')
-    const { registerCliModules } = await import('./mercato.js')
     // Use the CLI resolver to find the app directory (handles monorepo detection)
     const { createResolver } = await import('./lib/resolver.js')
     const resolver = createResolver()
     const appDir = resolver.getAppDir()
+
+    if (mode === 'dev-supervisor') {
+      const {
+        canUseLightweightDevSupervisor,
+        loadDevSupervisorManifest,
+        registerDevSupervisorManifest,
+      } = await import(
+        './lib/dev-supervisor-manifest.js'
+      )
+      const manifest = loadDevSupervisorManifest(appDir)
+      if (canUseLightweightDevSupervisor(manifest)) {
+        registerDevSupervisorManifest(manifest)
+        return true
+      }
+    }
+
+    const { bootstrapFromAppRoot } = await import('@open-mercato/shared/lib/bootstrap/dynamicLoader')
+    const { registerCliModules } = await import('./mercato.js')
     const data = await bootstrapFromAppRoot(appDir)
     // Register CLI modules directly to avoid module resolution issues
     registerCliModules(data.modules)
@@ -70,8 +59,11 @@ async function tryBootstrap(): Promise<boolean> {
     const message = err instanceof Error ? err.message : String(err)
     // Check if the error is about missing generated files
     if (
-      message.includes('Cannot find module') &&
-      (message.includes('/generated/') || message.includes('.generated') || message.includes('.mercato'))
+      message.includes('dev-supervisor.generated.json') ||
+      (
+        message.includes('Cannot find module') &&
+        (message.includes('/generated/') || message.includes('.generated') || message.includes('.mercato'))
+      )
     ) {
       return false
     }
@@ -82,10 +74,30 @@ async function tryBootstrap(): Promise<boolean> {
 
 async function main(): Promise<void> {
   assertNode24Runtime()
-  const requiresBootstrap = needsBootstrap(process.argv)
+  const bootstrapMode = resolveCliBootstrapMode(process.argv)
+
+  if (bootstrapMode !== 'none') {
+    // Load the app's `.env` BEFORE initTelemetry(): `run()` only dotenv-loads it
+    // later (ensureEnvLoaded), which is too late — TELEMETRY_BACKEND set only in
+    // `.env` would silently resolve to `noop` for worker/scheduler processes.
+    // The loader touches only the resolver + dotenv (no `pg`), preserving the
+    // instrumentation load-order guarantee below.
+    const { loadAppEnv } = await import('./lib/load-env.js')
+    await loadAppEnv()
+
+    // Initialize telemetry BEFORE bootstrapping the app graph. Bootstrap and the
+    // per-command handlers load MikroORM's Postgres driver → `pg`, and the
+    // OpenTelemetry pg/undici auto-instrumentation only records spans for a
+    // driver required AFTER the SDK has started. Registering here — ahead of any
+    // app module — is what lets long-running worker/scheduler processes emit DB
+    // spans (not just the bullmq-otel add/process envelope). The package itself
+    // is not imported unless an explicit supported backend is selected.
+    if (isTelemetryBackendEnabled()) {
+      const { initTelemetry } = await import('@open-mercato/telemetry')
+      await initTelemetry()
+    }
 
-  if (requiresBootstrap) {
-    const bootstrapSucceeded = await tryBootstrap()
+    const bootstrapSucceeded = await tryBootstrap(bootstrapMode)
     if (!bootstrapSucceeded) {
       console.error('╔═══════════════════════════════════════════════════════════════════╗')
       console.error('║  Generated files not found!                                       ║')
@@ -100,7 +112,13 @@ async function main(): Promise<void> {
     }
   }
 
+  // Dynamic import (not a top-level static import) so the mercato entry — and the
+  // Postgres driver it pulls in — loads only after initTelemetry() above.
+  const { run } = await import('./mercato.js')
   const code = await run(process.argv)
+  // Flush spans/logs for commands that return (workers block forever and flush via
+  // their own shutdown handler instead).
+  await getTelemetryRuntime()?.shutdown()
   process.exit(code ?? 0)
 }
 

package/src/lib/__integration__/TC-INT-008.spec.ts

@@ -14,6 +14,8 @@ const cliIntegrationRunnerPath = path.join(cliDir, 'src', 'lib', 'testing', 'int
 const standaloneTemplatePackageJsonPath = path.join(repoRoot, 'packages', 'create-app', 'template', 'package.json.template')
 const agenticRoot = path.join(repoRoot, 'packages', 'create-app', 'agentic')
 const packagesRoot = path.join(repoRoot, 'packages')
+const coreVersion = JSON.parse(fs.readFileSync(path.join(packagesRoot, 'core', 'package.json'), 'utf8')).version as string
+const UNROUTED_PACKAGE_GUIDES = new Set(['cache', 'core', 'events', 'queue', 'search', 'shared', 'ui'])
 
 // Modules the standalone fixture enables in src/modules.ts. Both are on the
 // fact-sheet allowlist, so agentic:init must ship exactly their fact-sheets
@@ -24,7 +26,7 @@ function normalizePath(value: string): string {
   return value.split(path.sep).join('/')
 }
 
-function runCommand(command: string, args: string[], cwd: string): string {
+function runCommand(command: string, args: string[], cwd: string, env: NodeJS.ProcessEnv = {}): string {
   return execFileSync(command, args, {
     cwd,
     encoding: 'utf8',
@@ -36,6 +38,7 @@ function runCommand(command: string, args: string[], cwd: string): string {
       // whose external step (`npx skills add`) needs the network. Local tier
       // symlinks are still installed.
       OM_SKIP_EXTERNAL_SKILLS: '1',
+      ...env,
     },
   })
 }
@@ -61,16 +64,48 @@ function createStandaloneFixture(rootDir: string): string {
       {
         name: 'sample-store',
         private: true,
+        dependencies: { '@open-mercato/core': coreVersion },
       },
       null,
       2,
     ),
   )
-  const moduleEntries = FIXTURE_ENABLED_MODULES.map((moduleId) => `  { id: '${moduleId}' },`).join('\n')
+  const moduleEntries = FIXTURE_ENABLED_MODULES
+    .map((moduleId) => `  { id: '${moduleId}', from: '@open-mercato/core' },`)
+    .join('\n')
   writeFile(path.join(appDir, 'src', 'modules.ts'), `export const enabledModules = [\n${moduleEntries}\n]\n`)
   return appDir
 }
 
+function installFakeFrameworkPackage(appDir: string): string {
+  const packageRoot = path.join(appDir, 'node_modules', '@open-mercato', 'core')
+  writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({
+    name: '@open-mercato/core',
+    version: coreVersion,
+    type: 'module',
+    exports: { '.': './dist/index.js' },
+  }))
+  writeFile(path.join(packageRoot, 'dist', 'index.js'), 'export {}\n')
+  writeFile(path.join(packageRoot, 'AGENTS.md'), '# Installed core instructions\n')
+  for (const moduleId of FIXTURE_ENABLED_MODULES) {
+    writeFile(path.join(packageRoot, 'src', 'modules', moduleId, 'AGENTS.md'), `# Installed ${moduleId} instructions\n`)
+    writeFile(
+      path.join(packageRoot, 'src', 'modules', moduleId, 'data', 'entities.ts'),
+      `export class ${moduleId === 'customers' ? 'Person' : 'Sale'} {}\n`,
+    )
+  }
+  return packageRoot
+}
+
+function snapshotTextFiles(rootDir: string): Record<string, string> {
+  return Object.fromEntries(
+    listRelativeFiles(rootDir).map((relativePath) => [
+      relativePath,
+      fs.readFileSync(path.join(rootDir, relativePath), 'utf8'),
+    ]),
+  )
+}
+
 function listRelativeFiles(rootDir: string): string[] {
   if (!fs.existsSync(rootDir)) {
     return []
@@ -194,7 +229,7 @@ function expectedGuideOutputNames(): string[] {
 
   for (const packageName of fs.readdirSync(packagesRoot)) {
     const packageGuide = path.join(packagesRoot, packageName, 'agentic', 'standalone-guide.md')
-    if (fs.existsSync(packageGuide)) {
+    if (fs.existsSync(packageGuide) && !UNROUTED_PACKAGE_GUIDES.has(packageName)) {
       collected.add(`${packageName}.md`)
     }
 
@@ -214,8 +249,14 @@ function expectedGuideOutputNames(): string[] {
   // Generated fact-sheet artifacts (spec 2026-06-27-ts-morph-module-fact-sheets):
   // the module-facts.json sidecar is copied as-is and fact-sheets are filtered to the
   // fixture's enabled modules. The legacy core.<module>.md redirect stubs are no longer
-  // emitted (#3754).
+  // emitted (#3754). framework-extension-points.md is likewise generated into
+  // dist/agentic/guides by both build.mjs pipelines (#4810) rather than checked in
+  // alongside the static conceptual guides, so it needs an explicit entry here.
   collected.add('module-facts.json')
+  collected.add('framework-extension-points.md')
+  collected.add('upstream/AGENTS.md')
+  collected.add('upstream/BACKWARD_COMPATIBILITY.md')
+  collected.add('upstream/manifest.json')
   for (const moduleId of FIXTURE_ENABLED_MODULES) {
     collected.add(normalizePath(path.join('modules', `${moduleId}.md`)))
   }
@@ -262,14 +303,17 @@ test.describe('TC-INT-008: CLI agentic init mirrors standalone scaffolding asset
 
       const agentsSource = fs.readFileSync(path.join(appDir, 'AGENTS.md'), 'utf8')
       expect(agentsSource).toContain('<!-- CODEX_ENFORCEMENT_RULES_START -->')
-      expect(agentsSource).toContain('.ai/guides/core.md')
+      expect(agentsSource).toContain('.ai/guides/upstream/BACKWARD_COMPATIBILITY.md')
 
-      // The Module-Specific Guides marker block lists exactly the enabled modules'
-      // fact-sheets (enabled ∩ allowlist), not the full bundled set.
+      // The Module-Specific Guides marker block is a compact enabled-module ID
+      // index (enabled ∩ bundled) plus one progressively loaded path pattern.
       for (const moduleId of FIXTURE_ENABLED_MODULES) {
-        expect(agentsSource).toContain(`.ai/guides/modules/${moduleId}.md`)
+        expect(agentsSource).toContain(`\`${moduleId}\``)
       }
-      expect(agentsSource).not.toContain('.ai/guides/modules/auth.md')
+      expect(agentsSource).toContain('`.ai/guides/modules/<id>.md`')
+      expect(agentsSource.match(/\.ai\/guides\/modules\//g)).toHaveLength(1)
+      expect(agentsSource).not.toContain('`auth`')
+      expect(agentsSource).not.toContain('Core CRM capabilities')
 
       const specsReadmeSource = fs.readFileSync(path.join(appDir, '.ai', 'specs', 'README.md'), 'utf8')
       expect(specsReadmeSource).toContain('sample-store')
@@ -308,4 +352,58 @@ test.describe('TC-INT-008: CLI agentic init mirrors standalone scaffolding asset
       fs.rmSync(tempRoot, { recursive: true, force: true })
     }
   })
+
+  test('emits a runnable exact-version framework context escape hatch for an installed package', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-cli-framework-context-'))
+
+    try {
+      const appDir = createStandaloneFixture(tempRoot)
+      const packageRoot = installFakeFrameworkPackage(appDir)
+      const resolvedPackageRoot = fs.realpathSync(packageRoot)
+      const packageBefore = snapshotTextFiles(packageRoot)
+
+      runMercato(['agentic:init', '--tool=codex'], appDir)
+      const generatedScript = path.join(appDir, 'scripts', 'framework-context.mjs')
+      expect(fs.existsSync(generatedScript)).toBe(true)
+
+      const output = runCommand(
+        process.execPath,
+        [generatedScript, '--module', 'customers', '--query', 'Person', '--json'],
+        appDir,
+        // The generated standalone helper must not depend on a globally
+        // installed ripgrep binary; process.execPath is already absolute.
+        { PATH: '', Path: '' },
+      )
+      const context = JSON.parse(output) as {
+        module: string
+        package: { name: string; version: string; root: string }
+        sourceKind: string
+        sourceRoot: string
+        materializedSource: string
+        instructions: Array<{ kind: string; path: string | null; materializedPath?: string }>
+        boundedSearch: { status: string; matches: number; maxMatches: number; result: string }
+        warnings: string[]
+      }
+
+      expect(context.module).toBe('customers')
+      expect(context.package).toEqual({ name: '@open-mercato/core', version: coreVersion, root: resolvedPackageRoot })
+      expect(context.sourceKind).toBe('source')
+      expect(normalizePath(context.sourceRoot)).toBe(normalizePath(path.join(resolvedPackageRoot, 'src', 'modules', 'customers')))
+      expect(context.instructions.filter((entry) => entry.path).map((entry) => entry.kind)).toEqual([
+        'standalone-root',
+        'upstream-bc',
+        'package',
+        'module-1',
+        'upstream-root',
+      ])
+      expect(context.instructions.filter((entry) => entry.path).every((entry) => entry.materializedPath)).toBe(true)
+      expect(context.boundedSearch).toMatchObject({ status: 'matched', matches: 1, maxMatches: 200 })
+      expect(fs.existsSync(path.join(appDir, context.materializedSource))).toBe(true)
+      expect(fs.existsSync(path.join(appDir, context.boundedSearch.result))).toBe(true)
+      expect(context.warnings.some((warning) => warning.includes('Generated facts for customers are stale'))).toBe(false)
+      expect(snapshotTextFiles(packageRoot)).toEqual(packageBefore)
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true })
+    }
+  })
 })

package/src/lib/__tests__/agentic-init.test.ts

@@ -17,7 +17,11 @@ const loadRunAgenticInit = async ({
 }: {
   existingPaths: Set<string>
   questionAnswer?: string
-  runAgenticSetupImplementation?: (targetDir: string, ask: (question: string) => Promise<string>, options?: { tool?: string; force?: boolean }) => Promise<void>
+  runAgenticSetupImplementation?: (
+    targetDir: string,
+    ask: (question: string) => Promise<string>,
+    options?: { tool?: string; force?: boolean; updateHarness?: boolean },
+  ) => Promise<void>
 }): Promise<AgenticInitTestContext> => {
   jest.resetModules()
 
@@ -136,6 +140,22 @@ describe('runAgenticInit', () => {
     expect(testContext.runAgenticSetup).not.toHaveBeenCalled()
   })
 
+  it('rejects force and ownership-aware update together before setup', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const testContext = await loadRunAgenticInit({
+      existingPaths: new Set<string>([appModulesPath]),
+    })
+
+    const exitCode = await testContext.runAgenticInit(['--force', '--update-harness'])
+
+    expect(exitCode).toBe(1)
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '❌  --force and --update-harness are mutually exclusive',
+    )
+    expect(testContext.createInterface).not.toHaveBeenCalled()
+    expect(testContext.runAgenticSetup).not.toHaveBeenCalled()
+  })
+
   it('warns and exits early when relevant agentic files already exist without force', async () => {
     const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
     const testContext = await loadRunAgenticInit({
@@ -150,7 +170,7 @@ describe('runAgenticInit', () => {
     expect(consoleLogSpy.mock.calls.flat()).toEqual(expect.arrayContaining([
       '⚠️  Agentic files already exist:',
       '   • .codex/mcp.json.example',
-      'Run with --force to regenerate from current templates.',
+      'Run with --update-harness to preserve local edits, or --force to replace generated files.',
     ]))
   })
 
@@ -160,7 +180,7 @@ describe('runAgenticInit', () => {
       questionAnswer: '  cursor  ',
       runAgenticSetupImplementation: async (currentTargetDir, ask, options) => {
         expect(currentTargetDir).toBe(targetDir)
-        expect(options).toEqual({ tool: undefined, force: undefined })
+        expect(options).toEqual({ tool: undefined, force: undefined, updateHarness: undefined })
         await expect(ask('Select a tool')).resolves.toBe('cursor')
       },
     })
@@ -188,7 +208,7 @@ describe('runAgenticInit', () => {
     expect(testContext.runAgenticSetup).toHaveBeenCalledWith(
       targetDir,
       expect.any(Function),
-      { tool: 'codex', force: undefined },
+      { tool: 'codex', force: undefined, updateHarness: undefined },
     )
     expect(consoleLogSpy.mock.calls.flat()).not.toContain('⚠️  Agentic files already exist:')
     expect(testContext.closeInterface).toHaveBeenCalledTimes(1)
@@ -205,7 +225,23 @@ describe('runAgenticInit', () => {
     expect(testContext.runAgenticSetup).toHaveBeenCalledWith(
       targetDir,
       expect.any(Function),
-      { tool: 'codex', force: true },
+      { tool: 'codex', force: true, updateHarness: undefined },
+    )
+    expect(testContext.closeInterface).toHaveBeenCalledTimes(1)
+  })
+
+  it('bypasses overwrite warnings and requests an ownership-aware update', async () => {
+    const testContext = await loadRunAgenticInit({
+      existingPaths: new Set<string>([appModulesPath, codexConfigPath]),
+    })
+
+    const exitCode = await testContext.runAgenticInit(['--tool=codex', '--update-harness'])
+
+    expect(exitCode).toBe(0)
+    expect(testContext.runAgenticSetup).toHaveBeenCalledWith(
+      targetDir,
+      expect.any(Function),
+      { tool: 'codex', force: undefined, updateHarness: true },
     )
     expect(testContext.closeInterface).toHaveBeenCalledTimes(1)
   })