@uniqbit/mate-core 0.17.0-canary.8 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.17.0-canary.8",
+  "version": "0.17.1",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [
@@ -16,6 +16,7 @@
     "./plugins": "./src/plugins.ts",
     "./runtime": "./src/runtime/index.ts",
     "./opencode": "./src/opencode/index.ts",
+    "./opencode/tui": "./src/opencode/tui.tsx",
     "./tui": "./src/tui.ts"
   },
   "publishConfig": {
@@ -31,11 +32,16 @@
     "format:check": "oxfmt src/ \"!**/*.generated.*\" \"!**/report-assets/**\" --check"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.18.3",
-    "@opentui/core": "^0.4.5",
-    "@opentui/keymap": "^0.4.5",
-    "@opentui/solid": "^0.4.5",
+    "@opencode/plugin": "^2.0.23",
+    "@opentui/core": "^0.5.14",
+    "@opentui/keymap": "^0.5.14",
+    "@opentui/solid": "^0.5.14",
     "@tanstack/highlight": "0.0.10",
+    "@xterm/addon-clipboard": "^0.2.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-unicode11": "^0.9.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
     "hono": "^4.13.5",
     "ink": "^7.1.0",
     "react": "^19.2.7",

package/src/cli/commands/artifact/finish/index.ts

@@ -1,10 +1 @@
 export { runArtifactPublishCommand } from "./command";
-export type { PublishCommandDeps } from "./command";
-export type { FinishResult, FinishStep, FinishStatus } from "./engine";
-export type {
-  ArtifactFinisher,
-  FinishContext,
-  FinisherFactory,
-  Produced,
-  ResolveResult,
-} from "./finisher";

package/src/cli/commands/artifact/finish/openspec.ts

@@ -269,7 +269,7 @@ async function resolved(
 }
 
 /** Tag namespace segregating spec publications from dated change anchors. */
-export const SPEC_TAG_NAMESPACE = "openspec/specs";
+const SPEC_TAG_NAMESPACE = "openspec/specs";
 /** Spec ids named individually before the remainder collapses into a count. */
 const SPEC_LABEL_LIMIT = 3;
 
@@ -297,7 +297,7 @@ function specLabel(paths: string[]): string {
 }
 
 /** Commit subject for a spec publication; it belongs to no change, so it names specs, never an anchor. */
-export function specCommitSubject(paths: string[]): string {
+function specCommitSubject(paths: string[]): string {
   const ids = specIds(paths);
   const named = ids.slice(0, SPEC_LABEL_LIMIT);
   const remaining = ids.length - named.length;

package/src/cli/commands/artifact/finish/registry.ts

@@ -5,7 +5,7 @@ import { openspecFinisher } from "./openspec";
  * Artifact-kind → finisher factory. openspec is the only kind for now; a future ADR
  * finisher registers here and is selected via `--type`, with no engine changes.
  */
-export const FINISHERS: Record<string, FinisherFactory> = {
+const FINISHERS: Record<string, FinisherFactory> = {
   openspec: openspecFinisher,
 };
 

package/src/cli/commands/artifact/pending/discovery.ts

@@ -52,7 +52,7 @@ export interface ArchiveEntry {
 const ARCHIVE_ANCHOR_PATTERN = /^\d{4}-\d{2}-\d{2}-.+$/;
 const ARCHIVE_DATE_PREFIX = /^\d{4}-\d{2}-\d{2}-/;
 
-export const ARCHIVE_RELATIVE_DIR = "openspec/changes/archive";
+const ARCHIVE_RELATIVE_DIR = "openspec/changes/archive";
 export const SPECS_RELATIVE_DIR = "openspec/specs";
 
 /** The tag `mate artifact publish` creates, never a recomputed date. */

package/src/cli/commands/artifact/pending/index.ts

@@ -1,17 +1 @@
 export { runArtifactPendingCommand } from "./command";
-export type { PendingCommandDeps, PendingResult } from "./command";
-export {
-  ARCHIVE_RELATIVE_DIR,
-  SPECS_RELATIVE_DIR,
-  discoverArchives,
-  finishMarker,
-  pendingArchives,
-  unattributedSpecs,
-} from "./discovery";
-export type {
-  ArchiveEntry,
-  CommitState,
-  SpecAttribution,
-  UnattributedSpec,
-  UncommittedSpecChange,
-} from "./discovery";

package/src/cli/commands/cap/graphify.ts

@@ -29,7 +29,7 @@ const GRAPHIFY_PATH_COMMANDS = new Set([
 
 const GRAPHIFY_GRAPH_COMMANDS = new Set(["query", "path", "explain", "affected", "tree"]);
 
-export function deriveGraphifyPaths(companionPath: string, repositoryId: string): GraphifyPaths {
+function deriveGraphifyPaths(companionPath: string, repositoryId: string): GraphifyPaths {
   const graphifyOut = path.join(
     companionPath,
     GRAPHIFY_STORE_SEGMENT,

package/src/cli/commands/cap/index-cmd.ts

@@ -159,7 +159,7 @@ export async function runIndexCapCommand(args: string[], deps: SyncCapDeps = {})
     const repoPath = process.env.MATE_REPO_PATH ?? process.cwd();
     if (!(await isTokensaveInitialized())) {
       await ensureStoreExcluded(repoPath);
-      const initOk = await runCapStep(() => runTokensave(["init"]));
+      const initOk = await runCapStep(() => runTokensave(["init", "--no-git-hook"]));
       if (!initOk) {
         failed = true;
         onStepDone("tokensave", false);

package/src/cli/commands/cap/tokensave.ts

@@ -15,8 +15,9 @@ interface TokensaveCapDeps {
  * @description Forwards `[...args]` to the `tokensave` CLI, run from the
  * active working repository. Requires the `tokensave` capability to be enabled
  * in `.mate/config/framework.yaml` and a registered working repo for the
- * current `MATE_REPO_ID`. Ensures the `tokensave` binary is installed and
- * upgraded in that repo (via {@link ensureTokensaveInstalled}) before forwarding.
+ * current `MATE_REPO_ID`. Ensures the `tokensave` binary is installed in that
+ * repo (via {@link ensureTokensaveInstalled}) before forwarding. Never upgrades:
+ * this runs mid-session (e.g. `mate cap index`), and upgrades belong to `mate setup`.
  * @remarks The child process's exit code is propagated via `process.exitCode`.
  */
 export async function runTokensaveCapCommand(
@@ -49,7 +50,7 @@ export async function runTokensaveCapCommand(
     return;
   }
 
-  if (!(await ensureInstalled(repo.path, { upgrade: true }))) {
+  if (!(await ensureInstalled(repo.path))) {
     process.exitCode = 1;
     return;
   }

package/src/cli/commands/companion/companion.ts

@@ -5,6 +5,7 @@ import { runCompanionPrepareCommand } from "./prepare";
 import { runSetupCommand } from "../setup";
 import { runCompanionListCommand } from "./list";
 import { runCompanionSyncCommand } from "./sync";
+import { runCompanionUpdateCommand } from "./update";
 import { runWorkspaceOpenCommand } from "./open";
 import { runCompanionTuiCommand } from "./tui";
 
@@ -31,6 +32,9 @@ export async function runCompanionCommand(
     case "sync":
       await runCompanionSyncCommand();
       return;
+    case "update":
+      await runCompanionUpdateCommand(argv);
+      return;
     case "open":
       await runWorkspaceOpenCommand();
       return;

package/src/cli/commands/companion/hub.ts

@@ -8,6 +8,7 @@ import {
   updateHubPlugins,
 } from "../../../lib/orchestrator/companion-hub";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
+import { writeJsonStdout } from "../../write-json-stdout";
 
 function positionalArgs(argv: string[]): string[] {
   const values: string[] = [];
@@ -71,7 +72,7 @@ async function runHubSync(argv: string[]): Promise<void> {
   const results = await syncHub(process.cwd());
   const plugins = await updateHubPlugins(process.cwd());
   if (argv.includes("--json")) {
-    console.log(JSON.stringify({ companions: results, plugins }));
+    await writeJsonStdout({ companions: results, plugins }, { space: 0 });
     return;
   }
   for (const result of results) console.log(`${result.id}: ${result.status} (${result.message})`);

package/src/cli/commands/companion/list.ts

@@ -1,6 +1,7 @@
 import { CompanionStore } from "../../../lib/orchestrator/companion-store";
 import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-context";
 import { renderRepoListTable } from "../../repo-list-table";
+import { writeJsonStdout } from "../../write-json-stdout";
 
 /**
  * @command mate companion list
@@ -23,7 +24,7 @@ export async function runCompanionListCommand(argv: string[] = []): Promise<void
   const forceJson = argv.includes("--json");
 
   if (forceJson || !process.stdout.isTTY) {
-    console.log(JSON.stringify({ repositories }, null, 2));
+    await writeJsonStdout({ repositories });
     return;
   }
 

package/src/cli/commands/companion/prepare.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { preparePrebuiltWorkspace } from "../../../lib/prebuilt-workspace-prepare";
 
-export const companionPrepareCommandDeps = {
+const companionPrepareCommandDeps = {
   preparePrebuiltWorkspace,
 };
 
@@ -13,7 +13,7 @@ interface ParsedPrepareArgs {
   error?: string;
 }
 
-export function parsePrepareArgs(argv: string[]): ParsedPrepareArgs {
+function parsePrepareArgs(argv: string[]): ParsedPrepareArgs {
   let bundle: string | undefined;
   const positional: string[] = [];
 

package/src/cli/commands/companion/update.ts

@@ -0,0 +1,334 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import { ConfigStore } from "../../../lib/orchestrator/config-store";
+import type { FrameworkConfig } from "../../../lib/orchestrator/types";
+import { YamlFileStore } from "../../../lib/orchestrator/yaml-file-store";
+import {
+  fetchLatestVersion,
+  getCurrentVersion,
+  isCanaryVersion,
+  isNewer,
+} from "../../../lib/update-checker";
+import { resolveCompanionRuntime } from "../../../runtime/env";
+import { syncCompanionFiles } from "../../../tools/setup";
+import { runCommand } from "../../../tools/setup/utils";
+import { confirm } from "../../confirm";
+import { defaultGitOps, type GitOps } from "../artifact/finish/git";
+import { resolveCompanionPath } from "./tui";
+
+/** Snapshot marker for a changed path that no longer exists on disk. */
+export const DELETED = "<deleted>";
+
+const SKILLS_LOCKFILE = "skills-lock.json";
+
+/**
+ * OpenSpec CLI output (skills and opsx commands): fully regenerated by every update, so
+ * pre-existing uncommitted edits there are stale output, never local work worth separating.
+ */
+const OPENSPEC_GENERATED = [
+  /^\.(claude|opencode)\/skills\/openspec-[^/]+(\/|$)/,
+  /^\.claude\/commands\/opsx(\/|$)/,
+  /^\.opencode\/commands\/opsx-[^/]+$/,
+];
+
+export function isOpenSpecGenerated(relativePath: string): boolean {
+  return OPENSPEC_GENERATED.some((pattern) => pattern.test(relativePath));
+}
+
+function frameworkConfigPath(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
+}
+
+/**
+ * Raw view of `framework.yaml`: `ConfigStore.load()` merges defaults, so saving
+ * its result would add keys the companion never declared.
+ */
+class RawFrameworkConfigStore extends YamlFileStore<Record<string, unknown>> {
+  protected onMissing(): Promise<Record<string, unknown>> {
+    return Promise.resolve({});
+  }
+}
+
+async function hashTree(absolute: string, hash: crypto.Hash, relative: string): Promise<void> {
+  const stat = await fs.lstat(absolute);
+  if (stat.isDirectory()) {
+    const entries = (await fs.readdir(absolute)).toSorted();
+    for (const entry of entries) {
+      await hashTree(path.join(absolute, entry), hash, path.posix.join(relative, entry));
+    }
+    return;
+  }
+  hash.update(`${relative}\0`);
+  hash.update(stat.isSymbolicLink() ? await fs.readlink(absolute) : await fs.readFile(absolute));
+  hash.update("\0");
+}
+
+/** Porcelain collapses an untracked directory into one `dir/` entry, so directories hash their whole tree. */
+async function snapshotPath(companionPath: string, relativePath: string): Promise<string> {
+  const absolute = path.join(companionPath, relativePath);
+  try {
+    const hash = crypto.createHash("sha256");
+    await hashTree(absolute, hash, ".");
+    return hash.digest("hex");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return DELETED;
+    throw error;
+  }
+}
+
+export interface CompanionUpdateDeps {
+  resolveCompanionPath: typeof resolveCompanionPath;
+  resolveProjectedCompanionPath: (cwd: string) => string | undefined;
+  getCurrentVersion: () => string;
+  fetchLatestVersion: () => Promise<string>;
+  loadConfig: (companionPath: string) => Promise<FrameworkConfig>;
+  syncCompanionFiles: (companionPath: string, config: FrameworkConfig) => Promise<void>;
+  /** Returns true when the file was rewritten. */
+  writeEngineFloor: (companionPath: string, range: string) => Promise<boolean>;
+  hasSkillsLock: (companionPath: string) => Promise<boolean>;
+  runSkillsUpdate: (companionPath: string) => Promise<void>;
+  createGitOps: (companionPath: string) => GitOps;
+  snapshotPath: (companionPath: string, relativePath: string) => Promise<string>;
+  confirm: (question: string) => Promise<boolean>;
+  isInteractive: () => boolean;
+}
+
+export const companionUpdateDeps: CompanionUpdateDeps = {
+  resolveCompanionPath,
+  resolveProjectedCompanionPath: (cwd) =>
+    resolveCompanionRuntime(process.env, cwd).context.companionPath || undefined,
+  getCurrentVersion,
+  fetchLatestVersion,
+  loadConfig: (companionPath) => new ConfigStore(frameworkConfigPath(companionPath)).load(),
+  syncCompanionFiles,
+  async writeEngineFloor(companionPath, range) {
+    const store = new RawFrameworkConfigStore(frameworkConfigPath(companionPath));
+    const raw = (await store.load()) ?? {};
+    const engines = (raw.engines ?? {}) as Record<string, string>;
+    if (engines[FRAMEWORK_NAME] === range) return false;
+    await store.save({ ...raw, engines: { ...engines, [FRAMEWORK_NAME]: range } });
+    return true;
+  },
+  hasSkillsLock: (companionPath) =>
+    fs
+      .access(path.join(companionPath, SKILLS_LOCKFILE))
+      .then(() => true)
+      .catch(() => false),
+  runSkillsUpdate: (companionPath) =>
+    runCommand("npx", ["skills", "update", "-p", "-y"], { cwd: companionPath }),
+  createGitOps: (companionPath) => defaultGitOps(companionPath, undefined),
+  snapshotPath,
+  confirm,
+  isInteractive: () => !!(process.stdin.isTTY && process.stdout.isTTY),
+};
+
+export interface UpdateChanges {
+  written: string[];
+  conflict: string[];
+}
+
+/** Content snapshot of every uncommitted path, taken before the update writes. */
+export async function snapshotChangedPaths(
+  companionPath: string,
+  git: GitOps,
+): Promise<Map<string, string>> {
+  const before = new Map<string, string>();
+  for (const changed of await git.changedPaths()) {
+    before.set(changed, await companionUpdateDeps.snapshotPath(companionPath, changed));
+  }
+  return before;
+}
+
+/** Paths the update wrote, and the subset that already carried local edits (design D4). */
+export async function diffChangedPaths(
+  companionPath: string,
+  git: GitOps,
+  before: Map<string, string>,
+): Promise<UpdateChanges> {
+  const written: string[] = [];
+  const conflict: string[] = [];
+  for (const changed of await git.changedPaths()) {
+    if (!before.has(changed)) written.push(changed);
+  }
+  for (const [changed, hash] of before) {
+    if ((await companionUpdateDeps.snapshotPath(companionPath, changed)) === hash) continue;
+    written.push(changed);
+    if (!isOpenSpecGenerated(changed)) conflict.push(changed);
+  }
+  return { written: written.toSorted(), conflict: conflict.toSorted() };
+}
+
+async function resolveCompanion(cwd: string): Promise<string | undefined> {
+  const resolved = await companionUpdateDeps.resolveCompanionPath(cwd);
+  if (resolved) return resolved;
+  return companionUpdateDeps.resolveProjectedCompanionPath(cwd);
+}
+
+function fail(message: string): void {
+  process.stderr.write(`${FRAMEWORK_NAME}: ${message}\n`);
+  process.exitCode = 1;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function listPaths(paths: string[]): string {
+  return paths.map((changed) => `  ${changed}`).join("\n");
+}
+
+/** Version precondition; returns the running version when the update may proceed. */
+async function checkVersion(): Promise<string | undefined> {
+  const current = companionUpdateDeps.getCurrentVersion();
+  if (isCanaryVersion(current)) {
+    fail(
+      `\`${FRAMEWORK_NAME} companion update\` requires a stable ${FRAMEWORK_NAME}; ${current} is a prerelease.`,
+    );
+    return undefined;
+  }
+  let latest: string;
+  try {
+    latest = await companionUpdateDeps.fetchLatestVersion();
+  } catch (error) {
+    fail(`could not check the registry for the newest version: ${errorMessage(error)}`);
+    return undefined;
+  }
+  if (isNewer(latest, current)) {
+    fail(
+      [
+        `${current} is installed, but the newest stable version is ${latest}.`,
+        `  Run \`${FRAMEWORK_NAME} update\` first.`,
+      ].join("\n"),
+    );
+    return undefined;
+  }
+  return current;
+}
+
+async function commitAndPush(
+  git: GitOps,
+  written: string[],
+  version: string,
+  yes: boolean,
+): Promise<void> {
+  if (!yes && !companionUpdateDeps.isInteractive()) {
+    process.stdout.write(
+      `${FRAMEWORK_NAME}: not an interactive shell; changes left uncommitted. Re-run with --yes to commit and push.\n`,
+    );
+    return;
+  }
+
+  const message = `chore(${FRAMEWORK_NAME}): update companion to ${FRAMEWORK_NAME} ${version}`;
+  if (!yes && !(await companionUpdateDeps.confirm(`Commit as "${message}"?`))) {
+    process.stdout.write(`${FRAMEWORK_NAME}: changes left uncommitted.\n`);
+    return;
+  }
+  try {
+    await git.add(written);
+    await git.commit(message, written);
+  } catch (error) {
+    fail(`commit failed: ${errorMessage(error)}`);
+    return;
+  }
+  process.stdout.write(`${FRAMEWORK_NAME}: committed "${message}".\n`);
+
+  if (!yes && !(await companionUpdateDeps.confirm("Push the commit?"))) return;
+  if (!(await git.hasUpstream())) {
+    process.stdout.write(
+      `${FRAMEWORK_NAME}: the current branch has no upstream; the commit stays local.\n`,
+    );
+    return;
+  }
+  const pushed = await git.push();
+  if (!pushed.ok) {
+    fail(`push failed; the commit stays local.\n  ${pushed.error}`);
+    return;
+  }
+  process.stdout.write(`${FRAMEWORK_NAME}: pushed.\n`);
+}
+
+/**
+ * @command mate companion update
+ * @description Regenerates the companion's Mate-managed files and skills with
+ * the newest stable Mate, raises `engines.mate` to match, and offers to commit
+ * and push exactly the files the update wrote.
+ */
+export async function runCompanionUpdateCommand(argv: string[]): Promise<void> {
+  const unknown = argv.filter((arg) => arg !== "--yes");
+  if (unknown.length > 0) {
+    fail(`unknown argument for companion update: ${unknown.join(" ")}`);
+    return;
+  }
+  const yes = argv.includes("--yes");
+
+  const companionPath = await resolveCompanion(process.cwd());
+  if (!companionPath) {
+    fail(
+      `no companion resolves for this directory. Run \`${FRAMEWORK_NAME} companion link\` first.`,
+    );
+    return;
+  }
+
+  const version = await checkVersion();
+  if (!version) return;
+
+  let git: GitOps;
+  let before: Map<string, string>;
+  try {
+    git = companionUpdateDeps.createGitOps(companionPath);
+    before = await snapshotChangedPaths(companionPath, git);
+  } catch (error) {
+    fail(errorMessage(error));
+    return;
+  }
+
+  try {
+    const config = await companionUpdateDeps.loadConfig(companionPath);
+    await companionUpdateDeps.syncCompanionFiles(companionPath, config);
+  } catch (error) {
+    fail(`companion file synchronization failed: ${errorMessage(error)}`);
+    return;
+  }
+
+  if (await companionUpdateDeps.hasSkillsLock(companionPath)) {
+    try {
+      await companionUpdateDeps.runSkillsUpdate(companionPath);
+    } catch (error) {
+      process.stderr.write(
+        `${FRAMEWORK_NAME}: warning: third-party skill refresh failed: ${errorMessage(error)}\n`,
+      );
+    }
+  }
+
+  try {
+    await companionUpdateDeps.writeEngineFloor(companionPath, `>=${version}`);
+  } catch (error) {
+    fail(`could not set engines.${FRAMEWORK_NAME}: ${errorMessage(error)}`);
+    return;
+  }
+
+  const { written, conflict } = await diffChangedPaths(companionPath, git, before);
+  if (written.length === 0) {
+    process.stdout.write(
+      `${FRAMEWORK_NAME}: ${companionPath} is already up to date with ${FRAMEWORK_NAME} ${version}.\n`,
+    );
+    return;
+  }
+  if (conflict.length > 0) {
+    fail(
+      [
+        "the update rewrote files that already had uncommitted changes; local edits and update output can no longer be separated, so nothing is committed:",
+        listPaths(conflict),
+      ].join("\n"),
+    );
+    return;
+  }
+
+  process.stdout.write(
+    [`${FRAMEWORK_NAME}: the update changed ${companionPath}:`, listPaths(written), ""].join("\n"),
+  );
+  await commitAndPush(git, written, version, yes);
+}

package/src/cli/commands/doctor.ts

@@ -10,6 +10,7 @@ import { resolveRootContext, type RootContext } from "../../lib/orchestrator/roo
 import type { CapabilityConfig, FrameworkConfig, HubMember } from "../../lib/orchestrator/types";
 import { getRequiredPluginDrift } from "../../tools/setup/policy";
 import { resolveCommandOnPath } from "../../tools/setup/utils";
+import { writeJsonStdout } from "../write-json-stdout";
 import { printSection, renderKeyValueTable, renderTable } from "./status";
 
 interface DoctorDeps {
@@ -354,7 +355,7 @@ function renderHumanReport(report: DoctorReport): void {
 export async function runDoctorCommand(argv: string[] = [], deps: DoctorDeps = {}): Promise<void> {
   const report = await collectDoctorReport(deps);
   if (argv.includes("--json")) {
-    console.log(JSON.stringify(report, null, 2));
+    await writeJsonStdout(report);
     return;
   }
   renderHumanReport(report);

package/src/cli/commands/install.ts

@@ -15,8 +15,14 @@ import {
   type PluginInstallResult,
 } from "../../tools/setup/dynamic-plugins/install";
 import { registryConfigHint } from "../../tools/setup/dynamic-plugins/registry-hint";
+import {
+  FrozenInstallError,
+  installDeclaredPluginsFrozen,
+} from "../../tools/setup/dynamic-plugins/frozen";
+import { verifyTrackedPluginOutputs } from "../../tools/setup/dynamic-plugins/staging";
+import { verifyDeclaredPlugins } from "../../tools/setup/dynamic-plugins/verify";
 
-export function reportPluginInstallResults(results: PluginInstallResult[]): void {
+export function reportPluginInstallResults(results: PluginInstallResult[]): boolean {
   for (const result of results) {
     if (result.status === "failed") {
       process.stderr.write(
@@ -27,6 +33,7 @@ export function reportPluginInstallResults(results: PluginInstallResult[]): void
       console.log(`  installed plugin ${result.package}@${result.resolvedVersion}`);
     }
   }
+  return results.every((result) => result.status !== "failed");
 }
 
 function printPlanText(plan: Awaited<ReturnType<typeof inspectInstallPlan>>): void {
@@ -47,10 +54,17 @@ function printPlanText(plan: Awaited<ReturnType<typeof inspectInstallPlan>>): vo
  * @description Installs and verifies the core runtime and dependencies selected by the current companion.
  * @flags
  * - `--yes` — skip confirmation; required for non-TTY execution.
+ * - `--frozen-plugins` — deployment restore: install declared plugins exactly from the committed lockfile, verify plugin-generated tracked files are committed, never rewrite tracked files.
  */
 export async function runInstallCommand(argv: string[], cwd = process.cwd()): Promise<boolean> {
   const skipConfirm = argv.includes("--yes");
+  const frozen = argv.includes("--frozen-plugins");
   const context = await resolveInstallContext(cwd);
+  if (frozen && context.kind !== "companion") {
+    process.stderr.write(`${FRAMEWORK_NAME}: --frozen-plugins requires a companion context.\n`);
+    process.exitCode = 1;
+    return false;
+  }
   if (context.kind === "ambiguous") {
     process.stderr.write(`${context.message}\n`);
     process.exitCode = 1;
@@ -64,10 +78,35 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     context.companionPath &&
     context.config.plugins?.length
   ) {
-    reportPluginInstallResults(
-      await installDeclaredPlugins(context.companionPath, context.config.plugins),
-    );
+    let results: PluginInstallResult[];
+    try {
+      results = frozen
+        ? await installDeclaredPluginsFrozen(context.companionPath, context.config.plugins)
+        : await installDeclaredPlugins(context.companionPath, context.config.plugins);
+    } catch (error) {
+      if (!(error instanceof FrozenInstallError)) throw error;
+      process.stderr.write(`${FRAMEWORK_NAME}: frozen plugin install refused: ${error.message}\n`);
+      process.exitCode = 1;
+      return false;
+    }
+    if (!reportPluginInstallResults(results)) {
+      process.stderr.write(
+        `${FRAMEWORK_NAME}: a declared plugin failed to install; installation is incomplete.\n`,
+      );
+      process.exitCode = 1;
+      return false;
+    }
     await hydrateDynamicPlugins({ companionPath: context.companionPath });
+    if (frozen) {
+      const failures = await verifyDeclaredPlugins(context.companionPath);
+      if (failures.length > 0) {
+        for (const failure of failures) {
+          process.stderr.write(`${FRAMEWORK_NAME}: plugin ${failure.package}: ${failure.reason}\n`);
+        }
+        process.exitCode = 1;
+        return false;
+      }
+    }
   }
   const plan = await inspectInstallPlan(buildInstallPlan(context));
   const missing = plan.requirements.filter((item) => !item.satisfied);
@@ -120,7 +159,22 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   }
 
   try {
-    await reconcileInstalledCompanion(plan);
+    if (frozen && plan.context.companionPath) {
+      const { syncCompanionFiles } = await import("../../tools/setup");
+      const drift = await verifyTrackedPluginOutputs(plan.context.companionPath, (staged) =>
+        syncCompanionFiles(staged, plan.context.config),
+      );
+      if (drift.length > 0) {
+        process.stderr.write(
+          `${FRAMEWORK_NAME}: plugin-generated files differ from the committed checkout: ${drift.join(", ")}\n` +
+            `Prepare and commit them in the companion's authoring flow; the checkout was left unchanged.\n`,
+        );
+        process.exitCode = 1;
+        return false;
+      }
+    } else {
+      await reconcileInstalledCompanion(plan);
+    }
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {
     process.stderr.write(