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

package/src/playbooks/companion-guidance.ts

@@ -1,117 +1,46 @@
-import path from "node:path";
-
-import { FRAMEWORK_NAME } from "../framework";
-import type { AdapterContext } from "../lib/orchestrator/adapters/base";
 import {
-  hasGraphifyCapability,
-  hasOpenspecCapability,
-  hasTokensaveCapability,
-} from "../lib/orchestrator/capabilities";
+  buildCompanionGuidance as buildCompanionGuidanceWith,
+  buildCompanionPolicyXml as buildCompanionPolicyXmlWith,
+  type GuidanceContext,
+} from "../runtime/companion-guidance";
 import { getWrapperBinPath } from "../lib/package-paths";
 
-export { hasGraphifyCapability, hasTokensaveCapability } from "../lib/orchestrator/capabilities";
-
-export const GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT =
-  "$MATE_ARTIFACT_PATH/.graphify/$MATE_REPO_ID/graphify-out/";
-
-export function buildCodebaseExplorationGuidanceSection(
-  options: {
-    useGraphify?: boolean;
-    useTokensave?: boolean;
-  } = {},
-): string {
-  const { useGraphify = false, useTokensave = false } = options;
-
-  if (!useGraphify && !useTokensave) {
-    return "";
-  }
-
-  if (useGraphify && useTokensave) {
-    return `<codebase-exploration-rules priority="mandatory">
-<path role="graphify-out">${GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT}</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.
-2. If tokensave is empty/file-only/irrelevant, run graphify query "<question>"; use graphify path/explain to deepen.
-3. Use grep/glob/read only after tokensave and graphify were tried.</order>
-<notes>Dirty graph files are expected. Use wiki/index.md for broad navigation; GRAPH_REPORT.md only if query/path/explain fall short.</notes>
-<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index.</post-edit>
-</codebase-exploration-rules>`;
-  }
-
-  if (useGraphify) {
-    return `<codebase-exploration-rules priority="mandatory">
-<path role="graphify-out">${GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT}</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.
-2. Use graphify path "<A>" "<B>" or graphify explain "<concept>" to deepen.
-3. Use grep/glob/read only after graphify was tried.</order>
-<notes>Dirty graph files are expected. Use wiki/index.md for broad navigation; GRAPH_REPORT.md only if query/path/explain fall short.</notes>
-<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index --graphify.</post-edit>
-</codebase-exploration-rules>`;
-  }
+/**
+ * The framework-side face of the guidance builders: identical output, with the
+ * running installation's wrapper bin path supplied when a caller does not name
+ * one. The builders themselves live in `runtime/` and take that path as data,
+ * because a hook shim and the OpenCode plugin build guidance with no launch and
+ * may not reach outside `runtime/`.
+ *
+ * A caller that is *not* the running installation — the projection reader —
+ * passes the projected path instead, and so calls the runtime builders direct.
+ */
 
-  return `<codebase-exploration-rules priority="mandatory">
-<trigger>Codebase-understanding: architecture, tracing, integrations, impact, "how does X work?"</trigger>
-<order>tokensave -> grep/glob/read. MUST try tokensave before raw source.
-1. tokensave_context first.
-2. Use grep/glob/read only after tokensave is empty or irrelevant.</order>
-<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index --tokensave.</post-edit>
-</codebase-exploration-rules>`;
-}
+export {
+  GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT,
+  buildCodebaseExplorationGuidanceSection,
+  hasGraphifyCapability,
+  hasOpenspecCapability,
+  hasTokensaveCapability,
+  type GuidanceCapability,
+  type GuidanceContext,
+} from "../runtime/companion-guidance";
 
 /**
  * Build just the `<companion-policy>` XML block: paths, CLI tools, and
- * mandatory rules (including the capability-gated `openspec-finish` rule).
+ * mandatory rules (including the capability-gated `openspec-publish` rule).
  * Does not include codebase-exploration guidance — see
  * `buildCompanionGuidance` for the merged single-string form, or call
  * `buildCodebaseExplorationGuidanceSection` directly when that guidance is
  * delivered through its own channel (as OpenCode's guidance contract does).
  */
 export function buildCompanionPolicyXml(
-  context: AdapterContext,
+  context: GuidanceContext,
   options: { wrapperBinPath?: string } = {},
 ): string {
-  const wrapperBinPath = options.wrapperBinPath ?? getWrapperBinPath();
-  const lines = [
-    "## MANDATORY RULES - NON-NEGOTIABLE",
-    "",
-    `<companion-policy framework="${FRAMEWORK_NAME}" priority="mandatory">`,
-    `  <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>",
-    "    <cli-tools>",
-    `      <cli name="openspec" type="wrapper" invokeAs="${path.join(wrapperBinPath, "openspec")}" />`,
-    `      <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="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 (hasOpenspecCapability(context.capabilities)) {
-    lines.push(
-      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run ${FRAMEWORK_NAME} artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
-    );
-  }
-
-  lines.push("  </mandatory-rules>");
-
-  lines.push("</companion-policy>");
-
-  return lines.join("\n");
+  return buildCompanionPolicyXmlWith(context, {
+    wrapperBinPath: options.wrapperBinPath ?? getWrapperBinPath(),
+  });
 }
 
 /**
@@ -121,23 +50,10 @@ export function buildCompanionPolicyXml(
  * fragment rather than delivering exploration guidance separately.
  */
 export function buildCompanionGuidance(
-  context: AdapterContext,
+  context: GuidanceContext,
   options: { wrapperBinPath?: string } = {},
 ): string {
-  const lines = [buildCompanionPolicyXml(context, options)];
-
-  const graphifyEnabled = hasGraphifyCapability(context.capabilities);
-  const tokensaveEnabled = hasTokensaveCapability(context.capabilities);
-
-  if (graphifyEnabled || tokensaveEnabled) {
-    lines.push(
-      "",
-      buildCodebaseExplorationGuidanceSection({
-        useGraphify: graphifyEnabled,
-        useTokensave: tokensaveEnabled,
-      }),
-    );
-  }
-
-  return lines.join("\n");
+  return buildCompanionGuidanceWith(context, {
+    wrapperBinPath: options.wrapperBinPath ?? getWrapperBinPath(),
+  });
 }

