@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

package/src/opencode/session-prepare.ts

@@ -1,5 +1,6 @@
 import type { Cleanup, Context } from "@opencode/plugin/promise/plugin";
 
+import { errorMessage } from "../runtime/error-message";
 import {
   PREPARE_TIMEOUT_MS,
   type PrepareRun,
@@ -52,7 +53,7 @@ async function report(
 }
 
 function failedRun(error: unknown): PrepareRun {
-  return { ok: false, notes: [error instanceof Error ? error.message : String(error)] };
+  return { ok: false, notes: [errorMessage(error)] };
 }
 
 /** No remote: OpenCode holds MCP servers and skills until `setup` returns. */

package/src/opencode/tui.tsx

@@ -6,6 +6,7 @@
  * does not accept it, so the jsx-key rules cannot be satisfied — only suppressed.
  * Arrays render through `.map`: Solid re-runs it whole on a store change, fine for a few lines.
  */
+import { BRAND_ACCENT } from "../brand/palette";
 import { mateVersion } from "../runtime/install";
 import { readContext, readStalenessLines } from "./companion-policy";
 
@@ -47,7 +48,8 @@ export const STALENESS_POLL_MS = 5_000;
 
 type SessionNotes = { lines: string[] };
 
-const MIDNIGHT_PURPLE_BRIGHT = "#c084fc";
+/** The `mate v<version>` line uses the brand accent, which reads on light and dark themes alike. */
+export const MATE_VERSION_COLOR = BRAND_ACCENT;
 const MATE_VERSION = process.env.MATE_VERSION ?? mateVersion();
 
 function SessionContext({
@@ -72,7 +74,7 @@ function SessionContext({
       paddingBottom={sidebar ? 1 : 0}
       flexShrink={0}
     >
-      <text fg={MIDNIGHT_PURPLE_BRIGHT}>mate v{MATE_VERSION}</text>
+      <text fg={MATE_VERSION_COLOR}>mate v{MATE_VERSION}</text>
       <text fg={text.muted}>repo: {context.repositoryPath}</text>
       <text fg={text.muted}>mate: {context.companionPath}</text>
       {notes.lines.map((note) => (

package/src/runtime/artifact-refusal.ts

@@ -0,0 +1,63 @@
+/** The artifact-write refusal both runtimes print; pure, so either guard can import it. */
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "./framework";
+
+/** Matched by consumers and tests; keep byte-identical. */
+export const ARTIFACT_REFUSAL_HEADLINE = "artifact writes must go to the companion framework path.";
+
+export interface ArtifactRefusalInput {
+  /** As the tool supplied it, relative or absolute. */
+  target: string;
+  /** The absolute path the guard judged. */
+  resolved: string;
+  companion: string;
+  /** The Working Repository root relative targets resolve against. */
+  repoRoot: string;
+}
+
+/** The absolute path both guards judge: a relative target resolves against the repo root, never a `cd`. */
+export function resolveArtifactTarget(target: string, repoRoot: string): string {
+  if (path.isAbsolute(target)) return path.normalize(target);
+  return path.normalize(path.join(repoRoot, target));
+}
+
+function relativeInside(target: string, root: string): string | null {
+  const relative = path.relative(path.normalize(root), path.normalize(target));
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) return null;
+  return relative;
+}
+
+/** The refusal text, without a trailing newline. */
+export function artifactRefusal({
+  target,
+  resolved,
+  companion,
+  repoRoot,
+}: ArtifactRefusalInput): string {
+  const isRelative = !path.isAbsolute(target);
+  const inside = relativeInside(resolved, repoRoot);
+  const suggested = inside ? path.join(companion, inside) : null;
+
+  const lines = [
+    `${FRAMEWORK_NAME} guardrail: ${ARTIFACT_REFUSAL_HEADLINE}`,
+    ` target:    ${target}`,
+  ];
+  if (isRelative) lines.push(` resolved:  ${resolved}`);
+  lines.push(` companion: ${companion}`);
+  if (suggested) lines.push(` suggested: ${suggested}`);
+  if (isRelative) {
+    lines.push(
+      "Relative paths resolve against the working repository; a preceding `cd` is not followed.",
+    );
+  }
+  lines.push(
+    suggested
+      ? "Rewrite to the suggested absolute path and retry."
+      : `Use an absolute path under ${companion}.`,
+  );
+  if (path.basename(target) === "CLAUDE.md") {
+    lines.push(`Note: CLAUDE.md already lives in the companion repo at ${companion}/CLAUDE.md.`);
+  }
+  return lines.join("\n");
+}

package/src/runtime/claude-delivery-plan.ts

@@ -1,4 +1,7 @@
+import path from "node:path";
+
 import type { ClaudeHookGroup } from "./claude-hook-group";
+import type { SessionKind } from "./session-kind";
 import { NOT_WRAPPED, readWrapStateSync, type WrapState } from "./wrap-state";
 
 /**
@@ -7,13 +10,6 @@ import { NOT_WRAPPED, readWrapStateSync, type WrapState } from "./wrap-state";
  * may import it.
  */
 
-/**
- * `managed-repo`: `mate claude` with a Working Repository; its prepare just
- * reconciled the Claude wrap, which the launcher asserts. `managed-companion`:
- * a companion-scoped launch. `unmanaged`: a session with no launch environment.
- */
-export type SessionKind = "managed-repo" | "managed-companion" | "unmanaged";
-
 export interface ClaudeDeliveryPlan {
   /** Capability hook groups; `launchSettingsExclude` is what `--settings` must not repeat. */
   readonly hooks: {
@@ -28,9 +24,95 @@ export interface ClaudeDeliveryPlan {
   readonly reconcile: "attended-prepare" | "prepare-hook" | "none";
   /** Companion Git synchronization. */
   readonly gitSync: "launch-preflight" | "prepare-hook" | "banner";
+  /**
+   * Plugin folders loaded as Claude plugins. A managed launch passes Mate's
+   * bundled plugin and every gathered Capability folder but `launchExclude`,
+   * the folders the wrap carries; a Claude-wrapped plain session gets those
+   * from the wrap alone.
+   */
+  readonly plugins: {
+    readonly owner: "launch-flag" | "wrap" | "none";
+    readonly launchExclude: readonly string[];
+  };
+  /** Companion Instructions, per thread kind; `dirAccess` through settings loads no memory file. */
+  readonly instructions: ClaudeInstructionOwners;
+}
+
+export interface ClaudeInstructionOwners {
+  /** `wrap-session-hook`: the wrap's session-prepare hook, once it has prepared, for a launch and a plain session alike. */
+  readonly main: "native-memory" | "wrap-session-hook" | "none";
+  /** `plugin-subagent-hook`: the bundled plugin's SubagentStart copy; `wrap-subagent-hook`: the wrap's. */
+  readonly subagents: "plugin-subagent-hook" | "native-memory" | "wrap-subagent-hook" | "none";
+}
+
+/**
+ * Whether the session's launch passes `--plugin-dir`: every managed launch does, a plain
+ * session cannot. Not whether the session loads plugin folders: a Claude-wrapped plain
+ * session gets them from the wrap.
+ */
+export function launchPassesClaudePluginFolders(kind: SessionKind): boolean {
+  return kind !== "unmanaged";
 }
 
 export function planClaudeDelivery(kind: SessionKind, wrap: WrapState): ClaudeDeliveryPlan {
+  return {
+    ...planChannels(kind, wrap),
+    plugins: planPlugins(kind, wrap),
+    instructions: planClaudeInstructions(kind, wrap.runtimes.has("claude")),
+  };
+}
+
+/**
+ * The instruction owners alone, for a hook that knows its wrap without reading
+ * one: a wrap-carried hook runs only because a Claude wrap installed it, maybe
+ * the main checkout's, so it must not gate on this Checkout's manifest.
+ */
+export function planClaudeInstructions(
+  kind: SessionKind,
+  wrappedForClaude: boolean,
+): ClaudeInstructionOwners {
+  switch (kind) {
+    case "managed-repo":
+      return { main: "wrap-session-hook", subagents: "plugin-subagent-hook" };
+    case "managed-companion":
+      return { main: "native-memory", subagents: "native-memory" };
+    case "unmanaged":
+      return wrappedForClaude
+        ? { main: "wrap-session-hook", subagents: "wrap-subagent-hook" }
+        : { main: "none", subagents: "none" };
+  }
+}
+
+/**
+ * The folders a managed launch passes with `--plugin-dir`, in order: the
+ * bundled plugin, then each gathered folder the wrap does not carry, matched
+ * by resolved path. None when the launch flag does not own plugin folders.
+ */
+export function launchPluginFolders(
+  plan: ClaudeDeliveryPlan,
+  gathered: readonly string[],
+  bundledPluginRoot: string,
+): string[] {
+  if (plan.plugins.owner !== "launch-flag") return [];
+  const carried = new Set(plan.plugins.launchExclude.map((dir) => path.resolve(dir)));
+  return [bundledPluginRoot, ...gathered.filter((dir) => !carried.has(path.resolve(dir)))];
+}
+
+function planPlugins(kind: SessionKind, wrap: WrapState): ClaudeDeliveryPlan["plugins"] {
+  switch (kind) {
+    case "managed-repo":
+      return { owner: "launch-flag", launchExclude: wrap.carriedClaudePluginDirectories };
+    case "managed-companion":
+      return { owner: "launch-flag", launchExclude: [] };
+    case "unmanaged":
+      return { owner: wrap.runtimes.has("claude") ? "wrap" : "none", launchExclude: [] };
+  }
+}
+
+function planChannels(
+  kind: SessionKind,
+  wrap: WrapState,
+): Omit<ClaudeDeliveryPlan, "plugins" | "instructions"> {
   switch (kind) {
     case "managed-repo":
       return {

package/src/runtime/commit-attribution-guard.ts

@@ -0,0 +1,181 @@
+import path from "node:path";
+
+import { heredocBodies, stripHeredocBodies } from "./shell-heredoc";
+
+const CO_AUTHOR_TRAILER = /^\s*co-authored-by\s*[:=]\s*(.+)$/gim;
+/** Substrings, not words: `ChatGPT` and `claude_bot` mention a model too. */
+const MODEL_NAME = /claude|anthropic|gpt|openai|codex|gemini|copilot|opencode/i;
+
+/** `git` options before the subcommand that take the next word as their value. */
+const GIT_VALUE_OPTIONS = new Set(["-C", "-c"]);
+/** `git commit` short options whose value is the next word, or the rest of the cluster. */
+const COMMIT_VALUE_SHORTS = new Set(["m", "F", "t", "c", "C"]);
+/** Words that run the command after them, with their own dash options. */
+const COMMAND_WRAPPERS = new Set(["env", "sudo", "command", "exec", "nice", "nohup", "time"]);
+/** Characters a backslash escapes inside double quotes; before any other it stays. */
+const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\", "\n"]);
+
+const SEPARATOR = Symbol("separator");
+/** A word and the first and last lines it spans. */
+interface Word {
+  text: string;
+  start: number;
+  end: number;
+}
+type Token = Word | typeof SEPARATOR;
+
+/** One simple command's words and the lines it spans. */
+interface Segment {
+  words: string[];
+  start: number;
+  end: number;
+}
+
+/**
+ * Shell words and command separators (`&&`, `||`, `;`, `|`, `&`, parentheses,
+ * newline), quotes removed. A quoted string stays one word across lines, so a
+ * multi-line `-m` message is one value. A heuristic, not a parser.
+ */
+function shellTokens(command: string): Token[] {
+  const tokens: Token[] = [];
+  let word = "";
+  let quote: string | undefined;
+  let quoted = false;
+  let line = 0;
+  let start = 0;
+  const markStart = () => {
+    if (!word && !quoted) start = line;
+  };
+  const append = (text: string) => {
+    markStart();
+    word += text;
+  };
+  const flush = () => {
+    if (word || quoted) tokens.push({ text: word, start, end: line });
+    word = "";
+    quoted = false;
+  };
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i];
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else if (char === "\\" && quote === '"' && DOUBLE_QUOTE_ESCAPES.has(command[i + 1] ?? "")) {
+        append(command[++i]);
+      } else append(char);
+    } else if (char === "'" || char === '"') {
+      markStart();
+      quote = char;
+      quoted = true;
+    } else if (char === "\\" && i + 1 < command.length) {
+      if (command[i + 1] !== "\n") append(command[i + 1]);
+      i++;
+    } else if (";|&\n()".includes(char)) {
+      flush();
+      if (tokens.at(-1) !== SEPARATOR) tokens.push(SEPARATOR);
+    } else if (/\s/.test(char)) {
+      flush();
+    } else {
+      append(char);
+    }
+    if (command[i] === "\n") line++;
+  }
+  flush();
+  return tokens;
+}
+
+function segments(tokens: Token[]): Segment[] {
+  const result: Segment[] = [];
+  let current: Segment | undefined;
+  for (const token of tokens) {
+    if (token === SEPARATOR) {
+      current = undefined;
+    } else if (current) {
+      current.words.push(token.text);
+      current.end = token.end;
+    } else {
+      current = { words: [token.text], start: token.start, end: token.end };
+      result.push(current);
+    }
+  }
+  return result;
+}
+
+/** The words after `git commit`, or null when the segment runs something else. */
+function commitArguments(segment: Segment): string[] | null {
+  const words = segment.words;
+  let i = 0;
+  while (i < words.length) {
+    const word = words[i];
+    if (COMMAND_WRAPPERS.has(word) || word === "{" || word === "!" || /^\w+=/.test(word)) i++;
+    else if (i > 0 && COMMAND_WRAPPERS.has(words[i - 1]) && word.startsWith("-")) i++;
+    else break;
+  }
+  if (i >= words.length || path.basename(words[i]) !== "git") return null;
+  i++;
+  while (i < words.length && words[i].startsWith("-")) {
+    i += GIT_VALUE_OPTIONS.has(words[i]) ? 2 : 1;
+  }
+  return words[i] === "commit" ? words.slice(i + 1) : null;
+}
+
+/**
+ * Message text the arguments carry: `-m x`, `-mx`, `-am x`, `--message=x` and
+ * `--message x` values, plus each `--trailer` value as a trailer line.
+ */
+function messageValues(args: string[]): string[] {
+  const values: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--") break;
+    if (arg === "--message" || arg === "--trailer") {
+      if (i + 1 < args.length) values.push(args[++i]);
+    } else if (arg.startsWith("--message=") || arg.startsWith("--trailer=")) {
+      values.push(arg.slice(arg.indexOf("=") + 1));
+    } else if (/^-[^-]/.test(arg)) {
+      for (let j = 1; j < arg.length; j++) {
+        if (!COMMIT_VALUE_SHORTS.has(arg[j])) continue;
+        const rest = arg.slice(j + 1);
+        const value = rest || args[++i];
+        if (arg[j] === "m" && value !== undefined) values.push(value);
+        break;
+      }
+    }
+  }
+  return values;
+}
+
+/** Whether a trailer credits a model; a literal `\n`, as `printf` or `$'…'` expand it, counts as a line break. */
+function creditsModel(text: string): boolean {
+  for (const trailer of text.replace(/\\n/g, "\n").matchAll(CO_AUTHOR_TRAILER)) {
+    if (MODEL_NAME.test(trailer[1])) return true;
+  }
+  return false;
+}
+
+const REFUSAL = [
+  "Mate guardrail: Co-Authored-By trailers that credit an AI model are not allowed in this repository.",
+  "No commit was created. Rerun the same commit without the Co-Authored-By trailer; do not amend or rewrite history to remove it.",
+].join("\n");
+
+/**
+ * Returns the refusal for a shell command running `git commit` whose message
+ * credits an AI model as co-author, or null. Reads only message text in the
+ * command: `-m`/`--message`/`--trailer` values and the heredoc bodies a commit
+ * reads, those whose marker sits on a line the commit spans. `-F`, `-t` and
+ * editor messages pass unchecked.
+ */
+export function checkCommitAttribution(command: string): string | null {
+  const commits = segments(shellTokens(stripHeredocBodies(command))).flatMap((segment) => {
+    const args = commitArguments(segment);
+    return args ? [{ segment, args }] : [];
+  });
+  if (commits.length === 0) return null;
+
+  const bodies = heredocBodies(command)
+    .filter((body) =>
+      commits.some(({ segment }) => body.line >= segment.start && body.line <= segment.end),
+    )
+    .map((body) => body.text);
+  const messages = [...commits.flatMap(({ args }) => messageValues(args)), ...bodies];
+  return messages.some(creditsModel) ? REFUSAL : null;
+}

package/src/runtime/companion-guidance.ts

@@ -27,8 +27,15 @@ export interface GuidanceContext {
   companionPath: string;
   repository?: { id: string; path: string };
   capabilities?: GuidanceCapability[];
+  /**
+   * Whether the companion's secret guardrails are active. Absent means active:
+   * a caller that cannot tell never drops the rule.
+   */
+  secretGuardrails?: boolean;
 }
 
+const SECRET_HANDLING_RULE = `    <rule id="secret-handling" severity="critical">Never read, print, copy, or write secret files (.env, .env.*, keys, certificates, credential files such as .npmrc or .netrc) or secret values. To learn which variables exist, read only the example files (.env.example, .env.sample, .env.template, .env.dist). Refer to a secret by its variable name only. Do not print environment variables that may hold secrets. When a secret must be set or rotated, ask the user to do it instead of writing it yourself. Guarded calls are blocked; the companion's framework.yaml secrets block is the user's switch, not yours.</rule>`;
+
 export function hasGraphifyCapability(capabilities: GuidanceCapability[] = []): boolean {
   return capabilities.some((capability) => capability.name === "graphify");
 }
@@ -149,7 +156,7 @@ export function buildCompanionPolicyXml(
       `    <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="guardrail" severity="critical">Bad artifact writes to ${context.repository.path} are rejected. The guardrail resolves relative paths against ${context.repository.path} and does not follow cd, so write artifacts, including shell redirects and tee, with absolute paths under ${context.companionPath}. 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>`,
     );
@@ -167,10 +174,14 @@ export function buildCompanionPolicyXml(
     );
   }
 
+  if (context.secretGuardrails !== false) {
+    lines.push(SECRET_HANDLING_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>`,
-      `    <rule id="openspec-publish" severity="critical">Archiving an OpenSpec change is a local operation and publishes nothing. Publish through the mate-artifact-publish skill: it lists candidates with ${FRAMEWORK_NAME} artifact pending --json, takes an explicit user selection, confirms the commit, tag, and push, then runs ${FRAMEWORK_NAME} artifact publish "<name>" --json per selected change. That command is the only sanctioned publication; never hand-commit or hand-tag one. Publishing only publishes an already-archived change: archiving is a precondition, and running publish on a still-active change is an error that names openspec archive as the missing step. Publish never archives and never applies delta specs itself, so archive first — by the archive workflow or an already-synced flow such as openspec-sync-specs — and then publish. Publish also refuses to run anywhere but the companion's default branch.</rule>`,
+      `    <rule id="openspec-publish" severity="critical">Archiving an OpenSpec change is a local operation and publishes nothing. Publish through the mate-publish-artifact skill: it lists candidates with ${FRAMEWORK_NAME} artifact pending --json, holds back archives whose delivery branch is not merged yet, takes an explicit user selection, confirms the commit, tag, and push, then runs ${FRAMEWORK_NAME} artifact publish "<name>" --json per selected change. That command is the only sanctioned publication; never hand-commit or hand-tag one. Publishing only publishes an already-archived change: archiving is a precondition, and running publish on a still-active change is an error that names openspec archive as the missing step. Publish never archives and never applies delta specs itself, so archive first with the mate-archive-change skill, which may run before the merge, and then publish. Publish also refuses to run anywhere but the companion's default branch.</rule>`,
     );
   }
 
@@ -225,7 +236,7 @@ export function buildCompanionGuidance(
  */
 export function buildOpenCodeGuidance(
   capabilities: GuidanceCapability[],
-  options: { companionScoped?: boolean } = {},
+  options: { companionScoped?: boolean; secretGuardrails?: boolean } = {},
 ): MateGuidanceFile {
   const repository = options.companionScoped
     ? undefined
@@ -235,6 +246,7 @@ export function buildOpenCodeGuidance(
       companionPath: "$MATE_ARTIFACT_PATH",
       repository,
       capabilities,
+      secretGuardrails: options.secretGuardrails,
     },
     { wrapperBinPath: "$MATE_WRAPPER_BIN_PATH" },
   );