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

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

@@ -1,5 +1,14 @@
 import path from "node:path";
 
+import semver from "semver";
+
+import {
+  BASE_AUDIENCE,
+  BASE_AUDIENCE_KEYS,
+  normalizeBaseAudience,
+} from "../../tools/setup/dynamic-plugins/audiences";
+
+import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
 import {
   getDefaultSetupSelections,
@@ -291,22 +300,95 @@ function validateAudiences(config: FrameworkConfig): void {
   }
 }
 
+/**
+ * The release that introduces the `audiences.base` shape. An older Mate would
+ * read a saved file as an empty base plus an audience called `base`, so every
+ * save in the new shape raises the companion's `engines` floor to it — capped
+ * at the running release, so a pre-release build never locks itself out.
+ */
+export const BASE_AUDIENCE_MIN_VERSION = "0.19.0";
+
+/** The floor version a save writes: the introducing release, or the running one when older. */
+export function baseAudienceFloorVersion(
+  runningVersion: string = getActiveDistribution().config.version,
+): string {
+  const running = semver.coerce(runningVersion)?.version;
+  return running && semver.lt(running, BASE_AUDIENCE_MIN_VERSION)
+    ? running
+    : BASE_AUDIENCE_MIN_VERSION;
+}
+
+/** Only companions carry audiences; a hub or a working repository keeps the root shape. */
+function usesAudiences(config: FrameworkConfig): boolean {
+  return config.type === undefined || config.type === "companion";
+}
+
+/** The floor that admits the base audience shape, keeping a higher one. */
+function raisedEngineFloor(range: string | undefined): string {
+  const version = baseAudienceFloorVersion();
+  const floor = `>=${version}`;
+  if (!range || semver.validRange(range) === null) return range ?? floor;
+  const minimum = semver.minVersion(range);
+  return minimum && semver.gte(minimum, version) ? range : floor;
+}
+
+/**
+ * The file shape of a companion config: the base set's audience-scoped keys
+ * under `audiences.base`, first among the audiences. The in-memory config
+ * keeps them at the root, so its readers never see the difference.
+ */
+function toFileShape(config: FrameworkConfig): FrameworkConfig {
+  if (!usesAudiences(config)) return config;
+  const base: Record<string, unknown> = {};
+  const rest: Record<string, unknown> = { ...config };
+  for (const key of BASE_AUDIENCE_KEYS) {
+    if (rest[key] === undefined) continue;
+    base[key] = rest[key];
+    delete rest[key];
+  }
+  if (Object.keys(base).length === 0) return config;
+  return {
+    ...(rest as unknown as FrameworkConfig),
+    audiences: { [BASE_AUDIENCE]: base, ...config.audiences } as FrameworkConfig["audiences"],
+    engines: {
+      ...config.engines,
+      [FRAMEWORK_NAME]: raisedEngineFloor(config.engines?.[FRAMEWORK_NAME]),
+    },
+  };
+}
+
 export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   constructor(configPath = process.env.MATE_CONFIG ?? defaultConfigPath()) {
     super(path.resolve(configPath));
   }
 
+  /** Either file shape loads as the base set at the root; the new shape persists on the next save. */
   override async load(): Promise<FrameworkConfig> {
-    const merged = mergeWithDefaults(migrateProfilesToAllowedAgents(await super.load()));
+    const merged = mergeWithDefaults(
+      migrateProfilesToAllowedAgents(normalizeBaseAudience(await super.load())),
+    );
     validateHubConfig(merged);
     validatePluginDeclarations(merged);
     validateAudiences(merged);
     return merged;
   }
 
