triad-plus 1.9.0 → 1.11.0

package/docs/configuration.md

@@ -31,14 +31,65 @@ 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
+agent to show or change role models without editing host-specific files. The
+agent reads `.triad-runtime/adapter.json`, validates `.triad-plus/team.json`,
+changes only the explicitly requested `model` or `reasoning_effort` fields, and
+uses the existing managed binding path to materialize supported values. It
+reports whether each request was applied host-natively, recorded only in the
+team file, left at the host default, or unsupported. It never invents model IDs
+and never puts credentials in the configuration.
+
+The skill follows the adapter metadata: `global-profiles` writes native
+user-level profiles, `project-frontmatter` writes only the declared native
+fields (OpenCode supports model plus its native `variant`, Copilot supports
+model plus `reasoningEffort`, and Claude Code currently supports model only),
+and `team-record` records intent without fabricating a host binding. A null or
+blank value deliberately means host default. Reasoning levels are host-specific
+and are never translated between providers.
+
 For project-frontmatter adapters, `.triad-plus/team.json` remains the canonical
 source of truth. Managed installation and `upgrade --apply` re-materialize each
-configured role's supported fields after refreshing agent assets. OpenCode and
-Copilot map `model` and `reasoning_effort` to the host-native `model` and
-`reasoningEffort` fields; Claude Code currently maps `model` only. Null or blank
-values are omitted so the host uses its session default. Other adapters may
-expose different controls; Triad+ only materializes fields supported by the
-selected host.
+configured role's supported fields after refreshing agent assets. OpenCode maps
+`model` to `model` and `reasoning_effort` to its native `variant` field; Copilot
+maps the same canonical fields to `model` and `reasoningEffort`; Claude Code
+currently maps `model` only. Null or blank values are omitted so the host uses
+its session default. Other adapters may expose different controls; Triad+ only
+materializes fields supported by the selected host. A host/session default is
+distinct from a role-agent binding.
 
 ## Retry and scope policy
 

package/docs/npx-installation.md

@@ -10,6 +10,10 @@ npx triad-plus
 The interactive setup selects a host, optional user-level command, language,
 owner address, role display names/personas, models, and whether the optional
 Evaluator+ is enabled. It changes files only after `install` is typed.
+Before confirmation it prints a compact summary of the host, control workspace,
+interaction settings, Evaluator+, and each role's model/binding. Colors are
+used only for an interactive terminal and are disabled by `NO_COLOR` or when
+output is not a TTY.
 
 For repeatable setup:
 
@@ -18,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
@@ -46,6 +107,18 @@ personas, models, and supported effort/options. Existing schema-version-1 team
 files remain valid. Core roles are always enabled; Evaluator+ is enabled only
 when `roles.evaluator.enabled` is `true`.
 
+The shared `triad-model-configuration` skill is installed with the selected
+adapter. Ask the host agent to inspect or change a role model; it keeps
+`.triad-plus/team.json` as the source of truth and re-materializes only fields
+the adapter declares as host-native. Unsupported fields are reported rather
+than silently substituted.
+
+For OpenCode, the canonical `reasoning_effort` value is materialized as the
+native per-agent `variant` field. Copilot uses its own native
+`reasoningEffort` field; these host contracts are intentionally not inferred
+from one another. The active host/session default remains separate from a
+materialized role profile.
+
 | Role | Responsibility |
 | --- | --- |
 | Orchestrator | Maintains goal/context and decides the next step. |

package/docs/opencode-replication.md

@@ -7,3 +7,11 @@ command assets carry the configured role models where OpenCode supports them.
 Verification uses explicit Orchestrator dispatch. A configured Evaluator+ is
 automatically invoked only after a Reviewer-approved result; it cannot reopen
 that run.
+
+`.triad-plus/team.json` is the desired source of truth for OpenCode role
+configuration. Triad+ materializes each supported role's `model` and native
+`variant` (from `reasoning_effort`) in `.opencode/agents/*.md` during init and
+after `upgrade --apply`. A null value leaves that field absent so OpenCode uses
+its host/session default. The OpenCode session default is independent of these
+per-agent bindings; use `opencode models` to inspect available IDs and
+variants.

package/docs/runtimes.md

@@ -49,6 +49,6 @@ validated independently as well.
 ## OpenCode
 
 Use the interactive OpenCode TUI for complete multi-step Triad runs. OpenCode
