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

package/src/cli/commands/artifact/pending/discovery.ts

@@ -0,0 +1,249 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { WorkingTreeChange } from "../finish/git";
+
+/** Whether an archived change still has uncommitted content in the companion working tree. */
+export type CommitState = "committed" | "uncommitted";
+
+/** An archive whose delta specs name a canonical spec. Evidence, never proof of authorship. */
+export interface SpecAttribution {
+  /** Dated archive directory name, e.g. `2026-09-07-acme`. */
+  anchor: string;
+  state: CommitState;
+}
+
+/** An uncommitted canonical spec no pending change accounts for, with its attribution. */
+export interface UnattributedSpec {
+  /** Companion-relative POSIX path of the canonical spec. */
+  path: string;
+  /** Whether the spec is new or already tracked and modified. */
+  kind: WorkingTreeChange;
+  /** Every archive naming this spec, oldest anchor first; empty when none does. */
+  touchedByArchives: SpecAttribution[];
+}
+
+export interface UncommittedSpecChange {
+  /** Companion-relative POSIX path of the canonical spec. */
+  path: string;
+  /** Whether the spec is new or already tracked and modified. */
+  kind: WorkingTreeChange;
+}
+
+export interface ArchiveEntry {
+  /** Change name with the archive date prefix stripped. */
+  name: string;
+  /** Dated archive directory name, e.g. `2026-09-07-acme`. */
+  anchor: string;
+  /** Companion-relative POSIX path of the archive directory. */
+  path: string;
+  /** Tag `mate artifact publish` creates for this anchor. */
+  tag: string;
+  /** Uncommitted owned directories that make this change pending. */
+  uncommittedPaths: string[];
+  /** Uncommitted canonical specs this change's delta specs applied to. */
+  uncommittedSpecs: string[];
+  /** Uncommitted canonical specs with their working-tree change kind. */
+  uncommittedSpecChanges: UncommittedSpecChange[];
+  state: CommitState;
+}
+
+/** Only dated archive directories are publishable; everything else is ignored. */
+const ARCHIVE_ANCHOR_PATTERN = /^\d{4}-\d{2}-\d{2}-.+$/;
+const ARCHIVE_DATE_PREFIX = /^\d{4}-\d{2}-\d{2}-/;
+
+export const ARCHIVE_RELATIVE_DIR = "openspec/changes/archive";
+export const SPECS_RELATIVE_DIR = "openspec/specs";
+
+/** The tag `mate artifact publish` creates, never a recomputed date. */
+export function finishMarker(anchor: string): string {
+  return `openspec/${anchor}`;
+}
+
+/** Porcelain collapses an untracked directory to `dir/`; compare without that suffix. */
+function withoutTrailingSlash(candidate: string): string {
+  return candidate.endsWith("/") ? candidate.slice(0, -1) : candidate;
+}
+
+/** True when the reported path is the owned path, sits inside it, or collapsed it. */
+function touches(worktreePath: string, ownedPath: string): boolean {
+  const reported = withoutTrailingSlash(worktreePath);
+  return (
+    reported === ownedPath ||
+    reported.startsWith(`${ownedPath}/`) ||
+    ownedPath.startsWith(`${reported}/`)
+  );
+}
+
+function matching(uncommittedPaths: string[], owned: string[]): string[] {
+  return [
+    ...new Set(
+      uncommittedPaths.filter((worktreePath) =>
+        owned.some((ownedPath) => touches(worktreePath, ownedPath)),
+      ),
+    ),
+  ].toSorted();
+}
+
+function matchingDirectories(uncommittedPaths: string[], owned: string[]): string[] {
+  return owned
+    .flatMap((ownedPath) =>
+      uncommittedPaths.some((worktreePath) => touches(worktreePath, ownedPath))
+        ? [ownedPath.endsWith("/") ? ownedPath : `${ownedPath}/`]
+        : [],
+    )
+    .toSorted();
+}
+
+function changeKindFor(
+  worktreePath: string,
+  kinds: Readonly<Record<string, WorkingTreeChange>>,
+): WorkingTreeChange {
+  const direct = kinds[worktreePath] ?? kinds[withoutTrailingSlash(worktreePath)];
+  if (direct) return direct;
+
+  return (
+    Object.entries(kinds).find(([candidate]) =>
+      touches(worktreePath, withoutTrailingSlash(candidate)),
+    )?.[1] ?? "modified"
+  );
+}
+
+/**
+ * Canonical specs the change's delta specs applied to. Only directory entry names under
+ * the archive's `specs/` tree are read — never any file contents — so archived prose
+ * cannot influence discovery.
+ */
+async function canonicalSpecsFor(companionPath: string, anchor: string): Promise<string[]> {
+  const collectDeltaSpecFiles = async (directory: string, relative = ""): Promise<string[]> => {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    const nested = await Promise.all(
+      entries.map(async (entry) => {
+        const entryRelative = path.posix.join(relative, entry.name);
+        if (entry.isDirectory()) {
+          return collectDeltaSpecFiles(path.join(directory, entry.name), entryRelative);
+        }
+        return entry.isFile() ? [path.posix.join(SPECS_RELATIVE_DIR, entryRelative)] : [];
+      }),
+    );
+    return nested.flat();
+  };
+  try {
+    const specs = await collectDeltaSpecFiles(
+      path.join(companionPath, ARCHIVE_RELATIVE_DIR, anchor, "specs"),
+    );
+    return specs.toSorted();
+  } catch {
+    // A change without delta specs still owns its archive and active directories.
+    return [];
+  }
+}
+
+/**
+ * Lists every dated archive directory with its commit state. State comes from the paths a
+ * change owns outright — its archive directory and the active directory archiving deleted
+ * — because canonical specs are shared: a spec today's work modified would otherwise
+ * resurrect every long-published change that ever touched it. Owned specs are still
+ * reported on a pending entry so the publication scope is visible. Ordering is the stable
+ * anchor sort (oldest date first).
+ */
+export async function discoverArchives(
+  companionPath: string,
+  uncommittedPaths: string[],
+  changeKinds: Readonly<Record<string, WorkingTreeChange>> = {},
+): Promise<ArchiveEntry[]> {
+  let entries;
+  try {
+    entries = await fs.readdir(path.join(companionPath, "openspec", "changes", "archive"), {
+      withFileTypes: true,
+    });
+  } catch {
+    return [];
+  }
+
+  const anchors = entries
+    .filter((entry) => entry.isDirectory() && ARCHIVE_ANCHOR_PATTERN.test(entry.name))
+    .map((entry) => entry.name)
+    .toSorted();
+
+  return Promise.all(
+    anchors.map(async (anchor) => {
+      const name = anchor.replace(ARCHIVE_DATE_PREFIX, "");
+      const ownedPaths = [`${ARCHIVE_RELATIVE_DIR}/${anchor}`, `openspec/changes/${name}`];
+      const owned = matching(uncommittedPaths, ownedPaths);
+      const ownedDirectories = matchingDirectories(uncommittedPaths, ownedPaths);
+      const specs =
+        owned.length > 0
+          ? matching(uncommittedPaths, await canonicalSpecsFor(companionPath, anchor))
+          : [];
+      const specChanges = specs.map((specPath) => ({
+        path: specPath,
+        kind: changeKindFor(specPath, changeKinds),
+      }));
+      return {
+        name,
+        anchor,
+        path: `${ARCHIVE_RELATIVE_DIR}/${anchor}`,
+        tag: finishMarker(anchor),
+        uncommittedPaths: ownedDirectories,
+        uncommittedSpecs: specs,
+        uncommittedSpecChanges: specChanges,
+        state: (owned.length > 0 ? "uncommitted" : "committed") as CommitState,
+      };
+    }),
+  );
+}
+
+export function pendingArchives(archives: ArchiveEntry[]): ArchiveEntry[] {
+  return archives.filter((archive) => archive.state === "uncommitted");
+}
+
+/**
+ * Every archive with the canonical specs its delta specs name, in the caller's archive
+ * order. Built once per call and only when something is unattributed, so the common
+ * `pending` invocation keeps its current I/O.
+ */
+async function attributionIndex(
+  companionPath: string,
+  archives: ArchiveEntry[],
+): Promise<Array<SpecAttribution & { specs: string[] }>> {
+  return Promise.all(
+    archives.map(async (archive) => ({
+      anchor: archive.anchor,
+      state: archive.state,
+      specs: await canonicalSpecsFor(companionPath, archive.anchor),
+    })),
+  );
+}
+
+/**
+ * Uncommitted canonical specs that no pending change accounts for, each attributed to
+ * every archive whose delta specs name it. An attributed spec belongs to a change whose
+ * archive is already committed and can be resumed by publishing that change by name; an
+ * unattributed one belongs to work that is not archived yet. `archives` is the full
+ * archive list, not just the pending ones, because attribution's whole point is naming
+ * the committed archives pending discovery excludes.
+ */
+export async function unattributedSpecs(
+  companionPath: string,
+  uncommittedPaths: string[],
+  archives: ArchiveEntry[],
+  changeKinds: Readonly<Record<string, WorkingTreeChange>> = {},
+): Promise<UnattributedSpec[]> {
+  const claimed = new Set(pendingArchives(archives).flatMap((entry) => entry.uncommittedSpecs));
+  const specPaths = uncommittedPaths
+    .filter(
+      (worktreePath) => touches(worktreePath, SPECS_RELATIVE_DIR) && !claimed.has(worktreePath),
+    )
+    .toSorted();
+  if (specPaths.length === 0) return [];
+
+  const index = await attributionIndex(companionPath, archives);
+  return specPaths.map((specPath) => ({
+    path: specPath,
+    kind: changeKindFor(specPath, changeKinds),
+    touchedByArchives: index.flatMap(({ anchor, state, specs }) =>
+      specs.some((spec) => touches(specPath, spec)) ? [{ anchor, state }] : [],
+    ),
+  }));
+}

