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

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,42 @@ 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 {
+  /** `args` are the operator's arguments, before `buildArgs` rewrites them. */
+  extendEnvironment(_context: C, _args: string[] = []): NodeJS.ProcessEnv {
     return {};
   }
 
@@ -67,7 +101,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,10 +128,10 @@ 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);
+    const extendedEnv = this.extendEnvironment(context, args);
     const env = { ...baseEnv, ...extendedEnv };
 
     const processPath = process.env.PATH ?? "";
@@ -120,7 +156,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,223 @@
 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 {
+  audienceLayerDir,
+  currentAudienceLayer,
+  readLayerGuidanceSync,
+} from "../../../runtime/audience-layer";
+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 { RenderedAudienceLayer } from "../../../tools/setup/audience-layer";
+import type { PrepareResult } from "../session-prepare";
+import { LaunchPreflightError } from "../types";
 import { type AdapterContext, LaunchAdapter } from "./base";
 
-export class ClaudeAdapter extends LaunchAdapter {
+/** The active audience's layer, attached to this launch only. */
+interface ClaudeLayerDelivery {
+  audience: string;
+  root: string;
+  /** The layer's MCP configuration, when the layer holds one. */
+  mcpConfigPath?: string;
+}
+
+/** The paths are present only where the plan names that channel and the file exists. */
+interface ClaudeDelivery {
+  plan: ClaudeDeliveryPlan;
+  settingsPath?: string;
+  mcpConfigPath?: string;
+  layer?: ClaudeLayerDelivery;
+  /**
+   * The guidance of the audience the checkout is wrapped for. The wrap carries
+   * the rest of that audience; its guidance hook stays silent in a managed
+   * session, so the launch's own system prompt carries this.
+   */
+  wrappedGuidance?: string;
+}
+
+/** A Claude launch's context: the delivery its plan chose, and the files it chose or wrote. */
+interface ClaudeLaunchContext extends AdapterContext {
+  delivery: ClaudeDelivery;
+}
+
+function safeName(value: string): string {
+  return value.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+/**
+ * Where a launch writes its derived `--settings`. Per Working Repository and
+ * audience, so concurrent launches never race; a companion-scoped launch
+ * derives one only for an audience. Without an audience it is git-ignored
+ * under the companion. With one it carries that audience's hooks and
+ * permission entries, so it lives beside the audience's layer, outside the
+ * companion, where no other audience's session can read it.
+ */
+export function launchSettingsPath(
+  companionPath: string,
+  repositoryId: string | null,
+  audience?: string,
+): string {
+  const scope = repositoryId === null ? "companion-scope" : `settings.${safeName(repositoryId)}`;
+  if (audience) {
+    return path.join(audienceLayerDir(companionPath, audience), `launch-${scope}.json`);
+  }
+  return path.join(companionPath, ".claude", "state", `launch-${scope}.json`);
+}
+
+async function readSettings(settingsPath: string): Promise<ClaudeSettings> {
+  if (!existsSync(settingsPath)) return {};
+  return JSON.parse(await fs.readFile(settingsPath, "utf8")) as ClaudeSettings;
+}
+
+/**
+ * Companion settings minus `exclude`, so each wrap-carried group runs once,
+ * plus the layer's hook groups and permission entries. A file, not inline JSON
+ * (platform arg limits). Claude reads one `--settings` file only — a second
+ * one replaces the first — so the layer is merged here, never passed beside.
+ */
+async function writeLaunchSettings(
+  companionSettingsPath: string,
+  target: string,
+  exclude: readonly ClaudeHookGroup[],
+  layerSettingsPath?: string,
+): Promise<void> {
+  const settings = await readSettings(companionSettingsPath);
+  const layer = layerSettingsPath ? await readSettings(layerSettingsPath) : {};
+  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;
+  }
+  for (const [event, groups] of Object.entries(layer.hooks ?? {})) {
+    hooks[event] = [...(hooks[event] ?? []), ...(groups ?? [])];
+  }
+  const derived: ClaudeSettings = { ...settings, hooks };
+  if (Object.keys(hooks).length === 0) delete derived.hooks;
+  const layerAllow = layer.permissions?.allow ?? [];
+  if (layerAllow.length > 0) {
+    const allow = [...new Set([...(settings.permissions?.allow ?? []), ...layerAllow])];
+    derived.permissions = { ...settings.permissions, allow };
+  }
+
+  const text = `${JSON.stringify(derived, null, 2)}\n`;
+  if (layerSettingsPath) {
+    /** Beside the audience's layer: as private as the layer itself. */
+    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    await writeAtomic(target, text, 0o600);
+  } else {
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await writeAtomic(target, text);
+  }
+}
+
+/** The `--settings` file the plan's hook owner calls for, writing it when derived. */
+async function settingsPathFor(
+  plan: ClaudeDeliveryPlan,
+  companionPath: string,
+  repository: AdapterContext["repository"],
+  layer: RenderedAudienceLayer | undefined,
+): Promise<string | undefined> {
+  const companionSettingsPath = getCompanionClaudeSettingsPath(companionPath);
+  if (plan.hooks.owner === "none") return undefined;
+  if (!layer && !existsSync(companionSettingsPath)) return undefined;
+  if (plan.hooks.owner === "settings" && !layer) return companionSettingsPath;
+  /** Owner `wrap` is planned only for `managed-repo`, which has a repository. */
+  const settingsPath = launchSettingsPath(
+    companionPath,
+    plan.hooks.owner === "wrap" ? repository!.id : null,
+    layer?.audience,
+  );
+  await writeLaunchSettings(
+    companionSettingsPath,
+    settingsPath,
+    plan.hooks.launchSettingsExclude,
+    layer ? getCompanionClaudeSettingsPath(layer.root) : undefined,
+  );
+  return settingsPath;
+}
+
+/** The layer as this launch attaches it: the directory, and its MCP configuration when present. */
+function layerDelivery(layer: RenderedAudienceLayer | undefined): ClaudeLayerDelivery | undefined {
+  if (!layer) return undefined;
+  const mcpConfigPath = getCompanionClaudeMcpConfigPath(layer.root);
+  return {
+    audience: layer.audience,
+    root: layer.root,
+    ...(existsSync(mcpConfigPath) ? { mcpConfigPath } : {}),
+  };
+}
+
+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,
+      prepared.audienceLayer,
+    );
+    const layer = layerDelivery(prepared.audienceLayer);
+    const wrappedLayer =
+      !layer && wrap.audience ? currentAudienceLayer(companionPath, wrap.audience) : null;
+    const wrappedGuidance = wrappedLayer ? readLayerGuidanceSync(wrappedLayer, "CLAUDE.md") : "";
+    const delivery: ClaudeDelivery = {
+      plan,
+      ...(plan.mcp === "mcp-config" && existsSync(mcpConfigPath) ? { mcpConfigPath } : {}),
+      ...(settingsPath ? { settingsPath } : {}),
+      ...(layer ? { layer } : {}),
+      ...(wrappedGuidance ? { wrappedGuidance } : {}),
+    };
+    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 +239,35 @@ 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, layer, wrappedGuidance } = context.delivery;
+    const companionGuidance = buildCompanionGuidance(context);
+    const systemPrompt = wrappedGuidance
+      ? `${companionGuidance}\n\n${wrappedGuidance}`
+      : companionGuidance;
+    /** 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]
+        : [];
+    /**
+     * The layer adds its skills, commands, agents and `CLAUDE.md` as one more
+     * directory, and its MCP servers as one more configuration beside every
+     * server the launch delivered before. Both flags are variadic, so each is
+     * followed by another flag, never by the operator's arguments.
+     */
+    const addDirArgs = [
+      ...(plan.dirAccess === "add-dir" ? ["--add-dir", context.companionPath] : []),
+      ...(layer ? ["--add-dir", layer.root] : []),
+    ];
+    const mcpConfigArgs = [
+      ...(plan.mcp === "mcp-config" && mcpConfigPath ? ["--mcp-config", mcpConfigPath] : []),
+      ...(layer?.mcpConfigPath ? ["--mcp-config", layer.mcpConfigPath] : []),
+    ];
     const contextModeArgs = context.capabilities.some(
       (capability) => capability.name === "context-mode",
     )
