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

package/src/cli/commands/wrap.ts

@@ -0,0 +1,164 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import { ConfigStore, mergeWithDefaults } from "../../lib/orchestrator/config-store";
+import { findRepoLocalLinkedRepository } from "../../lib/orchestrator/repo-local-registry";
+import {
+  projectWorkingRepository,
+  projectWorkingRuntimeDocuments,
+} from "../../lib/orchestrator/working-repo-projection";
+import { renderWorkingRuntimeDocuments } from "../../tools/setup";
+import { launchAmbiguityDeps } from "./shared/companion-selection";
+
+export interface WrapCommandDependencies {
+  findRepoLocalLinkedRepository?: typeof findRepoLocalLinkedRepository;
+  projectWorkingRepository?: typeof projectWorkingRepository;
+  projectWorkingRuntimeDocuments?: typeof projectWorkingRuntimeDocuments;
+  renderWorkingRuntimeDocuments?: typeof renderWorkingRuntimeDocuments;
+  resolveLinkedCompanions?: typeof launchAmbiguityDeps.resolveLinkedCompanions;
+}
+
+export const wrapCommandDeps: Required<WrapCommandDependencies> = {
+  findRepoLocalLinkedRepository,
+  projectWorkingRepository,
+  projectWorkingRuntimeDocuments,
+  renderWorkingRuntimeDocuments,
+  resolveLinkedCompanions: (cwd: string) => launchAmbiguityDeps.resolveLinkedCompanions(cwd),
+};
+
+/** The companion's own selection, read from files: wrapping runs no setup pass. */
+async function readCompanionConfig(companionPath: string) {
+  return mergeWithDefaults(
+    await new ConfigStore(
+      path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+    ).load(),
+  );
+}
+
+/**
+ * `--companion` is consumed by the dispatch gate before the command runs, so it
+ * is parsed there too; this only rejects anything else.
+ */
+export function parseWrapArgs(argv: string[]): { companion?: string } | { error: string } {
+  let companion: string | undefined;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (arg === "--companion") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) return { error: "--companion requires a path" };
+      companion = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--companion=")) {
+      const value = arg.slice("--companion=".length);
+      if (!value) return { error: "--companion requires a path" };
+      companion = value;
+      continue;
+    }
+    return { error: `unknown wrap option: ${arg}` };
+  }
+  return companion === undefined ? {} : { companion };
+}
+
+/**
+ * Writes the Working Repository's Projection Root and the documents the Agent
+ * Runtimes discover by themselves, so an Unmanaged Session both resolves its
+ * Repository Link and loads the readers that consult it. The companion has
+ * already been settled by the dispatch gate, which honors `--companion`, the
+ * launch environment, and the picker in that order; wrapping only makes the
+ * answer durable.
+ */
+export async function runWrapCommand(
+  argv: string[] = [],
+  cwd: string = process.cwd(),
+  deps: WrapCommandDependencies = {},
+): Promise<void> {
+  const findRepository =
+    deps.findRepoLocalLinkedRepository ?? wrapCommandDeps.findRepoLocalLinkedRepository;
+  const project = deps.projectWorkingRepository ?? wrapCommandDeps.projectWorkingRepository;
+  const projectDocuments =
+    deps.projectWorkingRuntimeDocuments ?? wrapCommandDeps.projectWorkingRuntimeDocuments;
+  const renderDocuments =
+    deps.renderWorkingRuntimeDocuments ?? wrapCommandDeps.renderWorkingRuntimeDocuments;
+  const resolveLinked = deps.resolveLinkedCompanions ?? wrapCommandDeps.resolveLinkedCompanions;
+
+  const parsed = parseWrapArgs(argv);
+  if ("error" in parsed) {
+    console.error(`${FRAMEWORK_NAME}: ${parsed.error}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const repository = await findRepository(cwd);
+  if (!repository) {
+    console.error(
+      `${FRAMEWORK_NAME}: this directory is not a working repository linked to a companion.`,
+    );
+    console.error(`Run \`${FRAMEWORK_NAME} companion link\` first.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  /**
+   * The gate pins only on ambiguity, so the unambiguous case still resolves
+   * here — a single Linked Companion needs no answer to have been recorded.
+   */
+  const companionPath =
+    (parsed.companion && path.resolve(parsed.companion)) ??
+    process.env.MATE_ARTIFACT_PATH ??
+    (await resolveLinked(cwd))[0]?.companionPath;
+  if (!companionPath) {
+    console.error(`${FRAMEWORK_NAME}: no registered companion links ${repository.id}.`);
+    console.error(`Run \`${FRAMEWORK_NAME} companion link\` first.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = await project(companionPath, repository);
+  if (result.kind === "failed") {
+    console.error(
+      `${FRAMEWORK_NAME}: failed to write the projection for ${repository.id}: ${result.error.message}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  /**
+   * After the projection, never instead of it: a runtime document that cannot
+   * be written fails the command while the projection already written stays.
+   */
+  const config = await readCompanionConfig(result.companionPath);
+  const documents = await projectDocuments(
+    result.companionPath,
+    repository,
+    config,
+    await renderDocuments(result.companionPath, config, repository.path),
+  );
+  if (documents.kind === "failed") {
+    console.error(
+      `${FRAMEWORK_NAME}: failed to reconcile ${documents.document} for ${repository.id}: ${documents.error.message}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const changed = result.kind === "written" || documents.kind === "written";
+  console.log(
+    changed
+      ? `Wrapped ${repository.id} at ${result.projectionRoot}`
+      : `Already wrapped: ${result.projectionRoot}`,
+  );
+  console.log(`  Companion: ${result.companionPath}`);
+  for (const document of documents.documents) {
+    console.log(`  Runtime:   ${document}`);
+  }
+  /**
+   * Said at the moment the mode is switched, not left to be discovered at the
+   * next launch: wrapping makes `mate claude` and `mate opencode` refuse here,
+   * and the operator has no other way to learn that from a successful command.
+   */
+  console.log(
+    `Start sessions yourself now: \`claude\` or \`opencode\`. \`${FRAMEWORK_NAME} claude\` and \`${FRAMEWORK_NAME} opencode\` do not run in a wrapped repository — \`${FRAMEWORK_NAME} unwrap\` reverses this.`,
+  );
+}

package/src/cli/main.ts

@@ -16,13 +16,22 @@ import { runLaunchClaudeCommand } from "./commands/launch/claude";
 import { runLaunchOpenCodeCommand } from "./commands/launch/opencode";
 import { runPluginCommand } from "./commands/plugin/plugin";
 import { runReportCommand } from "./commands/report";
+import { runStudioCommand } from "./commands/studio";
 import { runUpdateCommand } from "./commands/update";
-import { runWorkspaceCommand } from "./commands/workspace/workspace";
+import { runUnwrapCommand } from "./commands/unwrap";
+import { parseWrapArgs, runWrapCommand } from "./commands/wrap";
 import { runWorkingCommand } from "./commands/working/working";
 import { runInstallCommand } from "./commands/install";
-import { inspectInstallPreflight } from "../lib/install";
+import {
+  inspectInstallPreflight,
+  isRepairableInstallPreflight,
+  repairInstallState,
+} from "../lib/install";
 import { resolveRootContext } from "../lib/orchestrator/root-context";
-import { ensureUnambiguousCompanion } from "./commands/shared/companion-selection";
+import {
+  ensureUnambiguousCompanion,
+  type CompanionSelectionOptions,
+} from "./commands/shared/companion-selection";
 import { hydrateDynamicPlugins } from "../tools/setup/dynamic-plugins/hydrate";
 import { findPluginCliCommand } from "./plugin-commands";
 import { usage } from "./usage";
@@ -34,8 +43,12 @@ export interface GateNeeds {
   notHubRoot?: boolean;
   /** Block the command when the current directory resolves to a companion root. */
   notCompanionRoot?: boolean;
-  /** Require an unambiguous companion (selection wizard on ambiguity) before dispatch. */
-  companion?: boolean;
+  /**
+   * Require an unambiguous companion (selection wizard on ambiguity) before
+   * dispatch. Options select a companion explicitly or force the wizard past a
+   * recorded answer.
+   */
+  companion?: boolean | CompanionSelectionOptions;
   /** Require a complete installation (install preflight) before dispatch. */
   install?: boolean;
 }
@@ -43,6 +56,7 @@ export interface GateNeeds {
 export interface MainDeps {
   ensureUnambiguousCompanion: typeof ensureUnambiguousCompanion;
   inspectInstallPreflight: typeof inspectInstallPreflight;
+  repairInstallState?: typeof repairInstallState;
   hydrateDynamicPlugins: typeof hydrateDynamicPlugins;
   resolveRootContext: typeof resolveRootContext;
 }
@@ -50,6 +64,7 @@ export interface MainDeps {
 const mainDeps: MainDeps = {
   ensureUnambiguousCompanion,
   inspectInstallPreflight,
+  repairInstallState,
   hydrateDynamicPlugins,
   resolveRootContext,
 };
@@ -80,17 +95,16 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
   const isPluginCommand =
     command === "cap" && findPluginCliCommand(subcommand, rest[0]) !== undefined;
 
-  // `workspace list`/`workspace materialize` are machine-JSON contracts an
-  // editor extension may poll frequently; their stdout must be pure JSON,
-  // and the un-awaited scheduleBackgroundCheck() has been observed to race
-  // a large final stdout write against process exit, truncating it. Both
-  // reasons put them in the same stdout-owning bucket as plugin commands.
-  const ownsStdout = isPluginCommand || command === "workspace";
+  // Plugin commands are the only stdout owners: the un-awaited
+  // scheduleBackgroundCheck() has been observed to race a large final stdout
+  // write against process exit, truncating it.
+  const ownsStdout = isPluginCommand;
 
   // Every dispatch case opens with a gate() call declaring what the command
   // needs before it may run. Declared gates run in fixed order — update
   // enforcement, companion selection, install preflight — and a blocked gate
   // sets the exit code, so callers only need `if (!(await gate(...))) return`.
+  let installRepairAttempted = false;
   const gate = async (needs: GateNeeds): Promise<boolean> => {
     if (!ownsStdout) {
       const updateStore = new UpdateStateStore();
@@ -120,7 +134,11 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       }
     }
 
-    if (needs.companion && !(await deps.ensureUnambiguousCompanion())) {
+    const companionOptions = typeof needs.companion === "object" ? needs.companion : {};
+    if (
+      needs.companion &&
+      !(await deps.ensureUnambiguousCompanion(process.cwd(), companionOptions))
+    ) {
       process.exitCode = 1;
       return false;
     }
@@ -128,6 +146,14 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
     if (needs.install) {
       const preflight = await deps.inspectInstallPreflight();
       if (!preflight.ok) {
+        if (!installRepairAttempted && isRepairableInstallPreflight(preflight)) {
+          installRepairAttempted = true;
+          try {
+            await (deps.repairInstallState ?? repairInstallState)(preflight.plan!);
+            process.stderr.write(`${FRAMEWORK_NAME}: repaired installation state; continuing.\n`);
+            if ((await deps.inspectInstallPreflight()).ok) return true;
+          } catch {}
+        }
         console.error(`${FRAMEWORK_NAME}: ${preflight.reason ?? "installation is incomplete"}`);
         console.error(`Run \`${FRAMEWORK_NAME} install\` before continuing.`);
         process.exitCode = 1;
@@ -171,9 +197,10 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
         case "hub":
           if (!(await gate({ updateGuard: true, notCompanionRoot: true }))) return;
           break;
-        // open/tui consume a companion context.
+        // open/tui/sync consume a companion context.
         case "open":
         case "tui":
+        case "sync":
           if (!(await gate({ updateGuard: true, notHubRoot: true, companion: true }))) return;
           break;
         // list and unknown subcommands (which fail inside the command).
@@ -199,6 +226,14 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       if (!(await gate({ updateGuard: true, install: true }))) return;
       await runReportCommand(argv.slice(3));
       return;
+    case "studio":
+      /**
+       * Serves the machine-wide inventory read-only, so it resolves no
+       * companion context and stays runnable from any directory.
+       */
+      if (!(await gate({ updateGuard: true }))) return;
+      await runStudioCommand(argv.slice(3));
+      return;
     case "config":
       if (!(await gate({ updateGuard: true }))) return;
       await runConfigCommand(argv.slice(3));
@@ -215,16 +250,30 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       if (!(await gate({}))) return;
       await runUpdateCommand(argv.slice(3));
       return;
-    case "workspace":
-      // list/materialize are context-independent: no companion, install, or
-      // update gating — an editor extension may call these frequently.
-      if (!(await gate({}))) return;
-      await runWorkspaceCommand(subcommand, rest);
-      return;
     case "working":
       if (!(await gate({}))) return;
       await runWorkingCommand(subcommand, rest);
       return;
+    case "wrap": {
+      // Recording the answer is the point, so a recorded one must not suppress
+      // the wizard; a bad flag is reported without prompting first.
+      const wrapArgs = argv.slice(3);
+      const parsedWrap = parseWrapArgs(wrapArgs);
+      if ("error" in parsedWrap) {
+        await runWrapCommand(wrapArgs);
+        return;
+      }
+      const needs = { ignoreProjection: true, companion: parsedWrap.companion };
+      if (!(await gate({ updateGuard: true, companion: needs, install: true }))) return;
+      await runWrapCommand(wrapArgs);
+      return;
+    }
+    case "unwrap":
+      // A recovery path: it withdraws what a wrap placed, so it must never be
+      // gated on a companion or an installation it does not consult.
+      if (!(await gate({}))) return;
+      await runUnwrapCommand(argv.slice(3));
+      return;
     default:
       // Unknown commands fail fast: no case matched, so no gate ever ran.
       console.error(`Unknown command: ${command}`);

package/src/cli/parse-flags.ts

@@ -7,31 +7,56 @@ import type { CapabilityConfig } from "../lib/orchestrator/types";
 
 export type CliFlags = Record<string, string | string[] | boolean>;
 
-export function parseFlags(argv: string[]): CliFlags {
+/**
+ * Flags whose presence is the whole value. A flag not listed here consumes the next
+ * non-`--` token, so an unlisted boolean silently swallows a positional and then reads
+ * as absent — e.g. `--no-push my-change` yielding `{"no-push": "my-change"}`.
+ */
+export type BooleanFlagSet = ReadonlySet<string>;
+
+const NO_BOOLEAN_FLAGS: BooleanFlagSet = new Set<string>();
+
+export function parseFlags(
+  argv: string[],
+  booleanFlags: BooleanFlagSet = NO_BOOLEAN_FLAGS,
+): CliFlags {
   const flags: CliFlags = {};
 
+  const assign = (key: string, value: string): void => {
+    const current = flags[key];
+    if (current === undefined) flags[key] = value;
+    else if (Array.isArray(current)) current.push(value);
+    else flags[key] = [current as string, value];
+  };
+
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (!token.startsWith("--")) {
       continue;
     }
 
-    const key = token.slice(2);
-    const next = argv[index + 1];
+    const body = token.slice(2);
+    const equals = body.indexOf("=");
+    if (equals !== -1) {
+      const key = body.slice(0, equals);
+      const value = body.slice(equals + 1);
+      if (booleanFlags.has(key)) flags[key] = value !== "false";
+      else assign(key, value);
+      continue;
+    }
 
-    if (!next || next.startsWith("--")) {
-      flags[key] = true;
+    if (booleanFlags.has(body)) {
+      flags[body] = true;
       continue;
     }
 
-    if (flags[key] === undefined) {
-      flags[key] = next;
-    } else if (Array.isArray(flags[key])) {
-      flags[key].push(next);
-    } else {
-      flags[key] = [flags[key] as string, next];
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      flags[body] = true;
+      continue;
     }
 
+    assign(body, next);
     index += 1;
   }
 

package/src/cli/usage.ts

@@ -14,17 +14,21 @@ export function usage(): string {
     ` ${n} companion link`,
     ` ${n} companion setup`,
     ` ${n} companion list`,
+    ` ${n} companion sync`,
     ` ${n} companion open`,
     ` ${n} companion tui`,
-    ` ${n} workspace list --json`,
-    ` ${n} workspace materialize --repository ID --companion PATH --json`,
     ` ${n} working cleanup`,
+    ` ${n} wrap [--companion PATH]`,
+    ` ${n} unwrap`,
     ` ${n} hub init [folder]`,
     ` ${n} hub add [source] [--id ID] [--path PATH]`,
     ` ${n} hub sync [--json] (companions + hub plugins)`,
-    ` ${n} artifact finish <change-name> [--type openspec] [--force] [--no-push] [--json]`,
+    ` ${n} artifact publish <anchor|change-name> [--type openspec] [--no-push] [--json]`,
+    "   target: a dated archive anchor, or a change name matching exactly one archive",
+    ` ${n} artifact pending [--json]`,
     ` ${n} doctor`,
     ` ${n} report [--days N] [--input FILE|-] [--json]`,
+    ` ${n} studio`,
     ` ${n} config`,
     ` ${n} claude [args...] (use -- --no-git to bypass companion Git sync)`,
     ` ${n} opencode [args...] (use -- --no-git to bypass companion Git sync)`,
@@ -41,6 +45,11 @@ export function usage(): string {
     ` ${n} working cleanup removes Mate-owned local integration without resetting product work`,
     " tracked files and capability data remain untouched; link or launch recreates required state",
     "",
+    "Wrapped repositories:",
+    ` ${n} wrap configures the repository so sessions you start yourself load the companion`,
+    ` ${n} claude and ${n} opencode do not run while a repository is wrapped`,
+    ` ${n} unwrap withdraws the wrap and restores managed launches; the link is kept`,
+    "",
     "Doctor states:",
     " linked-working-repository — cwd is inside a registered working repository",
     " companion-repository — cwd is the companion repository itself",

package/src/framework.ts

@@ -1,7 +1 @@
-/**
- * Framework identity: names everything identity-shaped — state directories
- * (`~/.mate`, `.mate/`), managed-block markers, `MATE_*` env values, usage
- * output, command hints, error prefixes, agent guidance, and permission
- * entries. The distribution is always invoked as `mate`.
- */
-export const FRAMEWORK_NAME = "mate";
+export { FRAMEWORK_NAME } from "./runtime/framework";

package/src/hooks/session-banner.ts

@@ -1,4 +1,13 @@
-// Show the active Mate companion paths in Claude Code.
+// Show the active Mate companion paths in Claude Code, and repair the
+// companion's Git state before the session reads it.
+import {
+  syncCompanionUnattended,
+  unattendedSyncStalenessLines,
+  type UnattendedSyncOptions,
+} from "../runtime/companion-sync";
+import { hasLaunchEnvironment, resolveCompanionRuntime } from "../runtime/env";
+import { projectionFreshness, projectionStalenessLines } from "../runtime/freshness";
+import { mateVersion } from "../runtime/install";
 import type { HookEnv } from "./validate-artifact-path";
 
 export interface BannerOutcome {
@@ -6,20 +15,64 @@ export interface BannerOutcome {
   stdout: string;
 }
 
-// Fail-soft outside managed sessions: no MATE_* env, no banner.
-export function buildBanner(env: HookEnv): BannerOutcome {
-  const repoPath = env.MATE_REPO_PATH;
-  const artifactPath = env.MATE_ARTIFACT_PATH;
-  if (!repoPath || !artifactPath) return { exitCode: 0, stdout: "" };
+/**
+ * Marks the copy a wrap inlines into the Working Repository's settings. A
+ * managed launch loads the plugin's own copy *and* that document, and both
+ * registrations resolve to the same command against the same environment, so
+ * nothing inside the process tells them apart. The flag is what keeps the
+ * banner from printing twice in exactly the session that is configured
+ * correctly — the projected copy defers, the launch's own copy prints.
+ */
+export const PROJECTED_BANNER_FLAG = "--projected";
 
-  const mateVersion = env.MATE_VERSION || "unknown";
-  const message = `mate v${mateVersion}\n  repo:     ${repoPath}\n  mate: ${artifactPath}`;
-  return { exitCode: 0, stdout: JSON.stringify({ systemMessage: message }) + "\n" };
+/**
+ * Resolves in-process from either source — no subprocess in either branch.
+ * With `mate doctor` out of scope this is one of only two surfaces where a
+ * drifted wrap becomes visible, so staleness is reported, never suppressed.
+ */
+export function buildBanner(
+  env: HookEnv,
+  cwd: string = process.cwd(),
+  argv: readonly string[] = [],
+  syncOptions: UnattendedSyncOptions = {},
+): BannerOutcome {
+  if (argv.includes(PROJECTED_BANNER_FLAG) && hasLaunchEnvironment(env)) {
+    return { exitCode: 0, stdout: "" };
+  }
+
+  const { context, projection } = resolveCompanionRuntime(env, cwd);
+  if (!context.repositoryPath || !context.companionPath) return { exitCode: 0, stdout: "" };
+
+  /**
+   * Session start is the only moment at which the companion may move without
+   * invalidating a read the session has already taken, so the repair happens
+   * here and nowhere later. The launch-environment check comes first, so a
+   * Managed Session pays nothing at all — not the freshness read, not the
+   * policy read; and the consent gate is the operation's own.
+   */
+  const gitNotes = hasLaunchEnvironment(env)
+    ? []
+    : unattendedSyncStalenessLines(syncCompanionUnattended(context.companionPath, syncOptions));
+
+  const lines = [
+    `mate v${env.MATE_VERSION || mateVersion()}`,
+    `  repo:     ${context.repositoryPath}`,
+    `  mate: ${context.companionPath}`,
+  ];
+  if (projection) {
+    for (const note of projectionStalenessLines(projection, projectionFreshness(projection))) {
+      lines.push(`  ${note}`);
+    }
+  }
+  /** `systemMessage` only: the model must never be told to run the command. */
+  for (const note of gitNotes) lines.push(`  ${note}`);
+
+  return { exitCode: 0, stdout: JSON.stringify({ systemMessage: lines.join("\n") }) + "\n" };
 }
 
 // Plugin-shim entry.
-export function run(): number {
-  const outcome = buildBanner(process.env);
+export function run(argv: readonly string[] = process.argv.slice(2)): number {
+  const outcome = buildBanner(process.env, process.cwd(), argv);
   if (outcome.stdout) process.stdout.write(outcome.stdout);
   return outcome.exitCode;
 }

package/src/hooks/session-guidance.ts

@@ -0,0 +1,40 @@
+// Deliver the companion guidance to a Claude session Mate did not launch.
+import { buildProjectedGuidance } from "../runtime/projected-guidance";
+import type { HookEnv } from "./validate-artifact-path";
+
+export interface GuidanceOutcome {
+  exitCode: number;
+  stdout: string;
+}
+
+/**
+ * `SessionStart.additionalContext` is the file-based form of the managed
+ * launch's `--append-system-prompt`: a settings document can declare a hook,
+ * and there is no settings key for the flag. The two never both fire —
+ * `buildProjectedGuidance` yields nothing when a launch environment is present
+ * — so the plugin may carry this group alongside the projected copy.
+ *
+ * Emits nothing rather than a note when no companion resolves: an unwrapped
+ * repository must read exactly as it did before the hook existed.
+ */
+export function buildSessionGuidance(env: HookEnv, cwd: string = process.cwd()): GuidanceOutcome {
+  const guidance = buildProjectedGuidance(env, cwd);
+  if (!guidance) return { exitCode: 0, stdout: "" };
+
+  return {
+    exitCode: 0,
+    stdout: `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: guidance,
+      },
+    })}\n`,
+  };
+}
+
+// Plugin-shim entry.
+export function run(): number {
+  const outcome = buildSessionGuidance(process.env);
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  return outcome.exitCode;
+}