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

package/src/tools/setup/capabilities/context-mode.ts

@@ -18,6 +18,7 @@ import type {
   RuntimeContributionsByRuntime,
   SetupContext,
 } from "../plugin";
+import type { InstallRequirement } from "../install-contract";
 import { readClaudeMcpConfig } from "../providers/claude-format";
 import { getOpenCodePluginReferences, readOpenCodeConfig } from "../providers/opencode-format";
 import { pruneEmptyAncestors } from "../utils";
@@ -84,32 +85,27 @@ async function assertNoMcpConflict(ctx: SetupContext, provider: "claude" | "open
  */
 async function validateOpenCodeReferences(ctx: LaunchPreflightContext): Promise<string[]> {
   const expected = getContextModePackageReference();
-  const diagnostics: string[] = [];
-  for (const name of ["opencode.json", "tui.json"]) {
-    const configPath = path.join(ctx.companionPath, ".opencode", name);
-    const { config } = await readOpenCodeConfig(configPath);
-    const references = getOpenCodePluginReferences(config);
-    if (references.includes(expected)) continue;
+  const configPath = path.join(ctx.companionPath, ".opencode", "opencode.json");
+  const { config } = await readOpenCodeConfig(configPath);
+  const references = getOpenCodePluginReferences(config);
+  if (references.includes(expected)) return [];
 
-    const bound = references.find(
-      (reference): reference is string =>
-        typeof reference === "string" &&
-        isPreinstalledPluginPath(reference, CONTEXT_MODE_PACKAGE_NAME),
-    );
-    if (bound !== undefined) {
-      const version = await installedVersionAt(bound);
-      if (version === CONTEXT_MODE_VERSION) continue;
-      diagnostics.push(
-        `Stale context-mode package reference in ${configPath}; it points at ${bound}, which is ${version ?? "not installed"} rather than ${CONTEXT_MODE_VERSION}.`,
-      );
-      continue;
-    }
-
-    diagnostics.push(
-      `Missing or stale context-mode package reference in ${configPath}; expected ${expected}.`,
-    );
+  const bound = references.find(
+    (reference): reference is string =>
+      typeof reference === "string" &&
+      isPreinstalledPluginPath(reference, CONTEXT_MODE_PACKAGE_NAME),
+  );
+  if (bound !== undefined) {
+    const version = await installedVersionAt(bound);
+    if (version === CONTEXT_MODE_VERSION) return [];
+    return [
+      `Stale context-mode package reference in ${configPath}; it points at ${bound}, which is ${version ?? "not installed"} rather than ${CONTEXT_MODE_VERSION}.`,
+    ];
   }
-  return diagnostics;
+
+  return [
+    `Missing or stale context-mode package reference in ${configPath}; expected ${expected}.`,
+  ];
 }
 
 export function createContextModePlugin(deps: ContextModePluginDeps = {}): CapabilityPlugin {
@@ -144,7 +140,7 @@ export function createContextModePlugin(deps: ContextModePluginDeps = {}): Capab
             {
               reference: getContextModePackageReference(),
               isManagedReference: isContextModePackageReference,
-              configFiles: ["opencode.json", "tui.json"],
+              configFiles: ["opencode.json"],
               preinstalled: {
                 packageName: CONTEXT_MODE_PACKAGE_NAME,
                 version: CONTEXT_MODE_VERSION,
@@ -154,6 +150,30 @@ export function createContextModePlugin(deps: ContextModePluginDeps = {}): Capab
         },
       };
     },
+    /**
+     * The machine-local workspace is gitignored, so a fresh checkout has none;
+     * `mate install` provisions it here because sync-mode apply only validates.
+     */
+    getInstallRequirements: ({ companionPath }): InstallRequirement[] => {
+      if (!companionPath) return [];
+      const command = `npm install ${getContextModePackageReference()} (in .mate/plugins/.local)`;
+      return [
+        {
+          id: "capability:context-mode",
+          label: "Context Mode package",
+          group: "companion",
+          source: "Context Mode capability",
+          command,
+          fingerprint: `context-mode:${command}`,
+          detect: () =>
+            validatePackage(companionPath).then(
+              () => true,
+              () => false,
+            ),
+          install: () => installPackage(companionPath),
+        },
+      ];
+    },
     async apply(ctx) {
       const legacyInstallDir = getLegacyInstallDir(ctx.companionPath);
       await fs.rm(legacyInstallDir, { recursive: true, force: true });

package/src/tools/setup/capabilities/graphify-shared.ts

@@ -9,10 +9,10 @@ import {
 // guidance plugin can consume it without an import cycle.
 
 // Marker names derive from the framework identity, never the invocation name.
-export const GRAPHIFY_START = () => `<!-- ${FRAMEWORK_NAME.toUpperCase()}:GRAPHIFY:START -->`;
-export const GRAPHIFY_END = () => `<!-- ${FRAMEWORK_NAME.toUpperCase()}:GRAPHIFY:END -->`;
+const GRAPHIFY_START = () => `<!-- ${FRAMEWORK_NAME.toUpperCase()}:GRAPHIFY:START -->`;
+const GRAPHIFY_END = () => `<!-- ${FRAMEWORK_NAME.toUpperCase()}:GRAPHIFY:END -->`;
 
-export function isGraphifyHeading(line: string): boolean {
+function isGraphifyHeading(line: string): boolean {
   return /^#{1,6}\s+graphify\s*$/i.test(line);
 }
 

package/src/tools/setup/capabilities/graphify.ts

@@ -33,7 +33,7 @@ import {
 export const GRAPHIFY_STORE_SEGMENT = ".graphify";
 
 /** Skill tree the external `graphify install` CLI writes into a runtime directory. */
-export const GRAPHIFY_SKILL_NAME = "graphify";
+const GRAPHIFY_SKILL_NAME = "graphify";
 export const GRAPHIFY_OUTPUT_SUBDIR = "graphify-out";
 
 const GRAPHIFY_INSTALL_CMD = `uv tool install graphifyy`;
@@ -62,7 +62,7 @@ const GRAPHIFY_PROVIDER_DIRS: Record<string, string> = {
 export const GRAPHIFY_COMPANION_OUT_PREFIX =
   "$MATE_ARTIFACT_PATH/.graphify/$MATE_REPO_ID/graphify-out/";
 
-export const GRAPHIFY_SUPPORTED_PROVIDERS = Object.keys(GRAPHIFY_PROVIDER_DIRS);
+const GRAPHIFY_SUPPORTED_PROVIDERS = Object.keys(GRAPHIFY_PROVIDER_DIRS);
 
 const CLAUDE_MANAGED_HOOK_COMMAND_SUFFIXES = new Set([
   "/.claude/hooks/validate-artifact-path",

package/src/tools/setup/capabilities/openspec.ts

@@ -21,7 +21,7 @@ import {
 } from "../utils";
 import { applyMateSkills, teardownMateSkills } from "../mate";
 
-export { MATE_ARTIFACT_SKILLS, MATE_SKILLS, deployMateSkillDir } from "../mate";
+export { MATE_ARTIFACT_SKILLS, MATE_SKILLS } from "../mate";
 
 const execFileAsync = promisify(execFileCb);
 
@@ -108,10 +108,7 @@ function getMateConventionsPath(companionPath: string): string {
   return path.join(companionPath, "openspec", "mate-conventions.yaml");
 }
 
-export async function teardownOpenspecSkills(
-  skillsDir: string,
-  companionPath: string,
-): Promise<void> {
+async function teardownOpenspecSkills(skillsDir: string, companionPath: string): Promise<void> {
   for (const skill of OPENSPEC_SKILLS) {
     try {
       await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
@@ -422,5 +419,3 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     },
   };
 }
-
-export const openspecPlugin = createOpenspecPlugin();

package/src/tools/setup/capabilities/react-doctor.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
 import { pruneEmptyAncestors } from "../utils";
 
-export const SKILL_SRC = path.join(
+const SKILL_SRC = path.join(
   import.meta.dirname,
   "../../../templates/capabilities/react-doctor/skill",
 );

package/src/tools/setup/capabilities/rtk.ts

@@ -3,8 +3,8 @@ import type { InstallRequirement } from "../install-contract";
 import { isCommandOnPath, runShellCommand, runShellCommandSilently } from "../utils";
 import { confirm } from "../../../cli/confirm";
 
-export const RTK_INSTALL_CMD_BREW = "brew install rtk-ai/tap/rtk";
-export const RTK_INSTALL_CMD_FALLBACK =
+const RTK_INSTALL_CMD_BREW = "brew install rtk-ai/tap/rtk";
+const RTK_INSTALL_CMD_FALLBACK =
   "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh";
 
 const RTK_INIT_COMMANDS: Record<string, string> = {

package/src/tools/setup/capabilities/tokensave.ts

@@ -1,9 +1,11 @@
 import { spawnSync } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 
 import { resolveGitInfoExcludePath } from "../git-utils";
+import type { InstallRequirement } from "../install-contract";
 import type { CapabilityPlugin, RuntimeContributionsByRuntime } from "../plugin";
 import { isCommandOnPath, resolveCommandOnPath, runCommand, runShellCommand } from "../utils";
 import { TOKENSAVE_CLAUDE_MD_MARKER } from "./tokensave-shared";
@@ -73,6 +75,9 @@ export const tokensaveDeps = {
   pathValue(): string {
     return process.env.PATH ?? "";
   },
+  homeDir(): string {
+    return os.homedir();
+  },
 };
 
 async function cleanupRepoLocalTokensaveArtifacts(repoPath: string): Promise<void> {
@@ -109,11 +114,12 @@ async function tokensaveInstalled(repoPath: string): Promise<boolean> {
 
 /**
  * Upgrades the installed binary without making setup depend on network
- * availability. `--kill` keeps the non-interactive setup path from hanging on
- * a running Tokensave MCP process.
+ * availability. Never passes `--kill`: it stops every tokensave process on the
+ * machine, including MCP servers of running agent sessions. Without a TTY,
+ * tokensave upgrades and leaves them running.
  */
 async function upgradeTokensave(repoPath: string): Promise<void> {
-  const result = tokensaveDeps.run(["upgrade", "--kill"], repoPath);
+  const result = tokensaveDeps.run(["upgrade"], repoPath);
   if (result.ok) return;
 
   const detail = result.stderr.trim();
@@ -122,17 +128,22 @@ async function upgradeTokensave(repoPath: string): Promise<void> {
   );
 }
 
-// Global agent integration (MCP entry, session hooks, wildcard permission grant, and
-// tokensave's own config bookkeeping) is owned by tokensave's installer — Mate never
-// hand-edits ~/.tokensave/config.toml. Runs in setup mode only; the installer is
-// idempotent, so re-running on every setup doubles as repair for stale global state.
+/**
+ * Global agent integration (MCP entry, session hooks, wildcard permission grant, and
+ * tokensave's own config bookkeeping) is owned by tokensave's installer — Mate never
+ * hand-edits ~/.tokensave/config.toml. Idempotent, so re-running doubles as repair.
+ */
+function installTokensaveAgentIntegration(agent: string, cwd: string): TokensaveRunResult {
+  return tokensaveDeps.run(
+    ["install", "--agent", agent, "--git-hook", "no", "--wildcard-permissions"],
+    cwd,
+  );
+}
+
 function installTokensaveAgentIntegrations(providers: string[], cwd: string): void {
   const agents = providers.filter((p) => TOKENSAVE_SUPPORTED_AGENTS.has(p)).sort();
   for (const agent of agents) {
-    const result = tokensaveDeps.run(
-      ["install", "--agent", agent, "--git-hook", "no", "--wildcard-permissions"],
-      cwd,
-    );
+    const result = installTokensaveAgentIntegration(agent, cwd);
     if (!result.ok) {
       const detail = result.stderr.trim();
       process.stderr.write(
@@ -142,6 +153,60 @@ function installTokensaveAgentIntegrations(providers: string[], cwd: string): vo
   }
 }
 
+async function readJsonObject(filePath: string): Promise<Record<string, unknown> | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await fs.readFile(filePath, "utf8"));
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read-only probe of the global files `tokensave install --agent <agent>` writes.
+ * tokensave's own permission check reads only these global files, never the
+ * companion-scoped settings Mate loads via `--settings`.
+ */
+export async function isTokensaveAgentIntegrated(agent: string): Promise<boolean> {
+  const home = tokensaveDeps.homeDir();
+  if (agent === "claude") {
+    const settings = await readJsonObject(path.join(home, ".claude", "settings.json"));
+    const allow = (settings?.permissions as { allow?: unknown } | undefined)?.allow;
+    return (
+      Array.isArray(allow) &&
+      allow.includes("mcp__tokensave__*") &&
+      (await fileExists(path.join(home, ".claude", "rules", "tokensave.md")))
+    );
+  }
+  if (agent === "opencode") {
+    const configDir = path.join(home, ".config", "opencode");
+    const config = await readJsonObject(path.join(configDir, "opencode.json"));
+    /**
+     * `tokensave install` writes the flat `mcp.<name>` entry, which OpenCode 2.x
+     * still loads; `mcp.servers.<name>` is the 2.x-native spelling.
+     */
+    const mcp = config?.mcp as
+      | (Record<string, unknown> & { servers?: Record<string, unknown> })
+      | undefined;
+    return (
+      (mcp?.tokensave !== undefined || mcp?.servers?.tokensave !== undefined) &&
+      (await fileExists(path.join(configDir, "tokensave.md")))
+    );
+  }
+  return true;
+}
+
 function getCargoRustVersionError(): string | undefined {
   const result = tokensaveDeps.rustcVersion();
   const version = `${result.stdout}\n${result.stderr}`.match(/\brustc\s+(\d+)\.(\d+)\.(\d+)/);
@@ -361,7 +426,7 @@ export function createTokensavePlugin(): CapabilityPlugin {
       "Enable TokenSave indexing in the repo and MCP access via companion-managed config.",
     defaultSelected: false,
     isEnabled: (config) => (config.capabilities ?? []).some((c) => c.name === "tokensave"),
-    getInstallRequirements: () => {
+    getInstallRequirements: ({ config }) => {
       const plan = getTokensaveInstallPlan();
       return [
         {
@@ -382,6 +447,27 @@ export function createTokensavePlugin(): CapabilityPlugin {
           },
           verify: () => tokensaveDeps.run(["--version"], process.cwd()).ok,
         },
+        ...(config.allowedAgents ?? [])
+          .filter((agent) => TOKENSAVE_SUPPORTED_AGENTS.has(agent))
+          .sort()
+          .map((agent): InstallRequirement => ({
+            id: `capability:tokensave:${agent}`,
+            label: `TokenSave ${agent} integration`,
+            group: "companion",
+            source: "TokenSave capability",
+            command: `tokensave install --agent ${agent} --git-hook no --wildcard-permissions`,
+            fingerprint: `tokensave-agent:${agent}`,
+            detect: () => isTokensaveAgentIntegrated(agent),
+            install: async () => {
+              const result = installTokensaveAgentIntegration(agent, process.cwd());
+              if (!result.ok) {
+                const detail = result.stderr.trim();
+                throw new Error(
+                  `\`tokensave install --agent ${agent}\` failed${detail ? `: ${detail}` : ""}`,
+                );
+              }
+            },
+          })),
       ];
     },
     // MCP access, session hooks, and permission pre-seeds are declared below

package/src/tools/setup/context-services.ts

@@ -31,10 +31,7 @@ interface ContextServicesManifest {
   plugins: Record<string, PluginServiceRecord>;
 }
 
-export function getContextServicesManifestPath(
-  companionPath: string,
-  frameworkName: string,
-): string {
+function getContextServicesManifestPath(companionPath: string, frameworkName: string): string {
   return path.join(companionPath, `.${frameworkName}`, "state", "context-services.json");
 }
 
@@ -129,7 +126,7 @@ export async function removeManagedBlocksForPlugin(
 }
 
 /** Remove a marker-delimited block if present. No-op when file or block is absent. */
-export async function removeManagedBlock(
+async function removeManagedBlock(
   filePath: string,
   frameworkName: string,
   blockKey: string,
@@ -164,7 +161,7 @@ export async function removeManagedBlock(
  * `playbooks/**`, and `wrappers/bin/*` below the root. Core's own templates
  * live at `src/templates`.
  */
-export async function resolveTemplateAsset(
+async function resolveTemplateAsset(
   templatePath: string,
   overrideRoots: string[] = [],
 ): Promise<string> {

package/src/tools/setup/dynamic-plugins/declarations.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Raw read of the companion's `plugins:` list. Deliberately avoids
+ * `ConfigStore.load()` — hydration runs on every invocation and must never
+ * create or migrate config files as a side effect.
+ */
+export async function readDeclarations(companionPath: string): Promise<unknown[]> {
+  try {
+    const raw = await fs.readFile(
+      path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+      "utf8",
+    );
+    const parsed = parse(raw) as unknown;
+    if (!isRecord(parsed) || !Array.isArray(parsed.plugins)) return [];
+    return parsed.plugins;
+  } catch {
+    return [];
+  }
+}
+
+export function validateDeclaration(entry: unknown): {
+  declaration?: PluginDeclaration;
+  error?: string;
+} {
+  if (!isRecord(entry) || typeof entry.package !== "string" || typeof entry.version !== "string") {
+    return { error: `ignoring malformed plugins entry: ${JSON.stringify(entry)}` };
+  }
+  const policy = entry.policy;
+  if (policy !== undefined && !PLUGIN_DECLARATION_POLICIES.includes(policy as never)) {
+    return {
+      error: `plugin "${entry.package}": policy "${String(policy)}" is not allowed for declared plugins (allowed: ${PLUGIN_DECLARATION_POLICIES.join(", ")}).`,
+    };
+  }
+  return { declaration: entry as unknown as PluginDeclaration };
+}

package/src/tools/setup/dynamic-plugins/frozen.ts

@@ -0,0 +1,215 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { NpmInstallRunner, PluginInstallResult } from "./install";
+import { dynamicPluginsWorkspaceRoot } from "./paths";
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
+
+/** Raised before anything is installed: policy, manifest or lockfile inputs are unusable. */
+export class FrozenInstallError extends Error {}
+
+export interface FrozenInstallDeps {
+  /** Restores the exact locked tree; defaults to `npm ci`. */
+  runNpmCi?: NpmInstallRunner;
+  env?: Record<string, string | undefined>;
+}
+
+interface LockEntry {
+  version?: string;
+  integrity?: string;
+  optional?: boolean;
+  inBundle?: boolean;
+  link?: boolean;
+}
+
+interface Lockfile {
+  packages?: Record<string, LockEntry & { dependencies?: Record<string, string> }>;
+}
+
+function defaultNpmCi(workspaceRoot: string): { ok: boolean; detail?: string } {
+  const result = spawnSync("npm", ["ci", "--no-audit", "--no-fund", "--loglevel=error"], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+  });
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      detail:
+        result.error?.message ?? (result.stderr?.trim() || `npm ci exited with ${result.status}`),
+    };
+  }
+  return { ok: true };
+}
+
+async function readText(file: string): Promise<string | null> {
+  try {
+    return await fs.readFile(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function parseJson<T>(text: string, label: string): T {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new FrozenInstallError(`${label} is not valid JSON`);
+  }
+}
+
+function sameMap(a: Record<string, string>, b: Record<string, string>): string[] {
+  const differences: string[] = [];
+  for (const name of new Set([...Object.keys(a), ...Object.keys(b)])) {
+    if (a[name] !== b[name]) {
+      differences.push(
+        `${name} (declared ${a[name] ?? "absent"}, recorded ${b[name] ?? "absent"})`,
+      );
+    }
+  }
+  return differences.toSorted();
+}
+
+/**
+ * Compares the installed tree's hidden lockfile with the committed lockfile:
+ * every non-optional locked package must be installed at the locked version
+ * and integrity, and nothing extra may be installed. Package presence alone
+ * proves nothing.
+ */
+async function treeMismatches(workspaceRoot: string, lock: Lockfile): Promise<string[]> {
+  const hiddenText = await readText(path.join(workspaceRoot, "node_modules", ".package-lock.json"));
+  if (hiddenText === null) return ["installed tree has no install record"];
+  let hidden: Lockfile;
+  try {
+    hidden = JSON.parse(hiddenText) as Lockfile;
+  } catch {
+    return ["installed tree's install record is unreadable"];
+  }
+  const installed = hidden.packages ?? {};
+  const mismatches: string[] = [];
+  for (const [key, locked] of Object.entries(lock.packages ?? {})) {
+    if (key === "" || locked.link) continue;
+    const present = installed[key];
+    if (!present) {
+      if (!locked.optional) mismatches.push(`${key} is not installed`);
+      continue;
+    }
+    if (present.version !== locked.version || present.integrity !== locked.integrity) {
+      mismatches.push(`${key} differs from the lockfile`);
+    }
+  }
+  for (const key of Object.keys(installed)) {
+    if (!lock.packages?.[key]) mismatches.push(`${key} is installed but not locked`);
+  }
+  return mismatches;
+}
+
+/**
+ * Deployment restore: installs exactly what the committed lockfile records.
+ * Inputs are validated before npm runs — the appliance allowlist, the
+ * workspace manifest against the declarations, and the lockfile against the
+ * manifest — and neither tracked file is ever rewritten. An installed tree is
+ * reused only when it matches the lockfile's versions and integrity.
+ */
+export async function installDeclaredPluginsFrozen(
+  companionPath: string,
+  declarations: PluginDeclaration[],
+  deps: FrozenInstallDeps = {},
+): Promise<PluginInstallResult[]> {
+  const workspaceRoot = dynamicPluginsWorkspaceRoot(companionPath);
+  const sorted = declarations.toSorted((a, b) => a.package.localeCompare(b.package));
+  const desired: Record<string, string> = {};
+  for (const declaration of sorted) desired[declaration.package] = declaration.version;
+
+  let policy: ReturnType<typeof readPluginPolicy>;
+  try {
+    policy = readPluginPolicy(deps.env ?? process.env);
+  } catch (error) {
+    if (error instanceof PluginPolicyError) throw new FrozenInstallError(error.message);
+    throw error;
+  }
+  const refused = sorted.filter((declaration) => !isPluginAllowed(policy, declaration.package));
+  if (refused.length > 0) {
+    throw new FrozenInstallError(
+      refused.map((declaration) => disallowedPluginMessage(declaration.package)).join("\n"),
+    );
+  }
+
+  const manifestFile = path.join(workspaceRoot, "package.json");
+  const lockFile = path.join(workspaceRoot, "package-lock.json");
+  const [manifestText, lockText] = await Promise.all([readText(manifestFile), readText(lockFile)]);
+  if (manifestText === null) {
+    throw new FrozenInstallError(
+      `${manifestFile} is missing; commit the plugin workspace manifest in the companion's authoring flow`,
+    );
+  }
+  if (lockText === null) {
+    throw new FrozenInstallError(
+      `${lockFile} is missing; commit the plugin lockfile in the companion's authoring flow`,
+    );
+  }
+
+  const manifest = parseJson<{ dependencies?: Record<string, string> }>(manifestText, manifestFile);
+  const manifestDrift = sameMap(desired, manifest.dependencies ?? {});
+  if (manifestDrift.length > 0) {
+    throw new FrozenInstallError(
+      `plugin workspace manifest disagrees with framework.yaml: ${manifestDrift.join("; ")}`,
+    );
+  }
+  const lock = parseJson<Lockfile>(lockText, lockFile);
+  const lockRoot = lock.packages?.[""]?.dependencies ?? {};
+  const lockDrift = sameMap(desired, lockRoot);
+  if (lockDrift.length > 0) {
+    throw new FrozenInstallError(
+      `plugin lockfile disagrees with framework.yaml: ${lockDrift.join("; ")}`,
+    );
+  }
+  const unlocked = sorted.filter((declaration) => {
+    const entry = lock.packages?.[`node_modules/${declaration.package}`];
+    return !entry?.version || !entry.integrity;
+  });
+  if (unlocked.length > 0) {
+    throw new FrozenInstallError(
+      `plugin lockfile has no resolved version and integrity for: ${unlocked.map((d) => d.package).join(", ")}`,
+    );
+  }
+
+  const lockedVersion = (name: string) => lock.packages?.[`node_modules/${name}`]?.version;
+  const fail = (error: string): PluginInstallResult[] =>
+    sorted.map((declaration) => ({ package: declaration.package, status: "failed", error }));
+
+  if ((await treeMismatches(workspaceRoot, lock)).length === 0) {
+    return sorted.map((declaration) => ({
+      package: declaration.package,
+      status: "unchanged",
+      resolvedVersion: lockedVersion(declaration.package),
+    }));
+  }
+
+  const outcome = await (deps.runNpmCi ?? defaultNpmCi)(workspaceRoot);
+  if (!outcome.ok) return fail(outcome.detail ?? "npm ci failed");
+
+  const [manifestAfter, lockAfter] = await Promise.all([
+    readText(manifestFile),
+    readText(lockFile),
+  ]);
+  if (manifestAfter !== manifestText || lockAfter !== lockText) {
+    await Promise.all([fs.writeFile(manifestFile, manifestText), fs.writeFile(lockFile, lockText)]);
+    return fail("the restore changed the committed manifest or lockfile; they were put back");
+  }
+  const remaining = await treeMismatches(workspaceRoot, lock);
+  if (remaining.length > 0) {
+    return fail(`installed tree does not match the lockfile: ${remaining.join("; ")}`);
+  }
+  return sorted.map((declaration) => ({
+    package: declaration.package,
+    status: "installed",
+    resolvedVersion: lockedVersion(declaration.package),
+  }));
+}