package/src/cli/commands/artifact/pending/index.ts

@@ -0,0 +1,17 @@
+export { runArtifactPendingCommand } from "./command";
+export type { PendingCommandDeps, PendingResult } from "./command";
+export {
+  ARCHIVE_RELATIVE_DIR,
+  SPECS_RELATIVE_DIR,
+  discoverArchives,
+  finishMarker,
+  pendingArchives,
+  unattributedSpecs,
+} from "./discovery";
+export type {
+  ArchiveEntry,
+  CommitState,
+  SpecAttribution,
+  UnattributedSpec,
+  UncommittedSpecChange,
+} from "./discovery";

package/src/cli/commands/cap/index-cmd.ts

@@ -8,6 +8,7 @@ import {
 import { resolveForCapability } from "../../../lib/orchestrator/framework-context";
 import type { CapabilityConfig } from "../../../lib/orchestrator/types";
 import {
+  ensureTokensaveBranchingPosture,
   ensureTokensaveStoreExcluded,
   TOKENSAVE_STORE_DIR,
 } from "../../../tools/setup/capabilities/tokensave";
@@ -24,6 +25,7 @@ export interface SyncCapDeps {
   loadCapabilities?: () => Promise<CapabilityConfig[]>;
   isTokensaveInitialized?: () => Promise<boolean>;
   ensureTokensaveStoreExcluded?: (repoPath: string) => Promise<void>;
+  ensureTokensaveBranchingPosture?: (repoPath: string) => Promise<void>;
   runGraphify?: CapRunner;
   runTokensave?: CapRunner;
   onStepStart?: (step: SyncCapStep) => void;
@@ -122,6 +124,8 @@ export async function runIndexCapCommand(args: string[], deps: SyncCapDeps = {})
   const ensureCompanion = deps.ensureUnambiguousCompanion ?? ensureUnambiguousCompanion;
   const isTokensaveInitialized = deps.isTokensaveInitialized ?? defaultIsTokensaveInitialized;
   const ensureStoreExcluded = deps.ensureTokensaveStoreExcluded ?? ensureTokensaveStoreExcluded;
+  const ensureBranchingPosture =
+    deps.ensureTokensaveBranchingPosture ?? ensureTokensaveBranchingPosture;
   const runGraphify = deps.runGraphify ?? runGraphifyCapCommand;
   const runTokensave = deps.runTokensave ?? runTokensaveCapCommand;
 
@@ -152,18 +156,22 @@ export async function runIndexCapCommand(args: string[], deps: SyncCapDeps = {})
 
   if (!options.includeGraphify && hasTokensaveCapability(capabilities)) {
     onStepStart("tokensave");
+    const repoPath = process.env.MATE_REPO_PATH ?? process.cwd();
     if (!(await isTokensaveInitialized())) {
-      await ensureStoreExcluded(process.env.MATE_REPO_PATH ?? process.cwd());
+      await ensureStoreExcluded(repoPath);
       const initOk = await runCapStep(() => runTokensave(["init"]));
       if (!initOk) {
         failed = true;
         onStepDone("tokensave", false);
       } else {
+        /** The store config only exists once `tokensave init` has created it. */
+        await ensureBranchingPosture(repoPath);
         const syncOk = await runCapStep(() => runTokensave(["sync"]));
         if (!syncOk) failed = true;
         onStepDone("tokensave", syncOk);
       }
     } else {
+      await ensureBranchingPosture(repoPath);
       const syncOk = await runCapStep(() => runTokensave(["sync"]));
       if (!syncOk) failed = true;
       onStepDone("tokensave", syncOk);

package/src/cli/commands/cap/index.ts

@@ -1,5 +1,4 @@
 import { runGraphifyCapCommand } from "./graphify";
-import { runHeadroomCapCommand } from "./headroom";
 import { runOpenspecCapCommand } from "./openspec";
 import { runIndexCapCommand } from "./index-cmd";
 import { runPluginCliCommand } from "../../plugin-commands";
@@ -7,7 +6,7 @@ import { runPluginCliCommand } from "../../plugin-commands";
 /**
  * @command mate cap <capability> [...args]
  * @description Dispatches to a capability-scoped subcommand: `graphify`,
- * `headroom`, `openspec` (each forwards `[...args]` to the underlying CLI tool,
+ * `openspec` (each forwards `[...args]` to the underlying CLI tool,
  * scoped to the resolved companion/working repo), or `index` (re-syncs
  * capability indexes such as tokensave/graphify after code changes; `sync` is
  * accepted as a compatibility alias for `index`). Names not claimed by the
@@ -21,7 +20,7 @@ export async function runCapCommand(
 ): Promise<void> {
   if (!capabilityName) {
     process.stderr.write(
-      "mate: capability name required. Use `mate cap <openspec|graphify|headroom|index|sync>`.\n",
+      "mate: capability name required. Use `mate cap <openspec|graphify|index|sync>`.\n",
     );
     process.exitCode = 1;
     return;
@@ -31,9 +30,6 @@ export async function runCapCommand(
     case "graphify":
       await runGraphifyCapCommand(args);
       return;
-    case "headroom":
-      await runHeadroomCapCommand(args);
-      return;
     case "openspec":
       await runOpenspecCapCommand(args);
       return;

package/src/cli/commands/cap/tokensave.ts

@@ -6,7 +6,7 @@ import { ensureTokensaveInstalled } from "../../../tools/setup/capabilities/toke
 
 interface TokensaveCapDeps {
   resolveForLaunch?: typeof resolveForLaunch;
-  ensureInstalled?: (repoPath: string) => Promise<boolean>;
+  ensureInstalled?: (repoPath: string, options?: { upgrade?: boolean }) => Promise<boolean>;
   spawn?: typeof spawnSync;
 }
 
@@ -15,8 +15,8 @@ interface TokensaveCapDeps {
  * @description Forwards `[...args]` to the `tokensave` CLI, run from the
  * active working repository. Requires the `tokensave` capability to be enabled
  * in `.mate/config/framework.yaml` and a registered working repo for the
- * current `MATE_REPO_ID`. Ensures the `tokensave` binary is installed in that
- * repo (via {@link ensureTokensaveInstalled}) before forwarding.
+ * current `MATE_REPO_ID`. Ensures the `tokensave` binary is installed and
+ * upgraded in that repo (via {@link ensureTokensaveInstalled}) before forwarding.
  * @remarks The child process's exit code is propagated via `process.exitCode`.
  */
 export async function runTokensaveCapCommand(
@@ -49,7 +49,7 @@ export async function runTokensaveCapCommand(
     return;
   }
 
-  if (!(await ensureInstalled(repo.path))) {
+  if (!(await ensureInstalled(repo.path, { upgrade: true }))) {
     process.exitCode = 1;
     return;
   }

package/src/cli/commands/companion/companion.ts

@@ -2,7 +2,8 @@ import { usage } from "../../usage";
 import { runCompanionLinkCommand } from "./link";
 import { runSetupCommand } from "../setup";
 import { runCompanionListCommand } from "./list";
-import { runWorkspaceOpenCommand } from "../workspace/open";
+import { runCompanionSyncCommand } from "./sync";
+import { runWorkspaceOpenCommand } from "./open";
 import { runCompanionTuiCommand } from "./tui";
 
 export async function runCompanionCommand(
@@ -19,6 +20,9 @@ export async function runCompanionCommand(
     case "list":
       await runCompanionListCommand(argv);
       return;
+    case "sync":
+      await runCompanionSyncCommand();
+      return;
     case "open":
       await runWorkspaceOpenCommand();
       return;

package/src/cli/commands/companion/link.ts

@@ -239,8 +239,8 @@ export async function runCompanionLinkCommandWithDeps(
   };
 
   // Writes both the companion-side registry entry (companionRootedStore, the
-  // source of truth for `mate workspace list`) and the repo-local pointer
-  // (CompanionStore's internal dual write) in one call.
+  // source of truth for the aggregate pairing inventory) and the repo-local
+  // pointer (CompanionStore's internal dual write) in one call.
   const registerRepository =
     deps.registerRepository ??
     ((nextRepository, options) =>

package/src/cli/commands/companion/sync.ts

@@ -0,0 +1,92 @@
+import { FRAMEWORK_NAME } from "../../../framework";
+import { syncCompanionGit } from "../../../lib/orchestrator/companion-git-sync";
+import { LaunchPreflightError } from "../../../lib/orchestrator/types";
+import { resolveCompanionRuntime } from "../../../runtime/env";
+import { readCompanionPolicy } from "../../../runtime/policy";
+import { resolveCompanionPath, resolveRepoPath } from "./tui";
+
+export interface CompanionSyncDeps {
+  resolveCompanionPath: typeof resolveCompanionPath;
+  resolveProjectedCompanionPath: (cwd: string) => string | undefined;
+  resolveRepoPath: typeof resolveRepoPath;
+  readCompanionPolicy: typeof readCompanionPolicy;
+  syncCompanionGit: typeof syncCompanionGit;
+}
+
+export const companionSyncDeps: CompanionSyncDeps = {
+  resolveCompanionPath,
+  resolveProjectedCompanionPath: (cwd) =>
+    resolveCompanionRuntime(process.env, cwd).context.companionPath || undefined,
+  resolveRepoPath,
+  readCompanionPolicy,
+  syncCompanionGit,
+};
+
+/**
+ * The Projection Root answers for a Wrapped Repository, which can never take
+ * the launch path — so the command must resolve there too, not only through the
+ * repo-local registry the launch uses.
+ */
+async function resolveCompanion(cwd: string): Promise<string | undefined> {
+  const resolved = await companionSyncDeps.resolveCompanionPath(cwd);
+  if (resolved) return resolved;
+  return companionSyncDeps.resolveProjectedCompanionPath(cwd);
+}
+
+/**
+ * @command mate companion sync
+ * @description Runs the companion Git synchronization a launch preflight
+ * performs, against the companion resolved for the current directory. Runs Git
+ * interactively so credentials and conflicts can be answered.
+ */
+export async function runCompanionSyncCommand(): Promise<void> {
+  const cwd = process.cwd();
+  const companionPath = await resolveCompanion(cwd);
+  if (!companionPath) {
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: no companion resolves for this directory. Run \`${FRAMEWORK_NAME} companion link\` first.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  /** An explicit request does not override a companion configured not to have one. */
+  if (!companionSyncDeps.readCompanionPolicy(companionPath).gitAutoMode) {
+    process.stderr.write(
+      [
+        `${FRAMEWORK_NAME}: the companion's Git policy disables synchronization.`,
+        `  companion: ${companionPath}`,
+        `  Set \`git: auto\` in the companion's framework configuration to enable it.`,
+        "",
+      ].join("\n"),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const repoPath = await companionSyncDeps.resolveRepoPath(cwd);
+
+  try {
+    const result = await companionSyncDeps.syncCompanionGit(
+      companionPath,
+      repoPath === companionPath ? undefined : repoPath,
+      true,
+    );
+    if (result.skipped) {
+      process.stdout.write(
+        `${FRAMEWORK_NAME}: ${companionPath} is not a Git working tree; nothing to synchronize.\n`,
+      );
+      return;
+    }
+    process.stdout.write(
+      `${FRAMEWORK_NAME}: synchronized ${companionPath} (${result.changed ? "updated" : "no changes"}).\n`,
+    );
+  } catch (error) {
+    if (error instanceof LaunchPreflightError) {
+      process.stderr.write(`${error.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}

package/src/cli/commands/doctor.ts

@@ -103,9 +103,6 @@ function getSelectedToolChecks(config: {
   if (selectedCapabilities.has("tokensave")) {
     checks.push({ name: "tokensave", command: "tokensave", source: "capability" });
   }
-  if (selectedCapabilities.has("headroom")) {
-    checks.push({ name: "headroom", command: "headroom", source: "capability" });
-  }
   if (selectedCapabilities.has("rtk")) {
     checks.push({ name: "rtk", command: "rtk", source: "capability" });
   }

package/src/cli/commands/launch/shared.ts

@@ -24,6 +24,20 @@ export interface ParsedLaunchArgs {
 
 export { ensureUnambiguousCompanion, launchAmbiguityDeps };
 
+export interface LaunchCommandDeps {
+  createLauncher: () => Pick<FrameworkLauncher, "prepare">;
+  createProgress: typeof createStartupProgress;
+  runIndexCapCommand: typeof runIndexCapCommand;
+  confirm: typeof confirm;
+}
+
+export const launchCommandDeps: LaunchCommandDeps = {
+  createLauncher: () => new FrameworkLauncher(),
+  createProgress: createStartupProgress,
+  runIndexCapCommand,
+  confirm,
+};
+
 export function parseDirectLaunchArgs(argv: string[]): ParsedLaunchArgs {
   const separatorIndex = argv.indexOf("--");
   if (separatorIndex < 0) return { agentArgs: argv };
@@ -72,15 +86,19 @@ export async function runLaunchToolCommand(
     skipGit?: boolean;
   } = {},
 ): Promise<void> {
-  const showProgress = !!(process.stdout.isTTY && process.stdin.isTTY);
-  const progress = showProgress ? createStartupProgress(`Starting ${tool}`) : undefined;
+  const interactiveGit = !!(process.stdin.isTTY && process.stdout.isTTY);
+  const progress = interactiveGit
+    ? launchCommandDeps.createProgress(`Starting ${tool}`)
+    : undefined;
 
   try {
     progress?.start("sync", STEP_LABELS.sync);
-    const prepared = await new FrameworkLauncher().prepare({
+    progress?.stop();
+    const prepared = await launchCommandDeps.createLauncher().prepare({
       tool,
       args,
       skipGit: options.skipGit,
+      interactiveGit,
     });
     progress?.succeed("sync");
     // Stop the Ink UI before running index steps: they spawn graphify/tokensave
@@ -89,14 +107,14 @@ export async function runLaunchToolCommand(
     progress?.stop();
 
     if (!options.skipConfirmation) {
-      const ok = await confirm("Continue? [y/N] ");
+      const ok = await launchCommandDeps.confirm("Continue? [y/N] ");
       if (!ok) {
         process.stderr.write("Aborted.\n");
         process.exit(1);
       }
     }
 
-    await runIndexCapCommand([], {
+    await launchCommandDeps.runIndexCapCommand([], {
       onStepStart: (step) => process.stdout.write(`${STEP_LABELS[step]}...\n`),
       onStepDone: (step, ok) => process.stdout.write(`${ok ? "✓" : "✗"} ${STEP_LABELS[step]}\n`),
     });