create-agentic-workspace 0.18.1 → 0.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-workspace",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "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",
@@ -25,6 +25,7 @@
     "templates",
     "permission-floor.json",
     "retired-artifacts.json",
+    "python-requirements.json",
     "package.json",
     "README.md"
   ],
@@ -35,7 +36,7 @@
     "marketplace_name": "agentic-foundry",
     "marketplace_repo": "lukasrepublic/agentic-foundry",
     "plugin_name": "foundry",
-    "plugin_version": "1.18.1",
+    "plugin_version": "1.18.2",
     "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.18.1",
+  "generated_for_plugin_version": "1.18.2",
   "entries": [
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-acceptance-contract-validate.py:*)",

package/python-requirements.json

@@ -0,0 +1,21 @@
+{
+  "//": "Third-party Python modules the plugin's scripts import, with the exact versions CI tests (requirements-dev.txt). Kept equal to the plugin's requirements.txt and to the scripts' actual imports by tests/test_python_runtime_deps.py. The updater installs a missing one into the user site; it never upgrades an existing install.",
+  "requirements": [
+    {
+      "module": "yaml",
+      "requirement": "PyYAML==6.0.3"
+    },
+    {
+      "module": "jsonschema",
+      "requirement": "jsonschema==4.25.0"
+    }
+  ],
+  "//constraints": "Exact pins for jsonschema's transitive dependencies (pip -c), so the updater installs exactly what CI tests; equal to requirements-dev.txt by test.",
+  "constraints": [
+    "attrs==26.1.0",
+    "jsonschema-specifications==2025.9.1",
+    "referencing==0.37.0",
+    "rpds-py==0.30.0",
+    "typing-extensions==4.16.0"
+  ]
+}

package/retired-artifacts.json

@@ -27,6 +27,8 @@
     { "path": ".claude/resume", "kind": "dir", "retired_in": "0.25.0", "reason": "the bespoke resume store; native --resume replaced it" },
     { "path": ".claude/logs", "kind": "dir", "retired_in": "1.10.0", "reason": "the retired dispatcher's logs" },
     { "path": ".claude/session-learnings", "kind": "dir", "retired_in": "1.0.0", "reason": "the old learnings location; the partition is .foundry/session-learnings" },
-    { "path": ".claude/hooks/*-exec-guard.sh", "kind": "file", "exclude_prefix": "foundry-", "retired_in": "1.8.0", "reason": "the retired session-context framework's cloud-cli exec guard; a hook still named by a command in .claude/settings*.json is refused, never removed" }
+    { "path": ".claude/hooks/*-exec-guard.sh", "kind": "file", "exclude_prefix": "foundry-", "retired_in": "1.8.0", "reason": "the retired session-context framework's cloud-cli exec guard; a hook still named by a command in .claude/settings*.json is refused, never removed" },
+    { "path": ".foundry/admission-ledger.jsonl", "kind": "file", "retired_in": "0.24.0", "reason": "the retired ADL admission gate's ledger; nothing reads it" },
+    { "path": ".claude/hooks/foundry-subagent-statusline.sh", "kind": "file", "retired_in": "1.18.2", "reason": "the subagent status line is retired (the status line runs for the root session only); removed only once no settings file names it" }
   ]
 }

package/src/cleanup.mjs

@@ -1,9 +1,9 @@
-// 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.
+// cleanup.mjs — Phase 3 (opt-in, `--cleanup`) of `npx update-agentic-workspace`: remove a stale or
+// duplicate marketplace registration, and REPORT superseded plugin-cache versions. Since v1.18.2 a
+// cache version is never deleted (a running session may still use it — see the note above
+// runCleanupPhase's report), so this module carries no recursive delete. Fail-closed throughout:
+// AC-UWC-4 skips on any indeterminate input, and AC-UWC-9 refuses 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';
@@ -118,14 +118,13 @@ export function planCachePrune({ pluginCacheDir, liveVersions }) {
   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 });
-  }
-}
+// v1.18.2: superseded plugin-cache versions are NEVER removed. A running Claude Code session keeps
+// the version it started with — its hooks resolve through ${CLAUDE_PLUGIN_ROOT} and the plugin's
+// bin/ is on its PATH — so deleting a version the registry no longer names broke every live session
+// still on it ("Plugin directory does not exist … run /plugin to reinstall" on every hook, and a
+// dead PATH entry). Measured on the operator's own session and reported by an adopter ("keeps
+// crashing since update"). The registry cannot tell which versions running sessions hold, and an
+// old version costs only disk, so the prune is retired; planCachePrune still lists them (report).
 
 // ── AC-UWC-7 — a stale or duplicate registration that no scope enables ──────────────────────────
 
