create-agentic-workspace 0.8.0 → 0.9.0

package/README.md

@@ -11,8 +11,14 @@ npx create-agentic-workspace --dir my-workspace
 
 The CLI walks you through the target directory, greenfield-vs-existing, git/GitHub identity, and
 stage mode, **previews every file it will write and every capability it will declare**, writes
-the workspace, and stops. It never runs `claude`, never accepts the workspace trust dialog, and
-never pre-grants anything — it *declares*, the platform's trust dialog is the consent ceremony.
+the workspace, and stops. `create-agentic-workspace` never runs `claude`, never accepts the
+workspace trust dialog, and never pre-grants anything — it *declares*, the platform's trust dialog
+is the consent ceremony.
+
+**Already have a workspace and want it current instead?** That is a different command, on purpose
+— see the sibling package [`update-agentic-workspace`](https://github.com/lukasrepublic/agentic-foundry/tree/main/cli-update#readme),
+which refreshes the marketplace, updates the plugin, and re-runs this reconcile. Unlike this one,
+it does invoke `claude` (bounded by a closed allowlist — see its own README).
 
 ## What it does
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-workspace",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The pre-session bootstrap wizard for an Agentic Foundry workspace: declares (never grants) the permission floor, absorbs foundry-bootstrap.sh's out-of-session identity wiring, and scaffolds a seven-file schema-valid workspace. Zero dependencies, no lifecycle scripts, no telemetry.",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "marketplace_name": "agentic-foundry",
     "marketplace_repo": "lukasrepublic/agentic-foundry",
     "plugin_name": "foundry",
-    "plugin_version": "1.8.0",
+    "plugin_version": "1.9.0",
     "pins_researched": "2026-08-02"
   }
 }

package/permission-floor.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "plugin_root_glob": "~/.claude/plugins/cache/*/foundry/*",
-  "generated_for_plugin_version": "1.8.0",
+  "generated_for_plugin_version": "1.9.0",
   "entries": [
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-acceptance-contract-validate.py:*)",

package/src/cleanup.mjs

