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

package/src/lib/prebuilt-workspace.ts

@@ -0,0 +1,236 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import semver from "semver";
+
+import { OPENCODE_PLUGIN_PACKAGE_NAME } from "./opencode-plugin-package";
+import { getCurrentVersion } from "./update-checker";
+import {
+  CONTEXT_MODE_NODE_REQUIREMENT,
+  CONTEXT_MODE_PACKAGE_NAME,
+  CONTEXT_MODE_VERSION,
+} from "./context-mode-package";
+import { getLocalWorkspaceDir } from "./preinstalled-plugins";
+
+/**
+ * Packages the distribution selects and pins for the machine-local workspace.
+ * A bundle may carry any subset; it may carry nothing else.
+ */
+export function getDistributionLocalDependencies(): Record<string, string> {
+  return {
+    [CONTEXT_MODE_PACKAGE_NAME]: CONTEXT_MODE_VERSION,
+    [OPENCODE_PLUGIN_PACKAGE_NAME]: getCurrentVersion(),
+  };
+}
+
+/** Assets a package must carry to count as fully installed rather than merely present. */
+const REQUIRED_PACKAGE_ASSETS: Record<string, string[]> = {
+  [CONTEXT_MODE_PACKAGE_NAME]: [
+    ".claude-plugin/plugin.json",
+    "hooks/hooks.json",
+    "skills/context-mode/SKILL.md",
+    "build/adapters/opencode/plugin.js",
+  ],
+};
+
+/** Runtime requirement the distribution knows independently of the installed manifest. */
+const DECLARED_NODE_REQUIREMENTS: Record<string, string> = {
+  [CONTEXT_MODE_PACKAGE_NAME]: CONTEXT_MODE_NODE_REQUIREMENT,
+};
+
+export interface PrebuiltWorkspaceTarget {
+  platform: string;
+  arch: string;
+  nodeVersion: string;
+}
+
+export interface PrebuiltWorkspaceValidation {
+  ok: boolean;
+  /** One entry per failure, each naming the package or file it is about. */
+  failures: string[];
+  /** Installed versions keyed by package name, for comparing one bundle with another. */
+  packages: Record<string, string>;
+}
+
+export function currentTarget(): PrebuiltWorkspaceTarget {
+  return { platform: process.platform, arch: process.arch, nodeVersion: process.versions.node };
+}
+
+interface InstalledManifest {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  engines?: { node?: string };
+  os?: string[];
+  cpu?: string[];
+}
+
+async function readJson<T>(file: string): Promise<T | null> {
+  try {
+    return JSON.parse(await fs.readFile(file, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Node's own resolution: nearest `node_modules` first, then each ancestor up to the bundle root. */
+async function resolveFromBundle(
+  nodeModules: string,
+  fromDir: string,
+  dependency: string,
+): Promise<InstalledManifest | null> {
+  let dir = fromDir;
+  for (;;) {
+    const candidate = path.join(dir, "node_modules", ...dependency.split("/"), "package.json");
+    const manifest = await readJson<InstalledManifest>(candidate);
+    if (manifest) return manifest;
+    if (path.resolve(dir, "node_modules") === path.resolve(nodeModules)) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function listInstalledPackages(nodeModules: string): Promise<string[]> {
+  const entries = await fs.readdir(nodeModules, { withFileTypes: true }).catch(() => []);
+  const names: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.name.startsWith(".")) continue;
+    if (entry.name.startsWith("@")) {
+      const scoped = await fs
+        .readdir(path.join(nodeModules, entry.name), { withFileTypes: true })
+        .catch(() => []);
+      for (const child of scoped) {
+        if (child.isDirectory() || child.isSymbolicLink())
+          names.push(`${entry.name}/${child.name}`);
+      }
+      continue;
+    }
+    names.push(entry.name);
+  }
+  return names;
+}
+
+/**
+ * Validates an explicitly supplied, fully installed dependency bundle before
+ * anything is copied: distribution-owned versions, a complete dependency
+ * graph, integrity, target architecture, and runtime compatibility. Nothing is
+ * installed, resolved, or downloaded — every answer comes off the filesystem.
+ */
+export async function validatePrebuiltWorkspace(
+  bundlePath: string,
+  target: PrebuiltWorkspaceTarget = currentTarget(),
+): Promise<PrebuiltWorkspaceValidation> {
+  const root = path.resolve(bundlePath);
+  const failures: string[] = [];
+  const packages: Record<string, string> = {};
+
+  const manifest = await readJson<InstalledManifest>(path.join(root, "package.json"));
+  if (!manifest || typeof manifest.dependencies !== "object" || manifest.dependencies === null) {
+    return {
+      ok: false,
+      failures: [`${root}: no framework-generated package.json with a dependencies map.`],
+      packages,
+    };
+  }
+
+  const owned = getDistributionLocalDependencies();
+  const nodeModules = path.join(root, "node_modules");
+
+  for (const [name, version] of Object.entries(manifest.dependencies)) {
+    const pinned = owned[name];
+    if (pinned === undefined) {
+      failures.push(`${name}: not a distribution-owned dependency; the bundle may not carry it.`);
+      continue;
+    }
+    if (version !== pinned) {
+      failures.push(`${name}: the distribution pins ${pinned}; the bundle declares ${version}.`);
+      continue;
+    }
+
+    const installed = await readJson<InstalledManifest>(
+      path.join(nodeModules, ...name.split("/"), "package.json"),
+    );
+    if (!installed) {
+      failures.push(`${name}: declared by the bundle but not installed in its node_modules.`);
+      continue;
+    }
+    if (installed.version !== pinned) {
+      failures.push(
+        `${name}: expected ${pinned} installed; found ${installed.version ?? "an unknown version"}.`,
+      );
+      continue;
+    }
+    packages[name] = pinned;
+
+    const missingAssets: string[] = [];
+    for (const asset of REQUIRED_PACKAGE_ASSETS[name] ?? []) {
+      const assetPath = path.join(nodeModules, ...name.split("/"), ...asset.split("/"));
+      if (
+        !(await fs.access(assetPath).then(
+          () => true,
+          () => false,
+        ))
+      )
+        missingAssets.push(asset);
+    }
+    if (missingAssets.length > 0) {
+      failures.push(`${name}: installed copy is incomplete; missing ${missingAssets.join(", ")}.`);
+    }
+
+    const declaredRequirement = DECLARED_NODE_REQUIREMENTS[name];
+    if (declaredRequirement && !semver.satisfies(target.nodeVersion, declaredRequirement)) {
+      failures.push(
+        `${name}: requires Node.js ${declaredRequirement}; the target runs ${target.nodeVersion}.`,
+      );
+    }
+  }
+
+  for (const name of await listInstalledPackages(nodeModules)) {
+    const packageDir = path.join(nodeModules, ...name.split("/"));
+    const installed = await readJson<InstalledManifest>(path.join(packageDir, "package.json"));
+    if (!installed) {
+      failures.push(`${name}: installed directory has no readable package.json.`);
+      continue;
+    }
+
+    if (
+      Array.isArray(installed.os) &&
+      installed.os.length > 0 &&
+      !installed.os.includes(target.platform)
+    ) {
+      failures.push(
+        `${name}: built for ${installed.os.join(", ")}; the target platform is ${target.platform}.`,
+      );
+    }
+    if (
+      Array.isArray(installed.cpu) &&
+      installed.cpu.length > 0 &&
+      !installed.cpu.includes(target.arch)
+    ) {
+      failures.push(
+        `${name}: built for ${installed.cpu.join(", ")}; the target architecture is ${target.arch}.`,
+      );
+    }
+    if (installed.engines?.node && !semver.satisfies(target.nodeVersion, installed.engines.node)) {
+      failures.push(
+        `${name}: requires Node.js ${installed.engines.node}; the target runs ${target.nodeVersion}.`,
+      );
+    }
+
+    for (const dependency of Object.keys(installed.dependencies ?? {})) {
+      if (installed.optionalDependencies?.[dependency] !== undefined) continue;
+      const resolved = await resolveFromBundle(nodeModules, packageDir, dependency);
+      if (!resolved) {
+        failures.push(`${dependency}: required by ${name} but not installed in the bundle.`);
+      }
+    }
+  }
+
+  return { ok: failures.length === 0, failures, packages };
+}
+
+export { getLocalWorkspaceDir };

package/src/lib/preinstalled-plugins.ts

@@ -0,0 +1,82 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import semver from "semver";
+
+import { FRAMEWORK_NAME } from "../framework";
+
+/**
+ * A plugin reference bound to installed files is an absolute path to the
+ * installed package root, so the Agent Runtime loads it instead of resolving,
+ * fetching, or installing the published package.
+ */
+/** The framework-owned machine-local workspace; a leaf definition, since the
+ * managed-reference predicates depend on it. */
+export function getLocalWorkspaceDir(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "plugins", ".local");
+}
+
+/**
+ * Written by prebuilt preparation, and the only mark that the distribution
+ * *supplied* an installed workspace. Ordinary setup installs into the same
+ * location, and that must keep writing the published reference.
+ */
+export const PREBUILT_BUNDLE_MARKER = ".mate-prebuilt.json";
+
+export function getPreinstalledPluginDir(companionPath: string, packageName: string): string {
+  return path.join(getLocalWorkspaceDir(companionPath), "node_modules", ...packageName.split("/"));
+}
+
+/** True for a reference that is a path whose last segment is the package itself. */
+export function isPreinstalledPluginPath(entry: unknown, packageName: string): boolean {
+  if (typeof entry !== "string") return false;
+  if (!entry.includes("/") && !entry.includes("\\")) return false;
+  const normalized = entry.replace(/\\/g, "/").replace(/\/+$/, "");
+  return normalized.endsWith(`/${packageName}`);
+}
+
+export class PreinstalledPluginMismatchError extends Error {}
+
+/**
+ * Resolves an installed copy of a declared plugin package from a workspace the
+ * distribution supplied. Returns null where none was supplied — the ordinary
+ * workstation, whose setup-installed workspace carries no bundle marker, so the
+ * published reference is written exactly as before. A supplied copy that does
+ * not match what the Capability declares is reported by name rather than bound,
+ * and nothing is installed to repair it.
+ */
+export async function resolvePreinstalledPluginReference(
+  companionPath: string,
+  packageName: string,
+  expectedVersion: string,
+  nodeVersion: string = process.versions.node,
+): Promise<string | null> {
+  const workspace = getLocalWorkspaceDir(companionPath);
+  const supplied = await fs.access(path.join(workspace, PREBUILT_BUNDLE_MARKER)).then(
+    () => true,
+    () => false,
+  );
+  if (!supplied) return null;
+
+  const dir = getPreinstalledPluginDir(companionPath, packageName);
+  let manifest: { version?: string; engines?: { node?: string } };
+  try {
+    manifest = JSON.parse(
+      await fs.readFile(path.join(dir, "package.json"), "utf8"),
+    ) as typeof manifest;
+  } catch {
+    return null;
+  }
+
+  if (manifest.version !== expectedVersion) {
+    throw new PreinstalledPluginMismatchError(
+      `${packageName}: the installed copy at ${dir} is ${manifest.version ?? "an unknown version"}; the capability declares ${expectedVersion}.`,
+    );
+  }
+  if (manifest.engines?.node && !semver.satisfies(nodeVersion, manifest.engines.node)) {
+    throw new PreinstalledPluginMismatchError(
+      `${packageName}: the installed copy at ${dir} requires Node.js ${manifest.engines.node}; this runtime is ${nodeVersion}.`,
+    );
+  }
+  return dir;
+}

package/src/lib/update-checker.ts

@@ -20,6 +20,42 @@ export const updateCheckerDeps = {
   toIsoString: () => new Date().toISOString(),
 };
 
+/** Declares that the installation's version is fixed by the artifact it was built into. */
+export const UPDATE_POLICY_ENV = "MATE_UPDATE_POLICY";
+
+export type UpdatePolicy = "default" | "pinned";
+
+/**
+ * Reported at most once per process: the three automatic-update entry points
+ * each consult the policy, and an unrecognized value must not be repeated.
+ */
+let unrecognizedPolicyReported = false;
+
+/** Test seam — the policy is process-wide, so its report latch must be resettable. */
+export function resetUpdatePolicyReport(): void {
+  unrecognizedPolicyReported = false;
+}
+
+export function getUpdatePolicy(env: NodeJS.ProcessEnv = process.env): UpdatePolicy {
+  const raw = env[UPDATE_POLICY_ENV];
+  if (raw === undefined || raw.trim() === "") return "default";
+
+  const value = raw.trim();
+  if (value === "pinned") return "pinned";
+
+  if (!unrecognizedPolicyReported) {
+    unrecognizedPolicyReported = true;
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: unrecognized ${UPDATE_POLICY_ENV} value \`${value}\`; automatic update handling is unchanged.\n`,
+    );
+  }
+  return "default";
+}
+
+export function isPinnedDeployment(env: NodeJS.ProcessEnv = process.env): boolean {
+  return getUpdatePolicy(env) === "pinned";
+}
+
 const updateStateFileSlug = (packageName: string): string =>
   packageName.replace(/^@/, "").replace(/[^a-zA-Z0-9._-]+/g, "-");
 
@@ -75,6 +111,7 @@ export function isNewer(latest: string, current: string): boolean {
 }
 
 export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Promise<void> {
+  if (isPinnedDeployment()) return;
   try {
     const state = await store.load();
     if (!state.latestVersion) return;
@@ -95,6 +132,7 @@ export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Prom
  * must stop; state-load failures never block.
  */
 export async function enforceUpdateIfRequired(store: UpdateStateStore): Promise<boolean> {
+  if (isPinnedDeployment()) return false;
   if (!getUpdateConfig().enforce) return false;
   try {
     const state = await store.load();
@@ -119,6 +157,7 @@ export async function fetchLatestVersion(): Promise<string> {
 }
 
 export function scheduleBackgroundCheck(store: UpdateStateStore): Promise<void> {
+  if (isPinnedDeployment()) return Promise.resolve();
   return (async () => {
     try {
       const state = await store.load();

package/src/opencode/companion-hooks.ts

@@ -9,6 +9,7 @@ import {
   unattendedSyncStalenessLines,
 } from "../runtime/companion-sync";
 import { hasLaunchEnvironment } from "../runtime/env";
+import { MATE_ENV } from "../runtime/env-names";
 import {
   buildArtifactError,
   extractPatchPaths,
@@ -122,7 +123,12 @@ export async function repairCompanionGitOnce(
   client: PluginInput["client"] | undefined,
   env: Record<string, string | undefined> = process.env,
 ): Promise<string[]> {
-  if (!context.companionPath || hasLaunchEnvironment(env)) return [];
+  if (
+    !context.companionPath ||
+    (hasLaunchEnvironment(env) &&
+      (env[MATE_ENV.repositoryPath] !== undefined || env[MATE_ENV.gitAutoMode] !== "1"))
+  )
+    return [];
   if (repairedCompanions.has(context.companionPath)) return [];
   repairedCompanions.add(context.companionPath);
 
@@ -182,7 +188,7 @@ type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
 export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
   const { client, $ } = pluginInput;
   const context = readContext();
-  if (!context.companionPath || !context.repositoryPath) return {};
+  if (!context.companionPath) return {};
 
   /**
    * The repair sits above the returned hooks, so anything escaping it would
@@ -195,29 +201,33 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
   const reactDoctorScansInFlight = new Set<string>();
 
   return {
-    event: async ({ event }: PluginEventInput) => {
-      if (event.type !== "session.idle") return;
-      const sessionID = event.properties.sessionID;
-      if (
-        !context.reactDoctorEnabled ||
-        reactDoctorScansInFlight.has(sessionID) ||
-        !dirtyReactDoctorSessions.delete(sessionID)
-      ) {
-        return;
-      }
-      await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
-    },
+    ...(context.repositoryPath
+      ? {
+          event: async ({ event }: PluginEventInput) => {
+            if (event.type !== "session.idle") return;
+            const sessionID = event.properties.sessionID;
+            if (
+              !context.reactDoctorEnabled ||
+              reactDoctorScansInFlight.has(sessionID) ||
+              !dirtyReactDoctorSessions.delete(sessionID)
+            ) {
+              return;
+            }
+            await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
+          },
+        }
+      : {}),
     "tool.execute.before": async (input: ToolBeforeInput, output: ToolBeforeOutput) => {
       const toolName = String(input.tool ?? "");
       const args = output.args ?? {};
-      if (["write", "edit"].includes(toolName)) {
+      if (context.repositoryPath && ["write", "edit"].includes(toolName)) {
         const filePath = String(args.filePath ?? "");
         if (filePath && shouldBlockArtifactWrite(context, filePath)) {
           throw new Error(buildArtifactError(context, filePath));
         }
         refuseForkedCompanionWrite(context, filePath);
       }
-      if (toolName === "apply_patch") {
+      if (context.repositoryPath && toolName === "apply_patch") {
         for (const filePath of extractPatchPaths(String(args.patchText ?? ""))) {
           if (shouldBlockArtifactWrite(context, filePath)) {
             throw new Error(buildArtifactError(context, filePath));
@@ -225,12 +235,27 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
           refuseForkedCompanionWrite(context, filePath);
         }
       }
-    },
-    "tool.execute.after": async (input: ToolAfterInput) => {
-      if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
-        dirtyReactDoctorSessions.add(input.sessionID);
+      if (!context.repositoryPath && toolName === "write") {
+        refuseForkedCompanionWrite(context, String(args.filePath ?? ""));
+      }
+      if (!context.repositoryPath && toolName === "edit") {
+        refuseForkedCompanionWrite(context, String(args.filePath ?? ""));
+      }
+      if (!context.repositoryPath && toolName === "apply_patch") {
+        for (const filePath of extractPatchPaths(String(args.patchText ?? ""))) {
+          refuseForkedCompanionWrite(context, filePath);
+        }
       }
     },
+    ...(context.repositoryPath
+      ? {
+          "tool.execute.after": async (input: ToolAfterInput) => {
+            if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
+              dirtyReactDoctorSessions.add(input.sessionID);
+            }
+          },
+        }
+      : {}),
   };
 };
 

package/src/playbooks/companion-guidance.ts

@@ -18,6 +18,7 @@ import { getWrapperBinPath } from "../lib/package-paths";
 
 export {
   GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT,
+  GRAPHIFY_COMPANION_PATH_CONTRACT,
   buildCodebaseExplorationGuidanceSection,
   hasGraphifyCapability,
   hasOpenspecCapability,

package/src/runtime/companion-guidance.ts

@@ -25,7 +25,7 @@ export interface GuidanceCapability {
 
 export interface GuidanceContext {
   companionPath: string;
-  repository: { id: string; path: string };
+  repository?: { id: string; path: string };
   capabilities?: GuidanceCapability[];
 }
 
@@ -43,14 +43,21 @@ export function hasTokensaveCapability(capabilities: GuidanceCapability[] = []):
 
 export const GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT =
   "$MATE_ARTIFACT_PATH/.graphify/$MATE_REPO_ID/graphify-out/";
+export const GRAPHIFY_COMPANION_PATH_CONTRACT =
+  "$MATE_ARTIFACT_PATH/.graphify/__companion__/graphify-out/";
 
 export function buildCodebaseExplorationGuidanceSection(
   options: {
     useGraphify?: boolean;
     useTokensave?: boolean;
+    graphifyOutContract?: string;
   } = {},
 ): string {
-  const { useGraphify = false, useTokensave = false } = options;
+  const {
+    useGraphify = false,
+    useTokensave = false,
+    graphifyOutContract = GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT,
+  } = options;
 
   if (!useGraphify && !useTokensave) {
     return "";
@@ -58,7 +65,7 @@ export function buildCodebaseExplorationGuidanceSection(
 
   if (useGraphify && useTokensave) {
     return `<codebase-exploration-rules priority="mandatory">
-<path role="graphify-out">${GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT}</path>
+<path role="graphify-out">${graphifyOutContract}</path>
 <trigger>Codebase-understanding: architecture, tracing, integrations, impact, "how does X work?"</trigger>
 <order>tokensave -> graphify -> grep/glob/read. MUST NOT skip steps.
 1. tokensave_context first.
@@ -71,7 +78,7 @@ export function buildCodebaseExplorationGuidanceSection(
 
   if (useGraphify) {
     return `<codebase-exploration-rules priority="mandatory">
-<path role="graphify-out">${GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT}</path>
+<path role="graphify-out">${graphifyOutContract}</path>
 <trigger>Codebase-understanding: architecture, tracing, integrations, impact, "how does X work?"</trigger>
 <order>graphify -> grep/glob/read. MUST try graphify before raw source.
 1. graphify query "<question>" first.
@@ -111,7 +118,6 @@ export function buildCompanionPolicyXml(
     `  <overview>You are operating inside the ${FRAMEWORK_NAME} companion repository.</overview>`,
     "  <context>",
     "    <paths>",
-    `      <path role="working-repository" env="MATE_REPO_PATH">${context.repository.path}</path>`,
     `      <path role="companion-repository" env="MATE_ARTIFACT_PATH">${context.companionPath}</path>`,
     `      <path role="package-wrapper-bin" env="MATE_WRAPPER_BIN_PATH">${wrapperBinPath}</path>`,
     "    </paths>",
@@ -120,19 +126,47 @@ export function buildCompanionPolicyXml(
     `      <cli name="graphify" type="wrapper" invokeAs="${path.join(wrapperBinPath, "graphify")}" />`,
     `      <cli name="${FRAMEWORK_NAME}" type="global" invokeAs="${FRAMEWORK_NAME}" />`,
     "    </cli-tools>",
-    `    <linked-repository id="${context.repository.id}" />`,
     "  </context>",
     "  <mandatory-rules>",
-    `    <rule id="artifact-location" severity="critical">Agent artifacts MUST go to ${context.companionPath}, NEVER ${context.repository.path}. Artifacts include plans, specs, ADRs, todos, notes, handoffs, reasoning docs, and scratch files.</rule>`,
-    `    <rule id="pre-write-classification" severity="critical">Before ANY write, classify the target as product-code or agent-artifact. If unsure, treat it as agent-artifact.</rule>`,
-    `    <rule id="product-code-location" severity="critical">Product code (README, docs, source, tests) belongs in ${context.repository.path}. Agent-artifacts belong in ${context.companionPath}.</rule>`,
-    `    <rule id="local-artifact-exception" severity="critical">Only write artifacts in ${context.repository.path} when the exact path is gitignored AND intentionally local-only; otherwise use ${context.companionPath}.</rule>`,
-    `    <rule id="guardrail" severity="critical">Bad artifact writes to ${context.repository.path} are rejected. Classify correctly first.</rule>`,
-    `    <rule id="companion-multi-repository" severity="critical">This Companion Repository may serve multiple Working Repositories. The working-repository path above identifies this session's single primary Working Repository, not the companion's full repository set. The Companion Repository is the shared artifact and context plane; the primary Working Repository is the product-code plane.</rule>`,
-    `    <rule id="repository-area-scope" severity="critical">For domain modeling, identify the canonical Working Repository and its repository-relative Area first. A checkout basename or Area alone is not a repository identity. Shared context applies only when the Companion Repository's CONTEXT-MAP explicitly maps it to the current repository and Area.</rule>`,
     `    <rule id="wrapper-only-cli-execution" severity="critical">For every CLI declared in cli-tools, invoke the exact path in its invokeAs attribute. Correct: ${path.join(wrapperBinPath, "openspec")} status ... . Incorrect: openspec status ... . Do not run bare openspec or graphify commands and do not rely on PATH, aliases, or shell functions. If the exact wrapper path is unavailable, stop and report it.</rule>`,
   ];
 
+  if (context.repository) {
+    lines.splice(
+      8,
+      0,
+      `      <path role="working-repository" env="MATE_REPO_PATH">${context.repository.path}</path>`,
+    );
+    lines.splice(
+      lines.indexOf("  </context>"),
+      0,
+      `    <linked-repository id="${context.repository.id}" />`,
+    );
+    lines.splice(
+      lines.indexOf("  </mandatory-rules>"),
+      0,
+      `    <rule id="artifact-location" severity="critical">Agent artifacts MUST go to ${context.companionPath}, NEVER ${context.repository.path}. Artifacts include plans, specs, ADRs, todos, notes, handoffs, reasoning docs, and scratch files.</rule>`,
+      `    <rule id="pre-write-classification" severity="critical">Before ANY write, classify the target as product-code or agent-artifact. If unsure, treat it as agent-artifact.</rule>`,
+      `    <rule id="product-code-location" severity="critical">Product code (README, docs, source, tests) belongs in ${context.repository.path}. Agent-artifacts belong in ${context.companionPath}.</rule>`,
+      `    <rule id="local-artifact-exception" severity="critical">Only write artifacts in ${context.repository.path} when the exact path is gitignored AND intentionally local-only; otherwise use ${context.companionPath}.</rule>`,
+      `    <rule id="guardrail" severity="critical">Bad artifact writes to ${context.repository.path} are rejected. Classify correctly first.</rule>`,
+      `    <rule id="companion-multi-repository" severity="critical">This Companion Repository may serve multiple Working Repositories. The working-repository path above identifies this session's single primary Working Repository, not the companion's full repository set. The Companion Repository is the shared artifact and context plane; the primary Working Repository is the product-code plane.</rule>`,
+      `    <rule id="repository-area-scope" severity="critical">For domain modeling, identify the canonical Working Repository and its repository-relative Area first. A checkout basename or Area alone is not a repository identity. Shared context applies only when the Companion Repository's CONTEXT-MAP explicitly maps it to the current repository and Area.</rule>`,
+    );
+  } else {
+    lines.splice(
+      lines.indexOf("  </mandatory-rules>"),
+      0,
+      "    <session>Companion-scoped launch with no Working Repository.</session>",
+    );
+    lines.splice(
+      lines.indexOf("  </mandatory-rules>"),
+      0,
+      `    <rule id="artifact-location" severity="critical">Agent artifacts MUST go to ${context.companionPath}. The Companion Repository is the artifact and context plane for this session.</rule>`,
+      `    <rule id="pre-write-classification" severity="critical">Before ANY write, classify the target as product-code or agent-artifact. If unsure, treat it as agent-artifact.</rule>`,
+    );
+  }
+
   if (hasOpenspecCapability(context.capabilities)) {
     lines.push(
       `    <rule id="openspec-scope" severity="critical">In OpenSpec, the frontmatter repository identifies the Working Repository. areas are repository-relative paths within that repository. Canonical specs use repository plus flat areas; change artifacts use paired scopes entries. In a monorepo, an Area normally stops at the package root. A cross-repository change may declare multiple scopes, but each resulting spec remains owned by one repository, and each requirement must bind its Area explicitly.</rule>`,
@@ -168,6 +202,9 @@ export function buildCompanionGuidance(
       buildCodebaseExplorationGuidanceSection({
         useGraphify: graphifyEnabled,
         useTokensave: tokensaveEnabled,
+        graphifyOutContract: context.repository
+          ? GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT
+          : GRAPHIFY_COMPANION_PATH_CONTRACT,
       }),
     );
   }
@@ -186,11 +223,17 @@ export function buildCompanionGuidance(
  * so capability-gated companion-policy rules — e.g. openspec-publish — render
  * exactly as they do for the Claude provider.
  */
-export function buildOpenCodeGuidance(capabilities: GuidanceCapability[]): MateGuidanceFile {
+export function buildOpenCodeGuidance(
+  capabilities: GuidanceCapability[],
+  options: { companionScoped?: boolean } = {},
+): MateGuidanceFile {
+  const repository = options.companionScoped
+    ? undefined
+    : { id: "$MATE_REPO_ID", path: "$MATE_REPO_PATH" };
   const companionGuidance = buildCompanionPolicyXml(
     {
       companionPath: "$MATE_ARTIFACT_PATH",
-      repository: { id: "$MATE_REPO_ID", path: "$MATE_REPO_PATH" },
+      repository,
       capabilities,
     },
     { wrapperBinPath: "$MATE_WRAPPER_BIN_PATH" },
@@ -200,6 +243,9 @@ export function buildOpenCodeGuidance(capabilities: GuidanceCapability[]): MateG
   const codebaseExplorationGuidance = buildCodebaseExplorationGuidanceSection({
     useGraphify: graphifyEnabled,
     useTokensave: tokensaveEnabled,
+    graphifyOutContract: options.companionScoped
+      ? GRAPHIFY_COMPANION_PATH_CONTRACT
+      : GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT,
   });
   const errors: string[] = [];
 

package/src/runtime/env.ts

@@ -90,9 +90,9 @@ export function readCompanionRuntimeContext(
 }
 
 /**
- * A session is Mate-managed only when both the companion path and the working
- * repository path resolved. Plugins must stay inert otherwise.
+ * A session is Mate-managed when a companion path resolved. A companion-scoped
+ * launch intentionally has no working repository.
  */
 export function isManagedCompanionContext(context: CompanionRuntimeContext): boolean {
-  return Boolean(context.companionPath && context.repositoryPath);
+  return Boolean(context.companionPath);
 }