@uniqbit/mate-core 0.15.5 → 0.16.0-canary.1

package/src/hooks/validate-artifact-path.ts

@@ -12,6 +12,10 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { companionForkRefusal } from "../runtime/companion-sync";
+import { readCompanionRuntimeContext } from "../runtime/env";
+import { companionLinkPath } from "../runtime/repo-local";
+
 export type HookEnv = Record<string, string | undefined>;
 
 export interface HookOutcome {
@@ -56,13 +60,53 @@ export function artifactLikePath(filePath: string): boolean {
   return false;
 }
 
-function repoRoot(env: HookEnv): string {
-  return env.MATE_REPO_PATH || process.cwd();
+/**
+ * Resolved once per evaluation: the companion may come from the launch
+ * environment or from the Working Repository's Projection Root, and every
+ * path check below is relative to whichever resolved.
+ */
+interface GuardContext {
+  env: HookEnv;
+  /** As resolved, for the operator: the message names the path they configured. */
+  companion: string;
+  /** Followed through every link, so filesystem identity decides the verdict. */
+  companionReal: string;
+  companionLink: string;
+  repoRoot: string;
+}
+
+/**
+ * The target's real path, resolved as far as it exists — a path being written
+ * does not yet, so the deepest existing ancestor is resolved and the rest
+ * appended.
+ */
+function realPath(target: string): string {
+  const absolute = path.resolve(target);
+  const trailing: string[] = [];
+  let current = absolute;
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(current), ...trailing);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return absolute;
+      trailing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
 }
 
-function companionRoot(env: HookEnv): string | null {
-  const companion = env.MATE_ARTIFACT_PATH;
-  return companion ? path.normalize(companion) : null;
+function guardContext(env: HookEnv, cwd: string): GuardContext | null {
+  const resolved = readCompanionRuntimeContext(env, cwd);
+  if (!resolved.companionPath) return null;
+  const repoRoot = resolved.repositoryPath || cwd;
+  return {
+    env,
+    companion: path.normalize(resolved.companionPath),
+    companionReal: realPath(resolved.companionPath),
+    companionLink: companionLinkPath(repoRoot),
+    repoRoot,
+  };
 }
 
 // Claude Code's own config/state directory (plan files, settings, todos).
@@ -73,9 +117,9 @@ function claudeConfigRoot(env: HookEnv): string {
   return path.normalize(path.join(env.HOME || os.homedir(), ".claude"));
 }
 
-function normalizePath(filePath: string, env: HookEnv): string {
+function normalizePath(filePath: string, ctx: GuardContext): string {
   if (path.isAbsolute(filePath)) return path.normalize(filePath);
-  return path.normalize(path.join(repoRoot(env), filePath));
+  return path.normalize(path.join(ctx.repoRoot, filePath));
 }
 
 function isUnder(target: string, root: string): boolean {
@@ -83,8 +127,17 @@ function isUnder(target: string, root: string): boolean {
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
-function isGitignored(target: string, env: HookEnv): boolean {
-  const root = repoRoot(env);
+/**
+ * Under the Projection Root's companion link, or under the companion it lands
+ * in — the second answers for a link the operator made, and for the first once
+ * its target exists.
+ */
+function isCompanionPath(target: string, ctx: GuardContext): boolean {
+  return isUnder(target, ctx.companionLink) || isUnder(realPath(target), ctx.companionReal);
+}
+
+function isGitignored(target: string, ctx: GuardContext): boolean {
+  const root = ctx.repoRoot;
   if (!isUnder(target, root)) return false;
 
   const relPath = path.relative(root, target);
@@ -96,8 +149,8 @@ function isGitignored(target: string, env: HookEnv): boolean {
 
 // A file already tracked in the working repo is product code being edited,
 // not a new agent artifact (e.g. packaged SKILL.md/spec.md template sources).
-function isGitTracked(target: string, env: HookEnv): boolean {
-  const root = repoRoot(env);
+function isGitTracked(target: string, ctx: GuardContext): boolean {
+  const root = ctx.repoRoot;
   if (!isUnder(target, root)) return false;
 
   const relPath = path.relative(root, target);
@@ -107,8 +160,8 @@ function isGitTracked(target: string, env: HookEnv): boolean {
   return result.status === 0;
 }
 
-function isProductDocumentationPath(target: string, env: HookEnv): boolean {
-  const root = repoRoot(env);
+function isProductDocumentationPath(target: string, ctx: GuardContext): boolean {
+  const root = ctx.repoRoot;
   if (!isUnder(target, root)) return false;
 
   const relPath = path.relative(root, target);
@@ -140,31 +193,45 @@ function blockWrite(target: string, companion: string): HookOutcome {
 
 function checkFilePath(
   filePath: string,
-  companion: string | null,
-  env: HookEnv,
+  ctx: GuardContext,
   allowExisting = false,
 ): HookOutcome | null {
-  if (!filePath || !companion) return null;
+  if (!filePath) return null;
 
-  const normalized = normalizePath(filePath, env);
-  if (normalized.startsWith(companion)) return null;
+  const normalized = normalizePath(filePath, ctx);
+  if (isCompanionPath(normalized, ctx)) return null;
 
-  if (isUnder(normalized, claudeConfigRoot(env))) return null;
+  if (isUnder(normalized, claudeConfigRoot(ctx.env))) return null;
 
   if (allowExisting && fs.existsSync(normalized) && fs.statSync(normalized).isFile()) return null;
 
-  if (isProductDocumentationPath(normalized, env)) return null;
+  if (isProductDocumentationPath(normalized, ctx)) return null;
 
   if (!artifactLikePath(filePath)) return null;
 
   if (
-    isUnder(normalized, repoRoot(env)) &&
-    (isGitignored(normalized, env) || isGitTracked(normalized, env))
+    isUnder(normalized, ctx.repoRoot) &&
+    (isGitignored(normalized, ctx) || isGitTracked(normalized, ctx))
   ) {
     return null;
   }
 
-  return blockWrite(filePath, companion);
+  return blockWrite(filePath, ctx.companion);
+}
+
+/**
+ * The fork refusal, unlike the path refusal, is not a function of the tool
+ * input alone: it depends on companion Git state, which a Managed Launch may
+ * have settled on purpose (`--no-git`, a non-automatic Git policy). So it is
+ * gated on the absence of a launch environment, and the path refusal keeps its
+ * input-only verdict and its double-load tolerance untouched.
+ */
+function checkForkedCompanion(filePath: string, ctx: GuardContext): HookOutcome | null {
+  if (!filePath || !artifactLikePath(filePath)) return null;
+  if (!isCompanionPath(normalizePath(filePath, ctx), ctx)) return null;
+
+  const refusal = companionForkRefusal(ctx.env, ctx.companion);
+  return refusal ? { exitCode: 2, stderr: `${refusal}\n` } : null;
 }
 
 export function commandMatches(command: string): string[] {
@@ -179,11 +246,15 @@ export function commandMatches(command: string): string[] {
   return targets;
 }
 
-export function evaluate(payload: unknown, env: HookEnv): HookOutcome {
+/**
+ * Fails open only when no Mate context resolves from either source; in a
+ * wrapped Working Repository the guard runs without a launch.
+ */
+export function evaluate(payload: unknown, env: HookEnv, cwd: string = process.cwd()): HookOutcome {
   const allow: HookOutcome = { exitCode: 0, stderr: "" };
 
-  const companion = companionRoot(env);
-  if (!companion) return allow;
+  const ctx = guardContext(env, cwd);
+  if (!ctx) return allow;
 
   const input = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {};
   const toolName = typeof input.tool_name === "string" ? input.tool_name : "";
@@ -193,19 +264,21 @@ export function evaluate(payload: unknown, env: HookEnv): HookOutcome {
       : {};
 
   if (toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
-    const outcome = checkFilePath(
-      String(toolInput.file_path ?? ""),
-      companion,
-      env,
-      toolName === "Edit" || toolName === "MultiEdit",
-    );
-    return outcome ?? allow;
+    const filePath = String(toolInput.file_path ?? "");
+    /** The path refusal wins when both apply: its message is not replaced. */
+    const outcome = checkFilePath(filePath, ctx, toolName === "Edit" || toolName === "MultiEdit");
+    return outcome ?? checkForkedCompanion(filePath, ctx) ?? allow;
   }
 
   if (toolName === "Bash") {
     const command = String(toolInput.command ?? "");
-    for (const target of commandMatches(command)) {
-      const outcome = checkFilePath(target, companion, env);
+    const targets = commandMatches(command);
+    for (const target of targets) {
+      const outcome = checkFilePath(target, ctx);
+      if (outcome) return outcome;
+    }
+    for (const target of targets) {
+      const outcome = checkForkedCompanion(target, ctx);
       if (outcome) return outcome;
     }
     return allow;

package/src/lib/fs-utils.ts

@@ -24,3 +24,12 @@ export async function fileExists(filePath: string): Promise<boolean> {
     return false;
   }
 }
+
+export async function pathIsDirectory(candidatePath: string): Promise<boolean> {
+  try {
+    const stats = await fs.stat(candidatePath);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/lib/install.ts

@@ -278,6 +278,15 @@ export interface InstallPreflightResult {
   plan?: InstallPlan;
 }
 
+export function isRepairableInstallPreflight(result: InstallPreflightResult): boolean {
+  return Boolean(
+    !result.ok &&
+    result.plan &&
+    result.plan.context.kind !== "ambiguous" &&
+    result.plan.requirements.every((requirement) => requirement.satisfied),
+  );
+}
+
 export async function inspectInstallPreflight(
   cwd = process.cwd(),
   deps: { stateStore?: InstallStateStore; globalConfigStore?: GlobalConfigStore } = {},
@@ -328,3 +337,27 @@ export async function reconcileInstalledCompanion(plan: InstallPlan): Promise<vo
   const { syncCompanionFiles } = await import("../tools/setup");
   await syncCompanionFiles(plan.context.companionPath, plan.context.config);
 }
+
+export async function repairInstallState(plan: InstallPlan): Promise<void> {
+  const results = plan.requirements.map((requirement) => ({
+    id: requirement.id,
+    status: "skipped" as const,
+    verified: true,
+  }));
+  await reconcileInstalledCompanion(plan);
+
+  const store = installStateStoreForContext(plan.context);
+  const state = await readInstallState(store);
+  const version = getActiveDistribution().config.version;
+  if (
+    state?.contractRevision === INSTALL_CONTRACT_REVISION &&
+    state.mateVersion === version &&
+    state.contextFingerprint === plan.context.fingerprint &&
+    state.requirementFingerprint === plan.fingerprint &&
+    JSON.stringify(state.requirements) === JSON.stringify(results)
+  ) {
+    return;
+  }
+
+  await saveCompleteInstallState(plan, results, store);
+}

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

@@ -1,22 +1,9 @@
 import { spawn } from "node:child_process";
 import path from "node:path";
 
-import { version } from "../../../../package.json";
-import { isCommandOnPath } from "../../fs-utils";
 import { FRAMEWORK_NAME } from "../../../framework";
-import { getReactDoctorBinPath, getWrapperBinPath } from "../../package-paths";
-import {
-  GRAPHIFY_OUTPUT_SUBDIR,
-  GRAPHIFY_STORE_SEGMENT,
-} from "../../../tools/setup/capabilities/graphify";
-import {
-  type SpawnProxyOpts,
-  getProxyStderr,
-  isProxyReachable as defaultIsProxyReachable,
-  resolveHeadroomPort,
-  spawnProxyBackground as defaultSpawnProxyBackground,
-  waitForProxyReachable as defaultWaitForProxyReachable,
-} from "../headroom/proxy";
+import { MATE_ENV } from "../../../runtime/env-names";
+import { buildProjection, projectionEnvironment } from "../projection-record";
 import type { CapabilityConfig, GitModeProfile, LinkedRepository } from "../types";
 
 export interface AdapterContext {
@@ -37,13 +24,6 @@ export interface PreparedLaunch {
   command: string;
   args: string[];
   env: NodeJS.ProcessEnv;
-  warning?: string;
-}
-
-export interface ProxyDeps {
-  isProxyReachable?: (port: number) => Promise<boolean>;
-  spawnProxyBackground?: (opts: SpawnProxyOpts) => void;
-  waitForProxyReachable?: (port: number) => Promise<boolean>;
 }
 
 function prependPathEntry(pathValue: string | undefined, entry: string): string {
@@ -63,63 +43,33 @@ export abstract class LaunchAdapter {
     return {};
   }
 
-  protected headroomEnv(
-    _context: AdapterContext,
-    _port: number,
-    _companionPath: string,
-    _env: NodeJS.ProcessEnv,
-  ): NodeJS.ProcessEnv {
-    return {};
-  }
-
+  /**
+   * The projected paths, materialized, plus the predicates the projection
+   * refuses to hold. Nothing here derives a path: a managed session and an
+   * Unmanaged Session read the same record, so they cannot disagree.
+   */
   environment(context: AdapterContext): NodeJS.ProcessEnv {
     const reactDoctorEnabled = context.capabilities.some((c) => c.name === "react-doctor");
-    const wrapperBinPath = getWrapperBinPath();
+    const projection = buildProjection(context.companionPath, context.repository);
     const env: NodeJS.ProcessEnv = {
       ...process.env,
+      ...projectionEnvironment(projection),
       MATE_NAME: FRAMEWORK_NAME,
-      MATE_VERSION: version,
-      MATE_ARTIFACT_PATH: context.companionPath,
-      MATE_WRAPPER_BIN_PATH: wrapperBinPath,
-      PATH: prependPathEntry(process.env.PATH, wrapperBinPath),
+      PATH: prependPathEntry(process.env.PATH, projection.wrapperBinPath),
       MATE_GRAPHIFY_ENABLED: context.capabilities.some((c) => c.name === "graphify") ? "1" : "0",
       MATE_OPENSPEC_ENABLED: context.capabilities.some((c) => c.name === "openspec") ? "1" : "0",
       MATE_REACT_DOCTOR_ENABLED: reactDoctorEnabled ? "1" : "0",
       MATE_GIT_AUTO_MODE: context.git === "auto" ? "1" : "0",
-      MATE_REPO_ID: context.repository.id,
-      MATE_REPO_PATH: context.repository.path,
       MATE_POLICY_JSON: JSON.stringify({ allowedAgents: context.allowedAgents }),
     };
 
-    if (reactDoctorEnabled) {
-      env.MATE_REACT_DOCTOR_BIN_PATH = getReactDoctorBinPath();
-    } else {
-      delete env.MATE_REACT_DOCTOR_BIN_PATH;
-    }
-
-    // Route launch-session graphify output to the companion store. graphifyy resolves its
-    // output dir from GRAPHIFY_OUT at import time (graphify/paths.py) and every
-    // reader honours it, so injecting it into the launch session env keeps the
-    // skill's per-shell `$GRAPHIFY_OUT` references and graphifyy's own defaults
-    // pointed at the companion store instead of leaking graphify-out/ into the
-    // working repo. Absolute value, matching the wrapper and deriveGraphifyPaths contract.
-    if (context.capabilities.some((c) => c.name === "graphify")) {
-      env.GRAPHIFY_OUT = path.join(
-        context.companionPath,
-        GRAPHIFY_STORE_SEGMENT,
-        context.repository.id,
-        GRAPHIFY_OUTPUT_SUBDIR,
-      );
-    }
+    /** The one field where a launch still narrows the projection rather than materializing it. */
+    if (!reactDoctorEnabled) delete env[MATE_ENV.reactDoctorBinPath];
 
     return env;
   }
 
-  async prepareLaunch(
-    context: AdapterContext,
-    args: string[],
-    proxyDeps: ProxyDeps = {},
-  ): Promise<PreparedLaunch> {
+  async prepareLaunch(context: AdapterContext, args: string[]): Promise<PreparedLaunch> {
     const builtArgs = this.buildArgs(context, args);
     const baseEnv = this.environment(context);
     const extendedEnv = this.extendEnvironment(context);
@@ -134,72 +84,11 @@ export abstract class LaunchAdapter {
       }
     }
 
-    // Headroom behaves like any other capability: when it is enabled the launch
-    // is routed through the proxy, with no per-launch opt-in. It only falls back
-    // to a direct launch if the `headroom` binary is missing or the proxy fails
-    // to become ready (handled below).
-    const headroomCap = context.capabilities.find((c) => c.name === "headroom");
-    if (!headroomCap) {
-      return { command: this.toolName, args: builtArgs, env };
-    }
-
-    if (!isCommandOnPath("headroom", env.PATH ?? process.env.PATH ?? "")) {
-      return {
-        command: this.toolName,
-        args: builtArgs,
-        env,
-        warning: `${FRAMEWORK_NAME}: headroom capability enabled but \`headroom\` was not found on PATH; install with \`uv tool install "headroom-ai[all]"\`; launching ${this.toolName} directly\n`,
-      };
-    }
-
-    const probeProxy = proxyDeps.isProxyReachable ?? defaultIsProxyReachable;
-    const spawnProxy = proxyDeps.spawnProxyBackground ?? defaultSpawnProxyBackground;
-    const waitForProxy = proxyDeps.waitForProxyReachable ?? defaultWaitForProxyReachable;
-
-    const port = resolveHeadroomPort();
-    const reachable = await probeProxy(port);
-    if (!reachable) {
-      const maxProxyStartAttempts = 3;
-      let ready = false;
-
-      for (let attempt = 1; attempt <= maxProxyStartAttempts; attempt += 1) {
-        spawnProxy({ port });
-        if (await waitForProxy(port)) {
-          ready = true;
-          break;
-        }
-      }
-
-      if (!ready) {
-        const proxyErr = getProxyStderr(port).trim();
-        const errorDetail = proxyErr
-          ? `\nProxy error:\n${proxyErr
-              .split("\n")
-              .map((line) => `  ${line}`)
-              .join("\n")}`
-          : "";
-        return {
-          command: this.toolName,
-          args: builtArgs,
-          env,
-          warning: `${FRAMEWORK_NAME}: headroom proxy failed to become ready on port ${port} after ${maxProxyStartAttempts} attempts; launching ${this.toolName} directly${errorDetail}\n`,
-        };
-      }
-    }
-
-    return {
-      command: this.toolName,
-      args: builtArgs,
-      env: {
-        ...env,
-        ...this.headroomEnv(context, port, context.companionPath, env),
-      },
-    };
+    return { command: this.toolName, args: builtArgs, env };
   }
 
   async run(context: AdapterContext, args: string[]): Promise<AdapterResult> {
     const launch = await this.prepareLaunch(context, args);
-    if (launch.warning) process.stderr.write(launch.warning);
 
     return new Promise((resolve, reject) => {
       const child = spawn(launch.command, launch.args, {

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

@@ -82,15 +82,4 @@ export class ClaudeAdapter extends LaunchAdapter {
       CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: "1",
     };
   }
-
-  protected headroomEnv(
-    context: AdapterContext,
-    port: number,
-    _companionPath: string,
-  ): NodeJS.ProcessEnv {
-    const project = encodeURIComponent(context.repository.id);
-    return {
-      ANTHROPIC_BASE_URL: `http://127.0.0.1:${port}/p/${project}`,
-    };
-  }
 }

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

@@ -14,6 +14,7 @@ import {
   mergeOpenCodeConfigContent,
   readOpenCodeConfig,
 } from "../../../tools/setup/providers/opencode-format";
+import { renderCompanionExternalDirectoryPermissions } from "../../../tools/setup/providers/opencode";
 import { buildOpenCodeGuidance } from "../opencode-guidance";
 import { LaunchPreflightError } from "../types";
 import { type AdapterContext, LaunchAdapter } from "./base";
@@ -38,10 +39,7 @@ export class OpenCodeAdapter extends LaunchAdapter {
       OPENCODE_CONFIG_CONTENT: mergeOpenCodeConfigContent(
         {
           permission: {
-            external_directory: {
-              [context.companionPath]: "allow",
-              [`${context.companionPath}/**`]: "allow",
-            },
+            external_directory: renderCompanionExternalDirectoryPermissions(context.companionPath),
           },
           references: {
             mate: context.companionPath,
@@ -60,34 +58,6 @@ export class OpenCodeAdapter extends LaunchAdapter {
     return buildOpenCodeGuidance(context.capabilities);
   }
 
-  protected headroomEnv(
-    context: AdapterContext,
-    port: number,
-    _companionPath: string,
-    env: NodeJS.ProcessEnv,
-  ): NodeJS.ProcessEnv {
-    const project = encodeURIComponent(context.repository.id);
-    const baseUrl = `http://127.0.0.1:${port}/p/${project}`;
-    const configContent = mergeOpenCodeConfigContent(
-      {
-        provider: {
-          anthropic: {
-            options: { baseURL: baseUrl },
-          },
-          openai: {
-            options: { baseURL: `${baseUrl}/v1` },
-          },
-        },
-      },
-      env,
-    );
-    return {
-      ANTHROPIC_BASE_URL: baseUrl,
-      OPENAI_BASE_URL: `${baseUrl}/v1`,
-      OPENCODE_CONFIG_CONTENT: configContent,
-    };
-  }
-
   async validateLaunch(context: AdapterContext): Promise<void> {
     const missingAssets = await Promise.all(
       this.requiredRuntimeAssets.map(async (asset) => {