@@ -0,0 +1,303 @@
+// cleanup.mjs — Phase 3 (opt-in, `--cleanup`) of `npx update-agentic-workspace`: prune superseded
+// plugin-cache versions and remove a stale/duplicate marketplace registration. THE FIRST recursive
+// delete of an adopter path in cli/src/ — every other `rmSync` in this package removes a temp file
+// the process itself just wrote. Fail-closed throughout: AC-UWC-4 skips (removes nothing) on any
+// indeterminate input, and AC-UWC-9 refuses (removes nothing AT ALL, superseded entries included)
+// on any cache entry that is not a plain immediate-child directory of the pinned root.
+import fs from 'node:fs';
+import path from 'node:path';
+import { RefusalError } from './util.mjs';
+import {
+  runClaude, readInstalledPluginsRegistry, scopeRecordsFor,
+  readMarketplaceManifest, pluginEntryOf,
+} from './pluginRefresh.mjs';
+
+// ── AC-UWC-1 — the live set is READ from the platform's own state, never computed by sorting ────
+
+/** The union of every scope record's `version` for `<plugin>@<marketplace>` in
+ * installed_plugins.json, plus the refreshed marketplace manifest's `version` — NEVER the highest
+ * semver on disk. `scripts/foundry-fleet-doctor.py:70-83`'s `installed_index()` is correct for its
+ * own job (report ONE adopter's resolved plugin) and unsafe here: it `break`s after the first
+ * record and would silently drop a scope pinned to an older version that is still live. */
+export function deriveLiveSet({ registry, manifestVersion, pluginKey }) {
+  if (!registry.ok) return { ok: false, reason: registry.reason };
+  const records = scopeRecordsFor(registry.doc, pluginKey);
+  if (records.length === 0) {
+    return { ok: false, reason: `installed plugin registry holds no record for ${pluginKey}` };
+  }
+  // REFUSE ON THE FIRST UNUSABLE RECORD, not merely when every record is unusable. A `.filter()`
+  // that drops a malformed record while its SIBLINGS keep the set non-empty is the dangerous
+  // shape: the set stays `ok`, and the dropped record's still-live directory is handed to
+  // planCachePrune as a prune candidate. That is a live install of ANOTHER project deleted on a
+  // registry the platform wrote — recoverable only by reinstalling, and invisible until that
+  // project's next session breaks. An empty-set check alone closes only the degenerate half.
+  // `!r.version.trim()` and not merely `!r.version`: a whitespace-only version is a non-empty
+  // string, so it passes a truthiness test, joins the live set as "  ", and leaves the record's
+  // REAL cache directory absent from the set — the same hole as a dropped record, reached through
+  // a value that looks usable.
+  const unusable = records.findIndex(
+    (r) => !r || typeof r.version !== 'string' || !r.version.trim(),
+  );
+  if (unusable !== -1) {
+    return {
+      ok: false,
+      reason: `installed plugin registry record ${unusable} for ${pluginKey} carries no usable version string`,
+    };
+  }
+  // `installPath` is REQUIRED, not opportunistic. The namespace-bridging below is only a safeguard
+  // if it actually runs; making it conditional on the field being present would mean the one shape
+  // that needs the bridge (a directory name that differs from `version`) is exactly the shape that
+  // silently skips it. Every registry the platform writes carries this field, so a record without
+  // one is indeterminate input and takes the AC-UWC-4 skip like any other.
+  const noPath = records.findIndex((r) => typeof r.installPath !== 'string' || !r.installPath.trim());
+  if (noPath !== -1) {
+    return {
+      ok: false,
+      reason: `installed plugin registry record ${noPath} for ${pluginKey} carries no usable installPath`,
+    };
+  }
+
+  // TWO NAMESPACES, seeded from both. `versions` is a set of version STRINGS; planCachePrune
+  // enumerates directory NAMES. Nothing in the platform's contract says those coincide, and if it
+  // ever normalises one differently from the other, every on-disk directory — the live one
+  // included — becomes a candidate while this function still reports `ok`. `installPath` is the
+  // only field that literally names the directory, so its basename is seeded alongside `version`:
+  // the live set is then expressed in BOTH namespaces and a divergence can only ever make the set
+  // larger (fewer deletions), never smaller.
+  const versions = new Set();
+  for (const r of records) {
+    versions.add(r.version);
+    const leaf = path.basename(r.installPath);
+    if (leaf && leaf !== '.' && leaf !== path.sep) versions.add(leaf);
+  }
+  if (manifestVersion) versions.add(manifestVersion);
+  // Belt-and-braces: unreachable given the per-record refusal above, but an empty live set is the
+  // one verdict this function must never hand back on indeterminate input (AC-UWC-4), so it is
+  // asserted rather than assumed.
+  if (versions.size === 0) {
+    return { ok: false, reason: `no live version could be read for ${pluginKey}` };
+  }
+  return { ok: true, versions };
+}
+
+// ── AC-UWC-2/-9 — the candidate set is constructed by name, inside ONE pinned root ──────────────
+
+/** Enumerate the immediate children of `pluginCacheDir`, subtract `liveVersions`, and return the
+ * prune candidates. Refuses — throwing BEFORE anything is removed, so nothing this run touches is
+ * ever partially applied — on the first entry that is a symlink, a non-directory, or whose
+ * resolved real path is not literally `pluginCacheDir/<name>`.
+ *
+ * The real-path check compares against the entry's OWN nominal join, not a realpath'd root: a
+ * SYMLINKED ANCESTOR (e.g. `plugins/cache/<marketplace>` itself replaced with a symlink to another
+ * disk) would resolve consistently on BOTH sides if the root were realpath'd first, hiding exactly
+ * the redirection this check exists to catch. Comparing the leaf's realpath to its own nominal path
+ * catches an ancestor symlink the same way it catches a leaf one — lstat on the leaf already ruled
+ * the leaf itself out, so any remaining divergence can only come from an ancestor. */
+export function planCachePrune({ pluginCacheDir, liveVersions }) {
+  if (!fs.existsSync(pluginCacheDir)) return [];
+  const names = fs.readdirSync(pluginCacheDir);
+  const candidates = [];
+  for (const name of names) {
+    const nominal = path.join(pluginCacheDir, name);
+    const lst = fs.lstatSync(nominal);
+    if (lst.isSymbolicLink()) {
+      throw new RefusalError(`refusing cache entry ${nominal}: symbolic link`, 'cleanup');
+    }
+    if (!lst.isDirectory()) {
+      throw new RefusalError(`refusing cache entry ${nominal}: not a directory`, 'cleanup');
+    }
+    const real = fs.realpathSync(nominal);
+    if (real !== nominal) {
+      throw new RefusalError(
+        `refusing cache entry ${nominal}: resolved real path (${real}) escapes the pinned root`,
+        'cleanup',
+      );
+    }
+    if (!liveVersions.has(name)) candidates.push(name);
+  }
+  return candidates;
+}
+
+/** Remove exactly the candidates already validated by planCachePrune — never re-validates, never
+ * enumerates further. Called only under `--cleanup` (AC-UWC-6), and only once planCachePrune has
+ * returned without throwing for the WHOLE directory (AC-UWC-9's "removes nothing at all"). */
+export function applyCachePrune(pluginCacheDir, candidates) {
+  for (const name of candidates) {
+    fs.rmSync(path.join(pluginCacheDir, name), { recursive: true, force: false });
+  }
+}
+
+// ── AC-UWC-7 — a stale or duplicate registration that no scope enables ──────────────────────────
+
+export function readKnownMarketplaces(configDir) {
+  const p = path.join(configDir, 'plugins', 'known_marketplaces.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(p, 'utf-8');
+  } catch (e) {
+    return { ok: false, reason: e.code === 'ENOENT' ? 'known_marketplaces.json is absent' : `known_marketplaces.json is unreadable: ${e.message}` };
+  }
+  try {
+    return { ok: true, doc: JSON.parse(raw) };
+  } catch (e) {
+    return { ok: false, reason: `known_marketplaces.json does not parse as JSON: ${e.message}` };
+  }
+}
+
+/** AC-UWC-4(ii)/AC-UWC-7(b) — the set of `<...>@<registrationName>` qualifiers enabled ANYWHERE,
+ * used both to decide whether a stale/duplicate registration is safe to remove and to route an
+ * unreadable settings scope to the SKIP branch rather than silently reading it as "not enabled",
+ * which would turn an I/O failure into permission to remove a LIVE registration (spec R4 — "the
+ * single most dangerous mis-implementation available in this atom"). Absence of a scope's settings
+ * file is NOT an error (nothing is configured there); a file that EXISTS but cannot be read or
+ * parsed is — mirrors the sibling AC-UAW-13 scope model exactly, for the same reason. */
+export function resolveEnabledQualifiers(scopeDescriptors) {
+  const qualifiers = new Set();
+  for (const scope of scopeDescriptors) {
+    let raw;
+    try {
+      raw = fs.readFileSync(scope.settingsPath, 'utf-8');
+    } catch (e) {
+      if (e.code === 'ENOENT') continue;
+      return { ok: false, reason: `${scope.name} scope settings file is unreadable (${scope.settingsPath})` };
+    }
+    let obj;
+    try {
+      obj = JSON.parse(raw);
+    } catch {
+      return { ok: false, reason: `${scope.name} scope settings file does not parse as JSON (${scope.settingsPath})` };
+    }
+    for (const key of Object.keys((obj && obj.enabledPlugins) || {})) qualifiers.add(key);
+  }
+  return { ok: true, qualifiers };
+}
+
+// R7 — `name` is a JSON OBJECT KEY read from the adopter's own known_marketplaces.json, not
+// adopter-typed input, but it still becomes an argv element passed to `claude plugin marketplace
+// remove <name>`. A key beginning with `-` (or containing anything outside a safe charset) would
+// reach the platform CLI's own option parser as a flag rather than a positional name. Filtered
+// out here, BEFORE any name reaches runCleanupPhase's runClaude call — never made removable, so it
+// can never become argv.
+// The FIRST character is restricted to alphanumeric — a leading `-` (or `.`, which some option
+// parsers also special-case) is exactly what would make the token look like a flag; only the
+// REST of the name may carry `.`/`_`/`-`.
+const SAFE_REGISTRATION_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** A registration for OUR repo is a candidate when it is STALE (`installLocation` names a path
+ * that does not exist) or DUPLICATE (its name is not the canonical marketplace name) — AND no
+ * scope's enabledPlugins names a plugin qualified by that registration's name, AND its name is a
+ * safe argv component (R7). */
+export function planRegistrationRemoval({ knownMarketplacesDoc, marketplaceRepo, canonicalName, enabledQualifiers }) {
+  const removable = [];
+  for (const [name, entry] of Object.entries(knownMarketplacesDoc || {})) {
+    const repo = entry && entry.source && entry.source.repo;
+    if (repo !== marketplaceRepo) continue;
+    if (!SAFE_REGISTRATION_NAME.test(name)) continue;
+    const stale = !(entry.installLocation && fs.existsSync(entry.installLocation));
+    const duplicate = name !== canonicalName;
+    if (!stale && !duplicate) continue;
+    const enabledHere = [...enabledQualifiers].some((q) => q.endsWith(`@${name}`));
+    if (enabledHere) continue;
+    removable.push(name);
+  }
+  return removable;
+}
+
+// ── the whole phase, composed ────────────────────────────────────────────────────────────────────
+
+/** Run cleanup end to end. `print` receives the preview lines BEFORE the first removal (AC-UWC-5);
+ * `cleanupFlag` gates BOTH the filesystem removals AND every `claude` invocation this phase makes
+ * (AC-UWC-6/-7 — a flagless run issues zero of either). Returns
+ * `{ verdict, reason?, prunedVersions, removedRegistrations }`. */
+export function runCleanupPhase({
+  cleanupFlag, configDir, marketplaceName, marketplaceRepo, pluginName, pluginKey,
+  scopeDescriptors, env, cwd, print, claudeBin,
+}) {
+  // The delete root is built from `marketplaceName`/`pluginName` — both come from this package's
+  // own bundled pins, never from adopter input, but `path.join` normalizes `..` regardless of
+  // provenance, and a corrupted or mis-edited pin (`"marketplace_name": "../.."`) would otherwise
+  // walk `pluginCacheDir` outside `plugins/cache/` entirely, past every symlink/realpath guard
+  // planCachePrune has (those guard the LEAVES, not this join). Validated before ANYTHING else in
+  // this phase runs.
+  const SAFE_COMPONENT = /^[A-Za-z0-9._-]+$/;
+  const isSafeComponent = (s) => SAFE_COMPONENT.test(s) && s !== '.' && s !== '..';
+  if (!isSafeComponent(marketplaceName) || !isSafeComponent(pluginName)) {
+    return {
+      verdict: 'skipped',
+      reason: 'marketplace or plugin name is not a safe path component; refusing to derive a cache root from it',
+      candidateVersions: [], prunedVersions: [], removedRegistrations: [],
+    };
+  }
+  const pluginCacheDirCandidate = path.join(configDir, 'plugins', 'cache', marketplaceName, pluginName);
+  const expectedPrefix = path.join(configDir, 'plugins', 'cache') + path.sep;
+  if (!pluginCacheDirCandidate.startsWith(expectedPrefix)) {
+    return {
+      verdict: 'skipped',
+      reason: 'the derived cache root escapes plugins/cache; refusing',
+      candidateVersions: [], prunedVersions: [], removedRegistrations: [],
+    };
+  }
+
+  const registry = readInstalledPluginsRegistry(configDir);
+  const manifest = readMarketplaceManifest(configDir, marketplaceName);
+  const manifestEntry = manifest.present ? pluginEntryOf(manifest.doc, pluginName) : null;
+  const liveSetResult = deriveLiveSet({
+    registry, manifestVersion: manifestEntry && manifestEntry.version, pluginKey,
+  });
+  const enabledResult = resolveEnabledQualifiers(scopeDescriptors);
+
+  // AC-UWC-4 — EITHER indeterminate input skips the WHOLE phase: every cache path present, every
+  // registration in place, a non-empty `skipped: <reason>` verdict, the run's own exit status
+  // untouched.
+  if (!liveSetResult.ok || !enabledResult.ok) {
+    return {
+      verdict: 'skipped',
+      reason: !liveSetResult.ok ? liveSetResult.reason : enabledResult.reason,
+      candidateVersions: [], prunedVersions: [], removedRegistrations: [],
+    };
+  }
+
+  const pluginCacheDir = pluginCacheDirCandidate;
+  // AC-UWC-9 — throws BEFORE anything is removed; propagated to the caller as a refusal.
+  const candidates = planCachePrune({ pluginCacheDir, liveVersions: liveSetResult.versions });
+
+  const known = readKnownMarketplaces(configDir);
+  const removableRegs = known.ok
+    ? planRegistrationRemoval({
+      knownMarketplacesDoc: known.doc, marketplaceRepo, canonicalName: marketplaceName,
+      enabledQualifiers: enabledResult.qualifiers,
+    })
+    : [];
+
+  // AC-UWC-5 — previewed before the first removal, in EVERY mode (report-only included, so the
+  // adopter sees the same list --cleanup would act on).
+  if (candidates.length > 0 || removableRegs.length > 0) {
+    print('cleanup: the following would be removed:');
+    for (const name of candidates) print(`  [cache] ${path.join(pluginCacheDir, name)}`);
+    for (const name of removableRegs) print(`  [marketplace registration] ${name}`);
+  } else {
+    print('cleanup: nothing to remove.');
+  }
+
+  const anything = candidates.length > 0 || removableRegs.length > 0;
+
+  if (!cleanupFlag) {
+    // AC-UWC-6/-7 — report-only: zero filesystem-removal calls AND zero `claude` invocations.
+    // `candidateVersions` is what WOULD be removed (always populated, for the preview/report);
+    // `prunedVersions` is what WAS actually removed — empty here by construction.
+    return {
+      verdict: anything ? 'changed' : 'already current',
+      candidateVersions: candidates, prunedVersions: [], removedRegistrations: [],
+    };
+  }
+
+  applyCachePrune(pluginCacheDir, candidates);
+  for (const name of removableRegs) {
+    runClaude(['plugin', 'marketplace', 'remove', name], { env, cwd, claudeBin });
+  }
+
+  return {
+    verdict: anything ? 'changed' : 'already current',
+    candidateVersions: candidates, prunedVersions: candidates, removedRegistrations: removableRegs,
+  };
+}

