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

package/src/cli/commands/session/prepare.ts

@@ -0,0 +1,119 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repository-link";
+import { prepareSession, type PrepareResult } from "../../../lib/orchestrator/session-prepare";
+import { readProjectionFile } from "../../../runtime/projection";
+import { readWrapState, WRAP_RUNTIMES } from "../../../runtime/wrap-state";
+import { writeJsonStdout } from "../../write-json-stdout";
+import { launchAmbiguityDeps } from "../shared/companion-selection";
+
+export interface SessionPrepareArgs {
+  repo: string;
+  json: boolean;
+  /** Fast-forward the companion first, then the local phase when it moved. */
+  sync: boolean;
+}
+
+const USAGE = `Usage: ${FRAMEWORK_NAME} session prepare --repo <dir> [--json] [--sync]`;
+
+function fail(message: string, usage = false): null {
+  console.error(`${FRAMEWORK_NAME}: ${message}`);
+  if (usage) console.error(USAGE);
+  process.exitCode = 1;
+  return null;
+}
+
+export function parseSessionPrepareArgs(
+  argv: string[],
+  cwd: string = process.cwd(),
+): SessionPrepareArgs | { error: string } {
+  const args: SessionPrepareArgs = { repo: cwd, json: false, sync: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    const [flag, inline] = arg.startsWith("--") && arg.includes("=") ? arg.split(/=(.*)/s) : [arg];
+    if (flag === "--json") {
+      args.json = true;
+    } else if (flag === "--repo") {
+      const repo = inline ?? argv[++index];
+      if (!repo) return { error: "--repo requires a directory" };
+      args.repo = path.resolve(cwd, repo);
+    } else if (flag === "--sync") {
+      args.sync = true;
+    } else {
+      return { error: `unknown session prepare option: ${arg}` };
+    }
+  }
+  return args;
+}
+
+export const sessionPrepareCommandDeps = {
+  findRepoLocalLinkedRepository,
+  prepareSession,
+  resolveLinkedCompanions: launchAmbiguityDeps.resolveLinkedCompanions,
+};
+
+async function resolveCompanionPath(repoPath: string): Promise<string | undefined> {
+  const projected = readProjectionFile(repoPath)?.projection.companionPath;
+  if (projected) return projected;
+  return (await sessionPrepareCommandDeps.resolveLinkedCompanions(repoPath))[0]?.companionPath;
+}
+
+function printHuman(result: PrepareResult): void {
+  for (const step of result.steps) {
+    const detail = step.detail ? ` — ${step.detail}` : "";
+    const runtimes = step.runtimes ? ` (${step.runtimes.join(", ")})` : "";
+    console.log(`  ${step.step}${runtimes}: ${step.outcome}${detail}`);
+  }
+  for (const warning of result.warnings) {
+    console.error(`${FRAMEWORK_NAME}: warning: ${warning}`);
+  }
+}
+
+/**
+ * `mate session prepare`: a launch's preparation for each runtime the
+ * repository is wrapped for, without the launch. Without `--sync` it touches no remote; with it,
+ * it fast-forwards the companion and re-projects only when the companion moved.
+ * Non-zero when the repository is not wrapped or a step failed; a Git conflict
+ * or an offline remote is only a warning.
+ */
+export async function runSessionPrepareCommand(
+  argv: string[],
+  cwd: string = process.cwd(),
+): Promise<PrepareResult | null> {
+  const parsed = parseSessionPrepareArgs(argv, cwd);
+  if ("error" in parsed) return fail(parsed.error, true);
+
+  const deps = sessionPrepareCommandDeps;
+  const repository = await deps.findRepoLocalLinkedRepository(parsed.repo);
+  const wrapped = repository ? (await readWrapState(repository.path)).runtimes : new Set();
+  const runtimes = WRAP_RUNTIMES.filter((runtime) => wrapped.has(runtime));
+  if (!repository || runtimes.length === 0) {
+    return fail(`${parsed.repo} is not wrapped. Run \`${FRAMEWORK_NAME} wrap\` there first.`);
+  }
+
+  const companionPath = await resolveCompanionPath(repository.path);
+  if (!companionPath) return fail(`no companion is linked to ${repository.id}.`);
+
+  const result = await deps.prepareSession({
+    runtime: runtimes[0]!,
+    runtimes,
+    companionPath,
+    repository,
+    mode: parsed.sync ? "sync" : "local",
+  });
+  /** The failure's own error and the wrap state are for an in-process caller; the JSON names steps. */
+  const { failure: _failure, wrapState: _wrapState, ...reported } = result;
+  if (parsed.json) await writeJsonStdout(reported);
+  else printHuman(result);
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}
+
+export async function runSessionCommand(subcommand: string | undefined, rest: string[]) {
+  if (subcommand === "prepare") {
+    await runSessionPrepareCommand(rest);
+    return;
+  }
+  fail(`unknown session subcommand: ${subcommand ?? ""}`.trimEnd(), true);
+}

package/src/cli/commands/shared/companion-selection.ts

@@ -4,9 +4,9 @@ import { FRAMEWORK_NAME } from "../../../framework";
 import {
   CompanionResolver,
   type CompanionMatch,
-} from "../../../lib/orchestrator/companion-resolver";
+  findRepoLocalLinkedRepository,
+} from "../../../lib/orchestrator/repository-link";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
-import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repo-local-registry";
 import { projectWorkingRepositoryBestEffort } from "../../../lib/orchestrator/working-repo-projection";
 import { resolveProjection } from "../../../runtime/projection";
 import { selectCompanion } from "../../companion-selector";

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

@@ -10,7 +10,6 @@ export const REPORT_LIMITS = {
   reports: 20,
   bytes: 50 * 1024 * 1024,
   ageMs: 7 * 24 * 60 * 60 * 1000,
-  /** The bundled inlined Mermaid runtime alone is about 5.3 MiB. */
   uploadBytes: 10 * 1024 * 1024,
 };
 

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/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,38 +1,34 @@
 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/`,
+    );
+  }
 }
 
 /**
@@ -76,11 +72,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 +97,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 +107,52 @@ 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;
-  }
-
-  /**
-   * After the projection, never instead of it: a runtime document that cannot
-   * be written fails the command while the projection already written stays.
-   */
-  const config = await readCompanionConfig(result.companionPath);
-  const documents = await projectDocuments(
-    result.companionPath,
-    repository,
-    config,
-    await renderDocuments(result.companionPath, config, repository.path),
+  /** Serialized with Session Prepare and every sync, which rewrite the same manifest. */
+  const locked = await withCompanionLock(companionPath, attendedLockOptions(companionPath), () =>
+    wrap(companionPath, repository),
   );
-  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) {
+  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

@@ -23,6 +23,7 @@ export function usage(): string {
     ` ${n} working cleanup`,
     ` ${n} wrap [--companion PATH]`,
     ` ${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,8 @@ 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} 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-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));
+}