@@ -62,14 +275,12 @@ export class ClaudeAdapter extends LaunchAdapter {
       : [];
 
     return [
-      "--add-dir",
-      context.companionPath,
+      ...addDirArgs,
       "--append-system-prompt",
-      buildCompanionGuidance(context),
+      systemPrompt,
       ...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 +288,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;
@@ -39,7 +36,32 @@ function parseOpenCodeMajor(output: string | undefined): number | undefined {
   return match ? Number(match[1]) : undefined;
 }
 
-export class OpenCodeAdapter extends LaunchAdapter {
+interface OpenCodeInvocation {
+  command: string | undefined;
+  rest: string[];
+  /**
+   * The launch runs its own private server, where the plugin loads with this
+   * launch's environment: the TUI or `run`, not pointed at a remote server.
+   * Every other invocation may start or reach the shared service, which must
+   * never receive a guidance payload.
+   */
+  hostsPrivateServer: boolean;
+}
+
+function readInvocation(launchWorkingDirectory: string, args: string[]): OpenCodeInvocation {
+  const isTui = args.length === 0 || args[0]?.startsWith("-");
+  const [command, ...rest] = isTui ? [launchWorkingDirectory, ...args] : args;
+  const hostsServer = isTui || command === "run";
+  const choosesRemoteServer = rest.some((arg) => arg === "--server" || arg.startsWith("--server="));
+  return { command, rest, hostsPrivateServer: Boolean(hostsServer) && !choosesRemoteServer };
+}
+
+/** An OpenCode launch's context: the audience layer its prepare rendered, if any. */
+interface OpenCodeLaunchContext extends AdapterContext {
+  audienceLayer?: string;
+}
+
+export class OpenCodeAdapter extends LaunchAdapter<OpenCodeLaunchContext> {
   readonly toolName = "opencode";
   readonly interactive = true;
   private readonly requiredRuntimeAssets = [path.join(".opencode", "opencode.json")] as const;
@@ -62,45 +84,61 @@ export class OpenCodeAdapter extends LaunchAdapter {
     );
   }
 
+  async planLaunch(
+    context: AdapterContext,
+    prepared: PrepareResult,
+  ): Promise<OpenCodeLaunchContext> {
+    return prepared.audienceLayer
+      ? { ...context, audienceLayer: prepared.audienceLayer.root }
+      : context;
+  }
+
+  /** 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("-");
-    const [command, ...rest] = isTui ? [codeDir, ...args] : args;
-    if (!command) return args;
-    const hostsServer = isTui || command === "run";
-    const choosesServer = rest.some(
-      (arg) => arg === "--standalone" || arg === "--server" || arg.startsWith("--server="),
+    const { command, rest, hostsPrivateServer } = readInvocation(
+      context.launchWorkingDirectory,
+      args,
     );
-    return hostsServer && !choosesServer ? [command, STANDALONE_FLAG, ...rest] : [command, ...rest];
+    if (!command) return args;
+    const addsStandalone = hostsPrivateServer && !rest.includes(STANDALONE_FLAG);
+    return addsStandalone ? [command, STANDALONE_FLAG, ...rest] : [command, ...rest];
   }
 
-  extendEnvironment(context: AdapterContext): NodeJS.ProcessEnv {
+  /**
+   * 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: OpenCodeLaunchContext, args: string[] = []): NodeJS.ProcessEnv {
+    const { hostsPrivateServer } = readInvocation(context.launchWorkingDirectory, args);
     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)),
+      // Masked unless the launch hosts its own server: a payload that reached
+      // the shared service would apply this session's guidance — and its
+      // audience layer — to every other.
+      [MATE_ENV.guidanceJson]: hostsPrivateServer
+        ? JSON.stringify(this.buildGuidance(context))
+        : "",
     };
   }
 
-  private buildGuidance(context: AdapterContext): MateGuidanceFile {
-    return buildOpenCodeGuidance(context.capabilities, {
+  /** The audience layer travels as a path; the plugin reads it through the surface's reader. */
+  private buildGuidance(context: OpenCodeLaunchContext): MateGuidanceFile {
+    const guidance = buildOpenCodeGuidance(context.capabilities, {
       companionScoped: !context.repository,
     });
+    return context.audienceLayer ? { ...guidance, audienceLayer: context.audienceLayer } : guidance;
   }
 
-  async validateLaunch(context: AdapterContext): Promise<void> {
+  async validateLaunch(context: OpenCodeLaunchContext): Promise<void> {
     this.validateOpenCodeVersion();
 
     const missingAssets = await Promise.all(
@@ -164,7 +202,7 @@ export class OpenCodeAdapter extends LaunchAdapter {
 
   // Self-check the guidance payload this launch is about to inject so a
   // broken playbook template fails preflight instead of inside OpenCode.
-  private validateGuidance(context: AdapterContext): string[] {
+  private validateGuidance(context: OpenCodeLaunchContext): string[] {
     const built = this.buildGuidance(context);
     const { guidance, errors } = validateGuidanceData(built);
 

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") {