feat(install): per-instance data dir isolation via --data-dir / --instance (#193)

[yashrajsapra]

Summary

• Adds --data-dir and --instance flags to install so multiple Claude Code instances running on the same machine use isolated config/log directories instead of fighting over a shared one
• Shell injection in --data-dir is eliminated by switching to execFileSync argv array (security fix surfaced in review)
• Multi-instance usage guide added to docs

Changes

• feat(install): per-instance data dir isolation via --data-dir / --instance + workspace CLI
• docs: multi-instance usage guide
• fix(install): eliminate shell injection in --data-dir via execFileSync argv array
• chore: cleanup fleet control files (PLAN.md, progress.json, feedback.md, CLAUDE.md, AGENTS.md)

Test plan

• node dist/index.js install --data-dir /tmp/inst-a and --data-dir /tmp/inst-b produce fully isolated runtime dirs
• node dist/index.js install --instance myproject resolves to a deterministic subdirectory
• Passing a path with spaces / special chars in --data-dir does not cause shell injection
• Existing installs without --data-dir continue to use the default data directory unchanged
• Multi-instance usage guide renders correctly in docs

🤖 Generated with Claude Code

[kumaakh]

MEDIUM (non-blocking): mcp remove still goes through run(), which calls execSync with the command as a shell string. serverName is validated upstream so this is safe in practice, but it is inconsistent with the execFileSync argv-array fix applied everywhere else in this PR.

Consider splitting run() into a runFile(bin, args[]) variant, or inlining this call as:

execFileSync('claude', ['mcp', 'remove', serverName, '--scope', 'user'], { stdio: 'ignore' });

This keeps the security posture consistent across the whole install path.

[kumaakh]

LOW (non-blocking): APRA_BASE and DEFAULT_DATA_DIR are re-derived here from scratch, but paths.ts already exports APRA_BASE and FLEET_DIR (which is APRA_FLEET_DATA_DIR ?? .apra-fleet/data). Importing from paths.ts would eliminate the duplication and ensure both files always agree on the canonical base path — especially important if the default ever changes.

[kumaakh]

BLOCKING — apra-fleet update silently loses custom workspace on replay

Two issues in this section mean that apra-fleet update will always reinstall to the default workspace, silently discarding any --data-dir / --instance the user originally passed.

Issue 1 (line 678): installConfig only saves { llm, skill }. dataDir and instanceName are not persisted.

Issue 2 (line 679): configDir is hardcoded to FLEET_BASE/data (i.e. ~/.apra-fleet/data/). When a custom --data-dir is used, the config is written to the wrong directory — the default workspace's data folder instead of the custom one.

Issue 3 (not in this diff — src/cli/update.ts line 91): Even if installConfig were fixed to save dataDir, the update replay only constructs ['install', '--llm', config.llm, '--skill', config.skill] — --data-dir and --instance are never read back or passed.

Fix needed in this PR:

// line 678 — include dataDir / instanceName
const installConfig: Record<string, string> = { llm, skill: skillMode };
if (dataDir) installConfig.dataDir = dataDir;
if (instanceName) installConfig.instance = instanceName;

// line 679 — write config to the active data dir, not hardcoded default
const configDir = dataDir ?? path.join(FLEET_BASE, 'data');

And update.ts must be updated to read config.dataDir / config.instance and append --data-dir / --instance to the replay args.

[kumaakh]

BLOCKING — installConfig omits dataDir and instanceName. When apra-fleet update reads this file to replay the install, it has no record of the custom data dir and will reinstall for the default workspace only, silently breaking any non-default workspace install. See review body for the full issue and suggested fix.

[kumaakh]

Design suggestion for the install-config.json fix

Rather than a per-workspace file, install-config.json should be a singleton accumulator at ~/.apra-fleet/install-config.json (outside any data dir) that tracks every install invocation:

{
  "installs": [
    { "llm": "claude", "skill": "all" },
    { "llm": "claude", "skill": "fleet", "instance": "work" },
    { "llm": "gemini", "skill": "fleet", "dataDir": "/custom/path" }
  ]
}

Each entry maps 1:1 to a CLI invocation. apra-fleet update reads this one file and replays every entry in order — no need to discover workspaces via workspaces.json first.

Upsert rule: key on { instance, dataDir } (both optional/undefined for the default workspace). On re-install, replace the matching entry rather than append — so running apra-fleet install --instance work --llm gemini a second time updates that entry in place.

Changes needed:

• src/cli/install.ts — after MCP registration, upsert into ~/.apra-fleet/install-config.json (not ${dataDir}/install-config.json)
• src/cli/update.ts — read config.installs[], replay each entry with ['install', '--llm', e.llm, '--skill', e.skill, ...(e.instance ? ['--instance', e.instance] : []), ...(e.dataDir ? ['--data-dir', e.dataDir] : [])]
• Tests: add a case that installs twice with different --instance values and verifies update would replay both