fix(cli): anchor engine cwd and rewrite bundled config with absolute paths

[rohitg00]

Closes #844, closes #700, closes #303.

The bundled iii-config.yaml uses cwd-relative paths and the engine was spawned without a cwd. On global and npx installs, ./data stores landed in whatever directory the user ran the CLI from, and the iii-exec supervision block (src watch, node dist/index.mjs exec) never resolved, so the engine never supervised a worker and nothing respawned it after the in-process worker died. That is the mechanism behind the data-loss-on-restart reports against a live REST port.

startIiiBin now writes ~/.agentmemory/iii-config.runtime.yaml (regenerated each boot) with absolute data paths and an absolute worker exec line whenever the bundled config is in play, copies legacy ./data stores from the invocation directory on first run, and spawns the engine with cwd anchored at ~/.agentmemory. Repo checkouts keep the cwd config and repo-root cwd, so dev behavior is unchanged. User overrides via AGENTMEMORY_III_CONFIG or ~/.agentmemory/iii-config.yaml pass through verbatim. agentmemory remove gains a plan item for the generated file.

Tested by test/engine-launch.test.ts including a drift guard that rewrites the repo's real iii-config.yaml and asserts no relative paths remain.

Summary by CodeRabbit

Release Notes

• New Features

  • Engine startup now prepares a dedicated runtime directory with automatic configuration setup
  • Added support for legacy data migration during engine launch
  • Improved handling of bundled configurations with proper path resolution

• Bug Fixes

  • Engine cleanup now properly removes generated runtime configuration files

• Tests

  • Added comprehensive test coverage for engine launch and configuration utilities

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentmemory	Ready	Preview, Comment	Jun 10, 2026 10:48pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 27aacc9b-7e1f-41eb-a69c-1c957fe75801

📥 Commits

Reviewing files that changed from the base of the PR and between 25e7701 and f358f93.

📒 Files selected for processing (4)

• src/cli.ts
• src/cli/engine-launch.ts
• src/cli/remove-plan.ts
• test/engine-launch.test.ts

---

📝 Walkthrough

Walkthrough

This PR resolves native engine supervision by preparing a runtime launch directory and rewriting bundled iii-config.yaml with absolute paths instead of relative ones that fail when the engine's working directory diverges from the package installation. The CLI now detects bundled configs, rewrites them with absolute data and worker paths, migrates legacy data if present, and spawns the engine with the computed home-based working directory.

Changes

Engine launch directory and config management

Layer / File(s)	Summary
Engine launch path and config utilities src/cli/engine-launch.ts	Exports path helpers anchoring engine state under ~/.agentmemory, detects bundled vs. local configs, resolves the appropriate engine working directory, and provides legacy data migration mappings from invocation context to the home data directory.
CLI integration: spawn with cwd and launch preparation src/cli.ts	Imports cpSync and engine-launch helpers; extends spawnEngineBackground to accept and forward optional cwd; introduces prepareEngineLaunch orchestration that detects bundled configs, rewrites them to absolute paths, migrates legacy data, and returns the runtime config path and working directory for engine startup; updates startIiiBin to use the prepared config and cwd.
Engine launch test coverage test/engine-launch.test.ts	Comprehensive Vitest suite validating path helpers, bundled config detection, engine cwd resolution, YAML path and command rewriting (including apostrophe escaping), and legacy data migration mapping against fixtures and real bundled config templates.
Runtime config cleanup in removal plan src/cli/remove-plan.ts	Imports runtimeConfigPath and adds a runtime-config destruction plan item that deletes the generated iii-config.runtime.yaml when the engine is removed, gated by file existence without alwaysAsk prompt.

Sequence Diagram

sequenceDiagram
  participant CLI
  participant prepareEngineLaunch
  participant resolveEngineCwd
  participant rewriteBundledConfig
  participant legacyDataMigrations
  participant spawnEngineBackground
  CLI->>prepareEngineLaunch: prepareEngineLaunch(configPath)
  prepareEngineLaunch->>resolveEngineCwd: resolve engine working directory
  alt is bundled config
    prepareEngineLaunch->>rewriteBundledConfig: rewrite to absolute paths
    prepareEngineLaunch->>legacyDataMigrations: enumerate data migrations
    prepareEngineLaunch->>prepareEngineLaunch: copy legacy data from→to
  end
  prepareEngineLaunch->>prepareEngineLaunch: write runtime config
  prepareEngineLaunch-->>CLI: return {configPath, cwd}
  CLI->>spawnEngineBackground: spawn engine with cwd

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 The bundled config wore a veil of relative paths so dear,
But when the engine roamed from home, those paths would disappear.
Now we anchor to ~/.agentmemory with absolute grace,
And legacy data follows home to find its resting place!
YAML apostrophes danced, the worker is supervised at last,
No more terminal-bound workers—persistence holds fast! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main changes: anchoring the engine cwd and rewriting bundled config with absolute paths to address the core issues.
Linked Issues check	✅ Passed	The PR fully implements requirements from all three linked issues: #844 (resolves iii-exec supervision via absolute paths), #700 (moves data to ~/.agentmemory), and #303 (prevents repo pollution by anchoring cwd outside projects).
Out of Scope Changes check	✅ Passed	All changes directly support the core objectives: engine launch preparation, bundled config rewriting, legacy data migration, runtime config generation, and cleanup plans. No unrelated changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/engine-spawn-absolute-paths

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}