@uniqbit/mate-core 0.18.3-canary.1 → 0.18.3

package/src/lib/orchestrator/adapters/base.ts

@@ -4,8 +4,15 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { MATE_ENV } from "../../../runtime/env-names";
+import { getWrapperBinPath } from "../../package-paths";
 import { buildProjection, companionEnvironment, projectionEnvironment } from "../projection-record";
-import type { CapabilityConfig, GitModeProfile, LinkedRepository } from "../types";
+import type { PrepareResult } from "../session-prepare";
+import {
+  LaunchPreflightError,
+  type CapabilityConfig,
+  type GitModeProfile,
+  type LinkedRepository,
+} from "../types";
 
 export interface AdapterContext {
   repository?: LinkedRepository;
@@ -47,15 +54,41 @@ function prependPathEntry(pathValue: string | undefined, entry: string): string
   return [entry, ...entries.filter((value) => value !== entry)].join(path.delimiter);
 }
 
-export abstract class LaunchAdapter {
+export function prepareFailure(result: PrepareResult): string {
+  return [
+    `${FRAMEWORK_NAME}: preparing ${result.repositoryId} for OpenCode failed.`,
+    ...result.steps.flatMap((step) =>
+      step.outcome === "failed" ? [`- ${step.step}: ${step.detail ?? "failed"}`] : [],
+    ),
+  ].join("\n");
+}
+
+/**
+ * `C` is the context one launch carries from `planLaunch` to `run`: returned,
+ * never stored, since one adapter instance serves every launch.
+ */
+export abstract class LaunchAdapter<C extends AdapterContext = AdapterContext> {
   abstract readonly toolName: string;
   readonly interactive: boolean = false;
 
-  abstract buildArgs(context: AdapterContext, args: string[]): string[];
+  abstract buildArgs(context: C, args: string[]): string[];
+
+  /**
+   * The runtime's share of a launch after a successful Session Prepare. Nothing
+   * to plan by default; an adapter that narrows `C` overrides it.
+   */
+  async planLaunch(context: AdapterContext, _prepared: PrepareResult): Promise<C> {
+    return context as C;
+  }
+
+  /** What a failed prepare raises: the failed step's own error, else a summary. */
+  launchFailure(prepared: PrepareResult): unknown {
+    return prepared.failure ?? new LaunchPreflightError(prepareFailure(prepared));
+  }
 
-  async validateLaunch(_context: AdapterContext): Promise<void> {}
+  async validateLaunch(_context: C): Promise<void> {}
 
-  extendEnvironment(_context: AdapterContext): NodeJS.ProcessEnv {
+  extendEnvironment(_context: C): NodeJS.ProcessEnv {
     return {};
   }
 
@@ -67,7 +100,9 @@ export abstract class LaunchAdapter {
   environment(context: AdapterContext): NodeJS.ProcessEnv {
     const reactDoctorEnabled = context.capabilities.some((c) => c.name === "react-doctor");
     const projection = context.repository
-      ? projectionEnvironment(buildProjection(context.companionPath, context.repository))
+      ? projectionEnvironment(
+          buildProjection(context.companionPath, context.repository, getWrapperBinPath()),
+        )
       : companionEnvironment(context.companionPath);
     const env: NodeJS.ProcessEnv = {
       ...process.env,
@@ -92,7 +127,7 @@ export abstract class LaunchAdapter {
     return env;
   }
 
-  async prepareLaunch(context: AdapterContext, args: string[]): Promise<PreparedLaunch> {
+  async prepareLaunch(context: C, args: string[]): Promise<PreparedLaunch> {
     const builtArgs = this.buildArgs(context, args);
     const baseEnv = this.environment(context);
     const extendedEnv = this.extendEnvironment(context);
@@ -120,7 +155,7 @@ export abstract class LaunchAdapter {
     return !(this.interactive && process.stdin.isTTY);
   }
 
-  async run(context: AdapterContext, args: string[]): Promise<AdapterResult> {
+  async run(context: C, args: string[]): Promise<AdapterResult> {
     const launch = await this.prepareLaunch(context, args);
 
     return new Promise((resolve, reject) => {

package/src/lib/orchestrator/adapters/claude.ts

@@ -1,21 +1,128 @@
 import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
 
+import { FRAMEWORK_NAME } from "../../../framework";
 import { buildCompanionGuidance } from "../../../playbooks/companion-guidance";
-import { getContextModePackageRoot, validateContextModePackage } from "../../context-mode-package";
-import { getClaudePluginRoot, validateClaudePluginAssets } from "../../package-paths";
+import {
+  planClaudeDelivery,
+  type ClaudeDeliveryPlan,
+  type SessionKind,
+} from "../../../runtime/claude-delivery-plan";
+import { hookGroupKey, type ClaudeHookGroup } from "../../../runtime/claude-hook-group";
+import { NOT_WRAPPED } from "../../../runtime/wrap-state";
+import { writeAtomic } from "../../../runtime/write-atomic";
 import {
   getCompanionClaudeMcpConfigPath,
   getCompanionClaudeSettingsPath,
 } from "../../../tools/setup/providers/claude";
+import type { ClaudeSettings } from "../../../tools/setup/providers/claude-format";
+import { getContextModePackageRoot, validateContextModePackage } from "../../context-mode-package";
+import { getClaudePluginRoot, validateClaudePluginAssets } from "../../package-paths";
+import type { PrepareResult } from "../session-prepare";
+import { LaunchPreflightError } from "../types";
 import { type AdapterContext, LaunchAdapter } from "./base";
 
-export class ClaudeAdapter extends LaunchAdapter {
+/** The paths are present only where the plan names that channel and the file exists. */
+interface ClaudeDelivery {
+  plan: ClaudeDeliveryPlan;
+  settingsPath?: string;
+  mcpConfigPath?: string;
+}
+
+/** A Claude launch's context: the delivery its plan chose, and the files it chose or wrote. */
+interface ClaudeLaunchContext extends AdapterContext {
+  delivery: ClaudeDelivery;
+}
+
+/** Where a launch with a Working Repository writes its derived `--settings`; git-ignored. */
+export function launchSettingsPath(companionPath: string, repositoryId: string): string {
+  const safeId = repositoryId.replace(/[^A-Za-z0-9._-]/g, "_");
+  return path.join(companionPath, ".claude", "state", `launch-settings.${safeId}.json`);
+}
+
+/**
+ * Companion settings minus `exclude`, so each wrap-carried group runs once. A
+ * file, not inline JSON (platform arg limits); per repository, so concurrent
+ * launches never race.
+ */
+async function writeLaunchSettings(
+  companionSettingsPath: string,
+  target: string,
+  exclude: readonly ClaudeHookGroup[],
+): Promise<void> {
+  const settings = JSON.parse(await fs.readFile(companionSettingsPath, "utf8")) as ClaudeSettings;
+  const excluded = new Set(exclude.map(hookGroupKey));
+  const hooks: Record<string, ClaudeHookGroup[]> = {};
+  for (const [event, groups] of Object.entries(settings.hooks ?? {})) {
+    const kept = (groups ?? []).filter((group) => !excluded.has(hookGroupKey(group)));
+    if (kept.length > 0) hooks[event] = kept;
+  }
+  const derived: ClaudeSettings = { ...settings, hooks };
+  if (Object.keys(hooks).length === 0) delete derived.hooks;
+
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await writeAtomic(target, `${JSON.stringify(derived, null, 2)}\n`);
+}
+
+/** The `--settings` file the plan's hook owner calls for, writing it when derived. */
+async function settingsPathFor(
+  plan: ClaudeDeliveryPlan,
+  companionPath: string,
+  repository: AdapterContext["repository"],
+): Promise<string | undefined> {
+  const companionSettingsPath = getCompanionClaudeSettingsPath(companionPath);
+  if (plan.hooks.owner === "none" || !existsSync(companionSettingsPath)) return undefined;
+  if (plan.hooks.owner === "settings") return companionSettingsPath;
+  /** Owner `wrap` is planned only for `managed-repo`, which has a repository. */
+  const settingsPath = launchSettingsPath(companionPath, repository!.id);
+  await writeLaunchSettings(companionSettingsPath, settingsPath, plan.hooks.launchSettingsExclude);
+  return settingsPath;
+}
+
+export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
   readonly toolName = "claude";
   readonly interactive = true;
 
-  async validateLaunch(context: AdapterContext): Promise<void> {
-    // The bundled mate plugin carries the artifact-path guard; never launch a
-    // managed session without it.
+  /**
+   * Plans from the wrap state the prepare's pass left, never a fresh read. A
+   * repository left without a Claude wrap fails preflight: the plan would defer
+   * to a wrap that is not there.
+   */
+  async planLaunch(context: AdapterContext, prepared: PrepareResult): Promise<ClaudeLaunchContext> {
+    const { repository, companionPath } = context;
+    const kind: SessionKind = repository ? "managed-repo" : "managed-companion";
+    const wrap = prepared.wrapState ?? NOT_WRAPPED;
+    if (repository && !wrap.runtimes.has("claude")) {
+      throw new LaunchPreflightError(
+        `${FRAMEWORK_NAME}: ${repository.id} is not wrapped for Claude after its prepare; run \`${FRAMEWORK_NAME} wrap\` in ${repository.path}.`,
+      );
+    }
+    const plan = planClaudeDelivery(kind, wrap);
+    const mcpConfigPath = getCompanionClaudeMcpConfigPath(companionPath);
+    const settingsPath = await settingsPathFor(plan, companionPath, repository);
+    const delivery: ClaudeDelivery = {
+      plan,
+      ...(plan.mcp === "mcp-config" && existsSync(mcpConfigPath) ? { mcpConfigPath } : {}),
+      ...(settingsPath ? { settingsPath } : {}),
+    };
+    return { ...context, delivery };
+  }
+
+  /** A failed Claude wrap pass names the entry that failed. */
+  launchFailure(prepared: PrepareResult): unknown {
+    const failed = prepared.steps.find((step) => step.outcome === "failed");
+    if (failed?.step === "working-target") {
+      return new LaunchPreflightError(
+        `${FRAMEWORK_NAME}: reconciling the Claude wrap of ${prepared.repositoryId} failed: ${failed.detail ?? "failed"}`,
+        { cause: prepared.failure },
+      );
+    }
+    return super.launchFailure(prepared);
+  }
+
+  async validateLaunch(context: ClaudeLaunchContext): Promise<void> {
+    /** The bundled plugin carries the artifact-path guard; never launch without it. */
     try {
       validateClaudePluginAssets();
     } catch (error) {
@@ -37,24 +144,20 @@ export class ClaudeAdapter extends LaunchAdapter {
     }
   }
 
-  buildArgs(context: AdapterContext, args: string[]): string[] {
-    // Load Mate-managed Claude config from companion settings when present,
-    // layered on top of the user's user/project/local sources so global
-    // skills and plugins still load. Only add the flags when the file
-    // exists so a companion without generated settings still launches with
-    // Claude's default discovery.
-    const companionSettingsPath = getCompanionClaudeSettingsPath(context.companionPath);
-    const settingsArgs = existsSync(companionSettingsPath)
-      ? ["--setting-sources", "user,project,local", "--settings", companionSettingsPath]
-      : [];
-
-    // Load Mate-managed MCP servers from the companion `.mcp.json` when present.
-    // It lives in the companion repo (not the working-repo cwd), so it must be
-    // passed explicitly rather than relying on Claude's cwd auto-discovery.
-    const companionMcpConfigPath = getCompanionClaudeMcpConfigPath(context.companionPath);
-    const mcpConfigArgs = existsSync(companionMcpConfigPath)
-      ? ["--mcp-config", companionMcpConfigPath]
-      : [];
+  /**
+   * Plan in, flags out; decides nothing. `--append-system-prompt`, `--plugin-dir`
+   * and context-mode are unconditional: no settings document can carry them.
+   */
+  buildArgs(context: ClaudeLaunchContext, args: string[]): string[] {
+    const { plan, settingsPath, mcpConfigPath } = context.delivery;
+    /** Layered on the user's own sources so global skills and plugins still load. */
+    const settingsArgs =
+      plan.hooks.owner !== "none" && settingsPath
+        ? ["--setting-sources", "user,project,local", "--settings", settingsPath]
+        : [];
+    const addDirArgs = plan.dirAccess === "add-dir" ? ["--add-dir", context.companionPath] : [];
+    const mcpConfigArgs =
+      plan.mcp === "mcp-config" && mcpConfigPath ? ["--mcp-config", mcpConfigPath] : [];
     const contextModeArgs = context.capabilities.some(
       (capability) => capability.name === "context-mode",
     )
@@ -62,14 +165,12 @@ export class ClaudeAdapter extends LaunchAdapter {
       : [];
 
     return [
-      "--add-dir",
-      context.companionPath,
+      ...addDirArgs,
       "--append-system-prompt",
       buildCompanionGuidance(context),
       ...settingsArgs,
       ...mcpConfigArgs,
-      // Bundled mate plugin (hooks) resolved from the running mate-core
-      // installation, coexisting with the context-mode plugin dir.
+      /** The bundled plugin from the running install, beside context-mode's. */
       "--plugin-dir",
       getClaudePluginRoot(),
       ...contextModeArgs,
@@ -77,7 +178,7 @@ export class ClaudeAdapter extends LaunchAdapter {
     ];
   }
 
-  extendEnvironment(_context: AdapterContext): NodeJS.ProcessEnv {
+  extendEnvironment(_context: ClaudeLaunchContext): NodeJS.ProcessEnv {
     return {
       CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: "1",
     };

package/src/lib/orchestrator/adapters/opencode.ts

@@ -7,15 +7,12 @@ const path = await import("node:path");
 import { MATE_ENV } from "../../../runtime/env";
 import { validateGuidanceData, type MateGuidanceFile } from "../../../runtime/guidance";
 
-import { getOpenCodePluginRoot, validateOpenCodePluginAssets } from "../../package-paths";
-import {
-  mergeOpenCodeConfigContent,
-  readOpenCodeConfig,
-} from "../../../tools/setup/providers/opencode-format";
-import { renderCompanionExternalDirectoryPermissions } from "../../../tools/setup/providers/opencode";
+import { validateOpenCodePluginAssets } from "../../package-paths";
+import { readOpenCodeConfig } from "../../../tools/setup/providers/opencode-format";
 import { buildOpenCodeGuidance } from "../opencode-guidance";
+import type { PrepareResult } from "../session-prepare";
 import { LaunchPreflightError } from "../types";
-import { type AdapterContext, LaunchAdapter } from "./base";
+import { type AdapterContext, LaunchAdapter, prepareFailure } from "./base";
 
 /** The Mate plugin is a V2 plugin; an older host rejects it at load time. */
 const MIN_OPENCODE_MAJOR = 2;
@@ -62,6 +59,13 @@ export class OpenCodeAdapter extends LaunchAdapter {
     );
   }
 
+  /** A prepared repository reports its failure as one summary, as it always has. */
+  launchFailure(prepared: PrepareResult): unknown {
+    return prepared.repositoryId
+      ? new LaunchPreflightError(prepareFailure(prepared))
+      : super.launchFailure(prepared);
+  }
+
   buildArgs(context: AdapterContext, args: string[]): string[] {
     const codeDir = context.launchWorkingDirectory;
     const isTui = args.length === 0 || args[0]?.startsWith("-");
@@ -74,20 +78,14 @@ export class OpenCodeAdapter extends LaunchAdapter {
     return hostsServer && !choosesServer ? [command, STANDALONE_FLAG, ...rest] : [command, ...rest];
   }
 
+  /**
+   * No `OPENCODE_CONFIG_DIR` and no config overlay: OpenCode 2.x treats the
+   * config dir as a replacement for the user's global one, and everything the
+   * overlay carried now lives in the wrapped `.opencode/opencode.json`. An
+   * inherited `OPENCODE_CONFIG_DIR` or `OPENCODE_CONFIG_CONTENT` passes through.
+   */
   extendEnvironment(context: AdapterContext): NodeJS.ProcessEnv {
     return {
-      OPENCODE_CONFIG_DIR: path.join(context.companionPath, ".opencode"),
-      OPENCODE_CONFIG_CONTENT: mergeOpenCodeConfigContent(
-        {
-          permissions: renderCompanionExternalDirectoryPermissions(context.companionPath),
-          plugins: [getOpenCodePluginRoot()],
-          references: {
-            mate: context.companionPath,
-          },
-        },
-        process.env,
-        { appendSkillPaths: [path.join(context.companionPath, ".agents", "skills")] },
-      ),
       // Built fresh per launch from the live capability config; always set so
       // a stale value inherited from an outer Mate session can never leak in.
       [MATE_ENV.guidanceJson]: JSON.stringify(this.buildGuidance(context)),

package/src/lib/orchestrator/companion-git-sync.ts

@@ -12,6 +12,8 @@ import {
   type UpstreamTarget,
 } from "../../runtime/companion-git";
 import { recordCompanionSync } from "../../runtime/companion-git-state";
+import { withCompanionLock, type CompanionLockOptions } from "../../runtime/companion-lock";
+import { FRAMEWORK_NAME } from "../../framework";
 import { LaunchPreflightError } from "./types";
 
 type GitCommandResult = GitResult;
@@ -427,10 +429,35 @@ export class CompanionGitSync {
   }
 }
 
+/**
+ * An attended operation waits for whoever holds the companion lock, however
+ * long: the holder may be an operator answering a merge conflict. The line
+ * explains the pause; a crashed holder frees the lock by itself.
+ */
+export function attendedLockOptions(companionPath: string): CompanionLockOptions {
+  return {
+    timeoutMs: Number.POSITIVE_INFINITY,
+    onWait: () =>
+      console.error(
+        `${FRAMEWORK_NAME}: waiting for another companion sync to finish (${companionPath})…`,
+      ),
+  };
+}
+
+/** Serialized with every other synchronization of this companion. */
 export async function syncCompanionGit(
   companionPath: string,
   workingRepoPath?: string,
   interactiveGit = false,
 ): Promise<CompanionGitSyncResult> {
-  return new CompanionGitSync().sync(companionPath, workingRepoPath, interactiveGit);
+  const locked = await withCompanionLock(companionPath, attendedLockOptions(companionPath), () =>
+    new CompanionGitSync().sync(companionPath, workingRepoPath, interactiveGit),
+  );
+  if (!locked.acquired) {
+    throw new CompanionGitSyncError(
+      companionPath,
+      "Another companion synchronization is still running.",
+    );
+  }
+  return locked.value;
 }

package/src/lib/orchestrator/companion-hub.ts

@@ -15,7 +15,7 @@ import {
 } from "../../tools/setup/dynamic-plugins/install";
 import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
 import { applySetupCompatibilities } from "../../tools/setup";
-import { findRepoLocalRegistryFile } from "./repo-local-registry";
+import { findRepoLocalRegistryFile } from "./repository-link";
 import { companionGit, describeGitFailure, type CompanionGit } from "../../runtime/companion-git";
 
 export interface HubGitOptions {
@@ -319,6 +319,7 @@ export async function syncHub(
   const { config, store } = await assertHubRoot(hubPath);
   const results: HubSyncResult[] = [];
   for (const member of config.hub!.companions) {
+    // oxlint-disable-next-line no-await-in-loop -- members sync one at a time, in declared order
     const result = await syncHubMember(hubPath, member, options);
     results.push(result);
     if (result.materializedCommit && result.status === "updated") {

package/src/lib/orchestrator/config-store.ts

@@ -310,3 +310,12 @@ export class ConfigStore extends YamlFileStore<FrameworkConfig> {
     return config;
   }
 }
+
+/** The companion's own selection, read from files: wrapping runs no setup pass. */
+export async function readCompanionConfig(companionPath: string): Promise<FrameworkConfig> {
+  return mergeWithDefaults(
+    await new ConfigStore(
+      path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+    ).load(),
+  );
+}

package/src/lib/orchestrator/framework-context.ts

@@ -4,12 +4,13 @@ import path from "node:path";
 import { FRAMEWORK_NAME } from "../../framework";
 import { parse } from "yaml";
 import { CompanionRegistryStore } from "./companion-registry-store";
-import { CompanionResolver } from "./companion-resolver";
-import { companionRootedStore } from "./companion-store";
-import { readCompanionRegistry } from "./companion-registry-reader";
 import { ConfigStore } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
-import { findRepoLocalLinkedRepository } from "./repo-local-registry";
+import {
+  backfillCompanionRegistration,
+  CompanionResolver,
+  findRepoLocalLinkedRepository,
+} from "./repository-link";
 import { projectWorkingRepositoryBestEffort } from "./working-repo-projection";
 import {
   AmbiguousCompanionError,
@@ -257,31 +258,6 @@ export async function resolveForLaunch(
   throw new WorkingRepoRequiredError();
 }
 
-/**
- * Self-heals repos linked before the companion-side registry write existed
- * (or whose companion registry was reset): backfills the companion-side
- * entry from the already-trusted repo-local pointer on every launch
- * resolution. Best-effort — never blocks a launch.
- */
-async function backfillCompanionRegistration(
-  companionPath: string,
-  repository: LinkedRepository,
-): Promise<void> {
-  try {
-    const { repos } = await readCompanionRegistry(companionPath).catch(() => ({ repos: [] }));
-    const existing = repos.find((repo) => repo.id === repository.id);
-    if (existing?.path === repository.path) return;
-
-    await companionRootedStore(companionPath).registerRepository(repository);
-  } catch (error) {
-    console.error(
-      `${FRAMEWORK_NAME}: warning: failed to backfill companion registry for ${repository.id}: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    );
-  }
-}
-
 // Resolves context for `mate cap` commands. Unlike resolveForLaunch, this allows
 // running from the companion directory itself — cap commands manage companion state
 // and don't need a working-repo cwd. resolveForLaunch intentionally lacks this