Seamless armonia migration — bootstrap + migration + retirement scripts (#386)

CONTEXT.md

@@ -43,8 +43,8 @@ _Avoid_: chat, side chat, ticket
 ### Knowledge
 
 **Armonia**:
-The canonical workspace and knowledge system. As a workspace: the `~/armonia/` directory tree (`repos/{packages,demos}`, `data/{env,problems,runs,vaults}`) surfaced as the structured "Armonia" sidebar panel via ArmoniaService. As a knowledge system: the precedence-ordered stack of mounted Vaults under `data/vaults/` (personal → project → team) that the agent reads for context. The sidebar panel shows both — semantic buckets for the full workspace, with Vaults as one bucket.
-_Avoid_: Vault (as the system name), knowledge base
+The canonical workspace and single state root. As a workspace: the `~/armonia/` directory tree (`repos/{packages,demos}`, `data/{config,env/julia,problems,runs,vaults,library,fleet,ledger,devices,authoring,amicode}`) surfaced as the structured "Armonia" sidebar panel via ArmoniaService. As a knowledge system: the precedence-ordered stack of mounted Vaults under `data/vaults/` (personal → project → team) that the agent reads for context. All amicode product state lives here; `~/.amico/` is a backward-compatible symlink farm into `data/` (ADR 0008), retired once ArmoniaService resolves paths directly.
+_Avoid_: Vault (as the system name), knowledge base, ~/.amico (as a canonical location)
 
 **Vault**:
 One mounted knowledge tier within Armonia — a git-backed store of notes, specs, and catalog entries at a single precedence level (personal / project / team). Many Vaults mount into the Armonia stack; the panel lists them as its roots and reads them top-to-bottom.

docs/adr/0008-armonia-subsumes-amico-state.md

@@ -0,0 +1,67 @@
+# Armonia subsumes ~/.amico — symlink farm now, ArmoniaService retirement later
+
+Status: accepted (2026-08-14)
+
+All amicode product state migrates from `~/.amico/` into `~/armonia/data/`. The
+`~/.amico/` directory becomes a backward-compatible symlink farm (phase B) that is
+retired by a user-run cleanup script once ArmoniaService resolves paths directly
+(phase C). Opencode's XDG paths (`~/.config/opencode/`, `~/.local/share/opencode/`)
+are untouched — they belong to the engine, not the product.
+
+**Why:** `~/.amico/` accumulated ~15 distinct paths organically. Issue #326 (Armonia
+as default workspace) needs a single tree it can browse, watch, and resolve against.
+Leaving state scattered across two roots (`~/armonia/` for repos+artifacts,
+`~/.amico/` for everything else) means the sidebar can never show the full picture
+and the session cwd story has a permanent asterisk. Subsuming everything under
+armonia gives one tree, one backup target, one mental model.
+
+**Why a symlink farm (not a code refactor first):** the codebase has ~30 call sites
+that resolve `homedir() + ".amico" + X`. Rewriting them all requires ArmoniaService
+(#326) which is a substantial PR. The symlink farm makes the filesystem migration
+zero-breakage today — every existing path resolves transparently — while the code
+catches up at its own pace.
+
+**Why config files stay as real files at `~/.amico/` (not symlinked):** file-level
+symlinks break if the target is deleted and recreated (the symlink becomes dangling
+and a new real file appears at the original path). Credential files like `cloud.json`
+are written atomically (delete + rename) by multiple code paths. Directory symlinks
+do not have this problem — `readdir` follows them transparently.
+
+**Considered:**
+
+- **(A) `~/.amico/` stays canonical, armonia is browse-only** — rejected: perpetuates
+  two roots, the sidebar is a projection of reality rather than reality itself, and
+  "where does X live?" remains a question with two answers.
+- **(B) Single symlink `~/.amico → ~/armonia/data`** — rejected: forces a flat layout
+  inside `data/` that matches `~/.amico/`'s structure exactly, blocking any
+  reorganization (e.g. `data/config/`, `data/env/julia/`).
+- **(C) Immediate code refactor (no symlink phase)** — rejected: blocks the migration
+  on #326 and a ~30-site refactor; users cannot benefit until both land.
+
+**Chosen: (D) symlink farm now, retirement script gated on ArmoniaService.** The
+retirement script (`tools/retire-amico-symlinks.sh`) ships in the same PR and checks
+for a marker file (`~/armonia/.armonia-active`) written by ArmoniaService on boot
+before it will run. This ensures the user cannot accidentally retire the symlinks
+while the code still reads through them.
+
+**Layout after migration:**
+
+```
+~/armonia/data/
+  config/       profile.json, cloud.json, pasqal.json, connections.json, lab.toml, mounts.toml
+  env/julia/    the provisioned Julia project
+  problems/     problem workspaces
+  runs/         run output
+  vaults/       mounted vaults
+  library/      uploaded papers
+  fleet/        fleet registry + tunnel state
+  ledger/       runs.jsonl, claims.jsonl, approvals/
+  devices/      calibration state
+  authoring/    authoring.json
+  amicode/      entitlements, solver mode
+```
+
+**Exit condition (phase C):** all `homedir() + ".amico" + X` callers migrated to
+`ArmoniaService.resolve()`, ArmoniaService writes `~/armonia/.armonia-active` on
+boot, the retirement script passes its gate check, and the user runs it. Phase C is
+a separate issue gated on #326 with the `hitl` label.

packages/amico-run/src/authoring.ts

@@ -5,8 +5,7 @@
 // defaults (public base ∪ support set) so a bare-but-spec'd dev invocation
 // still gates sanely. $AMICO_AUTHORING_FILE overrides the path (tests).
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { authoringFile as _authoringFile } from "./paths.js";
 
 // NOTE (spec-20260704-113005 §3): session prep ALSO writes an additive
 // `skills: [{source: "library"|"package", package?, name, description, path}]`
@@ -37,7 +36,7 @@ function defaults(): AuthoringConfig {
 export function authoringFile(): string {
   const env = process.env.AMICO_AUTHORING_FILE;
   if (env && env.trim() !== "") return env;
-  return join(homedir(), ".amico", "authoring", "authoring.json");
+  return _authoringFile();
 }
 
 export function readAuthoring(): { config: AuthoringConfig; warning?: string } {

packages/amico-run/src/coordination_ledger.ts

@@ -4,12 +4,9 @@
 
 import { createHash } from "node:crypto";
 import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
 import path from "node:path";
+import { claimsFile } from "./paths.js";
 
-function claimsFile(): string {
-  return process.env.AMICO_CLAIMS_FILE ?? path.join(homedir(), ".amico", "ledger", "claims.jsonl");
-}
 function appendClaimLine(claim: Claim): void {
   const file = claimsFile();
   mkdirSync(path.dirname(file), { recursive: true });

packages/amico-run/src/device_graph.ts

@@ -12,9 +12,9 @@
 // Loaders never throw: a missing/corrupt graph or state degrades to an empty view,
 // exactly like repertoire.ts's loaders degrade to an empty repertoire.
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { parse as parseToml } from "smol-toml";
+import { devicesDir } from "./paths.js";
 
 /** The single status enum — node state, evaluate() verdict, and the per-qubit
  *  rollup all use it (no divergent vocabularies). */
@@ -571,7 +571,7 @@ export function releaseDecision(
 export function deviceRoot(): string {
   const env = process.env.AMICO_DEVICE_DIR;
   if (env && env.trim() !== "") return env;
-  return join(homedir(), ".amico", "devices");
+  return devicesDir();
 }
 
 export interface DeviceLoad {

packages/amico-run/src/fleet_registry.ts

@@ -34,9 +34,10 @@
 // `retierEventFor` are that mapping, kept pure and here so the CLI cannot invent a
 // fourth reading of it.
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
-import { homedir, hostname } from "node:os";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { fleetDir } from "./paths.js";
 
 // ── §3.2 states ──────────────────────────────────────────────────────────────────
 /** The six registry states. Entered when:
@@ -887,7 +888,7 @@ export function signalFromToml(text: string): { ok: true; signal: FleetSignal }
 /** The registry root. Precedence: explicit argument (tests, `--root`) → `$AMICO_FLEET_DIR`
  *  → `~/.amico/ops/fleet` (§3.2). Mirrors ledger.ts's single-env idiom. */
 export function fleetRoot(explicit?: string): string {
-  return explicit || process.env.AMICO_FLEET_DIR || join(homedir(), ".amico", "ops", "fleet");
+  return explicit || fleetDir();
 }
 
 export function recordPath(root: string, session_id: string): string {

packages/amico-run/src/index.ts

@@ -1,3 +1,11 @@
+export {
+  baseDir, isCanonicalLayout, isLegacyLayout, _resetBaseDir,
+  runsRoot, problemsRoot, juliaProject, ledgerDir, ledgerFile, claimsFile,
+  authoringDir, authoringFile, devicesDir, libraryDir, opsDir,
+  fleetDir, configFile, profileFile, pasqalConfigFile, connectionsFile,
+  labTomlFile, mountsTomlFile, vaultsRoot, teamVaultDir,
+  catalogPulsesDir, profilesVaultDir, teamSkillsDir, reposRoot,
+} from "./paths.js";
 export * from "./types.js";
 export * from "./estimate.js";
 export * from "./telemetry.js";

packages/amico-run/src/ledger.ts

@@ -18,9 +18,9 @@
 // cross-process guarantee is exercised by a real-subprocess concurrency test at the
 // `ledger` verb layer (ledger_verb.test.ts), where the built CLI exists.
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
 import { validate } from "@amicode/schema";
+import { ledgerFile } from "./paths.js";
 
 /** POSIX minimum PIPE_BUF; O_APPEND writes at or under this size are atomic on
  *  Linux (a single `write(2)` never interleaves with another). */
@@ -293,7 +293,7 @@ export type LedgerRecord =
 
 /** The ledger file path: `$AMICO_LEDGER` override, else `~/.amico/ledger/runs.jsonl`. */
 export function ledgerPath(): string {
-  return process.env.AMICO_LEDGER || join(homedir(), ".amico", "ledger", "runs.jsonl");
+  return ledgerFile();
 }
 
 /** Append one record as a single JSONL line. Validates against the `ledger-record`

packages/amico-run/src/mounts.ts

@@ -41,9 +41,9 @@
 // House style (mirrors repertoire.ts): never-throwing loaders (a missing/corrupt
 // vault or manifest degrades to a warning, never a throw) + pure functions.
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { parse as parseToml } from "smol-toml";
+import { vaultsRoot, mountsTomlFile } from "./paths.js";
 
 /** One resolved Armonia vault mount. `writable` is the effective posture after the
  *  kind default + any manifest override. */
@@ -80,14 +80,10 @@ function defaultWritable(kind: string): boolean {
 
 // ── env-seam defaults ─────────────────────────────────────────────────────────
 function defaultVaultsRoot(): string {
-  const env = process.env.AMICO_VAULTS_ROOT;
-  if (env && env.trim() !== "") return env;
-  return join(homedir(), ".amico", "vaults");
+  return vaultsRoot();
 }
 function defaultMountsToml(): string {
-  const env = process.env.AMICO_MOUNTS_TOML;
-  if (env && env.trim() !== "") return env;
-  return join(homedir(), ".amico", "mounts.toml");
+  return mountsTomlFile();
 }
 
 // ── manifest (`mounts.toml`) ─────────────────────────────────────────────────────

packages/amico-run/src/pasqal_devices.ts

@@ -12,8 +12,7 @@
 // a poisoned "token", anything — has no path into our output.
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { connectionsFile } from "./paths.js";
 
 export const PASQAL_CONNECTION_ID = "pasqal-cloud";
 
@@ -35,7 +34,7 @@ export type DeviceTier = "free" | "non-free";
 export function connectionsCacheFile(env: NodeJS.ProcessEnv = process.env): string {
   const v = env.AMICODE_CONNECTIONS_FILE;
   if (v && v.trim() !== "") return v;
-  return join(homedir(), ".amico", "connections.json");
+  return connectionsFile();
 }
 
 /** Default-deny classification, case-insensitive on the identifier. */

packages/amico-run/src/pasqal_launch.ts

@@ -8,9 +8,10 @@
 // child env is built from scratch (never a process.env spread).
 import { spawn } from "node:child_process";
 import { accessSync, constants as fsConstants, existsSync, readFileSync } from "node:fs";
-import { constants as osConstants, homedir } from "node:os";
+import { constants as osConstants } from "node:os";
 import { delimiter, join, resolve } from "node:path";
 import { ConfigError } from "./types.js";
+import { pasqalConfigFile } from "./paths.js";
 
 export interface PasqalCredentials {
   projectId: string;
@@ -22,7 +23,7 @@ export interface PasqalCredentials {
 export function pasqalCredentialFile(env: NodeJS.ProcessEnv = process.env): string {
   const v = env.AMICO_PASQAL_FILE;
   if (v && v.trim() !== "") return v;
-  return join(homedir(), ".amico", "pasqal.json");
+  return pasqalConfigFile();
 }
 
 /** Read + shape-check the credential file. Distinct, actionable, TOKEN-FREE errors

packages/amico-run/src/pasqal_verb.ts

@@ -24,9 +24,9 @@
 // token appears in the digest, the JSON output, or the launcher argv.
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { opsDir } from "./paths.js";
 import {
   pulseSha256,
   readDevicePathStatus,
@@ -61,7 +61,7 @@ function flagValue(argv: string[], name: string): string | undefined {
 function amicodeOpsDir(env: NodeJS.ProcessEnv): string {
   const v = env.AMICODE_OPS_DIR;
   if (v && v.trim() !== "") return v;
-  return join(homedir(), ".amico", "amicode");
+  return opsDir();
 }
 
 /** $AMICO_PASQAL_CONNECTOR overrides; default is the staged submit connector. */