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

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

@@ -7,6 +7,7 @@ import {
   type StudioAccess,
   type StudioInvocation,
 } from "./access";
+import { MERMAID_RUNTIME_URL } from "../report/renderer";
 import { collectStudioInventory, type StudioInventory } from "./inventory";
 import { assembleCompanionPayload, type StudioCompanionResponse } from "./payload";
 import { createReportStore, isReportId, REPORT_LIMITS, type ReportStore } from "./reports";
@@ -189,11 +190,14 @@ function refused(reason: string, status: number): Response {
   });
 }
 
-/** Sent with every hosted report: opaque origin, no connections, no Studio cookie or storage. */
+/**
+ * Sent with every hosted report: opaque origin, no Studio cookie or storage, and
+ * no connections beyond the one pinned, integrity-checked diagram runtime.
+ */
 const REPORT_CSP = [
   "sandbox allow-scripts allow-modals",
   "default-src 'none'",
-  "script-src 'unsafe-inline'",
+  `script-src 'unsafe-inline' ${MERMAID_RUNTIME_URL}`,
   "style-src 'unsafe-inline'",
   "img-src data:",
   "font-src data:",

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

@@ -3,9 +3,11 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { ConfigStore, mergeWithDefaults } from "../../../lib/orchestrator/config-store";
+import { currentAudienceLayer } from "../../../runtime/audience-layer";
 import {
   effectiveStudioAgent,
   readAudienceSelection,
+  resolveAudience,
 } from "../../../tools/setup/dynamic-plugins/audiences";
 import type { StudioInventory, StudioInventoryCompanion } from "./inventory";
 import { findAction, promptArgs, skillInstalledFor, SUBJECT_PATTERN } from "./actions";
@@ -51,7 +53,8 @@ export interface DefaultAgentOutcome {
 /**
  * The companion's effective default agent for one provider: the active
  * audience's `studio.terminal.agent` (Studio's own `MATE_AUDIENCE`, never the
- * browser's), else the base one. Never throws and never echoes the configured
+ * browser's), else the base one. Its definition may come from the companion
+ * or from the active audience's rendered layer. Never throws and never echoes the configured
  * value into the notice.
  */
 export async function defaultAgentFor(
@@ -62,11 +65,13 @@ export async function defaultAgentFor(
   const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
   if (!fs.existsSync(configPath)) return {};
   let name: unknown;
+  let layer: string | null = null;
   try {
-    name = effectiveStudioAgent(
-      await new ConfigStore(configPath).load(),
-      readAudienceSelection(env),
-    );
+    const config = await new ConfigStore(configPath).load();
+    const audience = resolveAudience(config, readAudienceSelection(env));
+    const active = audience.ok ? audience.active : null;
+    name = effectiveStudioAgent(config, active);
+    if (active) layer = currentAudienceLayer(companionPath, active);
   } catch {
     return {};
   }
@@ -76,8 +81,12 @@ export async function defaultAgentFor(
       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)) {
+  /** The audience's own agents live in its launch layer, which the terminal's launch attaches. */
+  const roots = layer ? [companionPath, layer] : [companionPath];
+  const defined = roots.some((root) =>
+    fs.existsSync(path.join(root, AGENT_DEFINITION_DIRS[agent], `${name}.md`)),
+  );
+  if (!defined) {
     return {
       notice: `Default agent "${name}" not applied: this companion has no ${agent} definition for it.`,
     };

package/src/cli/commands/unwrap.ts

@@ -1,6 +1,9 @@
 import { FRAMEWORK_NAME } from "../../framework";
-import { findRepoLocalLinkedRepository } from "../../lib/orchestrator/repo-local-registry";
+import { attendedLockOptions } from "../../lib/orchestrator/companion-git-sync";
+import { findRepoLocalLinkedRepository } from "../../lib/orchestrator/repository-link";
 import { unwrapWorkingRuntimeDocuments } from "../../lib/orchestrator/working-repo-projection";
+import { withCompanionLock } from "../../runtime/companion-lock";
+import { readProjectionFile } from "../../runtime/projection";
 
 export interface UnwrapCommandDependencies {
   findRepoLocalLinkedRepository?: typeof findRepoLocalLinkedRepository;
@@ -48,7 +51,24 @@ export async function runUnwrapCommand(
     return;
   }
 
-  const result = await unwrap(repository.path);
+  /**
+   * Under the lock of the companion the projection names, so a prepare or sync
+   * for it cannot rewrite the manifest mid-withdrawal. No companion, no lock:
+   * unwrapping must still work when the companion is gone.
+   */
+  const companionPath = readProjectionFile(repository.path)?.projection.companionPath;
+  const locked = companionPath
+    ? await withCompanionLock(companionPath, attendedLockOptions(companionPath), () =>
+        unwrap(repository.path),
+      )
+    : { acquired: true as const, value: await unwrap(repository.path) };
+  if (!locked.acquired) {
+    console.error(`${FRAMEWORK_NAME}: another companion synchronization is still running.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = locked.value;
   if (result.kind === "failed") {
     console.error(
       `${FRAMEWORK_NAME}: failed to withdraw ${result.document} for ${repository.id}: ${result.error.message}`,
@@ -66,5 +86,10 @@ export async function runUnwrapCommand(
   for (const document of result.documents) {
     console.log(`  Withdrawn: ${document}`);
   }
-  console.log(`\`${FRAMEWORK_NAME} claude\` and \`${FRAMEWORK_NAME} opencode\` work here again.`);
+  if (result.copies.length > 0) {
+    console.log(`  Withdrawn: ${result.copies.length} companion copies under .opencode/`);
+  }
+  console.log(
+    `The next \`${FRAMEWORK_NAME} claude\` or \`${FRAMEWORK_NAME} opencode\` wraps this repository again.`,
+  );
 }

package/src/cli/commands/wrap.ts

@@ -1,48 +1,61 @@
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../framework";
-import { ConfigStore, mergeWithDefaults } from "../../lib/orchestrator/config-store";
-import { findRepoLocalLinkedRepository } from "../../lib/orchestrator/repo-local-registry";
-import {
-  projectWorkingRepository,
-  projectWorkingRuntimeDocuments,
-} from "../../lib/orchestrator/working-repo-projection";
-import { renderWorkingRuntimeDocuments } from "../../tools/setup";
+import { findRepoLocalLinkedRepository } from "../../lib/orchestrator/repository-link";
+import type { ProjectionChangedPaths } from "../../lib/orchestrator/projection-types";
+import { attendedLockOptions } from "../../lib/orchestrator/companion-git-sync";
+import { readCompanionConfig } from "../../lib/orchestrator/config-store";
+import { runWrapPass, type WrapPassResult } from "../../lib/orchestrator/wrap-pass";
+import { withCompanionLock } from "../../runtime/companion-lock";
+import { WRAP_RUNTIMES } from "../../runtime/wrap-state";
 import { launchAmbiguityDeps } from "./shared/companion-selection";
 
 export interface WrapCommandDependencies {
   findRepoLocalLinkedRepository?: typeof findRepoLocalLinkedRepository;
-  projectWorkingRepository?: typeof projectWorkingRepository;
-  projectWorkingRuntimeDocuments?: typeof projectWorkingRuntimeDocuments;
-  renderWorkingRuntimeDocuments?: typeof renderWorkingRuntimeDocuments;
+  runWrapPass?: typeof runWrapPass;
   resolveLinkedCompanions?: typeof launchAmbiguityDeps.resolveLinkedCompanions;
 }
 
 export const wrapCommandDeps: Required<WrapCommandDependencies> = {
   findRepoLocalLinkedRepository,
-  projectWorkingRepository,
-  projectWorkingRuntimeDocuments,
-  renderWorkingRuntimeDocuments,
+  runWrapPass,
   resolveLinkedCompanions: (cwd: string) => launchAmbiguityDeps.resolveLinkedCompanions(cwd),
 };
 
-/** The companion's own selection, read from files: wrapping runs no setup pass. */
-async function readCompanionConfig(companionPath: string) {
-  return mergeWithDefaults(
-    await new ConfigStore(
-      path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
-    ).load(),
-  );
+/** Counts rather than names: a companion folder can hold dozens of files. */
+function reportChangedPaths(changed: ProjectionChangedPaths): void {
+  if (changed.written.length > 0 || changed.removed.length > 0) {
+    console.log(
+      `  Copies:    ${changed.written.length} written, ${changed.removed.length} withdrawn under .opencode/`,
+    );
+  }
 }
 
 /**
  * `--companion` is consumed by the dispatch gate before the command runs, so it
- * is parsed there too; this only rejects anything else.
+ * is parsed there too. `--audience` names the audience the checkout's bare
+ * sessions get beside base.
  */
-export function parseWrapArgs(argv: string[]): { companion?: string } | { error: string } {
+export function parseWrapArgs(
+  argv: string[],
+): { companion?: string; audience?: string } | { error: string } {
   let companion: string | undefined;
+  let audience: string | undefined;
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index]!;
+    if (arg === "--audience") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) return { error: "--audience requires a name" };
+      audience = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--audience=")) {
+      const value = arg.slice("--audience=".length);
+      if (!value) return { error: "--audience requires a name" };
+      audience = value;
+      continue;
+    }
     if (arg === "--companion") {
       const value = argv[index + 1];
       if (!value || value.startsWith("--")) return { error: "--companion requires a path" };
@@ -58,7 +71,10 @@ export function parseWrapArgs(argv: string[]): { companion?: string } | { error:
     }
     return { error: `unknown wrap option: ${arg}` };
   }
-  return companion === undefined ? {} : { companion };
+  return {
+    ...(companion === undefined ? {} : { companion }),
+    ...(audience === undefined ? {} : { audience }),
+  };
 }
 
 /**
@@ -76,11 +92,7 @@ export async function runWrapCommand(
 ): Promise<void> {
   const findRepository =
     deps.findRepoLocalLinkedRepository ?? wrapCommandDeps.findRepoLocalLinkedRepository;
-  const project = deps.projectWorkingRepository ?? wrapCommandDeps.projectWorkingRepository;
-  const projectDocuments =
-    deps.projectWorkingRuntimeDocuments ?? wrapCommandDeps.projectWorkingRuntimeDocuments;
-  const renderDocuments =
-    deps.renderWorkingRuntimeDocuments ?? wrapCommandDeps.renderWorkingRuntimeDocuments;
+  const wrap = deps.runWrapPass ?? wrapCommandDeps.runWrapPass;
   const resolveLinked = deps.resolveLinkedCompanions ?? wrapCommandDeps.resolveLinkedCompanions;
 
   const parsed = parseWrapArgs(argv);
@@ -105,8 +117,8 @@ export async function runWrapCommand(
    * here — a single Linked Companion needs no answer to have been recorded.
    */
   const companionPath =
-    (parsed.companion && path.resolve(parsed.companion)) ??
-    process.env.MATE_ARTIFACT_PATH ??
+    (parsed.companion && path.resolve(parsed.companion)) ||
+    process.env.MATE_ARTIFACT_PATH ||
     (await resolveLinked(cwd))[0]?.companionPath;
   if (!companionPath) {
     console.error(`${FRAMEWORK_NAME}: no registered companion links ${repository.id}.`);
@@ -115,50 +127,57 @@ export async function runWrapCommand(
     return;
   }
 
-  const result = await project(companionPath, repository);
-  if (result.kind === "failed") {
-    console.error(
-      `${FRAMEWORK_NAME}: failed to write the projection for ${repository.id}: ${result.error.message}`,
-    );
-    process.exitCode = 1;
-    return;
-  }
-
+  /** Serialized with Session Prepare and every sync, which rewrite the same manifest. */
   /**
-   * After the projection, never instead of it: a runtime document that cannot
-   * be written fails the command while the projection already written stays.
+   * The flag is the only way to give a checkout's bare sessions an audience;
+   * without it the wrap is base and any recorded audience is withdrawn.
    */
-  const config = await readCompanionConfig(result.companionPath);
-  const documents = await projectDocuments(
-    result.companionPath,
-    repository,
-    config,
-    await renderDocuments(result.companionPath, config, repository.path),
+  const locked = await withCompanionLock(companionPath, attendedLockOptions(companionPath), () =>
+    wrap(companionPath, repository, { audience: parsed.audience ?? null }),
   );
-  if (documents.kind === "failed") {
-    console.error(
-      `${FRAMEWORK_NAME}: failed to reconcile ${documents.document} for ${repository.id}: ${documents.error.message}`,
-    );
+  const result: WrapPassResult = locked.acquired
+    ? locked.value
+    : { kind: "failed", message: "another companion synchronization is still running." };
+  if (result.kind === "failed") {
+    console.error(`${FRAMEWORK_NAME}: ${result.message}`);
     process.exitCode = 1;
     return;
   }
 
-  const changed = result.kind === "written" || documents.kind === "written";
   console.log(
-    changed
+    result.kind === "written"
       ? `Wrapped ${repository.id} at ${result.projectionRoot}`
       : `Already wrapped: ${result.projectionRoot}`,
   );
   console.log(`  Companion: ${result.companionPath}`);
-  for (const document of documents.documents) {
+  if (result.audience) console.log(`  Audience:  ${result.audience}`);
+  for (const document of result.documents) {
     console.log(`  Runtime:   ${document}`);
   }
-  /**
-   * Said at the moment the mode is switched, not left to be discovered at the
-   * next launch: wrapping makes `mate claude` and `mate opencode` refuse here,
-   * and the operator has no other way to learn that from a successful command.
-   */
+  for (const warning of result.warnings) {
+    console.error(`${FRAMEWORK_NAME}: warning: ${warning}`);
+  }
+  reportChangedPaths(result.changed);
+  const { runtimes } = result;
+  const tools = WRAP_RUNTIMES.filter((runtime) => runtimes.has(runtime));
+  if (tools.length === 0) return;
+  const plain = tools.map((tool) => `\`${tool}\``).join(", ");
+  const managed = tools.map((tool) => `\`${FRAMEWORK_NAME} ${tool}\``).join(", ");
   console.log(
-    `Start sessions yourself now: \`claude\` or \`opencode\`. \`${FRAMEWORK_NAME} claude\` and \`${FRAMEWORK_NAME} opencode\` do not run in a wrapped repository — \`${FRAMEWORK_NAME} unwrap\` reverses this.`,
+    `Start sessions yourself (${plain}) or through ${managed}; both work here. \`${FRAMEWORK_NAME} unwrap\` reverses this.`,
   );
+  if (runtimes.has("claude") && (await contextModeEnabled(result.companionPath))) {
+    console.log(
+      `Note: context-mode loads only in sessions started with \`${FRAMEWORK_NAME} claude\`.`,
+    );
+  }
+}
+
+async function contextModeEnabled(companionPath: string): Promise<boolean> {
+  try {
+    const config = await readCompanionConfig(companionPath);
+    return (config.capabilities ?? []).some((capability) => capability.name === "context-mode");
+  } catch {
+    return false;
+  }
 }

package/src/cli/companion-selector.tsx

@@ -3,7 +3,7 @@ import React, { useEffect } from "react";
 import { SelectMenu, type SelectMenuItem } from "../lib/components/select-menu";
 import { WizardFooter } from "../lib/components/wizard-footer";
 import { WizardHeader } from "../lib/components/wizard-header";
-import type { CompanionMatch } from "../lib/orchestrator/companion-resolver";
+import type { CompanionMatch } from "../lib/orchestrator/repository-link";
 
 export interface CompanionSelectorOptions {
   stdin?: NodeJS.ReadStream;

package/src/cli/main.ts

@@ -16,6 +16,7 @@ import { runLaunchClaudeCommand } from "./commands/launch/claude";
 import { runLaunchOpenCodeCommand } from "./commands/launch/opencode";
 import { runPluginCommand } from "./commands/plugin/plugin";
 import { runReportCommand } from "./commands/report";
+import { runSessionCommand } from "./commands/session/prepare";
 import { runStudioCommand } from "./commands/studio";
 import { runUpdateCommand } from "./commands/update";
 import { runUnwrapCommand } from "./commands/unwrap";
@@ -33,6 +34,7 @@ import {
   ensureUnambiguousCompanion,
   type CompanionSelectionOptions,
 } from "./commands/shared/companion-selection";
+import { ensureRuntimeDirectory, refreshRuntimeDirectory } from "../lib/runtime-directory-refresh";
 import { hydrateDynamicPlugins } from "../tools/setup/dynamic-plugins/hydrate";
 import { findPluginCliCommand } from "./plugin-commands";
 import { usage } from "./usage";
@@ -60,6 +62,7 @@ export interface MainDeps {
   repairInstallState?: typeof repairInstallState;
   hydrateDynamicPlugins: typeof hydrateDynamicPlugins;
   resolveRootContext: typeof resolveRootContext;
+  refreshRuntimeDirectory?: typeof refreshRuntimeDirectory;
 }
 
 const mainDeps: MainDeps = {
@@ -68,11 +71,17 @@ const mainDeps: MainDeps = {
   repairInstallState,
   hydrateDynamicPlugins,
   resolveRootContext,
+  refreshRuntimeDirectory,
 };
 
 export async function main(argv = process.argv, deps: MainDeps = mainDeps): Promise<void> {
   const [, , command, subcommand, ...rest] = argv;
 
+  if (!(await ensureRuntimeDirectory(command, deps.refreshRuntimeDirectory))) {
+    process.exitCode = 1;
+    return;
+  }
+
   if (command === "-v" || command === "--version") {
     console.log(getActiveDistribution().config.version);
     return;
@@ -292,6 +301,14 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       await runWrapCommand(wrapArgs);
       return;
     }
+    case "session":
+      /**
+       * Spawned by the OpenCode plugin for a bare session: no update prompt,
+       * no companion picker, no install repair may block it.
+       */
+      if (!(await gate({}))) return;
+      await runSessionCommand(subcommand, rest);
+      return;
     case "unwrap":
       // A recovery path: it withdraws what a wrap placed, so it must never be
       // gated on a companion or an installation it does not consult.

package/src/cli/usage.ts

@@ -21,8 +21,9 @@ export function usage(): string {
     ` ${n} companion open`,
     ` ${n} companion tui`,
     ` ${n} working cleanup`,
-    ` ${n} wrap [--companion PATH]`,
+    ` ${n} wrap [--companion PATH] [--audience NAME]`,
     ` ${n} unwrap`,
+    ` ${n} session prepare --repo <dir> [--json] [--sync]`,
     ` ${n} hub init [folder]`,
     ` ${n} hub add [source] [--id ID] [--path PATH]`,
     ` ${n} hub sync [--json] (companions + hub plugins)`,
@@ -53,7 +54,9 @@ export function usage(): string {
     "",
     "Wrapped repositories:",
     ` ${n} wrap configures the repository so sessions you start yourself load the companion`,
-    ` ${n} claude and ${n} opencode do not run while a repository is wrapped`,
+    ` ${n} wrap --audience NAME gives those sessions one audience beside base; plain wrap returns to base`,
+    ` ${n} claude does not run while a repository is wrapped for Claude`,
+    ` ${n} opencode wraps the repository for OpenCode itself, then starts plain \`opencode\``,
     ` ${n} unwrap withdraws the wrap and restores managed launches; the link is kept`,
     "",
     "Doctor states:",

package/src/hooks/session-banner.ts

@@ -1,5 +1,6 @@
 // Show the active Mate companion paths in Claude Code, and repair the
 // companion's Git state before the session reads it.
+import { unmanagedClaudeDelivery } from "../runtime/claude-delivery-plan";
 import {
   syncCompanionUnattended,
   unattendedSyncStalenessLines,
@@ -44,17 +45,25 @@ export async function buildBanner(
   if (!context.repositoryPath || !context.companionPath) return { exitCode: 0, stdout: "" };
 
   /**
-   * Session start is the only moment at which the companion may move without
-   * invalidating a read the session has already taken, so the repair happens
-   * here and nowhere later. The launch-environment check comes first, so a
-   * Managed Session pays nothing at all — not the freshness read, not the
-   * policy read; and the consent gate is the operation's own.
+   * Repaired before the session reads the companion, so its first reads are
+   * current. The companion can still move later — a plain OpenCode session's
+   * background sync fast-forwards it — but a fast-forward never overwrites a
+   * local edit, so the worst case is a stale read of an upstream change. Only
+   * tries the companion lock: a held lock means another sync is already on it,
+   * and a session start must not stall behind it. The launch-environment check
+   * comes first, so a Managed Session pays nothing at all — not the freshness
+   * read, not the policy read; and the consent gate is the operation's own.
+   * Who owns it otherwise is the delivery plan's call, so a session start
+   * fetches once.
    */
-  const gitNotes = hasLaunchEnvironment(env)
-    ? []
-    : unattendedSyncStalenessLines(
-        await syncCompanionUnattended(context.companionPath, syncOptions),
-      );
+  const ownsGitSync =
+    !hasLaunchEnvironment(env) &&
+    unmanagedClaudeDelivery(projection?.repoRoot).gitSync === "banner";
+  const gitNotes = ownsGitSync
+    ? unattendedSyncStalenessLines(
+        await syncCompanionUnattended(context.companionPath, { lock: "try", ...syncOptions }),
+      )
+    : [];
 
   const lines = [
     `mate v${env.MATE_VERSION || mateVersion()}`,

package/src/hooks/session-guidance.ts

@@ -1,5 +1,8 @@
 // Deliver the companion guidance to a Claude session Mate did not launch.
+import { currentAudienceLayer, readLayerGuidanceSync } from "../runtime/audience-layer";
+import { resolveProjection } from "../runtime/projection";
 import { buildProjectedGuidance } from "../runtime/projected-guidance";
+import { readWrapStateSync } from "../runtime/wrap-state";
 import type { HookEnv } from "./validate-artifact-path";
 
 export interface GuidanceOutcome {
@@ -7,6 +10,19 @@ export interface GuidanceOutcome {
   stdout: string;
 }
 
+/**
+ * The guidance of the audience this checkout is wrapped for, from its layer.
+ * The wrap is the only source: an inherited `MATE_AUDIENCE` selects nothing.
+ */
+function wrappedAudienceGuidance(cwd: string): string {
+  const projection = resolveProjection(cwd);
+  if (!projection) return "";
+  const audience = readWrapStateSync(projection.repoRoot).audience;
+  if (!audience) return "";
+  const layer = currentAudienceLayer(projection.companionPath, audience);
+  return layer ? readLayerGuidanceSync(layer, "CLAUDE.md") : "";
+}
+
 /**
  * `SessionStart.additionalContext` is the file-based form of the managed
  * launch's `--append-system-prompt`: a settings document can declare a hook,
@@ -18,8 +34,10 @@ export interface GuidanceOutcome {
  * repository must read exactly as it did before the hook existed.
  */
 export function buildSessionGuidance(env: HookEnv, cwd: string = process.cwd()): GuidanceOutcome {
-  const guidance = buildProjectedGuidance(env, cwd);
-  if (!guidance) return { exitCode: 0, stdout: "" };
+  const companionGuidance = buildProjectedGuidance(env, cwd);
+  if (!companionGuidance) return { exitCode: 0, stdout: "" };
+  const layer = wrappedAudienceGuidance(cwd);
+  const guidance = layer ? `${companionGuidance}\n\n${layer}` : companionGuidance;
 
   return {
     exitCode: 0,

package/src/hooks/session-prepare.ts

@@ -0,0 +1,101 @@
+/** Prepares a plain Claude session in a Claude-wrapped repository as `mate claude` would. */
+import fs from "node:fs";
+
+import { unmanagedClaudeDelivery } from "../runtime/claude-delivery-plan";
+import { hasLaunchEnvironment } from "../runtime/env";
+import { resolveProjection } from "../runtime/projection";
+import { runtimeDirectoryPath, runtimeMateBin } from "../runtime/runtime-directory";
+import {
+  PREPARE_TIMEOUT_MS,
+  spawnPrepareRunner,
+  startDetachedPrepareSync,
+  type PrepareRun,
+  type PrepareRunner,
+} from "../runtime/session-prepare-runner";
+import type { HookEnv } from "./validate-artifact-path";
+
+export interface SessionPrepareHookOutcome {
+  exitCode: number;
+  stdout: string;
+}
+
+export interface SessionPrepareHookDeps {
+  /** The runtime-directory launcher; `null` until a `mate` run wrote it. */
+  mateBin: () => string | null;
+  runner: (mateBin: string, repoPath: string) => PrepareRunner;
+  startSync: (mateBin: string, repoPath: string) => void;
+  timeoutMs: number;
+}
+
+export const sessionPrepareHookDeps: SessionPrepareHookDeps = {
+  mateBin: () => {
+    const launcher = runtimeMateBin();
+    return fs.existsSync(launcher) ? launcher : null;
+  },
+  runner: spawnPrepareRunner,
+  startSync: startDetachedPrepareSync,
+  timeoutMs: PREPARE_TIMEOUT_MS,
+};
+
+const INERT: SessionPrepareHookOutcome = { exitCode: 0, stdout: "" };
+
+/** `systemMessage` only: the model must never be told to repair the companion. */
+function operatorMessage(lines: string[]): SessionPrepareHookOutcome {
+  if (lines.length === 0) return INERT;
+  return { exitCode: 0, stdout: `${JSON.stringify({ systemMessage: lines.join("\n") })}\n` };
+}
+
+async function runLocalPhase(
+  deps: SessionPrepareHookDeps,
+  mateBin: string,
+  projectDir: string,
+): Promise<PrepareRun> {
+  const pending = deps.runner(mateBin, projectDir)({ sync: false, timeoutMs: deps.timeoutMs });
+  try {
+    return await pending;
+  } catch (error) {
+    return { ok: false, notes: [error instanceof Error ? error.message : String(error)] };
+  }
+}
+
+/**
+ * Inert under a launch environment or where the plan gives it nothing to own.
+ * Awaits the local phase within a bound, then starts Git sync detached. Always
+ * exits zero: a failed prepare must not block the session.
+ */
+export async function runSessionPrepareHook(
+  env: HookEnv,
+  cwd: string = process.cwd(),
+  deps: SessionPrepareHookDeps = sessionPrepareHookDeps,
+): Promise<SessionPrepareHookOutcome> {
+  if (hasLaunchEnvironment(env)) return INERT;
+  const projectDir = env.CLAUDE_PROJECT_DIR || cwd;
+  const projection = resolveProjection(projectDir);
+  if (!projection) return INERT;
+  const plan = unmanagedClaudeDelivery(projection.repoRoot);
+  const reconciles = plan.reconcile === "prepare-hook";
+  const syncs = plan.gitSync === "prepare-hook";
+  if (!reconciles && !syncs) return INERT;
+
+  const mateBin = deps.mateBin();
+  if (!mateBin) {
+    return operatorMessage([
+      `mate: session prepare skipped: ${runtimeDirectoryPath()} is missing; run \`mate\` once to repair it.`,
+    ]);
+  }
+
+  const local = reconciles
+    ? await runLocalPhase(deps, mateBin, projectDir)
+    : { ok: true, notes: [] };
+  if (syncs) deps.startSync(mateBin, projectDir);
+
+  const verdict = local.ok ? "warning" : "failed";
+  return operatorMessage(local.notes.map((note) => `mate: session prepare ${verdict}: ${note}`));
+}
+
+/** Plugin-shim entry. */
+export async function run(): Promise<number> {
+  const outcome = await runSessionPrepareHook(process.env);
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  return outcome.exitCode;
+}

package/src/lib/fs-utils.ts

@@ -33,3 +33,16 @@ export async function pathIsDirectory(candidatePath: string): Promise<boolean> {
     return false;
   }
 }
+
+/**
+ * Real path, so a Windows junction (read back `\\?\`-prefixed) or an aliased
+ * spelling compares equal; resolved text when dangling.
+ */
+export async function realOrResolved(candidate: string): Promise<string> {
+  return fs.realpath(candidate).catch(() => path.resolve(candidate));
+}
+
+/** {@link realOrResolved} for a link whose raw `readlink` text is `target`. */
+export async function realLinkTarget(link: string, target: string): Promise<string> {
+  return fs.realpath(link).catch(() => path.resolve(path.dirname(link), target));
+}