@uniqbit/mate-core 0.18.1-canary.0 → 0.18.1-canary.2

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

@@ -1,6 +1,5 @@
 import os from "node:os";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 
 import { FRAMEWORK_NAME } from "../../../framework";
@@ -19,16 +18,16 @@ import { runSetupFlowAtPath } from "../setup";
 import { runInstallCommand } from "../install";
 import type { CompanionSource, LinkedRepository } from "../../../lib/orchestrator/types";
 import { invalidateInstallState } from "../../../lib/install";
+import { companionGit, describeGitFailure, type GitResult } from "../../../runtime/companion-git";
 
 interface CompanionLinkCommandDeps {
   selectCompanionLinkInputs?: (
     options: CompanionLinkWizardOptions,
   ) => Promise<CompanionLinkInputs | null>;
   extractRepoName?: (url: string) => string | null;
-  spawnSync?: typeof spawnSync;
+  cloneCompanion?: (url: string, destination: string) => Promise<GitResult>;
   mkdir?: typeof fs.mkdir;
   stat?: typeof fs.stat;
-  rm?: typeof fs.rm;
   listCompanions?: () => Promise<string[]>;
   registerCompanion?: (companionPath: string) => Promise<void>;
   resolveCompanion?: (cwd: string) => ReturnType<CompanionResolver["resolve"]>;
@@ -61,23 +60,6 @@ export async function runCompanionLinkCommand(argv: string[]): Promise<void> {
   return companionLinkCommandDeps.runCompanionLinkCommandWithDeps(argv);
 }
 
-function toSshUrl(url: string): string | null {
-  try {
-    const parsed = new URL(url.trim());
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
-    if (!parsed.hostname || parsed.pathname === "/") return null;
-
-    const repositoryPath = parsed.pathname.replace(/^\/+/, "");
-    if (!repositoryPath) return null;
-
-    // Keep the usual scp-style form when no SSH port is specified.
-    if (!parsed.port) return `git@${parsed.hostname}:${repositoryPath}`;
-    return `ssh://git@${parsed.hostname}:${parsed.port}/${repositoryPath}`;
-  } catch {
-    return null;
-  }
-}
-
 function exitWithError(message: string): never {
   process.stderr.write(`${message}\n`);
   process.exit(1);
@@ -96,10 +78,12 @@ export async function runCompanionLinkCommandWithDeps(
 
   const selectInputs = deps.selectCompanionLinkInputs ?? selectCompanionLinkInputs;
   const extractName = deps.extractRepoName ?? extractRepoName;
-  const spawn = deps.spawnSync ?? spawnSync;
+  const cloneCompanion =
+    deps.cloneCompanion ??
+    ((url: string, destination: string) =>
+      companionGit(path.dirname(destination), { prompt: "if-terminal" }).clone(url, destination));
   const mkdir = deps.mkdir ?? fs.mkdir;
   const stat = deps.stat ?? fs.stat;
-  const rm = deps.rm ?? fs.rm;
   const listCompanions =
     deps.listCompanions ??
     (() => {
@@ -165,44 +149,14 @@ export async function runCompanionLinkCommandWithDeps(
     const existingTarget = await stat(companionPath).catch(() => null);
     if (!existingTarget?.isDirectory()) {
       await mkdir(companionsDir, { recursive: true });
-      const sshUrl = toSshUrl(gitUrl);
-      const cloneUrls = sshUrl && sshUrl !== gitUrl ? [sshUrl, gitUrl] : [gitUrl];
-      let cloneResult:
-        | {
-            status: number | null;
-            stderr?: string | Buffer;
-            stdout?: string | Buffer;
-          }
-        | undefined;
-      const cloneErrors: string[] = [];
-
-      for (const cloneUrl of cloneUrls) {
-        cloneResult = spawn("git", ["clone", cloneUrl, companionPath], {
-          encoding: "utf8",
-          stdio: ["ignore", "pipe", "pipe"],
-        });
-        if (cloneResult.status === 0) {
-          break;
-        }
-
-        cloneErrors.push(
-          String(cloneResult.stderr || cloneResult.stdout || `Clone failed for ${cloneUrl}`),
+      const clone = await cloneCompanion(gitUrl, companionPath);
+      if (clone.status !== 0) {
+        const detail = describeGitFailure(clone);
+        exitWithError(
+          `mate: failed to clone companion repository:\n${
+            detail === "unknown Git error" ? "review the Git or SSH diagnostics above" : detail
+          }`,
         );
-        try {
-          await rm(companionPath, { recursive: true, force: true });
-        } catch {
-          // Ignore cleanup errors after a failed clone.
-        }
-      }
-
-      if (!cloneResult || cloneResult.status !== 0) {
-        try {
-          await rm(companionPath, { recursive: true, force: true });
-        } catch {
-          // Ignore cleanup errors after a failed clone.
-        }
-        const output = cloneErrors.join("\n\n");
-        exitWithError(`mate: failed to clone companion repository:\n${output}`);
       }
     }
     companionPaths = [companionPath];

package/src/cli/commands/doctor.ts

@@ -2,12 +2,17 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../framework";
+import { gitEnvironment } from "../../runtime/companion-git";
 import { getActiveDistribution } from "../../distribution";
 import { checkEngineRequirement } from "../../lib/orchestrator/engine-guard";
 import type { GlobalConfigStore } from "../../lib/orchestrator/global-config-store";
 import { pathIsDirectory } from "../../lib/orchestrator/repo-local-registry";
 import { resolveRootContext, type RootContext } from "../../lib/orchestrator/root-context";
 import type { CapabilityConfig, FrameworkConfig, HubMember } from "../../lib/orchestrator/types";
+import {
+  verifyDeclaredPlugins,
+  type PluginVerificationFailure,
+} from "../../tools/setup/dynamic-plugins/verify";
 import { getRequiredPluginDrift } from "../../tools/setup/policy";
 import { resolveCommandOnPath } from "../../tools/setup/utils";
 import { writeJsonStdout } from "../write-json-stdout";
@@ -19,6 +24,7 @@ interface DoctorDeps {
   pathValue?: string;
   /** Returns a member checkout's HEAD commit, or null when unreadable. */
   gitHead?: (memberPath: string) => string | null;
+  verifyPlugins?: (companionPath: string) => Promise<PluginVerificationFailure[]>;
 }
 
 export type DoctorKind = "core" | "working" | "companion" | "hub";
@@ -51,6 +57,7 @@ export interface DoctorReport {
   capabilities?: string[];
   toolInstallations?: DoctorToolInstallation[];
   requiredPluginDrift?: Array<{ pluginId: string; kind: string; reason: string }>;
+  pluginFailures?: PluginVerificationFailure[];
   engineRequirement?: { range: string; ok: boolean; detail: string };
   hub?: { members: DoctorHubMember[] };
   resolutionFailures: Array<{ companionPath: string; message: string }>;
@@ -74,6 +81,7 @@ function defaultGitHead(memberPath: string): string | null {
   try {
     return execFileSync("git", ["-C", memberPath, "rev-parse", "HEAD"], {
       stdio: ["ignore", "pipe", "ignore"],
+      env: gitEnvironment(),
     })
       .toString()
       .trim();
@@ -237,6 +245,10 @@ export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<Doctor
     report.engineRequirement = collectEngineRequirement(root.config);
   }
 
+  if (root.rootPath && root.config) {
+    report.pluginFailures = await (deps.verifyPlugins ?? verifyDeclaredPlugins)(root.rootPath);
+  }
+
   return report;
 }
 
@@ -329,6 +341,15 @@ function renderHumanReport(report: DoctorReport): void {
       ),
     );
   }
+  if (report.pluginFailures && report.pluginFailures.length > 0) {
+    printSection(
+      "Declared Plugins",
+      renderTable(
+        ["Plugin", "Issue"],
+        report.pluginFailures.map((failure) => [failure.package, failure.reason]),
+      ),
+    );
+  }
   if (report.engineRequirement) {
     printSection("Version Requirement", report.engineRequirement.detail);
   }
@@ -350,13 +371,18 @@ function renderHumanReport(report: DoctorReport): void {
  * working repository), `companion`, `hub`, or `core` (not linked) — with
  * kind-specific diagnostics: policy and capabilities for working repos,
  * capabilities and tool checks for companions, member health for hubs.
+ * Declared plugins are verified strictly (allowed by `MATE_ALLOWED_PLUGINS`,
+ * installed, loadable); any failure is named on stderr and exits non-zero.
  * `--json` emits the same report as one JSON document.
  */
 export async function runDoctorCommand(argv: string[] = [], deps: DoctorDeps = {}): Promise<void> {
   const report = await collectDoctorReport(deps);
-  if (argv.includes("--json")) {
-    await writeJsonStdout(report);
-    return;
+  if (argv.includes("--json")) await writeJsonStdout(report);
+  else renderHumanReport(report);
+
+  const failures = report.pluginFailures ?? [];
+  for (const failure of failures) {
+    process.stderr.write(`${FRAMEWORK_NAME}: plugin ${failure.package}: ${failure.reason}\n`);
   }
-  renderHumanReport(report);
+  if (failures.length > 0) process.exitCode = 1;
 }

package/src/cli/commands/install.ts

@@ -19,6 +19,7 @@ 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[]): boolean {
@@ -158,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(

package/src/cli/commands/plugin/plugin.ts

@@ -1,6 +1,5 @@
 import { usage } from "../../usage";
 import { runPluginInstallCommand } from "./install";
-import { runPluginVerifyCommand } from "./verify";
 
 export async function runPluginCommand(
   subcommand: string | undefined,
@@ -10,9 +9,6 @@ export async function runPluginCommand(
     case "install":
       await runPluginInstallCommand(argv);
       return;
-    case "verify":
-      await runPluginVerifyCommand(argv);
-      return;
     default:
       console.error(`Unknown plugin command: ${subcommand ?? ""}`);
       console.error(usage());

package/src/cli/commands/report/formatter.ts

@@ -11,7 +11,3 @@ export function formatTokens(count: number): string {
 export function formatCost(amount: number): string {
   return `$${amount.toFixed(2)}`;
 }
-
-export function formatPercentage(value: number): string {
-  return `${value.toFixed(1)}%`;
-}

package/src/cli/commands/studio/selection.ts

@@ -30,6 +30,9 @@ export const STUDIO_PARAMS: readonly string[] = [
 /** Filled into a prompt when no change is named, so a prompt is never half-written. */
 export const CHANGE_PLACEHOLDER = "<change-name>";
 
+/** Filled into pre-explore prompts, which run before any change exists. */
+export const IDEA_PLACEHOLDER = "<idea>";
+
 const DIGEST_LENGTH = 10;
 
 interface SelectionBase {

package/src/cli/commands/studio/terminal-launch.ts

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
@@ -27,56 +26,11 @@ export async function launchableAgents(
   return TERMINAL_AGENTS.filter((agent) => allowed.includes(agent) && installed(agent));
 }
 
-/** Lowercase letters, digits and hyphens, so a name can never carry shell syntax or a flag. */
-export const AGENT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
-
-const AGENT_DEFINITION_DIRS: Record<TerminalAgent, string> = {
-  claude: path.join(".claude", "agents"),
-  opencode: path.join(".opencode", "agents"),
-};
-
-export interface DefaultAgentOutcome {
-  agentArgs?: string[];
-  notice?: string;
-}
-
-/**
- * The companion's `studio.terminal.agent` for one provider. Never throws and
- * never echoes the configured value into the notice.
- */
-export async function defaultAgentFor(
-  companionPath: string,
-  agent: TerminalAgent,
-): Promise<DefaultAgentOutcome> {
-  const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
-  if (!fs.existsSync(configPath)) return {};
-  let name: unknown;
-  try {
-    name = (await new ConfigStore(configPath).load()).studio?.terminal?.agent;
-  } catch {
-    return {};
-  }
-  if (name === undefined || name === null) return {};
-  if (typeof name !== "string" || !AGENT_NAME_PATTERN.test(name)) {
-    return {
-      notice: "Default agent not applied: studio.terminal.agent is not a valid agent name.",
-    };
-  }
-  const definition = path.join(companionPath, AGENT_DEFINITION_DIRS[agent], `${name}.md`);
-  if (!fs.existsSync(definition)) {
-    return {
-      notice: `Default agent "${name}" not applied: this companion has no ${agent} definition for it.`,
-    };
-  }
-  return { agentArgs: ["--agent", name] };
-}
-
 export interface LaunchResolverOptions {
   collectInventory: () => Promise<StudioInventory>;
   /** Pinned by `serve --companion`; overrides the page selection. */
   launchCompanion?: string | null;
   launchableAgents?: (companionPath: string) => Promise<TerminalAgent[]>;
-  defaultAgent?: (companionPath: string, agent: TerminalAgent) => Promise<DefaultAgentOutcome>;
 }
 
 /** The companion a launch targets: the pinned one, else the page's, both read from the current inventory. */
@@ -96,7 +50,6 @@ export function createLaunchResolver(
   options: LaunchResolverOptions,
 ): (agent: string, digest: string | null) => Promise<TerminalLaunchResolution> {
   const agents = options.launchableAgents ?? launchableAgents;
-  const defaultAgent = options.defaultAgent ?? defaultAgentFor;
   return async (agent, digest) => {
     const companion = await effectiveLaunchCompanion(
       await options.collectInventory(),
@@ -113,9 +66,6 @@ export function createLaunchResolver(
     if (!(await agents(companion.path)).includes(agent as TerminalAgent)) {
       return { reason: `${agent} is not allowed by this companion or is not installed` };
     }
-    return {
-      companionPath: companion.path,
-      ...(await defaultAgent(companion.path, agent as TerminalAgent)),
-    };
+    return { companionPath: companion.path };
   };
 }

package/src/cli/commands/studio/terminal.ts

@@ -177,15 +177,7 @@ export interface TerminalSessionInfo {
   startedAt: number;
 }
 
-export type TerminalLaunchResolution =
-  | {
-      companionPath: string;
-      /** Extra argv entries for the managed launch; set only by companion configuration. */
-      agentArgs?: string[];
-      /** Written to the terminal before the agent starts. */
-      notice?: string;
-    }
-  | { reason: string };
+export type TerminalLaunchResolution = { companionPath: string } | { reason: string };
 
 export interface TerminalRegistryOptions {
   detachMs: number;
@@ -396,7 +388,7 @@ export class TerminalRegistry {
       void this.finish(detached, { type: "ended", reason: "evicted" });
     }
 
-    const session = this.launch(agent, resolved.companionPath, size, resolved);
+    const session = this.launch(agent, resolved.companionPath, size);
     this.attachTo(connection, session, size);
   }
 
@@ -404,7 +396,6 @@ export class TerminalRegistry {
     agent: TerminalAgent,
     companionPath: string,
     size: { cols: number; rows: number },
-    extras: { agentArgs?: string[]; notice?: string } = {},
   ): Session {
     const env: Record<string, string> = {};
     for (const [key, value] of Object.entries(this.options.env ?? process.env)) {
@@ -422,7 +413,6 @@ export class TerminalRegistry {
       "--companion",
       "--yes",
       ...(this.options.noGit ? ["--no-git"] : []),
-      ...(extras.agentArgs ?? []),
     ];
 
     const session = {
@@ -437,7 +427,6 @@ export class TerminalRegistry {
       ending: null,
       exited: false,
     } as Omit<Session, "process"> as Session;
-    if (extras.notice) session.ring.push(new TextEncoder().encode(`${extras.notice}\r\n`));
     session.process = this.spawn({
       argv,
       cwd: companionPath,

package/src/cli/commands/studio/vault.ts

@@ -4,6 +4,8 @@ import * as fsp from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";
 
+import { gitEnvironment } from "../../../runtime/companion-git";
+
 export interface VaultTreeNode {
   name: string;
   path: string;
@@ -108,7 +110,7 @@ function inside(root: string, candidate: string): boolean {
   );
 }
 
-async function realpathContaining(root: string, candidate: string): Promise<string> {
+async function realpathContaining(candidate: string): Promise<string> {
   let current = candidate;
   while (true) {
     try {
@@ -146,7 +148,7 @@ export async function resolveVaultPath(
     absolute = await fsp.realpath(lexical);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-    const containing = await realpathContaining(root, path.dirname(lexical));
+    const containing = await realpathContaining(path.dirname(lexical));
     if (!inside(root, containing))
       throw new VaultPathError("the requested path leaves the companion root");
     absolute = lexical;
@@ -167,7 +169,7 @@ export async function resolveVaultPath(
 
 function runGit(args: string[], input?: string): Promise<VaultGitResult> {
   return new Promise((resolve, reject) => {
-    const child = spawn("git", args, { stdio: ["pipe", "pipe", "pipe"] });
+    const child = spawn("git", args, { stdio: ["pipe", "pipe", "pipe"], env: gitEnvironment() });
     const stdout: Buffer[] = [];
     const stderr: Buffer[] = [];
     child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));

package/src/cli/commands/studio/views/workflow/steps.ts

@@ -1,4 +1,4 @@
-import { CHANGE_PLACEHOLDER } from "../../selection";
+import { CHANGE_PLACEHOLDER, IDEA_PLACEHOLDER } from "../../selection";
 
 export type WorkflowStepKind = "skill" | "review" | "completion" | "optional";
 export type WorkflowStepBadge = "optional" | "skill" | "openspec" | "human-in-loop";
@@ -56,11 +56,12 @@ function stepPrompt(
   includeChange = true,
 ): string {
   const changeNote = includeChange ? ` for ${CHANGE_PLACEHOLDER}` : " for";
+  const ideaNote = includeChange ? ` about ${IDEA_PLACEHOLDER}` : " about";
   const schemaNote = profile && profile !== "mate-v1" ? ` (use schema: ${profile})` : "";
 
   switch (step.id) {
     case "pre-explore":
-      return `/mate-interview-me or /mate-grill-me${changeNote}`;
+      return `/mate-interview-me or /mate-grill-me${ideaNote}`;
     case "explore":
       return `/openspec-explore${schemaNote}${changeNote}`;
     case "proposal":
@@ -172,8 +173,8 @@ export function workflowPlan(
         name === "mate-interview-me"
           ? "Difference: guided, one-question-at-a-time clarification. Best when: the request is ambiguous and intent, constraints, or scope still need confirmation."
           : "Difference: adversarial, round-based review of the full design-tree frontier. Best when: the direction is mostly known but hidden assumptions, risks, and downstream impacts need surfacing.",
-      prompt: `/${name} for ${CHANGE_PLACEHOLDER}`,
-      copyPrompt: `/${name} for`,
+      prompt: `/${name} about ${IDEA_PLACEHOLDER}`,
+      copyPrompt: `/${name} about`,
     });
   }
   const start = optionalStep(

package/src/cli/commands/update.ts

@@ -1,10 +1,6 @@
 import { spawnSync } from "node:child_process";
 
 import { FRAMEWORK_NAME } from "../../framework";
-import {
-  OPENCODE_PLUGIN_PACKAGE_NAME,
-  warmOpenCodePluginCache,
-} from "../../lib/opencode-plugin-package";
 import { installPublicPackageSync, isPackageInstalledAtNpmGlobalRoot } from "../../lib/public-npm";
 import {
   fetchLatestVersion,
@@ -66,8 +62,6 @@ export const updateCommandDeps = {
   },
   spawnPostInstall: (executable: string, args: string[]): InstallResult =>
     spawnSync(executable, args, { stdio: "inherit" }) as InstallResult,
-  warmOpenCodePluginCache: (latest: string) =>
-    warmOpenCodePluginCache(latest, process.env, getUpdateConfig().registry),
 };
 
 /**
@@ -157,20 +151,6 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
 
   await updateCommandDeps.saveUpdateState(latest);
 
-  // The plugin package is released in lockstep with the CLI; pre-fetch the
-  // newly coordinated version into OpenCode's plugin environment so the next
-  // managed launch does not stall on a registry download. Best effort only.
-  const warmed = await updateCommandDeps.warmOpenCodePluginCache(latest);
-  if (!warmed.ok) {
-    process.stderr.write(
-      [
-        `${FRAMEWORK_NAME}: could not pre-fetch ${OPENCODE_PLUGIN_PACKAGE_NAME}@${latest} for OpenCode.`,
-        "The next managed OpenCode launch will download it (requires registry access).",
-        ...(warmed.detail ? [`Details: ${warmed.detail}`] : []),
-      ].join("\n") + "\n",
-    );
-  }
-
   const postInstall = updateCommandDeps.runPostInstall(skipConfirm);
   if (postInstall.status !== 0 || postInstall.error) {
     process.stderr.write(
@@ -182,4 +162,8 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
 
   console.log(`\nUpgraded to ${latest}.`);
   console.log("Post-update installation complete.");
+  /** Managed launches run standalone; only a long-lived service keeps the replaced plugin loaded. */
+  console.log(
+    "Restart any running OpenCode service to load the new plugin: `opencode service restart`.",
+  );
 }

package/src/cli/commands/working/cleanup.ts

@@ -6,6 +6,7 @@ import { promisify } from "node:util";
 import { parse } from "yaml";
 
 import { FRAMEWORK_NAME } from "../../../framework";
+import { gitEnvironment } from "../../../runtime/companion-git";
 import type { RootKind } from "../../../lib/orchestrator/root-context";
 import {
   collectWorkspaceInventory,
@@ -39,7 +40,9 @@ export interface WorkingCleanupCommandDeps {
 
 async function resolveGitRoot(cwd: string): Promise<string | null> {
   try {
-    const { stdout } = await execFileAsync("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+    const { stdout } = await execFileAsync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+      env: gitEnvironment(),
+    });
     return canonicalPath(stdout.trim());
   } catch {
     return null;