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

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" },
   );

package/src/runtime/companion-instructions.ts

@@ -0,0 +1,340 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { MATE_ENV } from "./env-names";
+import { FRAMEWORK_NAME } from "./framework";
+import {
+  findCompanionBlock,
+  findManagedBlocks,
+  managedBlockPluginId,
+  stripManagedBlocks,
+  type ManagedBlock,
+} from "./managed-block";
+import { joinLines, scanLinesWithoutComments, type ScannedLine } from "./markdown-scan";
+
+/**
+ * Companion Instructions: the companion's own `AGENTS.md`, rendered for one
+ * Claude session. Read-only. The text mirrors what native loading of the
+ * companion `CLAUDE.md` (`@AGENTS.md`) yields: block-level HTML comments
+ * stripped, `AGENTS.override.md` not read. `@` lines stay literal, because
+ * expanding an import outside the project needs an approval a hook or `-p`
+ * session never gets.
+ */
+
+export const COMPANION_INSTRUCTIONS_TAG = "companion-instructions";
+
+/**
+ * Below Claude Code's 10,000-character cap on one hook's `additionalContext`;
+ * a longer value arrives as a file preview instead of in context.
+ */
+export const COMPANION_INSTRUCTIONS_BUDGET = 9_000;
+
+/** Where the Claude Runtime Surface writes its `mate:managed` blocks; those in `AGENTS.md` are OpenCode's. */
+const CLAUDE_BLOCK_FILE = "CLAUDE.md";
+
+export interface CompanionInstructionsInput {
+  companionPath: string;
+  repository: { id: string; path: string };
+  wrapperBinPath: string;
+}
+
+export type CompanionInstructions =
+  | {
+      kind: "available";
+      /** Absolute path of the companion `AGENTS.md`. */
+      source: string;
+      text: string;
+      omitted: string[];
+      /** The `MATE:COMPANION` block alone overruns the budget; it is never cut, so every other segment is omitted. */
+      oversized: boolean;
+    }
+  | { kind: "unavailable"; source: string; reason: string };
+
+export type InstructionReader = (input: CompanionInstructionsInput) => CompanionInstructions;
+
+export function companionInstructionsUnavailableLine(
+  result: Extract<CompanionInstructions, { kind: "unavailable" }>,
+): string {
+  return `Companion instructions unavailable: ${result.source} ${result.reason}`;
+}
+
+export interface CompanionInstructionsDeps {
+  isFile?: (filePath: string) => boolean;
+  readFile?: (filePath: string) => string;
+}
+
+function defaultIsFile(filePath: string): boolean {
+  return fs.statSync(filePath).isFile();
+}
+
+function defaultReadFile(filePath: string): string {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+/** Only a regular file is opened: a FIFO would block the read, and a hook that never returns stalls the session. */
+function readText(
+  filePath: string,
+  deps: CompanionInstructionsDeps,
+): { text: string } | { reason: string } {
+  const isFile = deps.isFile ?? defaultIsFile;
+  const readFile = deps.readFile ?? defaultReadFile;
+  try {
+    if (!isFile(filePath)) return { reason: "is not a regular file" };
+    return { text: readFile(filePath).replace(/\r\n?/g, "\n") };
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { reason: "not found" };
+    return { reason: `could not be read (${code ?? (error as Error).message})` };
+  }
+}
+
+function fillPlaceholders(text: string, input: CompanionInstructionsInput): string {
+  const values: Record<string, string> = {
+    [MATE_ENV.repositoryPath]: input.repository.path,
+    [MATE_ENV.repositoryId]: input.repository.id,
+    [MATE_ENV.companionPath]: input.companionPath,
+    [MATE_ENV.wrapperBinPath]: input.wrapperBinPath,
+  };
+  return text.replace(
+    /\$\{(MATE_\w+)\}|\$(MATE_\w+)/g,
+    (match, braced?: string, bare?: string) => values[(braced ?? bare)!] ?? match,
+  );
+}
+
+interface Segment {
+  /** The `##` heading, or a description for text no heading introduces. */
+  name: string;
+  text: string;
+  /** The `MATE:COMPANION` block: always kept whole. */
+  required: boolean;
+  source: string;
+  /** Shared by the two halves of a section the block sits in, so they are kept or omitted together. */
+  section: object;
+}
+
+const UNTITLED = "text before the first section";
+/** An empty `##` heading still opens a section, which the omission line must name. */
+const EMPTY_HEADING = "untitled section";
+
+function splitSections(text: string, source: string): Segment[] {
+  const sections: { name: string; lines: ScannedLine[] }[] = [{ name: UNTITLED, lines: [] }];
+  for (const line of scanLinesWithoutComments(text)) {
+    if (line.heading !== null) sections.push({ name: line.heading || EMPTY_HEADING, lines: [] });
+    sections.at(-1)!.lines.push(line);
+  }
+  return sections.map(({ name, lines }) => ({
+    name,
+    text: joinLines(lines),
+    required: false,
+    source,
+    section: {},
+  }));
+}
+
+/** The block's markers are found before the scan, which would strip them as comments. */
+function segmentAgents(text: string, source: string): Segment[] {
+  const found = findCompanionBlock(text, FRAMEWORK_NAME);
+  if (!found) return splitSections(text, source).filter((part) => part.text.length > 0);
+
+  const before = splitSections(text.slice(0, found.start), source);
+  const after = splitSections(text.slice(found.end), source);
+  /** The text after the block, up to the next heading, continues the section the block opened in. */
+  const enclosing = before.at(-1)!;
+  after[0] = { ...after[0]!, name: enclosing.name, section: enclosing.section };
+  const block: Segment = {
+    name: `${FRAMEWORK_NAME.toUpperCase()}:COMPANION block`,
+    text: joinLines(scanLinesWithoutComments(text.slice(found.start, found.end))),
+    required: true,
+    source,
+    section: {},
+  };
+  return [...before, block, ...after].filter((part) => part.text.length > 0);
+}
+
+function segmentBlocks(
+  blocks: readonly ManagedBlock[],
+  source: string,
+  input: CompanionInstructionsInput,
+): Segment[] {
+  return blocks
+    .map((block) => ({
+      name: `${path.basename(source)} block ${managedBlockPluginId(block.key)}`,
+      text: joinLines(scanLinesWithoutComments(fillPlaceholders(block.body, input))),
+      required: false,
+      source,
+      section: {},
+    }))
+    .filter((part) => part.text.length > 0);
+}
+
+function segment(
+  agents: string,
+  source: string,
+  input: CompanionInstructionsInput,
+  deps: CompanionInstructionsDeps,
+): Segment[] {
+  const own = stripManagedBlocks(agents, FRAMEWORK_NAME);
+  const blockSource = path.join(input.companionPath, CLAUDE_BLOCK_FILE);
+  const read = readText(blockSource, deps);
+  const blocks = "text" in read ? findManagedBlocks(read.text, FRAMEWORK_NAME) : [];
+  return [
+    ...segmentAgents(fillPlaceholders(own, input), source),
+    ...segmentBlocks(blocks, blockSource, input),
+  ];
+}
+
+function escapeAttribute(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+}
+
+function render(source: string, segments: readonly Segment[], closing?: string): string {
+  const body = [...segments.map((part) => part.text), ...(closing ? [closing] : [])].join("\n\n");
+  return `<${COMPANION_INSTRUCTIONS_TAG} source="${escapeAttribute(source)}">\n${body}\n</${COMPANION_INSTRUCTIONS_TAG}>`;
+}
+
+/** Hundreds of headings would otherwise make the omission line alone exceed the budget. */
+const OMISSION_NAMES_CAP = 400;
+const OMISSION_NAME_MAX = 80;
+
+/** Cut by code point, so a heading of astral characters never ends in half a surrogate pair. */
+function omissionName(name: string): string {
+  const points = [...name];
+  if (points.length <= OMISSION_NAME_MAX) return name;
+  return `${points.slice(0, OMISSION_NAME_MAX - 1).join("")}…`;
+}
+
+function listOmitted(names: readonly string[], cap: number): string {
+  const shown: string[] = [];
+  for (const name of names.map(omissionName)) {
+    const listing = [...shown, name].join(", ");
+    if (shown.length > 0 && listing.length > cap) break;
+    shown.push(name);
+  }
+  const more = names.length - shown.length;
+  return more > 0 ? `${shown.join(", ")} and ${more} more` : shown.join(", ");
+}
+
+function omissionLine(listing: string, sources: readonly string[]): string {
+  return `Sections not included here: ${listing}. Full text: ${sources.join(" and ")}`;
+}
+
+/** Capped at `room` too: a block that leaves little room gets a count, not a listing that carries the result past Claude Code's hook cap. */
+function closingLine(names: readonly string[], sources: readonly string[], room: number): string {
+  const fixed = omissionLine("", sources).length + ` and ${names.length} more`.length;
+  return omissionLine(listOmitted(names, Math.min(OMISSION_NAMES_CAP, room - fixed)), sources);
+}
+
+function fullTextSources(source: string, parts: readonly Segment[]): string[] {
+  const others = new Set(parts.map((part) => part.source).filter((file) => file !== source));
+  return [source, ...others];
+}
+
+/**
+ * The longest omission line any subset of `optional` can produce. A subset
+ * lists at most the capped names, and its count of unlisted names, which only
+ * appears once the full listing passes the cap, has at most as many digits as
+ * the whole.
+ */
+function omissionReserve(sections: readonly Segment[][], source: string): number {
+  const listed = sections.map((parts) => omissionName(parts[0]!.name)).join(", ").length;
+  const more = listed > OMISSION_NAMES_CAP ? ` and ${sections.length} more`.length : 0;
+  const fixed = omissionLine("", fullTextSources(source, sections.flat())).length;
+  return fixed + Math.min(listed, OMISSION_NAMES_CAP) + more;
+}
+
+/** The segments other than the block, grouped by section in document order. */
+function optionalSections(segments: readonly Segment[]): Segment[][] {
+  const sections = new Map<object, Segment[]>();
+  for (const part of segments) {
+    if (part.required) continue;
+    const parts = sections.get(part.section);
+    if (parts) parts.push(part);
+    else sections.set(part.section, [part]);
+  }
+  return [...sections.values()];
+}
+
+/** The omission line's worst case is reserved before any section is added, so adding the real line never pushes a fitting result over. */
+function fit(
+  source: string,
+  segments: readonly Segment[],
+): { text: string; omitted: string[]; oversized: boolean } {
+  const whole = render(source, segments);
+  if (whole.length <= COMPANION_INSTRUCTIONS_BUDGET) {
+    return { text: whole, omitted: [], oversized: false };
+  }
+
+  const sections = optionalSections(segments);
+  const reserve = "#".repeat(omissionReserve(sections, source));
+  const kept = new Set<Segment>(segments.filter((part) => part.required));
+  let length = render(source, [...kept], reserve).length;
+  for (const parts of sections) {
+    const next = parts.reduce((sum, part) => sum + part.text.length + "\n\n".length, length);
+    if (next > COMPANION_INSTRUCTIONS_BUDGET) continue;
+    for (const part of parts) kept.add(part);
+    length = next;
+  }
+
+  const build = (): { text: string; omitted: string[] } => {
+    const chosen = segments.filter((part) => kept.has(part));
+    const omitted = sections.filter((parts) => !kept.has(parts[0]!));
+    const names = omitted.map((parts) => parts[0]!.name);
+    const body = render(source, chosen);
+    const closing =
+      omitted.length > 0
+        ? closingLine(
+            names,
+            fullTextSources(source, omitted.flat()),
+            COMPANION_INSTRUCTIONS_BUDGET - body.length - "\n\n".length,
+          )
+        : undefined;
+    return { text: render(source, chosen, closing), omitted: names };
+  };
+
+  let result = build();
+  /**
+   * The reserve names every section; a dropped one may still fit beside the
+   * real, shorter line. Each section added shortens that line, so the pass
+   * repeats until none is added.
+   */
+  for (let added = true; added;) {
+    added = false;
+    for (const parts of sections) {
+      if (result.text.length > COMPANION_INSTRUCTIONS_BUDGET || kept.has(parts[0]!)) continue;
+      for (const part of parts) kept.add(part);
+      const next = build();
+      if (next.text.length <= COMPANION_INSTRUCTIONS_BUDGET) {
+        result = next;
+        added = true;
+      } else for (const part of parts) kept.delete(part);
+    }
+  }
+  return { ...result, oversized: result.text.length > COMPANION_INSTRUCTIONS_BUDGET };
+}
+
+export function buildCompanionInstructions(
+  input: CompanionInstructionsInput,
+  deps: CompanionInstructionsDeps = {},
+): CompanionInstructions {
+  const source = path.join(input.companionPath, "AGENTS.md");
+  const read = readText(source, deps);
+  if (!("text" in read)) return { kind: "unavailable", source, reason: read.reason };
+
+  return { kind: "available", source, ...fit(source, segment(read.text, source, input, deps)) };
+}
+
+/**
+ * Text beyond the `@AGENTS.md` import, Mate-managed blocks and HTML comments:
+ * only a companion-scoped session reads it; the Companion Instructions leave it out.
+ */
+export function companionClaudeMdHasOwnText(
+  companionPath: string,
+  deps: CompanionInstructionsDeps = {},
+): boolean {
+  const read = readText(path.join(companionPath, "CLAUDE.md"), deps);
+  if (!("text" in read)) return false;
+  return scanLinesWithoutComments(stripManagedBlocks(read.text, FRAMEWORK_NAME)).some((line) => {
+    const trimmed = line.text.trim();
+    return trimmed !== "" && trimmed !== "@AGENTS.md" && trimmed !== "@./AGENTS.md";
+  });
+}

package/src/runtime/error-message.ts

@@ -0,0 +1,4 @@
+/** The message of a thrown value, whether or not it is an `Error`. */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/runtime/guidance.ts

@@ -1,5 +1,3 @@
-import path from "node:path";
-
 /**
  * Versioned companion guidance contract. The CLI builds the guidance data
  * from its playbooks at launch time and delivers it through the
@@ -18,12 +16,6 @@ export type MateGuidanceFile = {
   companionGuidance: string;
   codebaseExplorationGuidance: string;
   errors: string[];
-  /**
-   * The active audience's layer, for a launch that hosts its own server only.
-   * The plugin applies it only from a payload it trusts; a masked payload
-   * carries none, so the shared service and bare sessions never see one.
-   */
-  audienceLayer?: string;
 };
 
 export type GuidanceValidation = {
@@ -84,21 +76,12 @@ export function validateGuidanceData(value: unknown): GuidanceValidation {
     errors.push("injected codebase exploration guidance is malformed");
   }
 
-  const audienceLayer =
-    typeof value.audienceLayer === "string" && path.isAbsolute(value.audienceLayer)
-      ? value.audienceLayer
-      : undefined;
-  if (value.audienceLayer !== undefined && audienceLayer === undefined) {
-    errors.push("injected audience layer is not an absolute path");
-  }
-
   return {
     guidance: {
       version: GUIDANCE_FILE_VERSION,
       companionGuidance,
       codebaseExplorationGuidance,
       errors,
-      ...(audienceLayer ? { audienceLayer } : {}),
     },
     errors,
   };

package/src/runtime/index.ts

@@ -1,3 +1,8 @@
+export {
+  ARTIFACT_REFUSAL_HEADLINE,
+  artifactRefusal,
+  type ArtifactRefusalInput,
+} from "./artifact-refusal";
 export {
   GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT,
   GRAPHIFY_COMPANION_PATH_CONTRACT,