@@ -272,14 +271,14 @@ export function runCleanupPhase({
   // 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)}`);
+    print(removableRegs.length > 0 ? 'cleanup: the following would be removed:' : 'cleanup: nothing to remove.');
+    for (const name of candidates) print(`  [cache] ${path.join(pluginCacheDir, name)} — superseded; KEPT (a running session may still use it)`);
     for (const name of removableRegs) print(`  [marketplace registration] ${name}`);
   } else {
     print('cleanup: nothing to remove.');
   }
 
-  const anything = candidates.length > 0 || removableRegs.length > 0;
+  const anything = removableRegs.length > 0;
 
   if (!cleanupFlag) {
     // AC-UWC-6/-7 — report-only: zero filesystem-removal calls AND zero `claude` invocations.
@@ -291,13 +290,12 @@ export function runCleanupPhase({
     };
   }
 
-  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,
+    candidateVersions: candidates, prunedVersions: [], removedRegistrations: removableRegs,
   };
 }

package/src/manifestTrueUp.mjs

@@ -0,0 +1,93 @@
+// v1.18.2 — the upgrade TRUES UP release manifests to the current contract (operator directive,
+// 2026-09-26: "whatever artifacts are no longer compatible with a new version must be fixed by the
+// updater … not dumped on a user as a surprise"). 41 of 84 real `.foundry/releases/*/release.yaml`
+// failed the loader. The loader now reads every harmless legacy shape (bookkeeping fields, dotted
+// ids, legacy state names, a missing description); this module rewrites the two that carry MEANING on
+// disk, so the file says what the machinery reads:
+//   * a legacy `state:` value -> the current vocabulary (in_progress/partially-* -> active, released/
+//     done -> completed);
+//   * a missing `description:` -> one line naming the release id, inserted after `id:`.
+// Edits are LINE-LEVEL on top-level keys only (column 0), so every comment and every other byte is
+// preserved (some manifests carry over 1,000 comment lines; a YAML round-trip would drop them all).
+// Idempotent; symlinks are never followed; anything it cannot rewrite safely is left alone and listed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { confinedJoin } from './util.mjs';
+
+export const STATE_TRUE_UP = Object.freeze({
+  in_progress: 'active', 'in-progress': 'active', 'partially-released': 'active', 'partially-merged': 'active',
+  released: 'completed', done: 'completed',
+});
+
+const STATE_LINE = /^state:[ \t]*(["']?)([A-Za-z_-]+)\1([ \t]*(?:#.*)?)$/m;
+const ID_LINE = /^id:[ \t]*(["']?)([a-z0-9.-]+)\1[ \t]*(?:#.*)?$/m;
+const DESCRIPTION_LINE = /^description:/m;
+
+/** The new text for one manifest, and what changed; `changes` empty when nothing applies. */
+export function trueUpText(text) {
+  let out = text;
+  const changes = [];
+  const sm = STATE_LINE.exec(out);
+  if (sm && Object.prototype.hasOwnProperty.call(STATE_TRUE_UP, sm[2])) {
+    const to = STATE_TRUE_UP[sm[2]];
+    out = out.replace(STATE_LINE, `state: ${to}${sm[3]}`);
+    changes.push(`state ${sm[2]} -> ${to}`);
+  }
+  const im = ID_LINE.exec(out);
+  if (im && !DESCRIPTION_LINE.test(out)) {
+    const at = im.index + im[0].length;
+    out = `${out.slice(0, at)}\ndescription: "${im[2]}"${out.slice(at)}`;
+    changes.push('description added');
+  }
+  return { text: out, changes };
+}
+
+/** Plan over every `.foundry/releases/<id>/release.yaml` of the workspace. */
+export function planManifestTrueUp({ physicalRoot }) {
+  const rows = [];
+  const dir = confinedJoin(physicalRoot, '.foundry/releases');
+  const st = dir ? fs.lstatSync(dir, { throwIfNoEntry: false }) : null;
+  if (!st || !st.isDirectory() || st.isSymbolicLink()) return { rows, applied: false };
+  for (const name of fs.readdirSync(dir).sort()) {
+    const rel = path.posix.join('.foundry/releases', name, 'release.yaml');
+    const abs = confinedJoin(physicalRoot, rel);
+    if (!abs) continue;
+    const fst = fs.lstatSync(abs, { throwIfNoEntry: false });
+    if (!fst || !fst.isFile()) continue; // a symlink or a missing manifest is never touched
+    let text;
+    try { text = fs.readFileSync(abs, 'utf-8'); } catch { continue; }
+    const { text: next, changes } = trueUpText(text);
+    if (changes.length > 0) rows.push({ rel, abs, changes, next, before: text });
+  }
+  return { rows, applied: false };
+}
+
+/** Atomic per-file write (temp + rename), re-checking the bytes did not change since the plan. */
+export function applyManifestTrueUp(plan) {
+  const written = [];
+  for (const r of plan.rows) {
+    let cur;
+    try { cur = fs.readFileSync(r.abs, 'utf-8'); } catch { continue; }
+    if (cur !== r.before) continue; // changed since the plan: left alone
+    // re-check at apply time (security review): still a regular, non-symlinked file inside the root
+    const fst = fs.lstatSync(r.abs, { throwIfNoEntry: false });
+    if (!fst || !fst.isFile()) continue;
+    const tmp = path.join(path.dirname(r.abs), `.release.yaml.${process.pid}.tmp`);
+    let fd;
+    try { fd = fs.openSync(tmp, 'wx', 0o644); } catch { continue; } // a stale temp from a crashed run: skip this row
+    try { fs.writeFileSync(fd, r.next); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    try {
+      fs.renameSync(tmp, r.abs);
+      written.push(r.rel);
+    } catch {
+      try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+    }
+  }
+  plan.applied = true;
+  plan.written = written;
+  return plan;
+}
+
+export function renderManifestTrueUpRows(plan) {
+  return plan.rows.map((r) => `  [${plan.applied ? 'trued-up' : 'would true up'}] ${r.rel} — ${r.changes.join('; ')}`);
+}

package/src/pythonDeps.mjs

@@ -0,0 +1,130 @@
+// v1.18.2: the plugin's scripts import two third-party Python packages (jsonschema, PyYAML), and
+// nothing ever put them on the machine: the plugin declared no runtime dependency, the updater
+// never checked, and a fresh agent container (whose image did not carry them) failed its doctor and
+// every contract script. This phase makes the interpreter the scripts run under (`python3` on PATH)
+// able to import every declared module, installing ONLY what is missing — an existing install is
+// never upgraded or replaced — at the exact versions CI tests (`python-requirements.json`, kept equal
+// to the plugin's `requirements.txt` by test).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/** A spawnSync-shaped result from the CLI's closed spawn surface (the named import above); never throws. */
+function runPython(bin, args, opts) {
+  try {
+    return { status: 0, stdout: execFileSync(bin, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] }), stderr: '' };
+  } catch (e) {
+    if (typeof e.status === 'number') return { status: e.status, stdout: String(e.stdout || ''), stderr: String(e.stderr || '') };
+    return { error: e, status: null, stdout: '', stderr: '' };
+  }
+}
+
+/** The declared runtime requirements shipped with this package: [{ module, requirement }], with the
+ * exact transitive pins attached as `.constraints` (pip -c) — the set CI tests (requirements-dev.txt). */
+export function loadPythonRequirements(pkgDir) {
+  const doc = JSON.parse(fs.readFileSync(path.join(pkgDir, 'python-requirements.json'), 'utf-8'));
+  const reqs = doc.requirements;
+  Object.defineProperty(reqs, 'constraints', { value: doc.constraints || [], enumerable: false });
+  return reqs;
+}
+
+// v1.18.2 security review (Risk 1): never run python in the workspace — `-c`/`-m` put the cwd first
+// on sys.path, so a stray json.py/pip/ there would run (and a `yaml/` dir would fake an install).
+// A neutral cwd plus PYTHONSAFEPATH (3.11+). Not `-I`: that also drops the user site we install into.
+function childOpts(env, timeout) {
+  return { env: { ...env, PYTHONSAFEPATH: '1' }, cwd: os.tmpdir(), encoding: 'utf-8', timeout };
+}
+
+// Prints JSON: the interpreter, whether it is a venv, and which declared modules cannot be found.
+// find_spec (no import) so a broken package's import-time side effects never run here.
+const PROBE = [
+  'import importlib.util, json, sys',
+  'mods = sys.argv[1:]',
+  'print(json.dumps({"python": sys.executable, "version": "%d.%d" % sys.version_info[:2],',
+  '  "venv": sys.prefix != sys.base_prefix,',
+  '  "missing": [m for m in mods if importlib.util.find_spec(m) is None]}))',
+].join('\n');
+
+/** Probe `python3` for the declared modules. `{ ok:false, reason }` when python3 cannot run. */
+export function probePythonDeps(requirements, { env = process.env, python = 'python3', spawn = runPython } = {}) {
+  const r = spawn(python, ['-c', PROBE, ...requirements.map((q) => q.module)], childOpts(env, 30000));
+  if (r.error || r.status !== 0) {
+    return { ok: false, reason: r.error ? `${python} not runnable (${r.error.code || r.error.message})` : `${python} probe exited ${r.status}` };
+  }
+  try {
+    const out = JSON.parse(String(r.stdout).trim().split('\n').pop());
+    const missing = requirements.filter((q) => out.missing.includes(q.module));
+    return { ok: true, python: out.python, version: out.version, venv: out.venv, missing };
+  } catch {
+    return { ok: false, reason: `${python} probe output unreadable` };
+  }
+}
+
+/** The pip argv for installing `missing`: `--user` outside a venv (a venv has no user site). */
+export function pipArgs(missing, { venv, breakSystem = false, constraintsFile = null }) {
+  // --only-binary: no sdist build backend ever runs on the operator's machine (review Risk 2).
+  const args = ['-m', 'pip', 'install', '--disable-pip-version-check', '--quiet', '--no-input', '--only-binary=:all:'];
+  if (!venv) args.push('--user');
+  if (breakSystem) args.push('--break-system-packages');
+  if (constraintsFile) args.push('-c', constraintsFile);
+  return [...args, ...missing.map((q) => q.requirement)];
+}
+
+function writeConstraints(requirements) {
+  const lines = requirements.constraints || [];
+  if (lines.length === 0) return null;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'foundry-pydeps-'));
+  const file = path.join(dir, 'constraints.txt');
+  fs.writeFileSync(file, lines.join('\n') + '\n', { mode: 0o600 });
+  return file;
+}
+
+/**
+ * Install what is missing, then re-probe. A PEP 668 "externally-managed-environment" refusal is
+ * retried once with --break-system-packages: with --user that writes only the user site (~/.local
+ * or ~/Library/Python), never the system interpreter's own packages. Never throws.
+ * Returns { verdict: 'already current'|'changed'|'failed'|'skipped', installed, missing, reason }.
+ */
+export function ensurePythonDeps(requirements, { env = process.env, python = 'python3', spawn = runPython, dryRun = false } = {}) {
+  const before = probePythonDeps(requirements, { env, python, spawn });
+  if (!before.ok) return { verdict: 'skipped', installed: [], missing: requirements.map((q) => q.module), reason: before.reason };
+  if (before.missing.length === 0) return { verdict: 'already current', installed: [], missing: [], python: before.python };
+  if (dryRun) {
+    return { verdict: 'would change', installed: [], missing: before.missing.map((q) => q.module), python: before.python };
+  }
+  let constraintsFile = null;
+  try { constraintsFile = writeConstraints(requirements); } catch { constraintsFile = null; }
+  let overrode = false;
+  let r = spawn(python, pipArgs(before.missing, { venv: before.venv, constraintsFile }), childOpts(env, 600000));
+  const out = `${r.stdout || ''}${r.stderr || ''}`;
+  if (r.status !== 0 && /externally-managed-environment/.test(out)) {
+    overrode = true;
+    r = spawn(python, pipArgs(before.missing, { venv: before.venv, breakSystem: true, constraintsFile }), childOpts(env, 600000));
+  }
+  if (constraintsFile) { try { fs.unlinkSync(constraintsFile); fs.rmdirSync(path.dirname(constraintsFile)); } catch { /* best effort */ } }
+  const after = probePythonDeps(requirements, { env, python, spawn });
+  const still = after.ok ? after.missing.map((q) => q.module) : before.missing.map((q) => q.module);
+  const installed = before.missing.map((q) => q.module).filter((m) => !still.includes(m));
+  if (still.length === 0) return { verdict: 'changed', installed, missing: [], python: before.python, pep668Overridden: overrode };
+  const tail = `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').slice(-1)[0] || `exit ${r.status}`;
+  const noPip = /No module named pip/.test(`${r.stdout || ''}${r.stderr || ''}`);
+  return {
+    verdict: 'failed', installed, missing: still, python: before.python,
+    reason: noPip
+      ? `pip is not available for ${before.python} — install it (Debian/Ubuntu: apt-get install python3-pip, or python3-${still.includes('yaml') ? 'yaml' : 'jsonschema'} directly), then re-run`
+      : `pip install failed: ${tail}`,
+  };
+}
+
+/** One output row per outcome, in the updater's `[verdict] subject — detail` shape. */
+export function renderPythonDepsRow(result, requirements) {
+  const want = requirements.map((q) => q.requirement).join(', ');
+  switch (result.verdict) {
+    case 'already current': return `  [ok] python deps: ${requirements.map((q) => q.module).join(', ')} importable (${result.python})`;
+    case 'would change': return `  [would install] python deps: ${result.missing.join(', ')} for ${result.python} (${want}; user site, missing only)`;
+    case 'changed': return `  [installed] python deps: ${result.installed.join(', ')} for ${result.python} (user site${result.pep668Overridden ? ', PEP 668 overridden' : ''})`;
+    case 'skipped': return `  [skipped] python deps: ${result.reason}`;
+    default: return `  [failed] python deps: still missing ${result.missing.join(', ')} — ${result.reason}`;
+  }
+}

package/src/statuslineWiring.mjs

@@ -27,7 +27,15 @@ import { resolveTarget, readTarget, writeTargetAtomically } from './floorReconci
 export const MARKER = 'feat-foundry-init-statusline-wrapper';
 export const WRAPPERS = Object.freeze([
   { template: 'foundry-statusline.sh', rel: '.claude/hooks/foundry-statusline.sh', key: 'statusLine' },
-  { template: 'foundry-subagent-statusline.sh', rel: '.claude/hooks/foundry-subagent-statusline.sh', key: 'subagentStatusLine' },
+]);
+
+// v1.18.2 (operator directive, 2026-09-26): the status line is for the ROOT session in a visual
+// terminal only — never subagents. v1.17.0–v1.18.1 also wired `subagentStatusLine`, which Claude Code
+// runs once per running subagent on every refresh; with the renderer's git/python work that fed the
+// process storm that crashed adopters' sessions. The key is RETIRED: removed wherever its command is
+// exactly the one this framework wrote (an operator's own value is never touched), and never added.
+export const RETIRED_KEYS = Object.freeze([
+  { key: 'subagentStatusLine', rel: '.claude/hooks/foundry-subagent-statusline.sh' },
 ]);
 
 export function desiredSettingsValue(rel) {
@@ -68,6 +76,12 @@ export function planStatuslineWiring({ physicalRoot, templatesDir }) {
     const unverifiable = fileRow && (fileRow.action === 'kept' || fileRow.action === 'refused');
     plan.keys.push({ key: w.key, action: present ? 'already-wired' : (unverifiable ? 'not-wired' : 'wired') });
   }
+  for (const r of RETIRED_KEYS) {
+    const v = settings[r.key];
+    if (v && typeof v === 'object' && v.command === desiredSettingsValue(r.rel).command) {
+      plan.keys.push({ key: r.key, action: 'unwired' });
+    }
+  }
   return plan;
 }
 
@@ -99,13 +113,19 @@ export function applyStatuslineWiring(plan) {
     }
   }
   const toAdd = plan.keys.filter((k) => k.action === 'wired');
-  if (toAdd.length > 0) {
+  const toRemove = plan.keys.filter((k) => k.action === 'unwired');
+  if (toAdd.length > 0 || toRemove.length > 0) {
     const settings = readTarget(plan.settingsPath);
     for (const k of toAdd) {
       if (Object.prototype.hasOwnProperty.call(settings, k.key)) continue; // raced in since plan
       const w = WRAPPERS.find((x) => x.key === k.key);
       settings[k.key] = desiredSettingsValue(w.rel);
     }
+    for (const k of toRemove) {
+      const r = RETIRED_KEYS.find((x) => x.key === k.key);
+      const v = settings[k.key];
+      if (v && typeof v === 'object' && v.command === desiredSettingsValue(r.rel).command) delete settings[k.key];
+    }
     writeTargetAtomically(plan.settingsPath, settings);
   }
   plan.applied = true;
@@ -126,6 +146,8 @@ export function renderStatuslineRows(plan) {
   const notWired = plan.keys.filter((k) => k.action === 'not-wired').map((k) => k.key);
   if (wired.length) rows.push(`  [statusline] wired ${wired.join(', ')} in .claude/settings.json`);
   if (already.length) rows.push(`  [statusline] already wired: ${already.join(', ')} (existing value kept)`);
+  const unwired = plan.keys.filter((k) => k.action === 'unwired').map((k) => k.key);
+  if (unwired.length) rows.push(`  [statusline] ${plan.applied ? 'removed' : 'would remove'} ${unwired.join(', ')} from .claude/settings.json (the status line is for the root session only)`);
   if (notWired.length) rows.push(`  [statusline] NOT wired: ${notWired.join(', ')} — the wrapper at that path is not one this framework wrote (kept or refused); verify it, then wire by hand`);
   return rows;
 }
@@ -133,6 +155,6 @@ export function renderStatuslineRows(plan) {
 export function statuslineChanged(plan) {
   return Boolean(plan && plan.applied && (
     plan.files.some((f) => f.action === 'create' || f.action === 'converged')
-    || plan.keys.some((k) => k.action === 'wired')
+    || plan.keys.some((k) => k.action === 'wired' || k.action === 'unwired')
   ));
 }

package/src/update.mjs

@@ -17,6 +17,7 @@ import {
 } from './floorReconcile.mjs';
 import { reconcileGitignorePlan, applyGitignorePlan, renderGitignoreRow } from './gitignoreReconcile.mjs';
 import { planAmendmentsBackfill, applyAmendmentsBackfill, renderAmendmentsRow } from './amendmentsBackfill.mjs';
+import { planManifestTrueUp, applyManifestTrueUp, renderManifestTrueUpRows } from './manifestTrueUp.mjs';
 import { buildUpgradeReport, writeUpgradeReport, installedVersionBefore, versionOrNull, NEXT_LINE } from './upgradeReport.mjs';
 import { planStatuslineWiring, applyStatuslineWiring, renderStatuslineRows, statuslineChanged } from './statuslineWiring.mjs';
 import { loadRetiredCatalogue, planRetiredArtifacts, applyRetiredArtifacts, renderRetiredArtifactRows } from './retiredArtifacts.mjs';
@@ -29,6 +30,7 @@ import {
   readInstalledPluginsRegistry, scopeRecordsFor,
 } from './pluginRefresh.mjs';
 import { runCleanupPhase } from './cleanup.mjs';
+import { loadPythonRequirements, ensurePythonDeps, renderPythonDepsRow } from './pythonDeps.mjs';
 
 export { ALLOWED_CLAUDE_SUBCOMMANDS };
 
@@ -266,6 +268,8 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     // re-plans fresh from disk before it writes.
     const previewAmendmentsRow = renderAmendmentsRow(planAmendmentsBackfill({ physicalRoot }));
     if (previewAmendmentsRow) previewLines.push(previewAmendmentsRow);
+    // v1.18.2: release manifests trued up to the current contract (preview only here)
+    previewLines.push(...renderManifestTrueUpRows(planManifestTrueUp({ physicalRoot })));
     // statusline-wiring (AC-SLW-1/-2): PREVIEW-ONLY rows; Phase 4 re-plans fresh from disk.
     previewLines.push(...renderStatuslineRows(planStatuslineWiring({ physicalRoot, templatesDir })));
     // retired-artifacts (hotfix-v1.17.4, ER #236): PREVIEW-ONLY rows; Phase 4 re-plans fresh from disk.
@@ -280,6 +284,9 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
       if (lp.plan && lp.plan.total > 0) previewLines.push(`  [permission-floor] ${lp.rel}: would retire allow=${lp.plan.retirements.allow.length}, ask=${lp.plan.retirements.ask.length}, deny=${(lp.plan.retirements.deny || []).length} (never adds)`);
       else if (lp.error) previewLines.push(`  [permission-floor] ${lp.rel}: would not be reconciled (${lp.error})`);
     }
+    // v1.18.2: python deps — the preview only probes (nothing installed before the first write).
+    const pythonRequirements = loadPythonRequirements(pkgDir);
+    previewLines.push(renderPythonDepsRow(ensurePythonDeps(pythonRequirements, { env: spawnEnv, python: spawnEnv.FOUNDRY_PYTHON || 'python3', dryRun: true }), pythonRequirements));
     print(previewLines.join('\n'));
     if (flags.dryRun) {
       print('');
@@ -337,6 +344,12 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
       ...(installedAfter ? {} : { reason: 'installed version unreadable from installed_plugins.json' }),
     });
 
+    // ── Phase 2b (v1.18.2): the plugin's Python runtime deps — install only what is missing ──────
+    // FOUNDRY_PYTHON names another interpreter (a venv's), and lets tests keep pip off the machine.
+    const pythonDeps = ensurePythonDeps(pythonRequirements, { env: spawnEnv, python: spawnEnv.FOUNDRY_PYTHON || 'python3' });
+    print(renderPythonDepsRow(pythonDeps, pythonRequirements));
+    phases.push({ name: 'python-deps', verdict: pythonDeps.verdict, ...(pythonDeps.reason ? { reason: pythonDeps.reason } : {}) });
+
     // ── Phase 3: cleanup (sibling atom; always previewed, only acts under --cleanup) ────────────
     const cleanupScopeDescriptors = scopes; // same {name, settingsPath} pairs, unresolved-required
     const cleanupResult = runCleanupPhase({
@@ -397,6 +410,10 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     for (const rel of amendmentsPlan.writtenPaths || []) wrote(rel, 'amendments-backfill');
     const amendmentsRow = renderAmendmentsRow(amendmentsPlan);
     if (amendmentsRow) print(amendmentsRow);
+    // v1.18.2: release manifests trued up to the current contract — re-planned fresh from disk
+    const trueUpPlan = applyManifestTrueUp(planManifestTrueUp({ physicalRoot }));
+    for (const rel of trueUpPlan.written || []) wrote(rel, 'manifest-true-up');
+    for (const row of renderManifestTrueUpRows(trueUpPlan)) print(row);
 
     const anyCreated = filePlan.some((f) => f.action === 'create');
     const anyFloorAdded = Boolean(floorPlan && floorPlan.total > 0)
@@ -447,7 +464,7 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
 
     phases.push({
       name: 'reinitialization',
-      verdict: anyCreated || anyFloorAdded || anyGitignoreChanged || anyAmendmentsBackfilled
+      verdict: anyCreated || anyFloorAdded || anyGitignoreChanged || anyAmendmentsBackfilled || (trueUpPlan.written || []).length > 0
         || statuslineChanged(statuslinePlan) || retiredRemoved > 0 || localRetired > 0 ? 'changed' : 'already current',
     });
 
@@ -459,7 +476,7 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     // named in the LAST line so the operator's next step is never a guess.
     const report = buildUpgradeReport({
       installedBefore, installedAfter, afterEntry, toPluginVersion: pins.plugin_version, phases, filePlan, amendmentsPlan,
-      written, removed, configDir, hostname: os.hostname(),
+      written, removed, configDir, hostname: os.hostname(), pythonDeps,
       updaterVersion, coreVersion: corePkg.version, updaterPluginVersion: pins.plugin_version,
       retiredArtifacts: { present: retiredPlan.rows.filter((r) => r.state === 'stale').map((r) => r.relPath), removed: retiredRemoved, refused: retiredPlan.refused },
       localRetired,
@@ -481,7 +498,9 @@ export async function runUpdate(argv, { cwd, configDir, homeDir, pkgDir, output,
     // into "the update failed" for the whole run (run.mjs makes the identical choice; see its own
     // comment on `gitignoreRefused`).
     const gitignoreRefused = Boolean(freshGitignorePlan && freshGitignorePlan.action === 'refused');
-    return { exitCode: anyDrifted || gitignoreRefused ? 2 : 0, output: lines.join('\n') };
+    // v1.18.2: a python dep that could not be installed leaves the plugin's scripts broken — exit 2
+    // (attention needed; the row above names what is missing and why), like a refused gitignore.
+    return { exitCode: anyDrifted || gitignoreRefused || pythonDeps.verdict === 'failed' ? 2 : 0, output: lines.join('\n') };
   } catch (e) {
     if (e instanceof RefusalError) {
       print(`refused: ${e.message}`);

package/src/upgradeReport.mjs

@@ -33,6 +33,7 @@ export function buildUpgradeReport({
   installedBefore = null, installedAfter = null, afterEntry, toPluginVersion, phases, filePlan, amendmentsPlan, now = new Date(),
   updaterVersion = null, coreVersion = null, updaterPluginVersion = null,
   retiredArtifacts = null, localRetired = 0, written = [], removed = [], configDir = null, hostname = null,
+  pythonDeps = null,
 }) {
   const seedRow = (filePlan || []).find((f) => f.seed);
   return {
@@ -59,6 +60,12 @@ export function buildUpgradeReport({
           failed: amendmentsPlan.failed ?? 0,
           total: amendmentsPlan.total ?? ((amendmentsPlan.written ?? 0) + amendmentsPlan.present + amendmentsPlan.skipped) }
       : { backfilled: 0, present: 0, skipped: 0, failed: 0, total: 0 },
+    // v1.18.2: whether python3 can import every module the plugin's scripts need, and what this run
+    // installed. null when the phase did not run (a dry run records nothing).
+    python_deps: pythonDeps
+      ? { verdict: pythonDeps.verdict, installed: pythonDeps.installed || [], missing: pythonDeps.missing || [],
+          ...(pythonDeps.python ? { python: pythonDeps.python } : {}), ...(pythonDeps.reason ? { reason: pythonDeps.reason } : {}) }
+      : null,
     permissions_policy: seedRow ? (seedRow.action === 'create' ? 'created' : 'kept') : 'absent',
     drifted: (filePlan || []).filter((f) => f.action === 'drifted').map((f) => f.relPath),
     // hotfix-v1.17.4: what the sweep found (paths are workspace-relative catalogue entries, never free text)

package/templates/foundry-statusline.sh

@@ -24,6 +24,55 @@
 # FAIL-OPEN is the only invariant: any error → print what could be built (possibly nothing) and `exit 0`.
 set +e
 
+# v1.18.2 — THROTTLE + SINGLE-FLIGHT. Claude Code re-runs the status line on every update; the
+# renderer shells out to git (a full `git status`) and python, which on WSL took seconds. Runs then
+# overlapped, each refresh spawning another, until the machine ran out of memory and Claude Code
+# itself crashed (an adopter's WSL session: 44,616 spawns in 21 minutes, SIGBUS). So: one render per
+# project at a time (an mkdir lock), its output cached for FOUNDRY_STATUSLINE_TTL seconds (default 5),
+# and a refresh that finds a render in flight prints the last line and exits at once. The cache-hit
+# path spawns only `cat` (and `date` where bash has no EPOCHSECONDS). Cache: ~/.cache/foundry-statusline.
+# Security review (v1.18.2, Block): the cache lives in the user's OWN cache dir, never a shared /tmp,
+# and is used only when it is a real directory owned by this user (not a symlink) — otherwise the
+# wrapper renders directly, uncached (fail-open), so a planted dir/link is never read or written.
+if [ -z "${FOUNDRY_STATUSLINE_INNER:-}" ]; then
+  PAYLOAD="$(cat 2>/dev/null || true)"
+  _d="${XDG_CACHE_HOME:-${HOME:-/nonexistent}/.cache}/foundry-statusline"
+  mkdir -p -m 700 "$_d" 2>/dev/null
+  if [ ! -d "$_d" ] || [ -L "$_d" ] || [ ! -O "$_d" ]; then
+    printf '%s' "$PAYLOAD" | FOUNDRY_STATUSLINE_INNER=1 bash "$0" "$@" 2>/dev/null
+    exit 0
+  fi
+  _k="${CLAUDE_PROJECT_DIR:-$PWD}"; _k="${_k//[^A-Za-z0-9]/_}"
+  _cache="$_d/${_k}.out"; _lock="$_d/${_k}.lock"
+  _now="${EPOCHSECONDS:-$(date +%s)}"; _ttl="${FOUNDRY_STATUSLINE_TTL:-5}"
+  _ts=0; [ -r "$_cache.ts" ] && read -r _ts < "$_cache.ts" 2>/dev/null
+  case "$_ts" in ''|*[!0-9]*) _ts=0 ;; esac
+  if [ -r "$_cache" ] && [ "$_ts" -le "$_now" ] && [ $(( _now - _ts )) -lt "$_ttl" ]; then
+    printf '%s' "$(< "$_cache")"; exit 0
+  fi
+  if ! mkdir "$_lock" 2>/dev/null; then
+    # a lock whose ts is not written yet is FRESH (a render just started), never stale
+    _lt="$_now"; [ -r "$_lock/ts" ] && read -r _lt < "$_lock/ts" 2>/dev/null
+    case "$_lt" in ''|*[!0-9]*) _lt="$_now" ;; esac
+    if [ $(( _now - _lt )) -gt 30 ]; then rm -f "$_lock/ts" 2>/dev/null; rmdir "$_lock" 2>/dev/null; fi
+    [ -r "$_cache" ] && printf '%s' "$(< "$_cache")"
+    exit 0
+  fi
+  printf '%s\n' "$_now" > "$_lock/ts" 2>/dev/null
+  # bounded: a hung render (git on a stalled filesystem) is killed at 20 s where `timeout` exists,
+  # so it can never outlive the 30 s stale-lock window and overlap the next one
+  if command -v timeout >/dev/null 2>&1; then
+    _out="$(printf '%s' "$PAYLOAD" | FOUNDRY_STATUSLINE_INNER=1 timeout 20 bash "$0" "$@" 2>/dev/null)"
+  else
+    _out="$(printf '%s' "$PAYLOAD" | FOUNDRY_STATUSLINE_INNER=1 bash "$0" "$@" 2>/dev/null)"
+  fi
+  printf '%s' "$_out" > "$_cache.tmp" 2>/dev/null && mv -f "$_cache.tmp" "$_cache" 2>/dev/null
+  printf '%s\n' "${EPOCHSECONDS:-$(date +%s)}" > "$_cache.ts" 2>/dev/null
+  rm -f "$_lock/ts" 2>/dev/null; rmdir "$_lock" 2>/dev/null
+  printf '%s' "$_out"
+  exit 0
+fi
+
 PAYLOAD="$(cat 2>/dev/null || true)"
 CFG="${CLAUDE_CONFIG_DIR:-${HOME}/.claude}"
 RENDERER="foundry-statusline.sh"