+  override async save(config: FrameworkConfig): Promise<void> {
+    await super.save(toFileShape(config));
+  }
+
   protected async onMissing(): Promise<FrameworkConfig> {
     const config = defaultConfig();
     await this.save(config);
     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

package/src/lib/orchestrator/launcher.ts

@@ -1,28 +1,13 @@
 // oxlint-disable no-underscore-dangle
-import { syncCompanionFiles } from "../../tools/setup";
-import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
-import type { CapabilityPlugin, LaunchPreflightContext } from "../../tools/setup/plugin";
-import type { LaunchAdapter, AdapterContext } from "./adapters/base";
+import type { AdapterContext, LaunchAdapter } from "./adapters/base";
 import { ClaudeAdapter } from "./adapters/claude";
 import { OpenCodeAdapter } from "./adapters/opencode";
-import { CompanionStore } from "./companion-store";
-import { syncCompanionGit } from "./companion-git-sync";
+import { CompanionStore } from "./repository-link";
 import { resolveForLaunch, type LaunchContext } from "./framework-context";
-import {
-  firstFailure,
-  type ProjectionEntryOutcome,
-  type ProjectionInput,
-  type ProjectionResult,
-} from "./projection-types";
-import {
-  isWorkingRepositoryWrapped,
-  project,
-  projectWorkingRepositoryBestEffort,
-} from "./working-repo-projection";
+import { prepareSession, type PrepareResult, type PrepareRuntime } from "./session-prepare";
 import {
   RepositoryNotSelectedError,
-  LaunchPreflightError,
   ToolNotAllowedError,
   type FrameworkConfig,
   type LaunchRequest,
@@ -53,60 +38,27 @@ interface ResolvedLaunchState {
 }
 
 export const launcherDeps = {
-  syncCompanionFiles,
-  /** The Managed Projection's launch scope; the working repo is written only here. */
-  projectWorkingRepo: (input: ProjectionInput) => project("launch", input),
-  /**
-   * The Projection Root a launch guarantees for itself. `resolveForLaunch` also
-   * writes it, but only on the branch that resolved a companion from the
-   * Working Repository; asking here makes the guarantee independent of which
-   * branch answered. Best-effort — a launch carries its own configuration.
-   */
-  refreshProjectionRoot: projectWorkingRepositoryBestEffort,
-  syncCompanionGit,
-  isWrapped: isWorkingRepositoryWrapped,
+  prepareSession,
 };
 
-/**
- * A wrapped Working Repository delivers the companion to sessions the operator
- * starts themselves, through documents the Agent Runtime discovers by its own
- * upward walk. A Managed Session loads those *and* everything the launch
- * injects through `--settings`, `--mcp-config` and `--plugin-dir`, which
- * ADR-014 established can never be withdrawn. Two delivery channels that cannot
- * be merged must therefore not both be live for one repository, so wrapping and
- * launching are exclusive rather than reconciled (ADR-015, superseding
- * ADR-014's judgement that the duplication is bounded enough to accept).
- *
- * Raised before every write the launch itself performs: the companion Git sync,
- * the companion file sync, the launch scope's projection and the runtime
- * invocation. Companion resolution has already refreshed the Projection Root by
- * this point — `resolveForLaunch` writes it while resolving — but that write is
- * idempotent and byte-identical to the one `mate wrap` performs, so it cannot
- * change what the repository holds.
- */
-function wrappedRepositoryRefusal(repository: LinkedRepository): string {
-  return [
-    `${FRAMEWORK_NAME}: ${repository.id} is wrapped — \`${FRAMEWORK_NAME} claude\` and \`${FRAMEWORK_NAME} opencode\` do not run in a wrapped working repository.`,
-    "Start the session yourself: `claude` or `opencode` — the wrap delivers the companion guidance.",
-    `Or restore managed launches: \`${FRAMEWORK_NAME} unwrap\`.`,
-  ].join("\n");
-}
-
-/**
- * The shape `projectWorkingRepositoryBestEffort` reports a failed projection
- * in, narrowed to the entry that failed: the launch scope writes several, so
- * "the projection" alone would not tell the operator what to fix.
- */
-function projectionFailure(outcome: ProjectionEntryOutcome, repository: LinkedRepository): string {
-  const error = outcome.error ?? new Error("projection failed");
-  return `failed to write ${outcome.path} for ${repository.id}: ${error.message}`;
+/** The wrap notice is informational: `process.stderr.write`, since Bun renders `console.error` red. */
+function report(result: PrepareResult): void {
+  const wrapped = result.steps.find((step) => step.step === "working-target");
+  if (wrapped?.outcome === "ok" && wrapped.detail !== "current") {
+    const runtime = wrapped.runtimes?.includes("claude") ? "Claude" : "OpenCode";
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: wrapped ${result.repositoryId} for ${runtime}: ${wrapped.detail}\n`,
+    );
+  }
+  for (const warning of result.warnings) {
+    console.error(`${FRAMEWORK_NAME}: warning: ${warning}`);
+  }
 }
 
 export class FrameworkLauncher {
-  private readonly adapters = new Map<string, LaunchAdapter>([
-    ["claude", new ClaudeAdapter()],
-    ["opencode", new OpenCodeAdapter()],
-  ]);
+  private readonly adapters = new Map<string, LaunchAdapter>(
+    [new ClaudeAdapter(), new OpenCodeAdapter()].map((adapter) => [adapter.toolName, adapter]),
+  );
 
   async resolveLaunchPreview(request: LaunchRequest): Promise<LaunchPreview> {
     const state = await this.resolveLaunchState(request);
@@ -119,42 +71,25 @@ export class FrameworkLauncher {
     };
   }
 
+  /**
+   * Session Prepare in its attended mode, then the adapter's share: it words a
+   * failed prepare, plans what the launch delivers, and runs its own checks.
+   * Each launch's plan travels in its own context, never on the adapter.
+   */
   async prepare(request: LaunchRequest): Promise<PreparedLaunch> {
     const state = await this.resolveLaunchState(request);
-    const adapterContext = this.makeAdapterContext(state);
 
-    if (state.repository && (await launcherDeps.isWrapped(state.repository.path))) {
-      throw new LaunchPreflightError(wrappedRepositoryRefusal(state.repository));
-    }
-
-    if (!request.skipGit && state.config.git === "auto") {
-      await launcherDeps.syncCompanionGit(
-        state.companionPath,
-        state.repository?.path,
-        request.interactiveGit ?? false,
-      );
-    }
-    if (state.repository) {
-      await launcherDeps.syncCompanionFiles(
-        state.companionPath,
-        state.config,
-        state.repository.path,
-      );
-    } else {
-      await launcherDeps.syncCompanionFiles(state.companionPath, state.config);
-    }
-    if (state.repository) {
-      this.answerForProjection(
-        await launcherDeps.projectWorkingRepo({
-          repoPath: state.repository.path,
-          companionPath: state.companionPath,
-          config: state.config,
-        }),
-        state.repository,
-      );
-      await launcherDeps.refreshProjectionRoot(state.companionPath, state.repository);
-    }
-    await this.runCapabilityPreflight(state, request.tool);
+    const prepared = await launcherDeps.prepareSession({
+      runtime: request.tool as PrepareRuntime,
+      companionPath: state.companionPath,
+      repository: state.repository,
+      mode: "attended",
+      config: state.config,
+      skipGit: state.skipGit,
+    });
+    report(prepared);
+    if (!prepared.ok) throw state.adapter.launchFailure(prepared);
+    const adapterContext = await state.adapter.planLaunch(this.makeAdapterContext(state), prepared);
     await state.adapter.validateLaunch(adapterContext);
 
     return {
@@ -174,7 +109,7 @@ export class FrameworkLauncher {
       repositoryId,
       repository: localRepository,
     } = await this.resolveConfig(request.scope);
-    const store = new CompanionStore(configStore, workingRepoStore);
+    const store = new CompanionStore(companionPath, workingRepoStore);
     const scope = request.scope ?? "working-repo";
     const repository =
       scope === "companion"
@@ -205,28 +140,6 @@ export class FrameworkLauncher {
     };
   }
 
-  /**
-   * `project` reports its failures rather than throwing, so the launch scope's
-   * caller is the one that has to answer for them. A non-degradable entry is a
-   * guardrail the session was promised — writing the companion into the
-   * runtime's allow-list, for one — so the launch fails instead of starting
-   * without it. A degradable entry warns in the voice
-   * {@link projectWorkingRepositoryBestEffort} uses, and the launch proceeds.
-   */
-  private answerForProjection(result: ProjectionResult, repository: LinkedRepository): void {
-    for (const outcome of result.outcomes) {
-      if (outcome.state !== "failed" || !outcome.degradable) continue;
-      console.error(`${FRAMEWORK_NAME}: warning: ${projectionFailure(outcome, repository)}`);
-    }
-
-    const failure = firstFailure(result.outcomes);
-    if (failure) {
-      throw new LaunchPreflightError(
-        `${FRAMEWORK_NAME}: ${projectionFailure(failure, repository)}`,
-      );
-    }
-  }
-
   private makeAdapterContext(state: ResolvedLaunchState): AdapterContext {
     return {
       repository: state.repository,
@@ -239,54 +152,6 @@ export class FrameworkLauncher {
     };
   }
 
-  private async runCapabilityPreflight(
-    state: ResolvedLaunchState,
-    providerId: string,
-  ): Promise<void> {
-    const context: LaunchPreflightContext = {
-      companionPath: state.companionPath,
-      config: state.config,
-      repository: state.repository,
-      providerId,
-    };
-    const preflights = getActiveDistribution()
-      .registry.getAll()
-      .reduce<
-        Array<{
-          capability: CapabilityPlugin;
-          preflight: NonNullable<NonNullable<CapabilityPlugin["forProvider"]>[string]["preflight"]>;
-        }>
-      >((entries, plugin) => {
-        if (plugin.kind !== "capability" || !plugin.isEnabled(state.config)) return entries;
-        const capability = plugin as CapabilityPlugin;
-        const preflight = capability.forProvider?.[providerId]?.preflight;
-        if (preflight) entries.push({ capability, preflight });
-        return entries;
-      }, []);
-    const results = await Promise.all(
-      preflights.map(async ({ capability, preflight }) => {
-        try {
-          return await preflight(context);
-        } catch (error) {
-          const detail = error instanceof Error ? error.message : String(error);
-          throw new LaunchPreflightError(
-            `Capability preflight failed for ${capability.id} on ${providerId}: ${detail}`,
-            { cause: error },
-          );
-        }
-      }),
-    );
-    const diagnostics = results.flat();
-
-    if (diagnostics.length > 0) {
-      throw new LaunchPreflightError(
-        ["Capability launch preflight failed.", ...diagnostics.map((item) => `- ${item}`)].join(
-          "\n",
-        ),
-      );
-    }
-  }
-
   private async resolveConfig(scope: LaunchScope = "working-repo"): Promise<LaunchContext> {
     return resolveForLaunch(process.cwd(), undefined, scope);
   }

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

@@ -0,0 +1,202 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { parse as parseYaml } from "yaml";
+
+import { MATE_ENV } from "../../runtime/env-names";
+import { runtimeWrapperBinPath } from "../../runtime/runtime-directory";
+import { resolveCommandOnPath } from "../../tools/setup/utils";
+import { getWrapperBinPath } from "../package-paths";
+
+/**
+ * The Companion Repository as an OpenSpec store. OpenSpec reports the Working
+ * Repository as an edit root only when the CLI runs inside a project whose
+ * `openspec/config.yaml` declares a registered store, so the store has to be
+ * registered before any pointer may name it.
+ *
+ * Registration is checked by reading OpenSpec's registry file, never by
+ * spawning: the check runs on every session refresh. The CLI is spawned only to
+ * register, which OpenSpec answers authoritatively.
+ */
+
+const execFileAsync = promisify(execFile);
+
+/** OpenSpec's one id grammar, shared by store and change ids. */
+const KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+const STORE_METADATA_FILE = path.join(".openspec-store", "store.yaml");
+
+/** Injectable so the suite never touches the developer's registry or binary. */
+export const openSpecStoreDeps = {
+  env: (): NodeJS.ProcessEnv => process.env,
+  platform: (): NodeJS.Platform => process.platform,
+  homedir: (): string => os.homedir(),
+  /** Mate's own `openspec` wrappers, which must never answer a registration. */
+  wrapperBinDirs: (): string[] => {
+    const launched = openSpecStoreDeps.env()[MATE_ENV.wrapperBinPath];
+    return [getWrapperBinPath(), runtimeWrapperBinPath(), ...(launched ? [launched] : [])];
+  },
+  resolveBinary: (): string | undefined => {
+    const excluded = new Set(openSpecStoreDeps.wrapperBinDirs().map((dir) => path.resolve(dir)));
+    const searchPath = (openSpecStoreDeps.env().PATH ?? "")
+      .split(path.delimiter)
+      .filter((dir) => dir && !excluded.has(path.resolve(dir)))
+      .join(path.delimiter);
+    return resolveCommandOnPath("openspec", searchPath);
+  },
+};
+
+export type StoreRegistrationCheck =
+  | { state: "registered" }
+  | { state: "absent" }
+  | { state: "conflict"; path: string }
+  | { state: "unreadable" };
+
+export type StoreRegistration =
+  | { state: "written" | "current"; id: string }
+  | { state: "skipped"; reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function canonicalPath(candidate: string): Promise<string> {
+  return fs.realpath(candidate).catch(() => path.resolve(candidate));
+}
+
+async function isDirectory(candidate: string): Promise<boolean> {
+  return fs
+    .stat(candidate)
+    .then((stats) => stats.isDirectory())
+    .catch(() => false);
+}
+
+function sanitizeStoreId(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * The id a registration already recorded beside the companion, else the
+ * companion folder name made into a valid id. Machine-local on purpose: no
+ * artifact embeds it, and a committed one would collide across clones.
+ */
+export async function deriveStoreId(companionPath: string): Promise<string> {
+  const metadata = await fs
+    .readFile(path.join(companionPath, STORE_METADATA_FILE), "utf8")
+    .then((content) => parseYaml(content) as unknown)
+    .catch(() => null);
+  if (isRecord(metadata) && typeof metadata.id === "string" && KEBAB_ID.test(metadata.id)) {
+    return metadata.id;
+  }
+  const folder = path.basename(path.resolve(companionPath));
+  const id = sanitizeStoreId(folder);
+  if (!KEBAB_ID.test(id)) {
+    throw new Error(`cannot derive an OpenSpec store id from the companion folder "${folder}"`);
+  }
+  return id;
+}
+
+/** Mirrors OpenSpec's `getGlobalDataDir`, so Mate reads the registry OpenSpec writes. */
+export function openSpecDataDir(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+  homedir: string,
+): string {
+  if (env.XDG_DATA_HOME) return path.join(env.XDG_DATA_HOME, "openspec");
+  if (platform === "win32") {
+    return path.join(env.LOCALAPPDATA ?? path.join(homedir, "AppData", "Local"), "openspec");
+  }
+  return path.join(homedir, ".local", "share", "openspec");
+}
+
+function registryPath(): string {
+  return path.join(
+    openSpecDataDir(
+      openSpecStoreDeps.env(),
+      openSpecStoreDeps.platform(),
+      openSpecStoreDeps.homedir(),
+    ),
+    "stores",
+    "registry.yaml",
+  );
+}
+
+/** Read-only: what the registry says about `id`, compared by canonical path. */
+export async function checkStoreRegistration(
+  companionPath: string,
+  id: string,
+): Promise<StoreRegistrationCheck> {
+  let content: string;
+  try {
+    content = await fs.readFile(registryPath(), "utf8");
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT"
+      ? { state: "absent" }
+      : { state: "unreadable" };
+  }
+  let registry: unknown;
+  try {
+    registry = parseYaml(content);
+  } catch {
+    return { state: "unreadable" };
+  }
+  if (!isRecord(registry) || !isRecord(registry.stores)) return { state: "unreadable" };
+  const entry = registry.stores[id];
+  if (entry === undefined) return { state: "absent" };
+  const localPath =
+    isRecord(entry) && isRecord(entry.backend) ? entry.backend.local_path : undefined;
+  if (typeof localPath !== "string") return { state: "unreadable" };
+  return (await canonicalPath(localPath)) === (await canonicalPath(companionPath))
+    ? { state: "registered" }
+    : { state: "conflict", path: localPath };
+}
+
+function commandOutput(error: unknown): string {
+  const { stderr, stdout, message } = error as {
+    stderr?: string;
+    stdout?: string;
+    message: string;
+  };
+  return (stderr || stdout || message).trim();
+}
+
+/**
+ * Registers the companion when the registry lacks it. A conflicting id fails
+ * rather than silently picking another one; OpenSpec without stores, or a
+ * companion that is no OpenSpec root, is skipped.
+ */
+export async function ensureStoreRegistration(companionPath: string): Promise<StoreRegistration> {
+  const companion = await canonicalPath(companionPath);
+  if (!(await isDirectory(path.join(companion, "openspec")))) {
+    return { state: "skipped", reason: `${companion} is not an OpenSpec root` };
+  }
+  const id = await deriveStoreId(companion);
+  const check = await checkStoreRegistration(companion, id);
+  if (check.state === "registered") return { state: "current", id };
+  if (check.state === "conflict") {
+    throw new Error(`OpenSpec store id "${id}" is already registered at ${check.path}`);
+  }
+
+  const bin = openSpecStoreDeps.resolveBinary();
+  if (!bin) return { state: "skipped", reason: "the openspec CLI is not on PATH" };
+  try {
+    await execFileAsync(bin, ["store", "register", companion, "--id", id, "--yes"], {
+      cwd: companion,
+      env: openSpecStoreDeps.env(),
+      timeout: 30_000,
+    });
+  } catch (error) {
+    const output = commandOutput(error);
+    if (/unknown command/i.test(output)) {
+      return { state: "skipped", reason: "the openspec CLI does not support stores" };
+    }
+    throw new Error(`openspec store register failed: ${output}`, { cause: error });
+  }
+  return { state: "written", id };
+}

package/src/lib/orchestrator/projection-claude-entry.ts

@@ -11,6 +11,7 @@ import {
   type ClaudeSettings,
 } from "../../tools/setup/providers/claude-format";
 import { isMateGuardHookGroup } from "../../tools/setup/providers/claude-plugin-hooks";
+import { readWrapState, type WrapState } from "../../runtime/wrap-state";
 import { pruneEmptyAncestors } from "../../tools/setup/utils";
 import { GlobalConfigStore } from "./global-config-store";
 
@@ -52,14 +53,21 @@ function parseSettings(raw: string | null): ClaudeSettings {
 }
 
 /**
- * Strips the managed hook groups earlier releases wrote here, but leaves the
- * guard group the `wrap` scope places: that one is managed by another entry,
- * and stripping it would disarm every Unmanaged Session on the next launch.
+ * Strips the managed hook groups earlier releases wrote here, but leaves every
+ * group the `wrap` scope places: those are owned by the wrap's own entry —
+ * Capability groups match a managed marker too — and stripping them would
+ * disarm every Unmanaged Session on the next launch.
  */
-function withoutForeignManagedHookGroups(settings: ClaudeSettings): ClaudeSettings {
+function withoutForeignManagedHookGroups(
+  settings: ClaudeSettings,
+  wrap: WrapState,
+): ClaudeSettings {
   const hooks = filterClaudeHookGroups(
     settings.hooks ?? {},
-    (group) => isMateGuardHookGroup(group) || !isManagedHookGroup(group),
+    (group) =>
+      isMateGuardHookGroup(group) ||
+      wrap.carriesClaudeHookGroup(group) ||
+      !isManagedHookGroup(group),
   );
   const next = { ...settings };
   if (Object.keys(hooks).length > 0) next.hooks = hooks;
@@ -81,7 +89,10 @@ export async function syncWorkingRepoClaudeAdditionalDirectories(
 ): Promise<"written" | "current"> {
   const target = settingsPath(repoPath);
   const raw = await readRaw(target);
-  const existing = withoutForeignManagedHookGroups(parseSettings(raw));
+  const existing = withoutForeignManagedHookGroups(
+    parseSettings(raw),
+    await readWrapState(repoPath),
+  );
   const permissions = { ...existing.permissions };
   const existingAdditionalDirectories = Array.isArray(permissions.additionalDirectories)
     ? permissions.additionalDirectories