package/src/plugins.ts

@@ -11,7 +11,6 @@ export { createUvPlugin } from "./tools/setup/package-managers/uv";
 export { createOpenspecPlugin } from "./tools/setup/capabilities/openspec";
 export { createReactDoctorPlugin } from "./tools/setup/capabilities/react-doctor";
 export { createTokensavePlugin } from "./tools/setup/capabilities/tokensave";
-export { createHeadroomPlugin } from "./tools/setup/capabilities/headroom";
 export { createRtkPlugin } from "./tools/setup/capabilities/rtk";
 export { createGraphifyPlugin } from "./tools/setup/capabilities/graphify";
 export { createContextModePlugin } from "./tools/setup/capabilities/context-mode";

package/src/runtime/companion-git-state.ts

@@ -0,0 +1,156 @@
+/**
+ * Bookkeeping for companion Git synchronization, kept in Mate's own state
+ * directory and keyed by companion path.
+ *
+ * It cannot live in the Companion Repository: `.mate/` content is authoritative
+ * from the upstream, and a tracked record would dirty the companion at every
+ * session start — turning "only ahead" into a permanent state. It cannot live
+ * in a Projection Root either: one companion serves several Working
+ * Repositories, and the record is a property of the companion.
+ *
+ * Every write is best-effort. An unwritable record degrades to "a
+ * synchronization is due", which is the safe direction.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "./framework";
+
+/** Long enough that consecutive sessions do no network work. */
+export const COMPANION_SYNC_TTL_MS = 4 * 60 * 60 * 1000;
+
+/** Short enough that a repaired fork is noticed, long enough that a retry loop cannot spawn Git per write. */
+export const FORK_VERDICT_TTL_MS = 60 * 1000;
+
+export interface CompanionForkRecord {
+  ahead: number;
+  behind: number;
+  checkedAt: string;
+}
+
+export interface CompanionGitRecord {
+  syncedAt?: string;
+  /** Set while the last unattended run left work for a human; cleared on completion. */
+  unfinishedReason?: string;
+  fork?: CompanionForkRecord;
+}
+
+/** `HOME` first, matching the guard: a projected hook runs with whatever the session set. */
+export function companionGitStateRoot(homeDir?: string): string {
+  const home = homeDir || process.env.HOME || os.homedir();
+  return path.join(home, `.${FRAMEWORK_NAME}`, "companion-git-state");
+}
+
+function companionKey(companionPath: string): string {
+  const resolved = (() => {
+    try {
+      return fs.realpathSync(companionPath);
+    } catch {
+      return path.resolve(companionPath);
+    }
+  })();
+  return createHash("sha256").update(resolved).digest("hex").slice(0, 16);
+}
+
+export function companionGitStatePath(companionPath: string, homeDir?: string): string {
+  return path.join(companionGitStateRoot(homeDir), `${companionKey(companionPath)}.json`);
+}
+
+export function readCompanionGitRecord(
+  companionPath: string,
+  homeDir?: string,
+): CompanionGitRecord {
+  try {
+    const parsed: unknown = JSON.parse(
+      fs.readFileSync(companionGitStatePath(companionPath, homeDir), "utf8"),
+    );
+    if (!parsed || typeof parsed !== "object") return {};
+    return parsed as CompanionGitRecord;
+  } catch {
+    return {};
+  }
+}
+
+/** Best-effort: a failure to record never fails its caller. */
+export function writeCompanionGitRecord(
+  companionPath: string,
+  record: CompanionGitRecord,
+  homeDir?: string,
+): boolean {
+  const target = companionGitStatePath(companionPath, homeDir);
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function recordCompanionSync(
+  companionPath: string,
+  at: Date = new Date(),
+  homeDir?: string,
+): boolean {
+  const { unfinishedReason: _cleared, ...record } = readCompanionGitRecord(companionPath, homeDir);
+  return writeCompanionGitRecord(companionPath, { ...record, syncedAt: at.toISOString() }, homeDir);
+}
+
+/**
+ * Clears `syncedAt`: a run that left work for a human is not a completion, and
+ * a concurrent winner's timestamp would otherwise suppress every later run —
+ * leaving this reason rendered for a whole freshness interval with nothing due
+ * to clear it.
+ */
+export function recordCompanionSyncUnfinished(
+  companionPath: string,
+  reason: string,
+  homeDir?: string,
+): boolean {
+  const { syncedAt: _stale, ...record } = readCompanionGitRecord(companionPath, homeDir);
+  return writeCompanionGitRecord(companionPath, { ...record, unfinishedReason: reason }, homeDir);
+}
+
+function withinInterval(stamp: string | undefined, intervalMs: number, now: Date): boolean {
+  if (!stamp) return false;
+  const recorded = Date.parse(stamp);
+  if (!Number.isFinite(recorded)) return false;
+  const age = now.getTime() - recorded;
+  return age >= 0 && age < intervalMs;
+}
+
+export function isCompanionSyncDue(
+  companionPath: string,
+  ttlMs: number = COMPANION_SYNC_TTL_MS,
+  now: Date = new Date(),
+  homeDir?: string,
+): boolean {
+  return !withinInterval(readCompanionGitRecord(companionPath, homeDir).syncedAt, ttlMs, now);
+}
+
+export function readCachedForkRecord(
+  companionPath: string,
+  ttlMs: number = FORK_VERDICT_TTL_MS,
+  now: Date = new Date(),
+  homeDir?: string,
+): CompanionForkRecord | null {
+  const fork = readCompanionGitRecord(companionPath, homeDir).fork;
+  if (!fork || typeof fork.ahead !== "number" || typeof fork.behind !== "number") return null;
+  return withinInterval(fork.checkedAt, ttlMs, now) ? fork : null;
+}
+
+export function recordForkVerdict(
+  companionPath: string,
+  verdict: { ahead: number; behind: number },
+  at: Date = new Date(),
+  homeDir?: string,
+): boolean {
+  const record = readCompanionGitRecord(companionPath, homeDir);
+  return writeCompanionGitRecord(
+    companionPath,
+    { ...record, fork: { ...verdict, checkedAt: at.toISOString() } },
+    homeDir,
+  );
+}

package/src/runtime/companion-git.ts

@@ -0,0 +1,203 @@
+/**
+ * Git primitives shared by the launch preflight and the session-runtime
+ * surfaces. Upstream-ref resolution lives here because two callers depend on
+ * meaning the same ref: `CompanionGitSync` (async, injectable runner) and the
+ * hooks (synchronous `spawnSync`). The resolution is expressed once as a step
+ * generator that both drivers run, so the two can never disagree.
+ */
+import { spawnSync } from "node:child_process";
+
+export interface GitResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface UpstreamTarget {
+  remote: string;
+  branch: string;
+  ref: string;
+}
+
+/** Bounded but far above any diagnostic output; 1 MiB truncates large fetches. */
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+
+/** Refs already local: no network, so a small bound is generous. */
+export const GIT_QUERY_TIMEOUT_MS = 5_000;
+
+export function outputLines(stdout: string): string[] {
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+/** Matches Git progress-meter lines such as `Updating files:  76% (11340/14790)` or `..., done.` */
+const GIT_PROGRESS_LINE = /^\S.*?: +\d+% \(\d+\/\d+\)(?:, done\.)?$/;
+
+export function stripGitProgress(text: string): string {
+  return text
+    .split(/\r\n|\r|\n/)
+    .filter((line) => !GIT_PROGRESS_LINE.test(line.trim()))
+    .join("\n")
+    .trim();
+}
+
+export function describeGitFailure(result: GitResult): string {
+  return stripGitProgress(result.stderr) || stripGitProgress(result.stdout) || "unknown Git error";
+}
+
+export function isAuthenticationFailure(result: GitResult): boolean {
+  const output = `${result.stderr}\n${result.stdout}`.toLowerCase();
+  return [
+    "terminal prompts disabled",
+    "could not read username",
+    "could not read password",
+    "authentication failed",
+    "permission denied (publickey)",
+    "could not open /dev/tty",
+    "can't open /dev/tty",
+    "cannot open /dev/tty",
+  ].some((marker) => output.includes(marker));
+}
+
+/**
+ * Inherited `GIT_*` overrides would point Git at the session's own repository
+ * rather than the companion, so they are stripped from every invocation.
+ */
+export function gitEnvironment(
+  env: Record<string, string | undefined> = process.env,
+): Record<string, string | undefined> {
+  const {
+    GIT_DIR: _gitDir,
+    GIT_WORK_TREE: _gitWorkTree,
+    GIT_COMMON_DIR: _gitCommonDir,
+    GIT_INDEX_FILE: _gitIndexFile,
+    GIT_TERMINAL_PROMPT: _gitTerminalPrompt,
+    ...rest
+  } = env;
+  return { ...rest, GIT_TERMINAL_PROMPT: "0" };
+}
+
+/** Never throws: an absent Git binary and an exceeded bound are ordinary results. */
+export function runGitSync(
+  cwd: string,
+  args: readonly string[],
+  timeoutMs: number = GIT_QUERY_TIMEOUT_MS,
+): GitResult {
+  const result = spawnSync("git", [...args], {
+    cwd,
+    encoding: "utf8",
+    env: gitEnvironment(),
+    maxBuffer: GIT_MAX_BUFFER,
+    timeout: Math.max(1, timeoutMs),
+  });
+  if (result.error) {
+    return { status: 1, stdout: result.stdout ?? "", stderr: result.error.message };
+  }
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+function parseRemoteRef(stdout: string): UpstreamTarget | undefined {
+  const ref = stdout.trim();
+  const separator = ref.indexOf("/");
+  if (separator <= 0 || separator === ref.length - 1) return undefined;
+  return { remote: ref.slice(0, separator), branch: ref.slice(separator + 1), ref };
+}
+
+/**
+ * The single definition of "which upstream does this companion mean":
+ * the branch's `@{u}`, then `origin/HEAD`, then an available `origin/main` or
+ * `origin/master`. Yields argv, receives the result — so a synchronous and an
+ * asynchronous driver share one decision procedure.
+ */
+export function* upstreamTargetSteps(): Generator<
+  readonly string[],
+  UpstreamTarget | null,
+  GitResult
+> {
+  const upstream = yield ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"];
+  const configured = parseRemoteRef(upstream.stdout);
+  if (upstream.status === 0 && configured) return configured;
+
+  const remoteHead = yield ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"];
+  const fromRemoteHead = parseRemoteRef(remoteHead.stdout);
+  if (remoteHead.status === 0 && fromRemoteHead) return fromRemoteHead;
+
+  for (const branch of ["main", "master"]) {
+    const exists = yield ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${branch}`];
+    if (exists.status === 0) return { remote: "origin", branch, ref: `origin/${branch}` };
+  }
+
+  return null;
+}
+
+export function resolveUpstreamTargetSync(
+  companionPath: string,
+  timeoutMs: number = GIT_QUERY_TIMEOUT_MS,
+): UpstreamTarget | null {
+  const steps = upstreamTargetSteps();
+  let step = steps.next();
+  while (!step.done) {
+    step = steps.next(runGitSync(companionPath, step.value, timeoutMs));
+  }
+  return step.value;
+}
+
+export async function resolveUpstreamTargetWith(
+  run: (args: readonly string[]) => Promise<GitResult>,
+): Promise<UpstreamTarget | null> {
+  const steps = upstreamTargetSteps();
+  let step = steps.next();
+  while (!step.done) {
+    // oxlint-disable-next-line no-await-in-loop -- the steps are a decision chain
+    step = steps.next(await run(step.value));
+  }
+  return step.value;
+}
+
+export interface CompanionForkState {
+  ahead: number;
+  behind: number;
+  /**
+   * Only ahead *and* behind. Ahead alone is the ordinary state of a session
+   * that has committed artifacts and not yet finished; behind alone a
+   * fast-forward resolves without a human.
+   */
+  forked: boolean;
+}
+
+/**
+ * Computed from refs already present locally — never fetches. `null` means the
+ * question could not be answered (no upstream ref, no working tree, no Git,
+ * exceeded bound), and every caller must fall through rather than refuse.
+ */
+export function companionForkState(
+  companionPath: string,
+  timeoutMs: number = GIT_QUERY_TIMEOUT_MS,
+): CompanionForkState | null {
+  const target = resolveUpstreamTargetSync(companionPath, timeoutMs);
+  if (!target) return null;
+  return forkStateAgainst(companionPath, target.ref, timeoutMs);
+}
+
+export function forkStateAgainst(
+  companionPath: string,
+  ref: string,
+  timeoutMs: number = GIT_QUERY_TIMEOUT_MS,
+): CompanionForkState | null {
+  const counts = runGitSync(
+    companionPath,
+    ["rev-list", "--left-right", "--count", `${ref}...HEAD`],
+    timeoutMs,
+  );
+  if (counts.status !== 0) return null;
+
+  const [behind, ahead] = counts.stdout.trim().split(/\s+/).map(Number);
+  if (!Number.isFinite(ahead) || !Number.isFinite(behind)) return null;
+  return { ahead, behind, forked: ahead > 0 && behind > 0 };
+}