package/src/pluginRefresh.mjs

@@ -0,0 +1,318 @@
+// pluginRefresh.mjs — Phase 1 (marketplace refresh + the AC-UAW-4 one-time migration) and Phase 2
+// (plugin update, AC-UAW-5/-6) of `npx update-agentic-workspace`. THE ONLY module in this atom that
+// spawns `claude` — every process-spawning call site anywhere in the update path goes through
+// `runClaude` below, gated by the ONE frozen allowlist (AC-UAW-14). cli/src/cleanup.mjs imports
+// `runClaude` from here rather than declaring a second spawn site or a second copy of the allowlist.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { RefusalError } from './util.mjs';
+import { writeTargetAtomically } from './floorReconcile.mjs';
+
+// AC-UAW-14 — the closed six-pair allowlist, declared EXACTLY ONCE across this atom's modules.
+// Every `claude` invocation anywhere in the update path is one of these pairs (optionally followed
+// by more argv, e.g. a source/name and `--scope <scope>`) — never a bare `claude`, never anything
+// that can start a session or reach the trust dialog. `plugin install` is the sixth pair, admitted
+// on docs/troubleshooting.md:196-219's grounding: it is what re-establishes a plugin AC-UAW-4's own
+// `marketplace remove` may have orphaned.
+export const ALLOWED_CLAUDE_SUBCOMMANDS = Object.freeze([
+  ['plugin', 'marketplace', 'update'],
+  ['plugin', 'marketplace', 'add'],
+  ['plugin', 'marketplace', 'remove'],
+  ['plugin', 'update'],
+  ['plugin', 'install'],
+  ['plugin', 'list'],
+]);
+
+/** Prefix match against the frozen allowlist. Exact-token comparison at every position closes both
+ * failure modes a looser check would admit: a NEAR-MISS in the same namespace (`plugin uninstall`,
+ * `plugin marketplace list`) fails because some token differs, and a PREFIX-EXTENSION shape
+ * (`plugin updatex`) fails for the same reason — `args[1] === 'update'` is false for `'updatex'`,
+ * so a `startsWith`-style bug can never pass here because none is used. */
+export function isAllowedInvocation(args) {
+  return ALLOWED_CLAUDE_SUBCOMMANDS.some(
+    (pair) => pair.length <= args.length && pair.every((tok, i) => args[i] === tok),
+  );
+}
+
+/** Resolve `claude` on PATH WITHOUT spawning anything (AC-UAW-13's preflight). An executable
+ * regular file or symlink named `claude` in one of PATH's directories; the first match wins, same
+ * as a shell would resolve it. */
+export function resolveClaudeOnPath(pathEnv) {
+  for (const dir of String(pathEnv || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, 'claude');
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      // not here — keep looking
+    }
+  }
+  return null;
+}
+
+/** THE spawn site (AC-UAW-14). Refuses — WITHOUT spawning anything — any argv not drawn from
+ * ALLOWED_CLAUDE_SUBCOMMANDS. `env`/`cwd` are always supplied explicitly by the caller so a test
+ * can drive an isolated CLAUDE_CONFIG_DIR and an injected stub `claude` on PATH without ever
+ * touching the real one. `claudeBin`, when given, is the ABSOLUTE path resolveClaudeOnPath already
+ * found — spawned directly rather than re-resolving the bare name `claude` against `env.PATH` a
+ * second time, so the AC-UAW-13(a) preflight actually binds the executable the rest of the run
+ * uses (R8) instead of merely proving SOME `claude` existed a moment earlier. Falls back to the
+ * bare name only when no resolved path is given, e.g. from a unit test exercising this function on
+ * its own. */
+export function runClaude(args, { env, cwd, claudeBin }) {
+  if (!isAllowedInvocation(args)) {
+    throw new RefusalError(
+      `refusing claude invocation outside the closed allowlist: claude ${args.join(' ')}`,
+      'claude',
+    );
+  }
+  return execFileSync(claudeBin || 'claude', args, { env, cwd, encoding: 'utf-8' });
+}
+
+// ── Scope model (AC-UAW-5/-13/-15) ──────────────────────────────────────────────────────────────
+//
+// The only two scopes grounded anywhere in this repository (docs/troubleshooting.md:196-228,
+// skills/cut-release/SKILL.md:189-197): `user` (`<config-dir>/settings.json`) and `project`
+// (`<cwd>/.claude/settings.json` — this command is run FROM WITHIN an already-scaffolded workspace,
+// exactly like the reconcile path in run.mjs). `project` is therefore REQUIRED: its absence means
+// this was not run inside a real workspace, which AC-UAW-13 treats as an unresolvable precondition.
+// `user` is OPTIONAL — its absence just means nothing is configured at that scope (the common case
+// on a fresh machine) — but a PRESENT-and-broken file at EITHER scope is still a refusal: an I/O
+// failure must never be read as "not configured here", which is the failure R4/AC-UWC-4(ii) name as
+// the single most dangerous mis-implementation on the sibling cleanup atom's side of this same seam.
+
+export function defaultScopes({ cwd, configDir }) {
+  return [
+    { name: 'project', settingsPath: path.join(cwd, '.claude', 'settings.json'), required: true },
+    { name: 'user', settingsPath: path.join(configDir, 'settings.json'), required: false },
+  ];
+}
+
+/** Read one scope's settings file. Throws RefusalError (AC-UAW-13) for a REQUIRED scope that is
+ * absent, or for ANY scope that exists but is unreadable or does not parse as a JSON object.
+ * Absence of an OPTIONAL scope is not an error — the caller filters it out. */
+export function readScopeSettings(scope) {
+  let raw;
+  try {
+    raw = fs.readFileSync(scope.settingsPath, 'utf-8');
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      if (scope.required) {
+        throw new RefusalError(
+          `refusing: ${scope.name} scope settings file is absent (${scope.settingsPath})`,
+          scope.name,
+        );
+      }
+      return { ...scope, present: false, obj: null };
+    }
+    throw new RefusalError(
+      `refusing: ${scope.name} scope settings file is unreadable (${scope.settingsPath}): ${e.message}`,
+      scope.name,
+    );
+  }
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) throw new Error('not an object');
+  } catch (e) {
+    throw new RefusalError(
+      `refusing: ${scope.name} scope settings file does not parse as a JSON object (${scope.settingsPath}): ${e.message}`,
+      scope.name,
+    );
+  }
+  return { ...scope, present: true, obj };
+}
+
+/** Read every scope BEFORE any mutation — the snapshot AC-UAW-15(b) requires the rest of the run to
+ * be derived from. Throws on the first unresolvable scope (AC-UAW-13); returns only the scopes that
+ * are actually present. */
+export function snapshotScopes(scopes) {
+  return scopes.map(readScopeSettings).filter((s) => s.present);
+}
+
+function marketplaceEntryOf(settingsObj, marketplaceName) {
+  return (settingsObj.extraKnownMarketplaces || {})[marketplaceName];
+}
+
+function isEnabled(settingsObj, pluginKey) {
+  return Boolean((settingsObj.enabledPlugins || {})[pluginKey]);
+}
+
+function entryHasRef(entry) {
+  const src = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry.source : undefined;
+  return Boolean(src && typeof src === 'object' && Object.prototype.hasOwnProperty.call(src, 'ref'));
+}
+
+// ── AC-UAW-4 — the migration to the tagless steady state ───────────────────────────────────────
+
+/** Classify ONE scope's migration trigger. Returns null for a scope already in the tagless steady
+ * state (or one carrying no marketplace/plugin state at all). `isInstalled(scopeName)` is the
+ * installedness oracle for the THIRD disjunct — a run killed between `marketplace add` and
+ * `plugin install` leaves a tagless, enabled entry whose plugin is not actually installed there,
+ * which the tagless-entry shape alone would read as healthy. `isInstalled` returns `true`, `false`,
+ * or `null` (cannot be determined, e.g. an unreadable installed_plugins.json) — a `null` is NEVER
+ * silently folded into either boolean: it is surfaced as its own `indeterminate-installedness`
+ * trigger so the caller can report it rather than either skip a genuine orphan or force an
+ * unneeded reinstall silently. */
+export function classifyMigration(scopeSnap, { marketplaceName, pluginKey, isInstalled }) {
+  const entry = marketplaceEntryOf(scopeSnap.obj, marketplaceName);
+  const enabled = isEnabled(scopeSnap.obj, pluginKey);
+  if (entry !== undefined) {
+    if (entryHasRef(entry)) return { kind: 'tag-pinned' };
+    if (enabled) {
+      const installed = isInstalled(scopeSnap.name);
+      if (installed === null) return { kind: 'indeterminate-installedness' };
+      if (!installed) return { kind: 'orphaned-install' };
+    }
+    return null;
+  }
+  // entry absent — the shape a run SIGKILLed between its own `marketplace remove` and
+  // `marketplace add` leaves behind. Only relevant if the scope still believes the plugin enabled;
+  // otherwise this scope simply never had the marketplace registered, which is not this atom's job.
+  if (enabled) return { kind: 'interrupted-remove' };
+  return null;
+}
+
+/** The AC-UAW-4 action sequence for one trigger, PER SCOPE with that scope named explicitly on
+ * every action. NEVER emits `marketplace remove` when there is no entry to remove (interrupted-
+ * remove), and NEVER re-adds an entry that is already tagless (orphaned-install needs only
+ * `plugin install`). */
+export function migrationActions(trigger, { scope, marketplaceName, marketplaceRepo, pluginKey }) {
+  const actions = [];
+  // Nothing is actionable on uncertain data — surfaced to the caller as its own trigger kind
+  // instead (see classifyMigration), never silently resolved to an action here.
+  if (trigger.kind === 'indeterminate-installedness') return actions;
+  if (trigger.kind === 'tag-pinned') {
+    actions.push(['plugin', 'marketplace', 'remove', marketplaceName, '--scope', scope]);
+  }
+  if (trigger.kind === 'tag-pinned' || trigger.kind === 'interrupted-remove') {
+    // source argument carries NO `#` — the tagless steady state (AC-UAW-4's own text).
+    actions.push(['plugin', 'marketplace', 'add', marketplaceRepo, '--scope', scope]);
+  }
+  actions.push(['plugin', 'install', pluginKey, '--scope', scope]);
+  return actions;
+}
+
+/** AC-UAW-15(a) — restore what the platform's own `marketplace remove` is OBSERVED to blank.
+ * `before` is the scope's settings object captured BEFORE the first migration mutation; `after` is
+ * a fresh read taken once every migration action for this scope has run. Every top-level key
+ * `before` carried survives with its ORIGINAL value except `extraKnownMarketplaces` — the one key
+ * the migration exists to change — and `enabledPlugins` is unconditionally guaranteed to still name
+ * the plugin, regardless of what either side carried. */
+export function repairScopeSettings(before, after, pluginKey) {
+  const repaired = { ...after };
+  for (const key of Object.keys(before)) {
+    if (key === 'extraKnownMarketplaces') continue;
+    repaired[key] = before[key];
+  }
+  repaired.enabledPlugins = { ...(repaired.enabledPlugins || {}), [pluginKey]: true };
+  return repaired;
+}
+
+/** Run one scope's migration end to end: the actions, a fresh read-back, the repair, and the
+ * atomic write (reusing floorReconcile.mjs's temp-in-directory + rename — the same mechanism the
+ * reconcile path already trusts for exactly this hazard). Returns the argv arrays actually
+ * invoked, for the caller's preview/summary. */
+export function migrateScope({ scopeSnap, trigger, marketplaceName, marketplaceRepo, pluginKey, env, cwd, claudeBin }) {
+  const actions = migrationActions(trigger, {
+    scope: scopeSnap.name, marketplaceName, marketplaceRepo, pluginKey,
+  });
+  // R6: if an action throws PARTWAY (offline, a non-zero exit, ^C) after `marketplace remove` has
+  // already blanked this scope's settings, the repair below must STILL run before the failure
+  // propagates — otherwise the adopter is left both unregistered/disabled AND with the `before`
+  // snapshot this run captured now unused and lost. Whatever landed on disk (even a partial
+  // blank) is read back and repaired the same way a fully-successful run would; the original
+  // error is then rethrown so the caller still reports the run as failed.
+  let caught = null;
+  for (const args of actions) {
+    try {
+      runClaude(args, { env, cwd, claudeBin });
+    } catch (e) {
+      caught = e;
+      break;
+    }
+  }
+  if (fs.existsSync(scopeSnap.settingsPath)) {
+    const after = readScopeSettings(scopeSnap).obj;
+    const repaired = repairScopeSettings(scopeSnap.obj, after, pluginKey);
+    writeTargetAtomically(scopeSnap.settingsPath, repaired);
+  }
+  if (caught) throw caught;
+  return actions;
+}
+
+// ── AC-UAW-6 — the verdict comes from the manifest read-back, never from stdout ─────────────────
+
+export function readMarketplaceManifest(configDir, marketplaceName) {
+  const manifestPath = path.join(
+    configDir, 'plugins', 'marketplaces', marketplaceName, '.claude-plugin', 'marketplace.json',
+  );
+  try {
+    const doc = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    return { present: true, path: manifestPath, doc };
+  } catch {
+    return { present: false, path: manifestPath, doc: null };
+  }
+}
+
+export function pluginEntryOf(manifestDoc, pluginName) {
+  const plugins = Array.isArray(manifestDoc && manifestDoc.plugins) ? manifestDoc.plugins : [];
+  return plugins.find((p) => p && p.name === pluginName) || null;
+}
+
+/** Both `version` AND `source.sha` must move for the run to be reported `refreshed` — the v1.4.1
+ * scar made mechanical. The invoked CLI's own stdout carries no verdict; it is never consulted.
+ * A manifest that APPEARED where none existed before (a fresh CLAUDE_CONFIG_DIR's first resolve)
+ * counts as refreshed too — `before === null` must not read as "nothing moved" when in fact
+ * everything just did. Only "still nothing after, as before" is genuinely unrefreshed. */
+export function manifestRefreshed(before, after) {
+  if (!after) return false;
+  if (!before) return true;
+  const versionMoved = before.version !== after.version;
+  const shaMoved = (before.source && before.source.sha) !== (after.source && after.source.sha);
+  return versionMoved && shaMoved;
+}
+
+// ── AC-UAW-5 — every enabled scope, once, from the pre-migration snapshot ───────────────────────
+
+export function enabledScopeNames(snapshot, pluginKey) {
+  return snapshot.filter((s) => isEnabled(s.obj, pluginKey)).map((s) => s.name);
+}
+
+export function runPluginUpdate({ scope, pluginKey, env, cwd, claudeBin }) {
+  return runClaude(['plugin', 'update', pluginKey, '--scope', scope], { env, cwd, claudeBin });
+}
+
+// ── shared with cli/src/cleanup.mjs — the platform's own per-scope install registry ─────────────
+
+/** `<config-dir>/plugins/installed_plugins.json` — schema READ LIVE on the operator's own machine
+ * (see the sibling workspace-update-cleanup spec): `{"version": 2, "plugins": {"<key>": [record,
+ * ...]}}`, one record per scope, each carrying `installPath`/`version` and — for a project-scope
+ * record — a `projectPath`. No published schema contract; an unrecognised `version` (including a
+ * future 3) is treated as indeterminate by every caller, never parsed optimistically. */
+export function readInstalledPluginsRegistry(configDir) {
+  const registryPath = path.join(configDir, 'plugins', 'installed_plugins.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(registryPath, 'utf-8');
+  } catch {
+    return { ok: false, reason: 'installed plugin registry is absent', doc: null };
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: 'installed plugin registry does not parse as JSON', doc: null };
+  }
+  if (!doc || typeof doc !== 'object' || doc.version !== 2) {
+    return { ok: false, reason: 'installed plugin registry carries an unrecognised schema version', doc: null };
+  }
+  return { ok: true, reason: null, doc };
+}
+
+export function scopeRecordsFor(doc, pluginKey) {
+  const plugins = (doc && doc.plugins) || {};
+  return Array.isArray(plugins[pluginKey]) ? plugins[pluginKey] : [];
+}