-1.18.0 validated the full Orchestrator → Developer → verifier → Reviewer →
+1.18.x validated the full Orchestrator → Developer → verifier → Reviewer →
 configured Evaluator+ lifecycle in the TUI. `opencode run` is useful for
 one-shot work but does not retain that multi-step parent/subagent lifecycle.

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.9.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",
+    "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/assignment-packet.mjs

@@ -3,6 +3,7 @@ import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { writeAtomicJson } from "./evidence.mjs";
 import { worktreeBranch } from "./fingerprint.mjs";
+import { inspectRepositoryContext } from "./repository-context.mjs";
 
 const SHA256 = /^[a-f0-9]{64}$/i;
 const PACKET_START = "<!-- triad-plus-assignment-packet:start -->";
@@ -227,6 +228,19 @@ async function resolveProjectRepository(root, assignment, worktree, external) {
   return matches.length === 1 ? matches[0].id : "declared-worktree";
 }
 
+async function repositoryMappingDetails(root, repository) {
+  if (!repository) return null;
+  const mapping = (await projectRepositoryMappings(root)).find((entry) => entry.id === repository);
+  if (!mapping) return null;
+  const declared = mapping.worktree || mapping.path;
+  return {
+    id: mapping.id,
+    path: mapping.path,
+    worktree: mapping.worktree,
+    resolved_worktree: declared ? await realpath(declaredPath(root, declared)).catch(() => null) : null
+  };
+}
+
 function section(source, names) {
   const wanted = new Set(names.map((name) => name.toLowerCase()));
   const lines = source.split("\n");
@@ -316,6 +330,21 @@ export async function resolveAssignmentContext(assignment, { projectRoot = proce
     throw packetError("assignment_packet_invalid", `worktree branch does not match assignment: ${branch}`);
   }
   const repository = await resolveProjectRepository(root, assignment, worktree, external);
+  const repositoryMapping = await repositoryMappingDetails(root, repository);
+  const requiredSkills = Array.isArray(assignment.required_repository_skills) ? assignment.required_repository_skills : [];
+  let repositoryContext;
+  try {
+    repositoryContext = await inspectRepositoryContext({ worktree, requiredSkills });
+  } catch (error) {
+    error.repositoryContext = error.repositoryContext ?? null;
+    throw error;
+  }
+  if (repositoryContext.status !== "pass") {
+    const details = repositoryContext.issues.map((item) => item.message).join("; ");
+    const error = packetError("repository_context_invalid", details || "assigned repository context is invalid");
+    error.repositoryContext = repositoryContext;
+    throw error;
+  }
   return {
     projectRoot: root,
     controlWorkspace: root,
@@ -324,11 +353,13 @@ export async function resolveAssignmentContext(assignment, { projectRoot = proce
     external,
     branch,
     repository,
+    repositoryMapping,
+    repositoryContext,
     declaredWorktree: assignment.worktree,
     cardPath: assignment.card_path ? relativeProjectPath(root, assignment.card_path, "card path") : null,
     prdPath: assignment.prd_path ? relativeProjectPath(root, assignment.prd_path, "PRD path") : null,
     gatesPath: assignment.gates_path ? relativeProjectPath(root, assignment.gates_path, "gates path") : null,
-    requiredSkills: Array.isArray(assignment.required_repository_skills) ? assignment.required_repository_skills : [],
+    requiredSkills,
   };
 }
 
@@ -341,6 +372,7 @@ function packetMetadata(assignment, context, packetPath) {
     feature_id: assignment.feature_id,
     attempt: assignment.attempt,
     repository: context.repository,
+    repository_mapping: context.repositoryMapping,
     branch: context.branch,
     worktree: context.declaredWorktree,
     control_workspace: ".",
@@ -357,6 +389,11 @@ function packetMetadata(assignment, context, packetPath) {
     },
     required_gate_ids: Array.isArray(assignment.required_gate_ids) ? assignment.required_gate_ids : [],
     mandatory_skills: context.requiredSkills.map((skill) => ({ path: skill.path, sha256: skill.sha256 })),
+    repository_context: {
+      assigned_worktree: context.repositoryContext.assigned_worktree,
+      assigned_git_top_level: context.repositoryContext.assigned_git_top_level,
+      skills: context.repositoryContext.skills
+    },
   });
 }
 

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)))
+  );
+}