@rosenfan/matrix 0.1.5 → 0.1.7

package/src/project-index.js

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const projectsIndexPath = (home = os.homedir()) => path.join(home, ".matrix", "projects.json");
+
+function writeAtomically(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(temporary, file);
+}
+
+export function readProjectsIndex({ home = os.homedir() } = {}) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(projectsIndexPath(home), "utf8"));
+    if (!Array.isArray(parsed)) return { ok: false, code: "PROJECTS_INDEX_CORRUPT", projects: [] };
+    const projects = parsed.filter((entry) => entry && typeof entry.path === "string");
+    return { ok: true, projects };
+  } catch (error) {
+    if (error.code === "ENOENT") return { ok: true, projects: [] };
+    return { ok: false, code: "PROJECTS_INDEX_CORRUPT", projects: [] };
+  }
+}
+
+export function registerProject({ projectRoot, scope, platforms, language, home = os.homedir() } = {}) {
+  const resolved = path.resolve(projectRoot);
+  const { ok, projects } = readProjectsIndex({ home });
+  const next = (ok ? projects : []).filter((entry) => entry.path !== resolved);
+  next.unshift({ path: resolved, scope, platforms, language, updatedAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z") });
+  writeAtomically(projectsIndexPath(home), next);
+  return { ok: true, projects: next };
+}
+
+export function pruneProject({ projectRoot, home = os.homedir() } = {}) {
+  const resolved = path.resolve(projectRoot);
+  const { ok, projects } = readProjectsIndex({ home });
+  if (!ok) return { ok: false, removed: null };
+  const removed = projects.find((entry) => entry.path === resolved) ?? null;
+  if (!removed) return { ok: true, removed: null };
+  writeAtomically(projectsIndexPath(home), projects.filter((entry) => entry.path !== resolved));
+  return { ok: true, removed };
+}

package/src/runtime-resolver.js

@@ -1,76 +1,76 @@
-import fs from "node:fs";
-import path from "node:path";
-import { MATRIX_VERSION, PLATFORMS, hashDirectory, releaseCatalog } from "./catalog.js";
-
-function readJson(file) {
-  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
-}
-
-function installationScope(projectRoot) {
-  try {
-    const line = fs.readFileSync(path.join(projectRoot, ".matrix", "config.yaml"), "utf8").split(/\r?\n/).find((value) => value.startsWith("installation_scope:"));
-    return line?.split(":").slice(1).join(":").trim() === "global" ? "global" : "project";
-  } catch { return "project"; }
-}
-
-function runtimeCommand(runtime) {
-  const quoted = process.platform === "win32" ? `"${runtime}"` : `'${runtime.replaceAll("'", "'\\''")}'`;
-  return `node ${quoted}`;
-}
-
-export function resolveProjectRuntime({ projectRoot = process.cwd() } = {}) {
-  const root = path.resolve(projectRoot);
-  const manifest = readJson(path.join(root, ".matrix", "installation.json"));
-  if (!manifest) return installationScope(root) === "global"
-    ? { ok: true, code: "GLOBAL_INSTALLATION", runtime: null }
-    : { ok: true, code: "PROJECT_INSTALLATION_ABSENT", runtime: null };
-  const candidates = [];
-  let currentCatalog = null;
-  let catalogUnavailable = false;
-  try { currentCatalog = releaseCatalog(manifest.language ?? "en"); } catch { catalogUnavailable = true; }
-  for (const platform of ["codex", "claude-code"]) {
-    const expected = manifest.platforms?.[platform]?.skills?.matrix?.hash;
-    if (!expected) continue;
-    const matrixRoot = path.join(PLATFORMS[platform].skillRoot(root), "matrix");
-    const runtime = path.join(matrixRoot, "scripts", "matrix-runtime.mjs");
-    if (!fs.existsSync(runtime)) { candidates.push({ platform, matrixRoot, runtime, reason: "missing" }); continue; }
-    try {
-      const actual = hashDirectory(matrixRoot);
-      if (actual === expected) {
-        if (manifest.catalogVersion !== MATRIX_VERSION) {
-          const catalogVersion = manifest.catalogVersion ?? null;
-          return {
-            ok: false,
-            code: catalogVersion ? "PROJECT_RUNTIME_VERSION_MISMATCH" : "PROJECT_RUNTIME_VERSION_UNKNOWN",
-            message: catalogVersion
-              ? `The project Matrix Runtime is ${catalogVersion}, while this launcher is ${MATRIX_VERSION}. The project remains authoritative, but a different-release Runtime requires explicit invocation.`
-              : `The project Matrix Runtime has no release identity. The project remains authoritative, but an unidentified Runtime requires explicit invocation.`,
-            platform,
-            runtime,
-            catalogVersion,
-            launcherVersion: MATRIX_VERSION,
-            recovery_command: runtimeCommand(runtime)
-          };
-        }
-        if (catalogUnavailable
-          || manifest.catalogDigest !== currentCatalog.digest || expected !== currentCatalog.skills.matrix) {
-          return {
-            ok: false,
-            code: "PROJECT_RUNTIME_RELEASE_MISMATCH",
-            message: `The project Matrix Runtime claims ${MATRIX_VERSION} but does not match that release catalog. Run matrix update.`,
-            platform,
-            runtime,
-            catalogVersion: manifest.catalogVersion,
-            expected: currentCatalog?.skills.matrix ?? null,
-            actual
-          };
-        }
-        return { ok: true, code: "PROJECT_RUNTIME", platform, runtime, catalogVersion: manifest.catalogVersion };
-      }
-      candidates.push({ platform, matrixRoot, runtime, reason: "modified" });
-    } catch { candidates.push({ platform, matrixRoot, runtime, reason: "unreadable" }); }
-  }
-  return candidates.length
-    ? { ok: false, code: "PROJECT_RUNTIME_UNTRUSTED", message: "The project Matrix Runtime does not match its installation manifest.", findings: candidates }
-    : { ok: true, code: "PROJECT_RUNTIME_ABSENT", runtime: null };
-}
+import fs from "node:fs";
+import path from "node:path";
+import { MATRIX_VERSION, PLATFORMS, PLATFORM_IDS, hashDirectory, releaseCatalog } from "./catalog.js";
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+function installationScope(projectRoot) {
+  try {
+    const line = fs.readFileSync(path.join(projectRoot, ".matrix", "config.yaml"), "utf8").split(/\r?\n/).find((value) => value.startsWith("installation_scope:"));
+    return line?.split(":").slice(1).join(":").trim() === "global" ? "global" : "project";
+  } catch { return "project"; }
+}
+
+function runtimeCommand(runtime) {
+  const quoted = process.platform === "win32" ? `"${runtime}"` : `'${runtime.replaceAll("'", "'\\''")}'`;
+  return `node ${quoted}`;
+}
+
+export function resolveProjectRuntime({ projectRoot = process.cwd() } = {}) {
+  const root = path.resolve(projectRoot);
+  const manifest = readJson(path.join(root, ".matrix", "installation.json"));
+  if (!manifest) return installationScope(root) === "global"
+    ? { ok: true, code: "GLOBAL_INSTALLATION", runtime: null }
+    : { ok: true, code: "PROJECT_INSTALLATION_ABSENT", runtime: null };
+  const candidates = [];
+  let currentCatalog = null;
+  let catalogUnavailable = false;
+  try { currentCatalog = releaseCatalog(manifest.language ?? "en"); } catch { catalogUnavailable = true; }
+  for (const platform of PLATFORM_IDS) {
+    const expected = manifest.platforms?.[platform]?.skills?.matrix?.hash;
+    if (!expected) continue;
+    const matrixRoot = path.join(PLATFORMS[platform].skillRoot(root), "matrix");
+    const runtime = path.join(matrixRoot, "scripts", "matrix-runtime.mjs");
+    if (!fs.existsSync(runtime)) { candidates.push({ platform, matrixRoot, runtime, reason: "missing" }); continue; }
+    try {
+      const actual = hashDirectory(matrixRoot);
+      if (actual === expected) {
+        if (manifest.catalogVersion !== MATRIX_VERSION) {
+          const catalogVersion = manifest.catalogVersion ?? null;
+          return {
+            ok: false,
+            code: catalogVersion ? "PROJECT_RUNTIME_VERSION_MISMATCH" : "PROJECT_RUNTIME_VERSION_UNKNOWN",
+            message: catalogVersion
+              ? `The project Matrix Runtime is ${catalogVersion}, while this launcher is ${MATRIX_VERSION}. The project remains authoritative, but a different-release Runtime requires explicit invocation.`
+              : `The project Matrix Runtime has no release identity. The project remains authoritative, but an unidentified Runtime requires explicit invocation.`,
+            platform,
+            runtime,
+            catalogVersion,
+            launcherVersion: MATRIX_VERSION,
+            recovery_command: runtimeCommand(runtime)
+          };
+        }
+        if (catalogUnavailable
+          || manifest.catalogDigest !== currentCatalog.digest || expected !== currentCatalog.skills.matrix) {
+          return {
+            ok: false,
+            code: "PROJECT_RUNTIME_RELEASE_MISMATCH",
+            message: `The project Matrix Runtime claims ${MATRIX_VERSION} but does not match that release catalog. Run matrix update.`,
+            platform,
+            runtime,
+            catalogVersion: manifest.catalogVersion,
+            expected: currentCatalog?.skills.matrix ?? null,
+            actual
+          };
+        }
+        return { ok: true, code: "PROJECT_RUNTIME", platform, runtime, catalogVersion: manifest.catalogVersion };
+      }
+      candidates.push({ platform, matrixRoot, runtime, reason: "modified" });
+    } catch { candidates.push({ platform, matrixRoot, runtime, reason: "unreadable" }); }
+  }
+  return candidates.length
+    ? { ok: false, code: "PROJECT_RUNTIME_UNTRUSTED", message: "The project Matrix Runtime does not match its installation manifest.", findings: candidates }
+    : { ok: true, code: "PROJECT_RUNTIME_ABSENT", runtime: null };
+}

package/src/self-update.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { buildNpmProcessInvocation } from "./npm-invocation.js";
 
 export const PACKAGE_NAME = "@rosenfan/matrix";
 const REGISTRY = "https://registry.npmjs.org/@rosenfan%2fmatrix/latest";
@@ -30,7 +31,13 @@ export async function latestVersion(fetchImpl = fetch) {
 }
 
 function run(command, args, options = {}) {
-  const result = spawnSync(command, args, { encoding: "utf8", ...options });
+  let invocation;
+  try {
+    invocation = buildNpmProcessInvocation({ command, args });
+  } catch (error) {
+    return { ok: false, status: null, error: error.message, stdout: "", stderr: "" };
+  }
+  const result = spawnSync(invocation.executable, invocation.args, { encoding: "utf8", ...options });
   return { ok: !result.error && result.status === 0, status: result.status, error: result.error?.message, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
 }
 

package/src/ui.js

@@ -1,89 +1,97 @@
-import readline from "node:readline";
-import { stdin, stdout } from "node:process";
-
-const codes = { cyan: "\u001b[96m", blue: "\u001b[94m", green: "\u001b[92m", yellow: "\u001b[93m", magenta: "\u001b[95m", dim: "\u001b[2m", reset: "\u001b[0m" };
-const pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-const logo = String.raw`███╗   ███╗ █████╗ ████████╗██████╗ ██╗██╗  ██╗
-████╗ ████║██╔══██╗╚══██╔══╝██╔══██╗██║╚██╗██╔╝
-██╔████╔██║███████║   ██║   ██████╔╝██║ ╚███╔╝
-██║╚██╔╝██║██╔══██║   ██║   ██╔══██╗██║ ██╔██╗
-██║ ╚═╝ ██║██║  ██║   ██║   ██║  ██║██║██╔╝ ██╗
-╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝`;
-const bannerLines = 9;
-
-function cancelled() {
-  const error = new Error("Cancelled.");
-  error.code = "CANCELLED";
-  return error;
-}
-
-export function createUi({ color = stdout.isTTY, animate = true } = {}) {
-  const paint = (name, value) => color ? `${codes[name]}${value}${codes.reset}` : value;
-  const shouldAnimate = animate && color && stdout.isTTY;
-  const writeFrame = (stage, status, clearPrevious = false) => {
-    if (clearPrevious) stdout.write(`\u001b[${bannerLines}A`);
-    stdout.write("\u001b[2K" + paint("green", `[ MATRIX BOOT // ${status} ]`) + "\n");
-    for (const line of logo.split("\n")) {
-      const reveal = Math.floor(line.length * stage);
-      const stable = line.slice(0, reveal);
-      const interference = stage === 1 ? "" : "#@%/\\|~".repeat(Math.ceil((line.length - reveal) / 7)).slice(0, line.length - reveal);
-      stdout.write("\u001b[2K" + paint(stage < 0.7 ? "green" : "cyan", stable + interference) + "\n");
-    }
-    stdout.write("\u001b[2K" + paint("yellow", `    ${Math.round(stage * 100)}%  ${status}`) + "\n\n");
-  };
-  return {
-    async banner() {
-      if (shouldAnimate) {
-        const sequence = [
-          [0.04, "SIGNAL LOST", 260],
-          [0.28, "MAGNETIC INTERFERENCE", 320],
-          [0.62, "NEURAL LINK FORMING", 360],
-          [1, "SIGNAL LOCKED", 420]
-        ];
-        stdout.write("\u001b[?25l");
-        try {
-          for (let index = 0; index < sequence.length; index += 1) {
-            const [stage, status, duration] = sequence[index];
-            writeFrame(stage, status, index > 0);
-            await pause(duration);
-          }
-        } finally {
-          stdout.write("\u001b[?25h");
-        }
-        stdout.write(`\u001b[${bannerLines}A`);
-      }
-      console.log(paint("cyan", logo));
-      console.log(paint("yellow", "Evidence-driven workflow with Prim and Arch orchestration"));
-      console.log();
-    },
-    info(message) { console.log(`${paint("blue", "> ")} ${message}`); },
-    success(message) { console.log(`${paint("green", "OK")} ${message}`); },
-    warn(message) { console.log(`${paint("yellow", "!")} ${message}`); },
-    muted(message) { console.log(paint("dim", message)); },
-    async select(question, choices, initial = 0) {
-      if (!stdin.isTTY || !stdout.isTTY) return choices[initial].value;
-      let selected = initial;
-      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
-      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); stdout.write(`${index === selected ? paint("blue", ">") : " "} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
-      render();
-      return new Promise((resolve, reject) => {
-        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
-        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "return") { cleanup(); resolve(choices[selected].value); } };
-        stdin.on("keypress", onKeypress);
-      });
-    },
-    async selectMany(question, choices) {
-      if (!stdin.isTTY || !stdout.isTTY) return choices.map((choice) => choice.value);
-      let selected = 0; const checked = new Set(choices.map((choice) => choice.value));
-      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
-      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); const marker = checked.has(choice.value) ? "[x]" : "[ ]"; stdout.write(`${index === selected ? paint("blue", ">") : " "} ${marker} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
-      render();
-      return new Promise((resolve, reject) => {
-        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
-        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "space") { const value = choices[selected].value; checked.has(value) ? checked.delete(value) : checked.add(value); render(true); } else if (key.name === "return") { cleanup(); resolve(choices.filter((choice) => checked.has(choice.value)).map((choice) => choice.value)); } };
-        stdin.on("keypress", onKeypress);
-      });
-    },
-    async confirm(question, defaultValue = true, labels = { yes: "Yes", no: "No" }) { return this.select(question, [{ label: defaultValue ? labels.yes : labels.no, value: defaultValue }, { label: defaultValue ? labels.no : labels.yes, value: !defaultValue }]); }
-  };
-}
+import readline from "node:readline";
+import { stdin, stdout } from "node:process";
+
+const codes = { cyan: "\u001b[96m", blue: "\u001b[94m", green: "\u001b[92m", yellow: "\u001b[93m", magenta: "\u001b[95m", dim: "\u001b[2m", reset: "\u001b[0m" };
+const pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const logo = String.raw`███╗   ███╗ █████╗ ████████╗██████╗ ██╗██╗  ██╗
+████╗ ████║██╔══██╗╚══██╔══╝██╔══██╗██║╚██╗██╔╝
+██╔████╔██║███████║   ██║   ██████╔╝██║ ╚███╔╝
+██║╚██╔╝██║██╔══██║   ██║   ██╔══██╗██║ ██╔██╗
+██║ ╚═╝ ██║██║  ██║   ██║   ██║  ██║██║██╔╝ ██╗
+╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝`;
+const bannerLines = 9;
+
+function cancelled() {
+  const error = new Error("Cancelled.");
+  error.code = "CANCELLED";
+  return error;
+}
+
+export function createUi({ color = stdout.isTTY, animate = true } = {}) {
+  const paint = (name, value) => color ? `${codes[name]}${value}${codes.reset}` : value;
+  const shouldAnimate = animate && color && stdout.isTTY;
+  const writeFrame = (stage, status, clearPrevious = false) => {
+    if (clearPrevious) stdout.write(`\u001b[${bannerLines}A`);
+    stdout.write("\u001b[2K" + paint("green", `[ MATRIX BOOT // ${status} ]`) + "\n");
+    for (const line of logo.split("\n")) {
+      const reveal = Math.floor(line.length * stage);
+      const stable = line.slice(0, reveal);
+      const interference = stage === 1 ? "" : "#@%/\\|~".repeat(Math.ceil((line.length - reveal) / 7)).slice(0, line.length - reveal);
+      stdout.write("\u001b[2K" + paint(stage < 0.7 ? "green" : "cyan", stable + interference) + "\n");
+    }
+    stdout.write("\u001b[2K" + paint("yellow", `    ${Math.round(stage * 100)}%  ${status}`) + "\n\n");
+  };
+  return {
+    async banner() {
+      if (shouldAnimate) {
+        const sequence = [
+          [0.04, "SIGNAL LOST", 260],
+          [0.28, "MAGNETIC INTERFERENCE", 320],
+          [0.62, "NEURAL LINK FORMING", 360],
+          [1, "SIGNAL LOCKED", 420]
+        ];
+        stdout.write("\u001b[?25l");
+        try {
+          for (let index = 0; index < sequence.length; index += 1) {
+            const [stage, status, duration] = sequence[index];
+            writeFrame(stage, status, index > 0);
+            await pause(duration);
+          }
+        } finally {
+          stdout.write("\u001b[?25h");
+        }
+        stdout.write(`\u001b[${bannerLines}A`);
+      }
+      console.log(paint("cyan", logo));
+      console.log(paint("yellow", "Evidence-driven workflow with Prim and Arch orchestration"));
+      console.log();
+    },
+    info(message) { console.log(`${paint("blue", "> ")} ${message}`); },
+    success(message) { console.log(`${paint("green", "OK")} ${message}`); },
+    warn(message) { console.log(`${paint("yellow", "!")} ${message}`); },
+    muted(message) { console.log(paint("dim", message)); },
+    async select(question, choices, initial = 0) {
+      if (!stdin.isTTY || !stdout.isTTY) return choices[initial].value;
+      let selected = initial;
+      let renderedLines = 0;
+      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
+      const render = (clear = false) => {
+        if (clear) stdout.write(`\u001b[${renderedLines}A`);
+        renderedLines = 0;
+        choices.forEach((choice, index) => {
+          stdout.write("\u001b[2K"); stdout.write(`${index === selected ? paint("blue", ">") : " "} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); renderedLines += 1;
+          if (choice.detail) { stdout.write("\u001b[2K"); stdout.write(`  ${paint("dim", choice.detail)}\n`); renderedLines += 1; }
+        });
+      };
+      render();
+      return new Promise((resolve, reject) => {
+        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
+        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "return") { cleanup(); resolve(choices[selected].value); } };
+        stdin.on("keypress", onKeypress);
+      });
+    },
+    async selectMany(question, choices) {
+      if (!stdin.isTTY || !stdout.isTTY) return choices.map((choice) => choice.value);
+      let selected = 0; const checked = new Set(choices.map((choice) => choice.value));
+      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
+      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); const marker = checked.has(choice.value) ? "[x]" : "[ ]"; stdout.write(`${index === selected ? paint("blue", ">") : " "} ${marker} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
+      render();
+      return new Promise((resolve, reject) => {
+        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
+        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "space") { const value = choices[selected].value; checked.has(value) ? checked.delete(value) : checked.add(value); render(true); } else if (key.name === "return") { cleanup(); resolve(choices.filter((choice) => checked.has(choice.value)).map((choice) => choice.value)); } };
+        stdin.on("keypress", onKeypress);
+      });
+    },
+    async confirm(question, defaultValue = true, labels = { yes: "Yes", no: "No" }) { return this.select(question, [{ label: defaultValue ? labels.yes : labels.no, value: defaultValue }, { label: defaultValue ? labels.no : labels.yes, value: !defaultValue }]); }
+  };
+}

package/src/workflow.js

@@ -49,6 +49,13 @@ const LEGACY_ARCH_SKILLS = [
   "grilling", "domain-modeling", "research", "wayfinder", "prototype",
   "codebase-design", "tdd", "diagnosing-bugs", "resolving-merge-conflicts", "code-review"
 ];
+// The bundled runtime is injected without catalog.js, so this platform→skill-root
+// mapping mirrors catalog.js PLATFORMS and is pinned by a parity test.
+export const PLATFORM_SKILL_ROOTS = Object.freeze({
+  "claude-code": ".claude/skills",
+  codex: ".agents/skills",
+  zcode: ".zcode/skills"
+});
 const ARTIFACT_POLICY = {
   proposal: ["## Goal", "## Scope", "## Non-goals", "## Acceptance", "## Risks"],
   design: ["## Decisions", "## Boundaries", "## Test seams", "## Risks"],
@@ -249,9 +256,11 @@ function archIntegrity(cwd, flow = null, contentHashes = MATT_CONTENT_HASHES) {
   }
   const findings = [];
   for (const [platform, record] of platforms) {
+    const relativeRoot = PLATFORM_SKILL_ROOTS[platform];
     for (const skill of legacy ? LEGACY_ARCH_SKILLS : MATT_AUTOMATIC_SKILLS) {
+      if (!relativeRoot) { findings.push({ platform, skill, reason: "unsupported" }); continue; }
       const installed = legacy ? record?.matt?.skills?.[skill] : mattReceipt?.platforms?.[platform]?.skills?.[skill];
-      const expectedRoot = path.join(cwd, platform === "codex" ? ".agents" : ".claude", "skills", skill);
+      const expectedRoot = path.join(cwd, relativeRoot, skill);
       const target = legacy ? installed?.root : expectedRoot;
       if (!legacy && installed?.root && path.resolve(installed.root) !== path.resolve(expectedRoot)) {
         findings.push({ platform, skill, reason: "non-project" });
@@ -272,8 +281,12 @@ function archIntegrity(cwd, flow = null, contentHashes = MATT_CONTENT_HASHES) {
     manifest: legacy ? manifestFile : mattReceiptFile, findings, recovery_command: "matrix init --with-mattpocock"
   } : { ok: true, code: "OK", manifest: legacy ? manifestFile : mattReceiptFile, platforms: platforms.map(([platform]) => platform), cohort: legacy ? "legacy-v0.1.3" : MATT_CATALOG_DIGEST, matt_release: legacy ? null : MATT_COMPATIBILITY.release };
 }
-function taskContent(change, taskId, proposal, design, plan, resultPath, contractHash, approvalRevision) {
-  return `# Claude Code task: ${taskId}\n\n## Metadata\n\n| Field | Value |\n| --- | --- |\n| Status | CLAUDE_QUEUED |\n| Matrix change | ${change} |\n| Decision owner | Codex |\n| Implementation actor | Claude Code |\n| Approved contract | ${contractHash} |\n| Approval revision | ${approvalRevision} |\n| Result | ${resultPath} |\n\n## Objective\n\nThe frozen Matrix artifacts below are authoritative. Do not expand their scope.\n\n## Proposal\n\n${proposal}\n\n## Frozen design\n\n${design}\n\n## Ordered plan\n\n${plan}\n\n## Allowed work\n\n- Read repository instructions and existing tests before implementing.\n- Change only files required by the frozen design and plan.\n\n## Prohibited work\n\n- Do not edit Matrix state, transition its phase, archive it, or alter the frozen design.\n- Do not add unrelated features, public APIs, dependencies, or external side effects.\n- Do not claim completion without recording verifiable evidence.\n\n## Stop and report\n\nStop with \`NEEDS_DECISION\` if the scope must expand, the design conflicts with the repository, validation cannot pass within scope, or an authorization/safety issue arises.\n\n## Required result\n\nCreate \`${resultPath}\` with metadata, changed files and reasons, commands and outcomes, test results, boundary confirmation, residual risks, and any \`NEEDS_DECISION\` items. Codex reviews the result and the actual diff.\n`;
+function taskContent(change, taskId, proposal, design, plan, resultPath, contractHash, approvalRevision, actor = {}) {
+  const agent = actor.agent ?? "Claude Code";
+  const owner = actor.owner ?? "Codex";
+  const statusToken = actor.statusToken ?? "CLAUDE_QUEUED";
+  const reviewer = actor.reviewer ?? "Codex";
+  return `# ${agent} task: ${taskId}\n\n## Metadata\n\n| Field | Value |\n| --- | --- |\n| Status | ${statusToken} |\n| Matrix change | ${change} |\n| Decision owner | ${owner} |\n| Implementation actor | ${agent} |\n| Approved contract | ${contractHash} |\n| Approval revision | ${approvalRevision} |\n| Result | ${resultPath} |\n\n## Objective\n\nThe frozen Matrix artifacts below are authoritative. Do not expand their scope.\n\n## Proposal\n\n${proposal}\n\n## Frozen design\n\n${design}\n\n## Ordered plan\n\n${plan}\n\n## Allowed work\n\n- Read repository instructions and existing tests before implementing.\n- Change only files required by the frozen design and plan.\n\n## Prohibited work\n\n- Do not edit Matrix state, transition its phase, archive it, or alter the frozen design.\n- Do not add unrelated features, public APIs, dependencies, or external side effects.\n- Do not claim completion without recording verifiable evidence.\n\n## Stop and report\n\nStop with \`NEEDS_DECISION\` if the scope must expand, the design conflicts with the repository, validation cannot pass within scope, or an authorization/safety issue arises.\n\n## Required result\n\nCreate \`${resultPath}\` with metadata, changed files and reasons, commands and outcomes, test results, boundary confirmation, residual risks, and any \`NEEDS_DECISION\` items. ${reviewer} reviews the result and the actual diff.\n`;
 }
 function activeBoard(taskId, taskPath, resultPath, change) {
   return `# Active task board\n\n## Current objective\n\n| Field | Value |\n| --- | --- |\n| ID | ${taskId} |\n| Status | CLAUDE_QUEUED |\n| Matrix change | ${change} |\n| Task | ${taskPath} |\n| Result | ${resultPath} |\n`;
@@ -381,7 +394,7 @@ function managedReviewPrefixes(cwd) {
   const { manifest, mattReceipt } = orchestrationConfig(cwd);
   const prefixes = [];
   for (const [platform, record] of Object.entries(manifest?.platforms ?? {})) {
-    const root = platform === "codex" ? ".agents/skills" : platform === "claude-code" ? ".claude/skills" : null;
+    const root = PLATFORM_SKILL_ROOTS[platform];
     if (!root) continue;
     for (const skill of Object.keys(record?.skills ?? {})) prefixes.push(`${root}/${skill}`);
     for (const skill of Object.keys(mattReceipt?.platforms?.[platform]?.skills ?? {})) prefixes.push(`${root}/${skill}`);
@@ -1030,10 +1043,29 @@ export function invoke(argv, { cwd = process.cwd(), failAfterOperation = null, m
     if (workflowProfile(p, flow).id === "lightweight") return fail("EXPORT_UNSUPPORTED_WORKFLOW", "Claude export requires the full three-artifact workflow contract.");
     const contract = contractState(p, flow); const failure = contractFailure(flow, contract); if (failure) return failure;
     const taskId = args.includes("--task-id") ? args[args.indexOf("--task-id") + 1] : args[0];
+    const agent = args.includes("--agent") ? args[args.indexOf("--agent") + 1] : null;
+    const from = args.includes("--from") ? args[args.indexOf("--from") + 1] : null;
+    if (agent && args.includes("--target")) return fail("INVALID_INTENT", "export --agent and --target are mutually exclusive.");
+    if (agent && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent)) return fail("INVALID_INTENT", "export --agent requires a kebab-case agent identifier.");
+    if (from && !agent) return fail("INVALID_INTENT", "export --from requires --agent.");
+    if (from && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(from)) return fail("INVALID_INTENT", "export --from requires a kebab-case agent identifier.");
+    if (agent && (!args.includes("--task-id") || !/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(taskId ?? ""))) return fail("INVALID_INTENT", "export --agent requires --task-id.");
     const target = args.includes("--target") ? args[args.indexOf("--target") + 1] : "generic";
     const applyBoard = args.includes("--apply-fnsec-board");
     if (!/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(taskId ?? "") || !["generic", "fnsec"].includes(target)) return fail("INVALID_INTENT", "export requires a task id and target generic or fnsec.");
     const { proposal, design, plan } = contract.snapshot.contents;
+    if (agent) {
+      const destination = path.join(p.artifacts, `handoff-task-${taskId}.md`);
+      const result = path.join(p.artifacts, `handoff-result-${taskId}.md`);
+      const content = taskContent(id, taskId, proposal, design, plan, path.relative(cwd, result).replaceAll("\\", "/"), flow.approved_contract_hash, flow.contract_approved_revision, {
+        agent,
+        owner: from ?? "Matrix change owner",
+        statusToken: `${agent.replaceAll("-", "_").toUpperCase()}_QUEUED`,
+        reviewer: from ?? "Matrix change owner"
+      });
+      fs.writeFileSync(destination, content);
+      return { ok: true, code: "OK", path: destination };
+    }
     if (target === "generic") {
       const destination = path.join(p.artifacts, "claude-task.md"); const result = path.join(p.artifacts, "claude-result.md");
       fs.writeFileSync(destination, taskContent(id, taskId, proposal, design, plan, path.relative(cwd, result).replaceAll("\\", "/"), flow.approved_contract_hash, flow.contract_approved_revision));

package/assets/skills/matrix-claude/SKILL.md

@@ -1,98 +0,0 @@
----
-name: matrix-claude
-description: Export a frozen Matrix design as a bounded Claude Code task package without changing Matrix workflow state. Use when Codex should design and Claude Code should implement.
----
-
-# Matrix Claude Handoff
-
-This is an optional Matrix sidecar, not a Matrix phase. It must not call `transition`, `archive`, or write `matrix.yaml` or `events.jsonl`. It supports only a matching full or legacy-full three-artifact Contract; new lightweight hotfix/tweak changes are intentionally unsupported.
-
-Use `artifact_language` from inspect for human-readable handoff text while retaining the stable machine-readable headings and metadata keys.
-
-## When to Use
-
-Use `$matrix-claude` when:
-- The active change is in Build and the Design -> Build transition has approved the contract
-- You want Claude Code (instead of Codex) to implement the design
-- You need a bounded task package with all implementation details
-
-## Preconditions
-
-The exporter performs this read-only check before writing anything:
-
-```powershell
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
-```
-
-If `matrix` is genuinely absent from PATH, use the bundled runtime from the installed root Matrix Skill. Do not fall back when the primary command starts and returns an error.
-
-If the build guard reports `CONTRACT_CHANGED` or `CONTRACT_UNAPPROVED`, return to `$matrix-design` and approve a new contract through Build. The exporter reads the approved bytes of `proposal.md`, `design.md`, and `plan.md`; it does not invent missing facts.
-
-## Export
-
-Treat explicit invocation of `$matrix-claude` as the user's choice of Claude Code as the implementation actor. Generate the package with the deterministic exporter; it refuses a non-matching approved contract and does not alter Matrix state.
-
-```powershell
-# Generic project: only exports a Matrix artifact.
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target generic
-
-# FnSec: exports its formal task package. Add --apply-fnsec-board only when
-# active.md is NO_ACTIVE_OBJECTIVE; an existing task is never overwritten.
-node <matrix-skill-directory>/scripts/matrix-runtime.mjs export --task-id <ID> --target fnsec --apply-fnsec-board
-```
-
-## Task Package Contents
-
-The exported package (`artifacts/claude-task.md`) contains everything Claude Code needs to implement and produce evidence for `$matrix-verify`:
-
-1. **Task ID, execution actor, and approved contract hash**: Claude Code and the exact approved snapshot
-2. **Objective and acceptance criteria** — copied from `proposal.md`
-3. **In-scope and out-of-scope boundaries** — from `proposal.md`
-4. **Frozen design decisions** — from `design.md` (Decisions, Boundaries, Test seams)
-5. **Ordered implementation plan** — from `plan.md` (Steps, Validation)
-6. **Allowed and prohibited files/actions** — to prevent scope creep
-7. **Required commands** — test, lint, typecheck, build commands to run
-8. **Stop conditions** — ambiguity, scope expansion, failing acceptance, design conflict
-9. **Required evidence for verify**:
-   - Changed files list
-   - Commands and their outputs
-   - Test results (pass/fail)
-   - Build evidence
-   - Residual risks
-   - `NEEDS_DECISION` items (if any)
-
-## After Claude Code Completes
-
-When Claude Code returns results, verify that the following evidence is present before proceeding to `$matrix-verify`:
-
-- [ ] `artifacts/verification.md` exists with `## Build evidence` section
-- [ ] Build evidence includes concrete commands and outcomes
-- [ ] All tests in the plan's validation section have been run
-- [ ] Any `NEEDS_DECISION` items have been resolved or documented
-
-If evidence is missing, ask Claude Code to补充 before proceeding.
-
-## Resuming Matrix Workflow
-
-After Claude Code completes and evidence is present:
-
-1. Run build guard to verify evidence:
-   ```powershell
-   node <matrix-skill-directory>/scripts/matrix-runtime.mjs guard build
-   ```
-
-2. If guard passes, transition to verify:
-   ```powershell
-   node <matrix-skill-directory>/scripts/matrix-runtime.mjs transition verify
-   ```
-
-3. Enter `$matrix-verify` to继续验证流程
-
-If the build guard fails, return to Claude Code to补充 missing evidence.
-
-## Important Notes
-
-- This sidecar does NOT change Matrix phase, workflow, or guard result
-- The Matrix state remains in `build` phase; export itself does not advance it
-- Claude Code must produce evidence that satisfies the build guard conditions
-- After successful transition to verify, the normal verify流程 continues

package/assets/skills/matrix-claude/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Matrix Claude Handoff"
-  short_description: "Export frozen Matrix design as a Claude Code task"
-  default_prompt: "Use $matrix-claude to prepare a Claude Code task package."