triad-plus 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.11.0 — 2026-09-17
+
+- Add an installation manifest that records Triad-owned assets, materialized
+  version, adapter scopes, hashes, and deterministic ownership fingerprint.
+- Add CLI/workspace version visibility, legacy manifest migration through
+  `upgrade --apply`, and conservative dry-run/apply uninstall for all adapters.
+- Preserve modified or unknown assets and all project-control state during
+  uninstall; report version skew and manifest integrity through `doctor`.
+- Preserve shared global assets by default, remove only exact managed
+  `AGENTS.md` blocks, and leave generic host directories untouched.
+
 ## 1.10.0 — 2026-09-16
 
 - Improve TUI and doctor output with terminal-native summaries, sober color

package/README.md

@@ -107,6 +107,38 @@ The Orchestrator first shows the feature cards, then delegates the bounded work.
 If a tutorial step is unclear, see the [OpenCode guide](docs/runtimes.md#opencode)
 and [troubleshooting](docs/troubleshooting.md).
 
+## Installation version and safe uninstall
+
+The CLI version and the version materialized in a control workspace are
+reported independently:
+
+```bash
+npx triad-plus --version
+npx triad-plus version --control /absolute/path/to/triad-control
+```
+
+Successful `init` and `upgrade --apply` operations record exact Triad-owned
+files in `.triad-plus/installation.json`. This manifest does not own
+`.triad-plus/team.json`, `.loop/`, product files, or evidence.
+`init` is the first-install path; `upgrade --apply` is also the managed
+update/repair/restore path for a registered workspace, including one left
+`uninstalled` or `partial` by safe uninstall.
+
+Uninstall is conservative and dry-run by default:
+
+```bash
+npx triad-plus uninstall --host opencode --control /absolute/path/to/triad-control
+npx triad-plus uninstall --host opencode --control /absolute/path/to/triad-control --apply
+```
+
+Only unchanged files recorded by the manifest are removed. Modified or
+unknown files are preserved and reported; user state remains available for a
+future installation or review. Generic host directories are never pruned. A
+managed `AGENTS.md` role-run block is removed only when its markers and hash
+are exact; surrounding user content is preserved. Global assets are shown but
+preserved by default with `--global` because another control workspace may
+share them.
+
 ## Optional immutable quality target
 
 An initialized project may bind an immutable JSON Quality Baseline through

package/bin/triad-plus.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
-import { access, cp, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { access, cp, mkdir, readFile, rm, stat, writeFile, lstat, readdir } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, relative, sep } from 'node:path';
 import process from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { getAdapter, listAdapters, roleDefinitions, sharedSkillNames } from '../adapters/registry.mjs';
@@ -20,8 +21,21 @@ import {
   formatDoctorSection,
   formatSetupSummary
 } from '../runtime/lib/terminal.mjs';
+import {
+  buildInstallationManifest,
+  collectManagedAssetRecords,
+  installationManifestFingerprint,
+  installationManifestPath,
+  loadInstallationManifest,
+  manifestIsUninstalled,
+  manifestScopeStatus,
+  sha256Text,
+  sha256File,
+  writeInstallationManifest
+} from '../runtime/lib/installation-manifest.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const packageVersion = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
 
 function usage(exitCode = 0) {
   const stream = exitCode === 0 ? process.stdout : process.stderr;
@@ -29,15 +43,18 @@ function usage(exitCode = 0) {
 
 Usage:
   npx triad-plus
+  npx triad-plus --version
   npx triad-plus init --host <adapter-id> --control <path> [--global] [--team-config <path>] [--allow-product-repo]
   npx triad-plus doctor --host <adapter-id> --control <path> [--global] [--hook-config <path>]
+  npx triad-plus version --control <path>
   npx triad-plus upgrade --host <adapter-id> --control <path> [--global] [--apply]
+  npx triad-plus uninstall --host <adapter-id> --control <path> [--global] [--apply]
   npx triad-plus import-bmad-story --source <story.md> --output <card.md> [--target-repository <id>] [--provenance <record.json>] [--required-gate <id>] [--depends-on <card-id>]
 
 Adapters: ${listAdapters().map((adapter) => adapter.id).join(', ')}
 
 The control path is a project-control workspace, not a product repository.
-Installation refuses every asset overwrite. Upgrade is a dry run unless --apply is supplied.
+Installation refuses conflicting asset overwrites; identical global assets may be reused. Upgrade is a dry run unless --apply is supplied.
 `);
   process.exit(exitCode);
 }
@@ -77,6 +94,16 @@ async function requireDirectory(target) {
   if (!(await stat(target)).isDirectory()) throw new Error(`Control path is not a directory: ${target}`);
 }
 
+async function requireExistingDirectory(target) {
+  let info;
+  try { info = await stat(target); }
+  catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`Control workspace does not exist: ${target}`);
+    throw error;
+  }
+  if (!info.isDirectory()) throw new Error(`Control path is not a directory: ${target}`);
+}
+
 function codexHome() {
   return process.env.CODEX_HOME || join(homedir(), '.codex');
 }
@@ -122,6 +149,101 @@ async function installAssets(assets, root, installContext) {
   for (const asset of assets) await copyAsset(asset, root, installContext);
 }
 
+function assetDestinations(assets, root, installContext) {
+  return assets.map((asset) => resolveDestination(asset.destination, root, installContext));
+}
+
+async function sourceFiles(source) {
+  const info = await lstat(source);
+  if (info.isFile()) return [source];
+  if (!info.isDirectory()) throw new Error(`Managed asset source is not a regular file or directory: ${source}`);
+  const files = [];
+  for (const name of (await readdir(source)).sort()) files.push(...await sourceFiles(join(source, name)));
+  return files;
+}
+
+/** Expand registry assets to exact source/destination file pairs, never to a host directory. */
+async function materializedAssetPairs(assets, root, installContext) {
+  const pairs = [];
+  for (const asset of assets) {
+    const destination = resolveDestination(asset.destination, root, installContext);
+    if (asset.source === 'shared-skills') {
+      for (const name of sharedSkillNames) {
+        const source = join(packageRoot, 'skills', name);
+        const sourceRoot = resolve(source);
+        for (const file of await sourceFiles(sourceRoot)) {
+          pairs.push({ source: file, target: join(destination, name, relative(sourceRoot, file)) });
+        }
+      }
+      continue;
+    }
+    const source = sourcePath(asset.source);
+    const sourceInfo = await lstat(source);
+    if (asset.file || sourceInfo.isFile()) {
+      pairs.push({ source, target: destination });
+      continue;
+    }
+    const sourceRoot = resolve(source);
+    for (const file of await sourceFiles(sourceRoot)) pairs.push({ source: file, target: join(destination, relative(sourceRoot, file)) });
+  }
+  return pairs.map((pair) => ({ source: resolve(pair.source), target: resolve(pair.target) }));
+}
+
+/** Expand registry assets to the exact files copied, never to a host directory. */
+async function materializedAssetPaths(assets, root, installContext) {
+  return (await materializedAssetPairs(assets, root, installContext)).map((pair) => pair.target);
+}
+
+function generatedRoleAssetPaths(adapter, installContext, scope, team) {
+  if (!team || scope !== 'global' || adapter.modelBinding !== 'global-profiles' || typeof adapter.roleModelPaths !== 'function') return [];
+  return adapter.roleModelPaths(installContext);
+}
+
+async function collectInstallationAssets(adapter, controlRoot, installContext, scope, team) {
+  const assets = scope === 'global' ? adapter.globalAssets : adapter.projectAssets;
+  const paths = [
+    ...await materializedAssetPaths(assets, controlRoot, installContext),
+    ...generatedRoleAssetPaths(adapter, installContext, scope, team)
+  ];
+  return collectManagedAssetRecords(paths, {
+    scope,
+    baseRoot: scope === 'project' ? controlRoot : null
+  });
+}
+
+function overallInstallationStatus(scopeStatus) {
+  const values = Object.values(scopeStatus);
+  if (values.every((value) => ['not_configured', 'uninstalled'].includes(value))) return 'uninstalled';
+  if (values.some((value) => ['partial', 'uninstalled'].includes(value))) return 'partial';
+  return 'installed';
+}
+
+async function installationManifestFor({ adapter, controlRoot, installContext, team, global = false, previous = null, installedAt = null }) {
+  const projectAssets = await collectInstallationAssets(adapter, controlRoot, installContext, 'project', team);
+  const previousManifest = previous?.manifest ?? previous;
+  const overlayAssets = await managedOverlayRecord(controlRoot, previousManifest, team);
+  const globalConfigured = Boolean(global || previousManifest?.scopes?.global);
+  const globalAssets = global
+    ? await collectInstallationAssets(adapter, controlRoot, installContext, 'global', team)
+    : (previousManifest?.managed_assets ?? []).filter((asset) => asset.scope === 'global');
+  const scopeStatus = {
+    project: 'installed',
+    global: globalConfigured
+      ? (global ? 'installed' : manifestScopeStatus(previousManifest, 'global'))
+      : 'not_configured'
+  };
+  return buildInstallationManifest({
+    triadVersion: packageVersion,
+    adapter: adapter.id,
+    installedAt: installedAt ?? previousManifest?.installed_at ?? new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    scopes: { project: true, global: globalConfigured },
+    scopeStatus,
+    managedAssets: [...projectAssets, ...overlayAssets, ...globalAssets],
+    status: overallInstallationStatus(scopeStatus)
+  });
+}
+
 async function replaceManagedPath(source, destination, backup, apply) {
   const present = await exists(destination);
   process.stdout.write(`  ${apply ? 'Update' : 'Would update'} ${destination}${present ? ' (backup)' : ''}\n`);
@@ -172,16 +294,26 @@ outside Triad+.
 ${overlayEnd}`;
 }
 
+function managedBlockIn(source, startMarker = overlayStart, endMarker = overlayEnd) {
+  const startCount = source.split(startMarker).length - 1;
+  const endCount = source.split(endMarker).length - 1;
+  if (startCount === 0 && endCount === 0) return null;
+  if (startCount !== 1 || endCount !== 1) throw new Error('Managed instruction block is ambiguous: duplicate or incomplete markers.');
+  const start = source.indexOf(startMarker);
+  const end = source.indexOf(endMarker, start + startMarker.length);
+  if (end < 0) throw new Error('Managed instruction block has invalid marker order.');
+  const blockEnd = end + endMarker.length;
+  return { start, end, blockEnd, content: source.slice(start, blockEnd) };
+}
+
 async function overlayPlan(controlRoot, team) {
   const target = join(controlRoot, 'AGENTS.md');
   const overlay = instructionOverlay(team);
   if (!(await exists(target))) return { target, action: 'create', content: `# Project instructions\n\n${overlay}\n` };
   const source = await readFile(target, 'utf8');
-  const start = source.indexOf(overlayStart);
-  const end = source.indexOf(overlayEnd);
-  if (start === -1 && end === -1) return { target, action: 'append', content: `${source.replace(/\s*$/, '')}\n\n${overlay}\n` };
-  if (start < 0 || end < start) throw new Error(`Cannot safely update managed instruction block: ${target}`);
-  return { target, action: 'update', content: `${source.slice(0, start)}${overlay}${source.slice(end + overlayEnd.length)}` };
+  const managed = managedBlockIn(source);
+  if (!managed) return { target, action: 'append', content: `${source}${source.endsWith('\n') ? '\n' : '\n\n'}${overlay}\n` };
+  return { target, action: 'update', content: `${source.slice(0, managed.start)}${overlay}${source.slice(managed.blockEnd)}` };
 }
 
 async function applyOverlay(controlRoot, apply, team) {
@@ -190,6 +322,23 @@ async function applyOverlay(controlRoot, apply, team) {
   if (apply) await writeFile(plan.target, plan.content, 'utf8');
 }
 
+async function managedOverlayRecord(controlRoot, previousManifest, team) {
+  const previousBlocks = (previousManifest?.managed_assets ?? []).filter((asset) => asset.kind === 'managed_block' && asset.scope === 'project');
+  if (!team) return previousBlocks;
+  const target = join(controlRoot, 'AGENTS.md');
+  const source = await readFile(target, 'utf8');
+  const managed = managedBlockIn(source);
+  if (!managed) throw new Error(`Managed instruction block is missing after materialization: ${target}`);
+  return [{
+    scope: 'project',
+    path: 'AGENTS.md',
+    kind: 'managed_block',
+    start_marker: overlayStart,
+    end_marker: overlayEnd,
+    sha256: sha256Text(managed.content)
+  }];
+}
+
 async function loadTeamConfig(options) {
   if (options.team) return validateTeamConfiguration(options.team);
   if (!options.teamConfig) return null;
@@ -306,6 +455,138 @@ async function anyExist(paths) {
   return false;
 }
 
+async function globalPathReusable(target, pairs) {
+  let info;
+  try { info = await lstat(target); } catch (error) {
+    if (error.code === 'ENOENT') return true;
+    throw error;
+  }
+  if (info.isDirectory()) {
+    const descendants = pairs.filter((pair) => pathWithin(target, pair.target));
+    if (descendants.length === 0) return false;
+    for (const pair of descendants) {
+      let pairInfo;
+      try { pairInfo = await lstat(pair.target); } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        return false;
+      }
+      if (!pairInfo.isFile() || await sha256File(pair.target) !== await sha256File(pair.source)) return false;
+    }
+    return true;
+  }
+  const pair = pairs.find((candidate) => candidate.target === resolve(target));
+  return Boolean(pair && info.isFile() && await sha256File(target) === await sha256File(pair.source));
+}
+
+function versionTuple(value) {
+  const match = String(value ?? '').match(/^(?:v)?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function compareVersions(left, right) {
+  const a = versionTuple(left);
+  const b = versionTuple(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] > b[index]) return 1;
+    if (a[index] < b[index]) return -1;
+  }
+  return 0;
+}
+
+function pathWithin(root, target) {
+  const base = resolve(root);
+  const candidate = resolve(target);
+  return candidate === base || candidate.startsWith(`${base}${sep}`);
+}
+
+async function managedAssetPaths(adapter, controlRoot, installContext, scope) {
+  const assets = scope === 'global' ? adapter.globalAssets : adapter.projectAssets;
+  const paths = await materializedAssetPaths(assets, controlRoot, installContext);
+  if (scope === 'global' && adapter.modelBinding === 'global-profiles' && typeof adapter.roleModelPaths === 'function') {
+    paths.push(...adapter.roleModelPaths(installContext));
+  }
+  return new Set(paths.map((target) => resolve(target)));
+}
+
+function manifestAssetPath(controlRoot, asset) {
+  return asset.scope === 'project' ? resolve(controlRoot, asset.path) : resolve(asset.path);
+}
+
+function displayManagedAssetPath(asset) {
+  if (asset.scope !== 'global') return asset.path;
+  const home = resolve(homedir());
+  const target = resolve(asset.path);
+  return pathWithin(home, target) ? `~${relative(home, target) ? `/${relative(home, target)}` : ''}` : target;
+}
+
+function assetAllowedByRegistry(managedPaths, controlRoot, asset) {
+  const target = manifestAssetPath(controlRoot, asset);
+  if (asset.kind === 'managed_block') return asset.scope === 'project' && target === resolve(controlRoot, 'AGENTS.md');
+  return managedPaths.has(target);
+}
+
+async function installationAssetIssues(controlRoot, adapter, installContext, manifest) {
+  const issues = [];
+  for (const asset of manifest.managed_assets) {
+    const target = manifestAssetPath(controlRoot, asset);
+    const expectedState = manifestScopeStatus(manifest, asset.scope);
+    let info;
+    try { info = await lstat(target); } catch (error) {
+      if (error.code === 'ENOENT') {
+        if (expectedState !== 'uninstalled') issues.push({ asset, status: 'missing' });
+        continue;
+      }
+      issues.push({ asset, status: `unreadable:${error.code ?? 'error'}` });
+      continue;
+    }
+    if (asset.kind === 'managed_block') {
+      if (!info.isFile()) {
+        issues.push({ asset, status: 'modified' });
+        continue;
+      }
+      let source;
+      try { source = await readFile(target, 'utf8'); } catch { issues.push({ asset, status: 'unreadable' }); continue; }
+      let managed;
+      try { managed = managedBlockIn(source, asset.start_marker, asset.end_marker); } catch { managed = null; }
+      if (managed && sha256Text(managed.content) !== asset.sha256) issues.push({ asset, status: 'modified' });
+      else if (managed && expectedState === 'uninstalled') issues.push({ asset, status: 'present_after_uninstall' });
+      else if (!managed && expectedState !== 'uninstalled') issues.push({ asset, status: 'modified' });
+      continue;
+    }
+    if (!info.isFile()) {
+      issues.push({ asset, status: 'modified' });
+      continue;
+    }
+    let observed;
+    try { observed = await sha256File(target); } catch { issues.push({ asset, status: 'unreadable' }); continue; }
+    if (observed !== asset.sha256) issues.push({ asset, status: 'modified' });
+    else if (expectedState === 'uninstalled') issues.push({ asset, status: 'present_after_uninstall' });
+  }
+  return issues;
+}
+
+async function inspectInstallation(controlRoot, adapter, installContext) {
+  let loaded;
+  try { loaded = await loadInstallationManifest(controlRoot); }
+  catch (error) {
+    return { state: 'invalid', message: error.message, manifest: null, issues: [] };
+  }
+  if (!loaded) return { state: 'legacy', manifest: null, issues: [] };
+  const manifest = loaded.manifest;
+  if (manifest.adapter !== adapter.id) {
+    return {
+      state: 'invalid',
+      message: `manifest adapter ${manifest.adapter} does not match selected ${adapter.id}`,
+      manifest,
+      issues: []
+    };
+  }
+  const issues = await installationAssetIssues(controlRoot, adapter, installContext, manifest);
+  const versionRelation = compareVersions(packageVersion, manifest.triad_version);
+  return { state: manifestIsUninstalled(manifest) ? 'uninstalled' : 'valid', manifest, issues, versionRelation };
+}
+
 /** Return one status per shared skill so a partial install cannot look healthy. */
 async function sharedSkillStatuses(adapter, root, installContext, scope) {
   const roots = sharedSkillRoots(adapter, root, installContext, scope);
@@ -438,24 +719,52 @@ async function init(options) {
   if (!options.allowProductRepo && productRepositoryAt(controlRoot)) {
     throw new Error('Control path appears to be a product repository. Use a separate project-control workspace, or pass --allow-product-repo after reviewing the risk.');
   }
+  let previousManifest = null;
+  if (await exists(installationManifestPath(controlRoot))) previousManifest = await loadInstallationManifest(controlRoot);
   const installContext = context(controlRoot);
-  const planned = [
+  const projectPlanned = [
     ...adapter.projectPaths(controlRoot, installContext),
-    ...(team ? [teamConfigPath(controlRoot)] : []),
-    ...(options.global ? adapter.globalPaths(installContext) : []),
-    ...(team && options.global && adapter.modelBinding === 'global-profiles' ? adapter.roleModelPaths(installContext) : []),
-    ...(team && options.global && adapter.modelBinding === 'project-frontmatter' && adapter.globalRoleModelPaths
-      ? adapter.globalRoleModelPaths(installContext)
-      : [])
+    ...(team ? [teamConfigPath(controlRoot)] : [])
   ];
-  const existing = await collisions(planned);
-  if (existing.length > 0) throw new Error(`Installation aborted; existing paths would be overwritten:\n${existing.map((target) => `  ${target}`).join('\n')}`);
+  const existingProject = await collisions(projectPlanned);
+  if (existingProject.length > 0) throw new Error(`Installation aborted; existing paths would be overwritten:\n${existingProject.map((target) => `  ${target}`).join('\n')}`);
+  if (options.global) {
+    const globalPlanned = [
+      ...adapter.globalPaths(installContext),
+      ...(team && adapter.modelBinding === 'global-profiles' ? adapter.roleModelPaths(installContext) : []),
+      ...(team && adapter.modelBinding === 'project-frontmatter' && adapter.globalRoleModelPaths
+        ? adapter.globalRoleModelPaths(installContext)
+        : [])
+    ];
+    const globalPairs = await materializedAssetPairs(adapter.globalAssets, controlRoot, installContext);
+    const teamModelPaths = team
+      ? new Set([
+        ...(adapter.modelBinding === 'global-profiles' && typeof adapter.roleModelPaths === 'function' ? adapter.roleModelPaths(installContext) : []),
+        ...(adapter.modelBinding === 'project-frontmatter' && typeof adapter.globalRoleModelPaths === 'function' ? adapter.globalRoleModelPaths(installContext) : [])
+      ].map((target) => resolve(target)))
+      : new Set();
+    const existingGlobal = [];
+    for (const target of globalPlanned) {
+      if (!(await exists(target))) continue;
+      if (teamModelPaths.has(resolve(target)) || !(await globalPathReusable(target, globalPairs))) existingGlobal.push(target);
+    }
+    if (existingGlobal.length > 0) throw new Error(`Installation aborted; existing global paths would be overwritten:\n${existingGlobal.map((target) => `  ${target}`).join('\n')}`);
+  }
   await installAssets(adapter.projectAssets, controlRoot, installContext);
   if (team) await writeTeamConfig(controlRoot, team);
   if (team) await applyOverlay(controlRoot, true, team);
   if (options.global) await installAssets(adapter.globalAssets, controlRoot, installContext);
   if (team) await applyTeamBinding(adapter, controlRoot, team, installContext, 'project');
   if (team && options.global) await applyTeamBinding(adapter, controlRoot, team, installContext, 'global');
+  const manifest = await installationManifestFor({
+    adapter,
+    controlRoot,
+    installContext,
+    team,
+    global: options.global,
+    previous: previousManifest
+  });
+  await writeInstallationManifest(controlRoot, manifest);
   process.stdout.write(`Triad+ installed for ${adapter.label} in ${controlRoot}\n`);
   if (adapter.globalEntry) {
     process.stdout.write(`Install user-level assets with --global to expose ${adapter.entry}.\n`);
@@ -504,7 +813,12 @@ async function upgrade(options) {
   if (!adapter) throw new Error(`Choose --host ${listAdapters().map((item) => item.id).join(', ')}.`);
   if (!options.control) throw new Error('Provide --control <project-control-path>.');
   const controlRoot = resolve(options.control);
-  await requireDirectory(controlRoot);
+  await requireExistingDirectory(controlRoot);
+  let previousManifest = null;
+  if (await exists(installationManifestPath(controlRoot))) previousManifest = await loadInstallationManifest(controlRoot);
+  if (previousManifest && previousManifest.manifest.adapter !== adapter.id) {
+    throw new Error(`Installation manifest belongs to ${previousManifest.manifest.adapter}, not ${adapter.id}.`);
+  }
   const team = await currentTeam(controlRoot);
   const installContext = context(controlRoot);
   const stamp = new Date().toISOString().replaceAll(':', '-').replaceAll('.', '-');
@@ -521,6 +835,20 @@ async function upgrade(options) {
     await refreshAssets(adapter.globalAssets, controlRoot, installContext, join(backupRoot, 'global'), options.apply);
     if (team && options.apply) await applyTeamBinding(adapter, controlRoot, team, installContext, 'global');
   }
+  if (options.apply) {
+    const manifest = await installationManifestFor({
+      adapter,
+      controlRoot,
+      installContext,
+      team,
+      global: options.global,
+      previous: previousManifest
+    });
+    await writeInstallationManifest(controlRoot, manifest);
+    process.stdout.write(`  Installation manifest updated ${installationManifestPath(controlRoot)}\n`);
+  } else {
+    process.stdout.write(`  Installation manifest would be ${previousManifest ? 'updated' : 'created'} ${installationManifestPath(controlRoot)}\n`);
+  }
   if (!options.apply) process.stdout.write('Dry run only. Re-run with --apply to update managed assets.\n');
 }
 
@@ -539,6 +867,181 @@ async function importBmadStory(options) {
   process.stdout.write(`Provenance ${result.provenancePath}\n`);
 }
 
+function installationScopeText(manifest, scope) {
+  const status = manifestScopeStatus(manifest, scope);
+  if (status === 'installed') return 'yes';
+  if (status === 'not_configured') return 'no';
+  return status;
+}
+
+async function versionCommand(options) {
+  if (!options.control) throw new Error('Provide --control <project-control-path>.');
+  const controlRoot = resolve(options.control);
+  await requireExistingDirectory(controlRoot);
+  process.stdout.write(`Triad+ CLI        ${packageVersion}\n`);
+  process.stdout.write(`Workspace         ${controlRoot}\n`);
+  let loaded;
+  try { loaded = await loadInstallationManifest(controlRoot); }
+  catch (error) {
+    process.stdout.write('Installed Triad   unknown (manifest invalid)\n');
+    process.stdout.write(`Manifest          invalid — ${error.message}\n`);
+    throw error;
+  }
+  if (!loaded) {
+    process.stdout.write('Installed Triad   unknown (legacy installation)\n');
+    process.stdout.write('Manifest          legacy / manifest missing\n');
+    process.stdout.write('Adapter           unknown\n');
+    process.stdout.write('Project install   unknown\n');
+    process.stdout.write('Global install    unknown\n');
+    return;
+  }
+  const manifest = loaded.manifest;
+  const adapter = getAdapter(manifest.adapter);
+  const uninstalled = manifestIsUninstalled(manifest);
+  process.stdout.write(`Installed Triad   ${uninstalled ? 'unknown (uninstalled)' : manifest.triad_version}\n`);
+  process.stdout.write(`Manifest          ${uninstalled ? 'OK (uninstalled)' : 'OK'}\n`);
+  process.stdout.write(`Adapter           ${adapter?.label ?? manifest.adapter}\n`);
+  process.stdout.write(`Project install   ${installationScopeText(manifest, 'project')}\n`);
+  process.stdout.write(`Global install    ${installationScopeText(manifest, 'global')}\n`);
+}
+
+async function uninstall(options) {
+  const adapter = getAdapter(options.host);
+  if (!adapter) throw new Error(`Choose --host ${listAdapters().map((item) => item.id).join(', ')}.`);
+  if (!options.control) throw new Error('Provide --control <project-control-path>.');
+  const controlRoot = resolve(options.control);
+  await requireExistingDirectory(controlRoot);
+  const loaded = await loadInstallationManifest(controlRoot);
+  process.stdout.write(`Triad+ uninstall — ${adapter.label}\n`);
+  if (!loaded) {
+    process.stdout.write('Manifest          legacy / manifest missing\n');
+    process.stdout.write('No files were changed. Refusing to delete assets without an installation manifest.\n');
+    return;
+  }
+  const manifest = loaded.manifest;
+  if (manifest.adapter !== adapter.id) throw new Error(`Installation manifest belongs to ${manifest.adapter}, not ${adapter.id}.`);
+  const installContext = context(controlRoot);
+  const selectedScopes = options.global ? ['project', 'global'] : ['project'];
+  const scopeStats = Object.fromEntries(selectedScopes.map((scope) => [scope, { modified: 0, removed: 0 }]));
+  if (options.global) process.stdout.write('Global assets are preserved because cross-workspace ownership cannot be proven.\n');
+  for (const scope of selectedScopes) {
+    const registryPaths = await managedAssetPaths(adapter, controlRoot, installContext, scope);
+    process.stdout.write(`\n${scope === 'project' ? 'Project' : 'Global'} managed assets\n`);
+    const entries = manifest.managed_assets.filter((asset) => asset.scope === scope);
+    if (entries.length === 0) process.stdout.write('  (none)\n');
+    for (const asset of entries) {
+      const target = manifestAssetPath(controlRoot, asset);
+      const display = displayManagedAssetPath(asset);
+      let info;
+      try { info = await lstat(target); } catch (error) {
+        if (error.code === 'ENOENT') {
+          process.stdout.write(`  ABSENT    ${display}\n`);
+          continue;
+        }
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write(`            cannot inspect asset: ${error.message}\n`);
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      if (scope === 'global') {
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write('            global ownership may be shared by another control workspace\n');
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      if (!assetAllowedByRegistry(registryPaths, controlRoot, asset)) {
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write('            path is not in the current adapter managed plan\n');
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      if (asset.kind === 'managed_block') {
+        if (!info.isFile()) {
+          process.stdout.write(`  PRESERVE  ${display}\n`);
+          process.stdout.write('            managed block host file is not a regular file\n');
+          scopeStats[scope].modified += 1;
+          continue;
+        }
+        let source;
+        let managed;
+        try {
+          source = await readFile(target, 'utf8');
+          managed = managedBlockIn(source, asset.start_marker, asset.end_marker);
+        } catch {
+          managed = null;
+        }
+        if (!managed || sha256Text(managed.content) !== asset.sha256) {
+          process.stdout.write(`  PRESERVE  ${display}\n`);
+          process.stdout.write('            managed block is modified, ambiguous, or unverifiable\n');
+          scopeStats[scope].modified += 1;
+          continue;
+        }
+        process.stdout.write(`  ${options.apply ? 'REMOVE' : 'WOULD REMOVE'} block ${display}\n`);
+        if (options.apply) {
+          await writeFile(target, `${source.slice(0, managed.start)}${source.slice(managed.blockEnd)}`, 'utf8');
+          scopeStats[scope].removed += 1;
+        }
+        continue;
+      }
+      if (!info.isFile()) {
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write('            asset is no longer a regular file\n');
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      const observed = await sha256File(target);
+      if (observed !== asset.sha256) {
+        process.stdout.write(`  PRESERVE  ${display}\n`);
+        process.stdout.write('            content differs from installation manifest\n');
+        scopeStats[scope].modified += 1;
+        continue;
+      }
+      process.stdout.write(`  ${options.apply ? 'REMOVE' : 'WOULD REMOVE'}   ${display}\n`);
+      if (options.apply) {
+        await rm(target, { force: true });
+        scopeStats[scope].removed += 1;
+      }
+    }
+  }
+  process.stdout.write('\nPreserved state\n');
+  for (const preserved of ['.triad-plus/team.json', '.loop/', 'project.yaml', 'features/', 'artifacts/', 'evidence/']) {
+    process.stdout.write(`  KEEP      ${preserved}\n`);
+  }
+  if (!options.apply) {
+    process.stdout.write('\nNo files were changed. Re-run with --apply to uninstall managed assets.\n');
+    return;
+  }
+  const scopeStatus = { project: manifestScopeStatus(manifest, 'project'), global: manifestScopeStatus(manifest, 'global') };
+  for (const scope of selectedScopes) scopeStatus[scope] = scopeStats[scope].modified > 0 ? 'partial' : 'uninstalled';
+  const status = overallInstallationStatus(scopeStatus);
+  const updated = buildInstallationManifest({
+    triadVersion: manifest.triad_version,
+    adapter: manifest.adapter,
+    installedAt: manifest.installed_at,
+    updatedAt: new Date().toISOString(),
+    uninstalledAt: status === 'uninstalled' ? new Date().toISOString() : undefined,
+    scopes: manifest.scopes,
+    scopeStatus,
+    managedAssets: manifest.managed_assets,
+    status
+  });
+  await writeInstallationManifest(controlRoot, updated);
+  process.stdout.write(`\nInstallation manifest updated ${installationManifestPath(controlRoot)}\n`);
+  const projectPartial = scopeStatus.project === 'partial';
+  const globalPreserved = options.global && scopeStatus.global === 'partial';
+  if (status === 'uninstalled') {
+    process.stdout.write('Complete project uninstall; user state was preserved.\n');
+  } else if (projectPartial && globalPreserved) {
+    process.stdout.write('Partial uninstall; modified or unverifiable project assets and shared global assets were preserved.\n');
+  } else if (projectPartial) {
+    process.stdout.write('Partial project uninstall; modified or unverifiable assets were preserved.\n');
+  } else if (globalPreserved) {
+    process.stdout.write('Project uninstall complete; global assets were intentionally preserved because shared ownership could not be proven.\n');
+  } else {
+    process.stdout.write('Uninstall completed conservatively; preserved assets remain in place.\n');
+  }
+}
+
 async function doctor(options) {
   if (!options.control) throw new Error('Provide --control <project-control-path>.');
   const controlRoot = resolve(options.control);
@@ -551,6 +1054,7 @@ async function doctor(options) {
   }
   for (const adapter of requested) {
     const installContext = context(controlRoot);
+    const installation = await inspectInstallation(controlRoot, adapter, installContext);
     const absent = [];
     for (const target of adapter.projectPaths(controlRoot, installContext)) if (!(await exists(target))) absent.push(target);
     const globalDetected = adapter.globalPaths ? await anyExist(adapter.globalPaths(installContext)) : false;
@@ -568,7 +1072,41 @@ async function doctor(options) {
     const triadSkillTargets = targets.filter((target) => /[/\\]skills[/\\]triad$/.test(target));
     const capability = manifest ? capabilitySnapshot(controlRoot, manifestPath) : null;
     process.stdout.write(`\n${formatDoctorSection(`Triad+ doctor — ${adapter.label}`)}\n`);
-    process.stdout.write(`${formatDoctorLine(adapter.label, absent.length || globalAbsent.length ? 'incomplete' : 'OK')}\n`);
+    process.stdout.write(`${formatDoctorLine(adapter.label, absent.length || globalAbsent.length || installation.issues.length ? 'incomplete' : 'OK')}\n`);
+    process.stdout.write(`${formatDoctorSection('Triad+ installation')}\n`);
+    process.stdout.write(`  ${formatDoctorLine('CLI version', packageVersion)}\n`);
+    if (installation.state === 'legacy') {
+      process.stdout.write(`  ${formatDoctorLine('Installed version', 'unknown (legacy installation)')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Manifest', 'legacy / manifest missing')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Adapter', adapter.label)}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Project scope', 'unknown (legacy)')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Global scope', 'unknown (legacy)')}\n`);
+    } else if (installation.state === 'invalid') {
+      process.stdout.write(`  ${formatDoctorLine('Installed version', 'unknown (manifest invalid)')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Manifest', 'invalid')} — ${installation.message}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Adapter', adapter.label)}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Project scope', 'unknown')}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Global scope', 'unknown')}\n`);
+    } else {
+      const versionStatus = installation.state === 'uninstalled'
+        ? `unknown (uninstalled; last ${installation.manifest.triad_version})`
+        : installation.manifest.triad_version;
+      const versionWarning = installation.versionRelation === 1
+        ? ' — CLI newer / upgrade available'
+        : installation.versionRelation === -1
+        ? ' — CLI older than installed version'
+        : '';
+      const issueStatus = installation.issues.some((issue) => issue.status === 'modified' || issue.status === 'present_after_uninstall')
+        ? 'managed asset modified'
+        : installation.issues.some((issue) => issue.status === 'missing')
+        ? 'managed asset missing'
+        : installation.state === 'uninstalled' ? 'OK (uninstalled)' : 'OK';
+      process.stdout.write(`  ${formatDoctorLine('Installed version', versionStatus)}${versionWarning}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Manifest', issueStatus)}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Adapter', adapter.label)}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Project scope', installationScopeText(installation.manifest, 'project'))}\n`);
+      process.stdout.write(`  ${formatDoctorLine('Global scope', installationScopeText(installation.manifest, 'global'))}\n`);
+    }
     process.stdout.write(`${formatDoctorSection('Runtime and installation')}\n`);
     process.stdout.write(`  ${formatDoctorLine('Host runtime', binary ? `OK (${binary})` : 'not installed or version unavailable')}\n`);
     process.stdout.write(`  ${formatDoctorLine('Verifier', node && await exists(join(controlRoot, '.triad-runtime', 'triad-verify.mjs')) ? 'OK' : 'incomplete')}\n`);
@@ -660,10 +1198,17 @@ async function interactiveInit() {
 }
 
 try {
-  const options = parseArgs(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  if (argv.length === 1 && ['--version', '-v'].includes(argv[0])) {
+    process.stdout.write(`${packageVersion}\n`);
+    process.exit(0);
+  }
+  const options = parseArgs(argv);
   if (options.command === 'init') await init(options);
   else if (options.command === 'doctor') await doctor(options);
+  else if (options.command === 'version') await versionCommand(options);
   else if (options.command === 'upgrade') await upgrade(options);
+  else if (options.command === 'uninstall') await uninstall(options);
   else if (options.command === 'import-bmad-story') await importBmadStory(options);
   else if (!options.command) await interactiveInit();
   else if (options.command === '--help' || options.command === '-h') usage(0);

package/docs/configuration.md

@@ -31,6 +31,37 @@ adapter writes those into host-native profiles only where the selected host
 supports that facility. A blank model means the host default. Never put tokens,
 API keys, or private deployment data in this file.
 
+## Installation ownership and version
+
+The package version and the installed workspace version are separate facts:
+
+```bash
+npx triad-plus --version
+npx triad-plus version --control /path/to/project-control
+```
+
+After successful materialization, `.triad-plus/installation.json` records the
+adapter, project/global scopes, exact managed files, SHA-256 hashes, timestamps,
+and a deterministic fingerprint. Project paths are control-workspace-relative;
+global paths identify the user-level managed asset. The manifest is generated
+from the same adapter registry and install plan used by `init` and `upgrade`.
+
+The manifest deliberately does not own `.triad-plus/team.json`, `.loop/`,
+`project.yaml`, feature cards, artifacts, evidence, or product source. A failed
+install never writes a success manifest. Legacy workspaces are migrated by
+`upgrade --apply` using the currently executing package version; the previous
+version is not guessed.
+
+When a team configuration is materialized, the managed role-run block in
+`AGENTS.md` is recorded as a bounded block asset. Uninstall removes that block
+only when its markers and hash still match, never the surrounding user file.
+Global assets are shared-capable and therefore preserved by default by
+`uninstall --global`.
+
+`doctor` reports CLI version, installed version, manifest state, adapter, and
+project/global scope. It reports version skew explicitly and never queries npm
+for `latest`.
+
 ## Configure models through the agent
 
 The installed `triad-model-configuration` skill lets an owner ask the selected

package/docs/npx-installation.md

@@ -22,11 +22,68 @@ npx triad-plus init --host codex --control /path/to/project-control --global
 npx triad-plus doctor --host codex --control /path/to/project-control
 ```
 
-## Upgrade an existing control workspace
+## Version visibility
 
-`upgrade` refreshes only Triad-managed runtime, skill, adapter, and optional
-host-entry assets. It never changes `team.json`, `.loop/`, PRD files, evidence,
-or product repositories. The default is a dry run:
+`--version` reports the package that is actually executing:
+
+```bash
+npx triad-plus --version
+```
+
+The workspace command reports the materialized installation recorded by the
+control workspace manifest:
+
+```bash
+npx triad-plus version --control /path/to/project-control
+```
+
+An older workspace without `.triad-plus/installation.json` is reported as a
+legacy installation. Triad+ does not infer a historical version from scattered
+agent files.
+
+## Installation manifest and safe uninstall
+
+After a successful `init`, Triad+ writes
+`.triad-plus/installation.json`. It records the selected adapter, CLI version,
+project/global scopes, normalized managed-file paths, SHA-256 hashes, and a
+manifest fingerprint. `upgrade --apply` refreshes this record after managed
+assets are materialized; a legacy workspace receives a new manifest without
+inventing its previous version.
+
+Uninstall is dry-run by default:
+
+```bash
+npx triad-plus uninstall --host opencode --control /path/to/project-control
+npx triad-plus uninstall --host opencode --control /path/to/project-control --apply
+npx triad-plus uninstall --host opencode --control /path/to/project-control --global --apply
+```
+
+Only files listed in the manifest, still unchanged from their recorded hash,
+are removed. Missing files are reported as `ABSENT`; modified assets are
+preserved. Host directories are never pruned because directory ownership is
+not claimed. The team configuration, `.loop/`, project manifest, feature
+cards, artifacts, evidence, and other user state are preserved. A managed
+`AGENTS.md` role-run block is tracked separately and removed only when its
+markers and hash are exact; surrounding user content remains. A manifest
+remains as an `uninstalled` or `partial` tombstone so a second uninstall is
+idempotent and the ownership history is auditable.
+
+`--global --apply` is deliberately preserve-by-default: global assets may be
+shared by several control workspaces, so the command reports them as shared
+and does not delete them without a cross-workspace ownership model.
+
+Read-only commands require an existing control workspace; a typo path is
+never created by `version` or `uninstall`.
+
+## Upgrade, repair, or restore an existing control workspace
+
+`init` is the first-install command and refuses to overwrite an existing
+workspace. `upgrade --apply` is the managed update, repair, and restore path
+for a workspace that is already registered by an installation manifest,
+including a workspace whose project scope is `uninstalled` or `partial` after a
+safe uninstall. It re-materializes project assets, reuses the preserved
+`team.json`, and refreshes the manifest without changing user state, `.loop/`,
+PRD files, evidence, or product repositories. The default is a dry run:
 
 ```bash
 npx triad-plus upgrade --host codex --control /path/to/project-control --global

package/docs/troubleshooting.md

@@ -6,6 +6,26 @@ Run doctor first:
 npx triad-plus doctor --host <runtime> --control /path/to/triad-control
 ```
 
+Compare the executing CLI with the materialized workspace installation:
+
+```bash
+npx triad-plus --version
+npx triad-plus version --control /path/to/triad-control
+```
+
+`legacy / manifest missing` means the workspace predates the installation
+manifest. Run `upgrade --apply` to materialize a current manifest; Triad+ does
+not infer the old version. The same `upgrade --apply` command is the managed
+restore path after a safe uninstall leaves an `uninstalled` or `partial`
+manifest: it re-materializes managed assets and reuses the preserved team
+configuration and user state. `init` is reserved for first installation and
+refuses existing paths. `manifest invalid` means the ownership record or its
+fingerprint is malformed and should be reviewed before any uninstall.
+
+Doctor also reports `CLI newer / upgrade available` and `CLI older than
+installed version` instead of silently claiming compatibility. It never checks
+the npm `latest` tag.
+
 `not installed` means the selected adapter assets are absent from that control
 workspace. `not installed or version unavailable` for a host means its binary is
 not on PATH or otherwise cannot answer `--version`. Re-run the appropriate host
@@ -20,3 +40,24 @@ baselines, worktree, branch, and candidate. Do not treat it as a passing test.
 
 If Evaluator+ is unavailable, check `roles.evaluator.enabled` in the team file.
 An Evaluator+ failure is post-run information, not an automatic repair request.
+
+## Safe uninstall
+
+Uninstall is a dry run unless `--apply` is supplied:
+
+```bash
+npx triad-plus uninstall --host <runtime> --control /path/to/triad-control
+npx triad-plus uninstall --host <runtime> --control /path/to/triad-control --apply
+```
+
+Only unchanged files listed in `.triad-plus/installation.json` are removed.
+`ABSENT` files are harmless. A `PRESERVE` line means the file was modified, no
+longer matches the trusted managed plan, or is not a regular file; no force
+option exists for this operation. Add `--global` only when user-level Triad
+assets should also be considered. Global assets are nevertheless preserved by
+default because another workspace may share them. Team config, loop state,
+cards, artifacts, evidence, generic host directories, and other user files are
+preserved. A managed `AGENTS.md` block is removed only when its exact markers
+and hash still match; a modified or ambiguous block leaves the uninstall
+partial. `version` and `uninstall` reject nonexistent control paths without
+creating them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triad-plus",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "A lightweight, evidence-backed engineering loop for coding agents.",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,7 +28,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node tests/runtime-forward-test.mjs && node tests/retry-scope-contracts-test.mjs && node tests/cli-install-test.mjs && node tests/codex-liveness-test.mjs && node tests/bmad-story-importer-test.mjs && node tests/bmad-epics-intake-test.mjs && node tests/immutable-quality-contract-test.mjs && node tests/assignment-packet-test.mjs && node tests/repository-context-test.mjs && node tests/tui-model-configuration-test.mjs",
+    "test": "node tests/runtime-forward-test.mjs && node tests/retry-scope-contracts-test.mjs && node tests/cli-install-test.mjs && node tests/installation-manifest-test.mjs && node tests/codex-liveness-test.mjs && node tests/bmad-story-importer-test.mjs && node tests/bmad-epics-intake-test.mjs && node tests/immutable-quality-contract-test.mjs && node tests/assignment-packet-test.mjs && node tests/repository-context-test.mjs && node tests/tui-model-configuration-test.mjs",
     "pack:check": "npm pack --dry-run"
   },
   "repository": {

package/runtime/lib/installation-manifest.mjs

@@ -0,0 +1,269 @@
+import { createHash } from 'node:crypto';
+import { access, lstat, mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const INSTALLATION_MANIFEST_SCHEMA_VERSION = 1;
+export const INSTALLATION_MANIFEST_PATH = '.triad-plus/installation.json';
+
+const SHA256 = /^[a-f0-9]{64}$/i;
+const SCOPES = new Set(['project', 'global']);
+const SCOPE_STATES = new Set(['installed', 'partial', 'uninstalled', 'not_configured']);
+const TOP_LEVEL_KEYS = new Set([
+  'schema_version',
+  'triad_version',
+  'adapter',
+  'installed_at',
+  'updated_at',
+  'uninstalled_at',
+  'scopes',
+  'scope_status',
+  'managed_assets',
+  'status',
+  'fingerprint'
+]);
+const ASSET_KEYS = new Set(['scope', 'path', 'kind', 'sha256', 'start_marker', 'end_marker']);
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = 'installation_manifest_invalid';
+  return error;
+}
+
+function objectLike(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function digest(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+/**
+ * Return a stable JSON-compatible value with object keys ordered recursively.
+ * Array order is intentionally preserved because the manifest is an ordered
+ * record of the managed install plan.
+ */
+export function canonicalize(value) {
+  if (Array.isArray(value)) return value.map((item) => canonicalize(item));
+  if (!objectLike(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+export function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+export function installationManifestPayload(manifest) {
+  const { fingerprint: _fingerprint, ...payload } = manifest;
+  return payload;
+}
+
+export function installationManifestFingerprint(manifest) {
+  return digest(canonicalJson(installationManifestPayload(manifest)));
+}
+
+function normalizeRelative(value) {
+  if (typeof value !== 'string' || !value.trim()) throw invalid('installation manifest asset path must be non-empty');
+  if (value.includes('\0') || path.isAbsolute(value)) throw invalid(`installation manifest project path must be relative: ${value}`);
+  const normalized = value.split(path.sep).join('/');
+  const parts = normalized.split('/');
+  if (parts.some((part) => !part || part === '.' || part === '..')) {
+    throw invalid(`installation manifest path contains traversal or empty segments: ${value}`);
+  }
+  if (path.posix.normalize(normalized) !== normalized) throw invalid(`installation manifest path is not normalized: ${value}`);
+  return normalized;
+}
+
+function normalizeAbsolute(value) {
+  if (typeof value !== 'string' || !value.trim() || value.includes('\0') || !path.isAbsolute(value)) {
+    throw invalid(`installation manifest global path must be absolute: ${value}`);
+  }
+  const normalized = path.resolve(value);
+  if (normalized !== value) throw invalid(`installation manifest global path is not normalized: ${value}`);
+  return normalized;
+}
+
+function validateTimestamp(value, label) {
+  if (typeof value !== 'string' || !value.trim() || Number.isNaN(Date.parse(value))) {
+    throw invalid(`installation manifest ${label} must be an ISO timestamp`);
+  }
+}
+
+function rejectUnknown(value, allowed, label) {
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw invalid(`${label} has unknown property: ${key}`);
+}
+
+/** Validate a manifest, including its self-declared fingerprint. */
+export function validateInstallationManifest(manifest) {
+  if (!objectLike(manifest)) throw invalid('installation manifest must be a JSON object');
+  rejectUnknown(manifest, TOP_LEVEL_KEYS, 'installation manifest');
+  if (manifest.schema_version !== INSTALLATION_MANIFEST_SCHEMA_VERSION) {
+    throw invalid(`installation manifest schema_version must be ${INSTALLATION_MANIFEST_SCHEMA_VERSION}`);
+  }
+  if (typeof manifest.triad_version !== 'string' || !manifest.triad_version.trim()) throw invalid('installation manifest triad_version must be non-empty');
+  if (typeof manifest.adapter !== 'string' || !manifest.adapter.trim()) throw invalid('installation manifest adapter must be non-empty');
+  validateTimestamp(manifest.installed_at, 'installed_at');
+  validateTimestamp(manifest.updated_at, 'updated_at');
+  if (manifest.uninstalled_at !== undefined) validateTimestamp(manifest.uninstalled_at, 'uninstalled_at');
+
+  if (!objectLike(manifest.scopes)) throw invalid('installation manifest scopes must be an object');
+  rejectUnknown(manifest.scopes, SCOPES, 'installation manifest scopes');
+  if (typeof manifest.scopes.project !== 'boolean' || typeof manifest.scopes.global !== 'boolean') {
+    throw invalid('installation manifest scopes.project and scopes.global must be booleans');
+  }
+
+  if (manifest.scope_status !== undefined) {
+    if (!objectLike(manifest.scope_status)) throw invalid('installation manifest scope_status must be an object');
+    rejectUnknown(manifest.scope_status, SCOPES, 'installation manifest scope_status');
+    for (const scope of SCOPES) {
+      if (!SCOPE_STATES.has(manifest.scope_status[scope])) throw invalid(`installation manifest scope_status.${scope} is invalid`);
+    }
+  }
+
+  if (!Array.isArray(manifest.managed_assets)) throw invalid('installation manifest managed_assets must be an array');
+  const seen = new Set();
+  for (const asset of manifest.managed_assets) {
+    if (!objectLike(asset)) throw invalid('installation manifest managed asset must be an object');
+    rejectUnknown(asset, ASSET_KEYS, 'installation manifest managed asset');
+    if (!SCOPES.has(asset.scope)) throw invalid(`installation manifest managed asset scope is invalid: ${asset.scope}`);
+    const normalized = asset.scope === 'project' ? normalizeRelative(asset.path) : normalizeAbsolute(asset.path);
+    if (normalized !== asset.path) throw invalid(`installation manifest managed asset path is not normalized: ${asset.path}`);
+    if (asset.kind === 'file') {
+      if (asset.start_marker !== undefined || asset.end_marker !== undefined) {
+        throw invalid(`installation manifest file asset cannot contain managed block markers: ${asset.path}`);
+      }
+    } else if (asset.kind === 'managed_block') {
+      if (asset.scope !== 'project') throw invalid(`installation manifest managed block must be project-scoped: ${asset.path}`);
+      if (typeof asset.start_marker !== 'string' || !asset.start_marker || typeof asset.end_marker !== 'string' || !asset.end_marker || asset.start_marker === asset.end_marker) {
+        throw invalid(`installation manifest managed block markers are invalid: ${asset.path}`);
+      }
+    } else {
+      throw invalid(`installation manifest managed asset kind is unsupported: ${asset.kind}`);
+    }
+    if (typeof asset.sha256 !== 'string' || !SHA256.test(asset.sha256)) throw invalid(`installation manifest managed asset sha256 is invalid: ${asset.path}`);
+    const key = `${asset.scope}:${asset.path}`;
+    if (seen.has(key)) throw invalid(`installation manifest managed asset is duplicated: ${key}`);
+    seen.add(key);
+  }
+
+  if (manifest.status !== undefined && !SCOPE_STATES.has(manifest.status)) throw invalid(`installation manifest status is invalid: ${manifest.status}`);
+  if (typeof manifest.fingerprint !== 'string' || !SHA256.test(manifest.fingerprint)) throw invalid('installation manifest fingerprint is invalid');
+  const calculated = installationManifestFingerprint(manifest);
+  if (manifest.fingerprint.toLowerCase() !== calculated) throw invalid('installation manifest fingerprint does not match its contents');
+  return manifest;
+}
+
+export function installationManifestPath(controlRoot) {
+  return path.join(controlRoot, INSTALLATION_MANIFEST_PATH);
+}
+
+export async function loadInstallationManifest(controlRoot) {
+  const manifestPath = installationManifestPath(controlRoot);
+  try {
+    await access(manifestPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch (error) {
+    throw invalid(`installation manifest is not valid JSON: ${error.message}`);
+  }
+  validateInstallationManifest(manifest);
+  return { path: manifestPath, manifest };
+}
+
+export async function writeInstallationManifest(controlRoot, manifest) {
+  validateInstallationManifest(manifest);
+  const target = installationManifestPath(controlRoot);
+  await mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  await rename(temporary, target);
+  return target;
+}
+
+function within(root, target) {
+  const base = path.resolve(root);
+  const resolved = path.resolve(target);
+  return resolved === base || resolved.startsWith(`${base}${path.sep}`);
+}
+
+async function walkFiles(target, files) {
+  let info;
+  try { info = await lstat(target); } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  if (info.isDirectory()) {
+    for (const name of (await readdir(target)).sort()) await walkFiles(path.join(target, name), files);
+    return;
+  }
+  if (!info.isFile()) throw invalid(`managed installation asset is not a regular file: ${target}`);
+  files.push(target);
+}
+
+export async function sha256File(filePath) {
+  return digest(await readFile(filePath));
+}
+
+export function sha256Text(value) {
+  return digest(value);
+}
+
+/** Collect the exact regular files materialized below one or more asset roots. */
+export async function collectManagedAssetRecords(roots, { scope, baseRoot = null } = {}) {
+  if (!SCOPES.has(scope)) throw new Error(`unknown installation asset scope: ${scope}`);
+  const files = [];
+  for (const root of [...new Set(roots.map((item) => path.resolve(item)))]) await walkFiles(root, files);
+  const unique = [...new Set(files.map((item) => path.resolve(item)))].sort();
+  return Promise.all(unique.map(async (filePath) => {
+    const assetPath = scope === 'project'
+      ? path.relative(path.resolve(baseRoot), filePath).split(path.sep).join('/')
+      : filePath;
+    if (scope === 'project' && (!assetPath || assetPath.startsWith('..') || !within(baseRoot, filePath))) {
+      throw invalid(`managed project asset escaped control root: ${filePath}`);
+    }
+    return { scope, path: assetPath, kind: 'file', sha256: await sha256File(filePath) };
+  }));
+}
+
+export function buildInstallationManifest({
+  triadVersion,
+  adapter,
+  installedAt = new Date().toISOString(),
+  updatedAt = installedAt,
+  uninstalledAt,
+  scopes = { project: true, global: false },
+  scopeStatus = { project: 'installed', global: scopes.global ? 'installed' : 'not_configured' },
+  managedAssets = [],
+  status = 'installed'
+}) {
+  const manifest = {
+    schema_version: INSTALLATION_MANIFEST_SCHEMA_VERSION,
+    triad_version: triadVersion,
+    adapter,
+    installed_at: installedAt,
+    updated_at: updatedAt,
+    scopes: { project: Boolean(scopes.project), global: Boolean(scopes.global) },
+    scope_status: { project: scopeStatus.project, global: scopeStatus.global },
+    managed_assets: [...managedAssets].sort((left, right) => `${left.scope}:${left.path}`.localeCompare(`${right.scope}:${right.path}`)),
+    status
+  };
+  if (uninstalledAt) manifest.uninstalled_at = uninstalledAt;
+  manifest.fingerprint = installationManifestFingerprint(manifest);
+  validateInstallationManifest(manifest);
+  return manifest;
+}
+
+export function manifestScopeStatus(manifest, scope) {
+  if (manifest.scope_status?.[scope]) return manifest.scope_status[scope];
+  return manifest.scopes?.[scope] ? 'installed' : 'not_configured';
+}
+
+export function manifestIsUninstalled(manifest) {
+  return manifest.status === 'uninstalled' || (
+    ['project', 'global'].every((scope) => ['not_configured', 'uninstalled'].includes(manifestScopeStatus(manifest, scope)))
+  );
+}