package/src/update.mjs

@@ -0,0 +1,275 @@
+// update.mjs — the `npx update-agentic-workspace` orchestrator: argv -> preflight -> preview ->
+// Phase 1 (marketplace refresh + AC-UAW-4 migration) -> Phase 2 (plugin update) -> Phase 3
+// (cleanup, opt-in) -> Phase 4 (reinitialization: managed-file + permission-floor reconcile) ->
+// per-phase summary. No `claude` invocation lives in this file — every one goes through
+// pluginRefresh.mjs's single allowlisted spawn site (AC-UAW-14); this file only decides WHICH
+// invocations to make and WHEN, and performs Phase 4's file writes via the SAME never-clobber
+// machinery run.mjs's create path already uses (cli/src/reconcile.mjs, cli/src/floorReconcile.mjs).
+import fs from 'node:fs';
+import path from 'node:path';
+import { RefusalError, physicalResolve } from './util.mjs';
+import { loadMap, buildSettings, classifyDrift } from './permissionFloor.mjs';
+import { buildManagedFiles } from './scaffold.mjs';
+import { planManagedFiles, applyPlan } from './reconcile.mjs';
+import {
+  resolveTarget, readTarget, readTrackedRules, planAdditions, applyAdditions, writeTargetAtomically,
+} from './floorReconcile.mjs';
+import {
+  ALLOWED_CLAUDE_SUBCOMMANDS, resolveClaudeOnPath, runClaude,
+  defaultScopes, snapshotScopes, classifyMigration, migrationActions, migrateScope,
+  readMarketplaceManifest, pluginEntryOf, manifestRefreshed,
+  enabledScopeNames, runPluginUpdate,
+  readInstalledPluginsRegistry, scopeRecordsFor,
+} from './pluginRefresh.mjs';
+import { runCleanupPhase } from './cleanup.mjs';
+
+export { ALLOWED_CLAUDE_SUBCOMMANDS };
+
+/** The update entry point's OWN small flag table (Clarifications: "the update entry point carries
+ * its own small flag table, disjoint from the wizard's") — deliberately NOT cli/src/argv.mjs +
+ * QUESTION_TABLE, which is denied to the sibling cleanup atom and whose flag set is derived from
+ * the wizard's prompts, not this command's. `--cleanup` is the cleanup atom's own opt-in. */
+export function parseUpdateArgv(argv) {
+  const values = { cleanup: false, help: false };
+  for (const tok of argv) {
+    if (tok === '--cleanup') values.cleanup = true;
+    else if (tok === '--help') values.help = true;
+    else throw new RefusalError(`unknown flag: ${tok}`, tok);
+  }
+  return values;
+}
+
+/** AC-UAW-11 — a pure formatter, unit-tested on its own with exactly the three phases this atom
+ * itself defines (marketplace-refresh, plugin-update, reinitialization); the full orchestrator
+ * below may print a fourth `cleanup` row once the sibling atom's phase is wired in, which is a
+ * property of the RUNTIME composition, not of this formatter's own contract. */
+export function renderSummary(phases) {
+  const lines = ['Summary:'];
+  for (const p of phases) {
+    const verdict = p.verdict === 'skipped' ? `skipped: ${p.reason}` : p.verdict;
+    lines.push(`  [${p.name}] ${verdict}`);
+  }
+  return lines.join('\n');
+}
+
+function isInstalledInScopeFactory(registry, pluginKey, cwd) {
+  return (scopeName) => {
+    // `null` = cannot be determined. NEVER folded into `true` or `false` silently — an unreadable
+    // registry must not be read as "installed everywhere" (which would silently suppress a real
+    // orphaned-install healing) nor as "installed nowhere" (which would force an unneeded
+    // reinstall on every run); classifyMigration surfaces this as its own reported trigger kind.
+    if (!registry.ok) return null;
+    const records = scopeRecordsFor(registry.doc, pluginKey);
+    if (scopeName === 'user') return records.some((r) => r && !r.projectPath);
+    return records.some((r) => r && r.projectPath && path.resolve(r.projectPath) === path.resolve(cwd));
+  };
+}
+
+/** Run the update command end to end. Never throws — every failure path is caught and turned into
+ * a refusal-shaped exit 1 (or, for a bug, exit 1 with the error message), matching run.mjs's own
+ * contract. */
+export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output, spawnEnv = process.env }) {
+  const lines = [];
+  const print = (s) => {
+    lines.push(s);
+    output.write(`${s}\n`);
+  };
+
+  try {
+    let flags;
+    try {
+      flags = parseUpdateArgv(argv);
+    } catch (e) {
+      if (e instanceof RefusalError) {
+        print(`refused: ${e.message}`);
+        return { exitCode: 1, output: lines.join('\n') };
+      }
+      throw e;
+    }
+
+    if (flags.help) {
+      print([
+        'Usage: update-agentic-workspace [--cleanup] [--help]',
+        '',
+        '  --cleanup   Also prune superseded plugin-cache versions and remove a stale or',
+        '              duplicate marketplace registration (previewed either way; only',
+        '              removed under this flag). Off by default.',
+        '  --help      Show this help and exit.',
+      ].join('\n'));
+      return { exitCode: 0, output: lines.join('\n') };
+    }
+
+    const pins = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8')).foundry;
+    const marketplaceName = pins.marketplace_name;
+    const marketplaceRepo = pins.marketplace_repo;
+    const pluginKey = `${pins.plugin_name}@${pins.marketplace_name}`;
+
+    // ── AC-UAW-13(a): the claude executable must resolve on PATH before anything else runs ──────
+    // R8: the RESOLVED path is what the rest of the run spawns — never the bare name re-resolved
+    // against env.PATH a second time, which would leave this preflight proving something the
+    // actual spawn calls do not rely on.
+    const claudeBin = resolveClaudeOnPath(spawnEnv.PATH);
+    if (!claudeBin) {
+      throw new RefusalError('claude executable not found on PATH');
+    }
+
+    // ── AC-UAW-15(b): snapshot every scope BEFORE any mutation; AC-UAW-13(b) refuses here too ───
+    const scopes = defaultScopes({ cwd, configDir });
+    const snapshot = snapshotScopes(scopes);
+    const enabledScopes = enabledScopeNames(snapshot, pluginKey);
+
+    const registry = readInstalledPluginsRegistry(configDir);
+    const isInstalled = isInstalledInScopeFactory(registry, pluginKey, cwd);
+
+    const migrations = [];
+    const indeterminateInstalledness = [];
+    for (const scopeSnap of snapshot) {
+      const trigger = classifyMigration(scopeSnap, { marketplaceName, pluginKey, isInstalled });
+      if (!trigger) continue;
+      if (trigger.kind === 'indeterminate-installedness') {
+        indeterminateInstalledness.push(scopeSnap.name);
+      } else {
+        migrations.push({ scopeSnap, trigger });
+      }
+    }
+
+    // ── Phase 4's plan, computed but NOT applied yet — needed for the preview below ─────────────
+    const physicalRoot = physicalResolve(cwd);
+    const map = loadMap(path.join(pkgDir, 'permission-floor.json'));
+    const shippedSettings = buildSettings(map, pins);
+    const settingsBytes = Buffer.from(`${JSON.stringify(shippedSettings, null, 2)}\n`, 'utf-8');
+    const managedFiles = buildManagedFiles({
+      templatesDir: path.join(pkgDir, 'templates'),
+      physicalRoot,
+      projectName: path.basename(physicalRoot),
+      stageMode: 'lean',
+      settingsBytes,
+    });
+    const filePlan = planManagedFiles(managedFiles);
+
+    // This is a PREVIEW-ONLY computation: `.claude/settings.json` is also `project` scope's
+    // settings file, and Phase 1's migration (below) may write to that SAME path. Applying THIS
+    // captured plan verbatim in Phase 4 would silently clobber whatever Phase 1 just wrote —
+    // Phase 4 therefore re-reads and recomputes the floor plan fresh, right before it writes.
+    const floorTarget = resolveTarget(physicalRoot);
+    const previewFloorPlan = floorTarget.present
+      ? planAdditions({
+        findings: classifyDrift(map, readTrackedRules(readTarget(floorTarget.path)), {
+          pluginRootExpansion: [], unreadableOrigins: [], home: homeDir,
+        }),
+        map, settingsObj: readTarget(floorTarget.path), pins,
+      })
+      : null;
+
+    // ── AC-UAW-7: the preview, before the first `claude` invocation and the first write ─────────
+    const previewLines = ['The following claude invocations will be made:'];
+    for (const { scopeSnap, trigger } of migrations) {
+      for (const args of migrationActions(trigger, {
+        scope: scopeSnap.name, marketplaceName, marketplaceRepo, pluginKey,
+      })) {
+        previewLines.push(`  claude ${args.join(' ')}`);
+      }
+    }
+    previewLines.push(`  claude plugin marketplace update ${marketplaceName}`);
+    for (const scopeName of enabledScopes) {
+      previewLines.push(`  claude plugin update ${pluginKey} --scope ${scopeName}`);
+    }
+    // C3 / AC-UAW-7: the concrete cleanup candidate list cannot be known until Phases 1-2 have
+    // refreshed the manifest, so it cannot be named here by path — but the SHAPE of what it may
+    // do, and whether this run can act on it at all, is known up front and disclosed here rather
+    // than only in the phase's own later, post-mutation block.
+    const cleanupCacheRoot = path.join(configDir, 'plugins', 'cache', marketplaceName, pins.plugin_name);
+    previewLines.push(
+      `  cleanup phase (${flags.cleanup ? 'will remove what it finds' : 'report-only — nothing removed without --cleanup'}):`,
+    );
+    previewLines.push(`    may prune superseded versions under ${cleanupCacheRoot}`);
+    previewLines.push(`    may invoke claude plugin marketplace remove <name> --scope <scope> for a stale/duplicate registration`);
+    previewLines.push('The following workspace paths will be reconciled (never-clobber):');
+    for (const f of filePlan) previewLines.push(`  [${f.action}] ${f.relPath}`);
+    if (previewFloorPlan) {
+      previewLines.push(`  [permission-floor] would add allow=${previewFloorPlan.additions.allow.length}, ask=${previewFloorPlan.additions.ask.length}, deny=${previewFloorPlan.additions.deny.length}`);
+    } else {
+      previewLines.push('  [permission-floor] .claude/settings.json absent — left to the create path');
+    }
+    print(previewLines.join('\n'));
+
+    const env = { ...spawnEnv, CLAUDE_CONFIG_DIR: configDir };
+    const phases = [];
+
+    // ── Phase 1: marketplace refresh ─────────────────────────────────────────────────────────────
+    let anyMigrated = false;
+    for (const { scopeSnap, trigger } of migrations) {
+      migrateScope({ scopeSnap, trigger, marketplaceName, marketplaceRepo, pluginKey, env, cwd, claudeBin });
+      anyMigrated = true;
+    }
+    const manifestBefore = readMarketplaceManifest(configDir, marketplaceName);
+    const beforeEntry = manifestBefore.present ? pluginEntryOf(manifestBefore.doc, pins.plugin_name) : null;
+    runClaude(['plugin', 'marketplace', 'update', marketplaceName], { env, cwd, claudeBin });
+    const manifestAfter = readMarketplaceManifest(configDir, marketplaceName);
+    const afterEntry = manifestAfter.present ? pluginEntryOf(manifestAfter.doc, pins.plugin_name) : null;
+    const refreshed = manifestRefreshed(beforeEntry, afterEntry);
+    // R (risk, not block): an unreadable installed_plugins.json must not silently suppress the
+    // orphaned-install trigger for a tagless, enabled scope — surfaced here rather than folded
+    // into a plain 'changed'/'already current' verdict.
+    const marketplaceRefreshVerdict = anyMigrated || refreshed ? 'changed' : 'already current';
+    phases.push(
+      indeterminateInstalledness.length > 0
+        ? {
+          name: 'marketplace-refresh',
+          verdict: 'skipped',
+          reason: `installedness could not be determined for scope(s) ${indeterminateInstalledness.join(', ')} (installed plugin registry unreadable) — the orphaned-install trigger was not evaluated there; every other migration still ran (${marketplaceRefreshVerdict})`,
+        }
+        : { name: 'marketplace-refresh', verdict: marketplaceRefreshVerdict },
+    );
+
+    // ── Phase 2: plugin update, once per PRE-migration-snapshot enabled scope (AC-UAW-15b) ──────
+    for (const scopeName of enabledScopes) {
+      runPluginUpdate({ scope: scopeName, pluginKey, env, cwd, claudeBin });
+    }
+    phases.push({ name: 'plugin-update', verdict: refreshed ? 'changed' : 'already current' });
+
+    // ── Phase 3: cleanup (sibling atom; always previewed, only acts under --cleanup) ────────────
+    const cleanupScopeDescriptors = scopes; // same {name, settingsPath} pairs, unresolved-required
+    const cleanupResult = runCleanupPhase({
+      cleanupFlag: flags.cleanup,
+      configDir, marketplaceName, marketplaceRepo, pluginName: pins.plugin_name, pluginKey,
+      scopeDescriptors: cleanupScopeDescriptors, env, cwd, print, claudeBin,
+    });
+    phases.push({ name: 'cleanup', verdict: cleanupResult.verdict, reason: cleanupResult.reason });
+
+    // ── Phase 4: reinitialization — managed files, then the additive floor reconcile ───────────
+    applyPlan(filePlan);
+    // Recomputed FRESH from disk — never the preview-time `previewFloorPlan` — because Phase 1's
+    // migration may have just rewritten this exact file (project scope's settings.json IS the
+    // floor-reconcile target). Applying a stale pre-migration plan here would silently clobber it.
+    let floorPlan = null;
+    const freshFloorTarget = resolveTarget(physicalRoot);
+    if (freshFloorTarget.present) {
+      const settingsObj = readTarget(freshFloorTarget.path);
+      const findings = classifyDrift(map, readTrackedRules(settingsObj), {
+        pluginRootExpansion: [], unreadableOrigins: [], home: homeDir,
+      });
+      floorPlan = planAdditions({ findings, map, settingsObj, pins });
+      floorPlan.settingsObj = settingsObj;
+      if (floorPlan.total > 0) {
+        writeTargetAtomically(freshFloorTarget.path, applyAdditions(settingsObj, floorPlan, { map, pins }));
+      }
+    }
+    const anyCreated = filePlan.some((f) => f.action === 'create');
+    const anyFloorAdded = Boolean(floorPlan && floorPlan.total > 0);
+    phases.push({ name: 'reinitialization', verdict: anyCreated || anyFloorAdded ? 'changed' : 'already current' });
+
+    print('');
+    print(renderSummary(phases));
+
+    const anyDrifted = filePlan.some((f) => f.action === 'drifted');
+    return { exitCode: anyDrifted ? 2 : 0, output: lines.join('\n') };
+  } catch (e) {
+    if (e instanceof RefusalError) {
+      print(`refused: ${e.message}`);
+      return { exitCode: 1, output: lines.join('\n') };
+    }
+    print(`error: ${e.stack || e.message}`);
+    return { exitCode: 1, output: lines.join('\n') };
+  }
+}