halfcycle 0.4.5 → 0.4.6

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // dist/bin.js
-import { existsSync as existsSync7, readFileSync as readFileSync11, realpathSync as realpathSync3, statSync, writeSync as writeSync2 } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync13, realpathSync as realpathSync4, statSync, writeSync as writeSync2 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join12 } from "node:path";
+import { join as join14 } from "node:path";
 
 // dist/install.js
 import { execFileSync as execFileSync2 } from "node:child_process";
@@ -1307,6 +1307,349 @@ var phaseRecordResponseSchema = z12.discriminatedUnion("outcome", [
   phaseRecordRefusedSchema
 ]);
 
+// ../events/dist/system-description.js
+import { z as z13 } from "zod";
+var SYSTEM_DESCRIPTION_FORMAT = 1;
+var SYSTEM_PARTS_MAX = 60;
+var SYSTEM_CONNECTIONS_MAX = 400;
+var SYSTEM_SLOT_MAX = 11;
+var SYSTEM_OWNS_MAX = 20;
+var SYSTEM_OWNED_PATTERN_MAX = 200;
+var SYSTEM_PART_NAME_MAX = 60;
+var SYSTEM_PART_DESCRIPTION_MAX = 160;
+var SYSTEM_CONNECTION_LABEL_MAX = 60;
+var SYSTEM_PART_ID_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+var SYSTEM_LANES = ["clients", "edge", "services", "data", "external"];
+var systemLaneSchema = z13.enum(SYSTEM_LANES, {
+  error: `must be one of ${SYSTEM_LANES.join(", ")}`
+});
+var SYSTEM_CONNECTION_KINDS = ["call", "event", "write", "external"];
+var systemConnectionKindSchema = z13.enum(SYSTEM_CONNECTION_KINDS, {
+  error: `must be one of ${SYSTEM_CONNECTION_KINDS.join(", ")}`
+});
+var LINE_SEPARATOR = /[\u2028\u2029]/;
+function descriptionText(max) {
+  return statementText(max).refine((v) => v.trim().length > 0, { message: "must not be empty or only spaces" }).refine((v) => !LINE_SEPARATOR.test(v), {
+    message: "must be one line: it holds a line or paragraph separator"
+  });
+}
+var systemPartIdSchema = z13.string().regex(SYSTEM_PART_ID_PATTERN, {
+  message: "must be a short id: a lowercase letter, then lowercase letters, digits or hyphens, 40 characters at most"
+}).refine((v) => !looksLikeSecret(v), { message: "looks like a password or key; choose another id" });
+function hasEmptySegment(pattern) {
+  return pattern.split("/").some((segment) => segment.length === 0);
+}
+function hasDotSegment(pattern) {
+  return pattern.split("/").some((segment) => segment === "." || segment === "..");
+}
+function hasPartialDoubleStar(pattern) {
+  return pattern.split("/").some((segment) => segment.includes("**") && segment !== "**");
+}
+var SEGMENT_CHARACTERS = /^[A-Za-z0-9._\-*]*$/;
+function hasForeignCharacter(pattern) {
+  return pattern.split("/").some((segment) => !SEGMENT_CHARACTERS.test(segment));
+}
+var systemOwnedPatternSchema = z13.string().max(SYSTEM_OWNED_PATTERN_MAX, { message: `must be at most ${SYSTEM_OWNED_PATTERN_MAX} characters` }).refine((v) => !hasEmptySegment(v), {
+  message: "must not start or end with a slash, or have two slashes together"
+}).refine((v) => !hasDotSegment(v), { message: 'must not have a "." or ".." folder in it' }).refine((v) => !hasPartialDoubleStar(v), { message: '"**" must stand alone between slashes' }).refine((v) => !hasForeignCharacter(v), {
+  message: 'may use only letters, digits, ".", "_", "-" and "*" between slashes'
+}).refine((v) => !looksLikeSecret(v), {
+  message: "this path looks like a credential; list a shorter folder above it"
+});
+var systemPartSchema = z13.object({
+  id: systemPartIdSchema,
+  name: descriptionText(SYSTEM_PART_NAME_MAX),
+  description: descriptionText(SYSTEM_PART_DESCRIPTION_MAX),
+  lane: systemLaneSchema,
+  slot: z13.number({ error: `must be a whole number from 0 to ${SYSTEM_SLOT_MAX}` }).int({ error: `must be a whole number from 0 to ${SYSTEM_SLOT_MAX}` }).min(0, { error: `must be a whole number from 0 to ${SYSTEM_SLOT_MAX}` }).max(SYSTEM_SLOT_MAX, { error: `must be a whole number from 0 to ${SYSTEM_SLOT_MAX}` }),
+  outside: z13.boolean(),
+  owns: z13.array(systemOwnedPatternSchema).max(SYSTEM_OWNS_MAX, { message: `can list at most ${SYSTEM_OWNS_MAX} paths` })
+}).strict();
+var systemConnectionSchema = z13.object({
+  from: systemPartIdSchema,
+  to: systemPartIdSchema,
+  kind: systemConnectionKindSchema,
+  label: descriptionText(SYSTEM_CONNECTION_LABEL_MAX)
+}).strict();
+var systemDescriptionSchema = z13.object({
+  format: z13.literal(SYSTEM_DESCRIPTION_FORMAT, { error: `must be ${SYSTEM_DESCRIPTION_FORMAT}` }),
+  parts: z13.array(systemPartSchema).min(1, { message: "must list at least one part" }).max(SYSTEM_PARTS_MAX, { message: `can hold at most ${SYSTEM_PARTS_MAX} parts (five lanes of twelve slots)` }),
+  connections: z13.array(systemConnectionSchema).max(SYSTEM_CONNECTIONS_MAX, { message: `can hold at most ${SYSTEM_CONNECTIONS_MAX} connections` })
+}).strict();
+var systemDescriptionProblemSchema = z13.object({
+  path: z13.string(),
+  message: z13.string()
+}).strict();
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dotted(path) {
+  return path.map((key) => String(key)).join(".");
+}
+function isMissingKey(raw, path) {
+  if (path.length === 0)
+    return false;
+  let parent = raw;
+  for (const key of path.slice(0, -1)) {
+    if (!isRecord(parent) && !Array.isArray(parent))
+      return false;
+    parent = parent[key];
+  }
+  return isRecord(parent) && !(String(path[path.length - 1]) in parent);
+}
+function shapeProblems(raw) {
+  const parsed = systemDescriptionSchema.safeParse(raw);
+  if (parsed.success)
+    return [];
+  const problems = [];
+  for (const issue of parsed.error.issues) {
+    if (issue.code === "unrecognized_keys") {
+      for (const key of issue.keys) {
+        problems.push({ path: dotted([...issue.path, key]), message: "is not a field a description has" });
+      }
+    } else if (isMissingKey(raw, issue.path)) {
+      problems.push({ path: dotted(issue.path), message: "is required" });
+    } else {
+      problems.push({ path: dotted(issue.path), message: issue.message });
+    }
+  }
+  return problems;
+}
+function shown(value) {
+  return looksLikeSecret(value) ? "a value that looks like a credential" : `"${value}"`;
+}
+function quoted(value) {
+  return typeof value === "string" ? shown(value) : "another part";
+}
+function crossFieldProblems(raw) {
+  const problems = [];
+  if (!isRecord(raw))
+    return problems;
+  const parts = Array.isArray(raw.parts) ? raw.parts : [];
+  const connections = Array.isArray(raw.connections) ? raw.connections : [];
+  const ids = /* @__PURE__ */ new Set();
+  const placed = /* @__PURE__ */ new Map();
+  const owners = /* @__PURE__ */ new Map();
+  parts.forEach((part, i) => {
+    if (!isRecord(part))
+      return;
+    if (typeof part.id === "string") {
+      if (ids.has(part.id)) {
+        problems.push({ path: `parts.${i}.id`, message: `another part already has the id ${shown(part.id)}` });
+      }
+      ids.add(part.id);
+    }
+    if (typeof part.lane === "string" && typeof part.slot === "number") {
+      const place = `${part.lane}\0${part.slot}`;
+      const earlier = placed.get(place);
+      if (earlier !== void 0) {
+        problems.push({
+          path: `parts.${i}.slot`,
+          message: `${quoted(parts[earlier].id)} already sits in lane ${shown(part.lane)} at slot ${part.slot}`
+        });
+      } else {
+        placed.set(place, i);
+      }
+    }
+    if (typeof part.outside === "boolean" && Array.isArray(part.owns)) {
+      if (part.outside && part.owns.length > 0) {
+        problems.push({ path: `parts.${i}.owns`, message: "must be empty for a part outside the repository" });
+      }
+      if (!part.outside && part.owns.length === 0) {
+        problems.push({ path: `parts.${i}.owns`, message: "must list at least one path this part owns" });
+      }
+    }
+    if (Array.isArray(part.owns)) {
+      part.owns.forEach((pattern, k) => {
+        if (typeof pattern !== "string")
+          return;
+        const owner = owners.get(pattern);
+        if (owner === void 0) {
+          owners.set(pattern, i);
+        } else if (owner === i) {
+          problems.push({ path: `parts.${i}.owns.${k}`, message: `${shown(pattern)} is listed twice in this part` });
+        } else {
+          problems.push({
+            path: `parts.${i}.owns.${k}`,
+            message: `${shown(pattern)} is already owned by ${quoted(parts[owner].id)}`
+          });
+        }
+      });
+    }
+  });
+  const pairs = /* @__PURE__ */ new Set();
+  connections.forEach((connection, i) => {
+    if (!isRecord(connection))
+      return;
+    const { from, to } = connection;
+    if (typeof from === "string" && !ids.has(from)) {
+      problems.push({ path: `connections.${i}.from`, message: `names no part: ${shown(from)}` });
+    }
+    if (typeof to === "string" && !ids.has(to)) {
+      problems.push({ path: `connections.${i}.to`, message: `names no part: ${shown(to)}` });
+    }
+    if (typeof from === "string" && typeof to === "string") {
+      if (from === to) {
+        problems.push({ path: `connections.${i}.to`, message: `must name a different part from "from" (${shown(from)})` });
+      }
+      const pair = `${from}\0${to}`;
+      if (pairs.has(pair)) {
+        problems.push({ path: `connections.${i}`, message: `another connection already goes from ${shown(from)} to ${shown(to)}` });
+      }
+      pairs.add(pair);
+    }
+  });
+  return problems;
+}
+function checkSystemDescription(value) {
+  const problems = [...shapeProblems(value), ...crossFieldProblems(value)];
+  if (problems.length > 0)
+    return { ok: false, problems };
+  return { ok: true, description: systemDescriptionSchema.parse(value) };
+}
+function segmentMatches(pattern, segment) {
+  const literals = pattern.split("*");
+  if (literals.length === 1)
+    return pattern === segment;
+  const first = literals[0];
+  const last = literals[literals.length - 1];
+  if (!segment.startsWith(first))
+    return false;
+  let position = first.length;
+  for (const literal of literals.slice(1, -1)) {
+    const found = segment.indexOf(literal, position + 1);
+    if (found === -1)
+      return false;
+    position = found + literal.length;
+  }
+  return segment.length - last.length >= position + 1 && segment.endsWith(last);
+}
+function patternOwns(pattern, path) {
+  const want = pattern.split("/");
+  const have = path.split("/");
+  const width = have.length + 1;
+  const seen = new Uint8Array((want.length + 1) * width);
+  const from = (i, j) => {
+    if (i === want.length)
+      return true;
+    const cell = i * width + j;
+    if (seen[cell] !== 0)
+      return seen[cell] === 2;
+    const segment = want[i];
+    const result = segment === "**" ? from(i + 1, j) || j < have.length && from(i, j + 1) : j < have.length && segmentMatches(segment, have[j]) && from(i + 1, j + 1);
+    seen[cell] = result ? 2 : 1;
+    return result;
+  };
+  return from(0, 0);
+}
+function specificity(pattern) {
+  const segments = pattern.split("/");
+  const firstWildcard = segments.findIndex((segment) => segment.includes("*"));
+  return {
+    leadingLiterals: firstWildcard === -1 ? segments.length : firstWildcard,
+    wildcards: segments.filter((segment) => segment.includes("*")).length,
+    literalCharacters: pattern.replace(/[*/]/g, "").length
+  };
+}
+function outranks(a, b) {
+  if (a.rank.leadingLiterals !== b.rank.leadingLiterals)
+    return b.rank.leadingLiterals - a.rank.leadingLiterals;
+  if (a.rank.wildcards !== b.rank.wildcards)
+    return a.rank.wildcards - b.rank.wildcards;
+  if (a.rank.literalCharacters !== b.rank.literalCharacters)
+    return b.rank.literalCharacters - a.rank.literalCharacters;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function ownerOf(path, description) {
+  let best = null;
+  for (const part of description.parts) {
+    for (const pattern of part.owns) {
+      if (!patternOwns(pattern, path))
+        continue;
+      const candidate = { id: part.id, rank: specificity(pattern) };
+      if (best === null || outranks(candidate, best) < 0)
+        best = candidate;
+    }
+  }
+  return best === null ? null : best.id;
+}
+var systemReportRecordedSchema = z13.object({
+  outcome: z13.literal("recorded"),
+  version: z13.number().int().min(1),
+  reportedAt: utcIso8601
+}).strict();
+var systemReportRefusedSchema = z13.object({
+  outcome: z13.literal("refused"),
+  problems: z13.array(systemDescriptionProblemSchema).min(1)
+}).strict();
+var systemReportUnavailableSchema = z13.object({
+  outcome: z13.literal("unavailable")
+}).strict();
+var systemReportResultSchema = z13.discriminatedUnion("outcome", [
+  systemReportRecordedSchema,
+  systemReportRefusedSchema,
+  systemReportUnavailableSchema
+]);
+var SYSTEM_DRAW_SVG_MAX_BYTES = 2 * 1024 * 1024;
+var SYSTEM_DRAW_MERMAID_MAX_BYTES = 256 * 1024;
+var SYSTEM_DRAW_PNG_MAX_BYTES = 8 * 1024 * 1024;
+var SYSTEM_DIAGRAM_MARKER_LINE = "<!-- drawn by Halfcycle from docs/system.json -->";
+var systemDrawRequestSchema = z13.object({
+  version: z13.number().int().min(1),
+  picture: z13.literal("architecture")
+}).strict();
+function utf8ByteLength2(text) {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const unit = text.charCodeAt(i);
+    if (unit < 128)
+      bytes += 1;
+    else if (unit < 2048)
+      bytes += 2;
+    else if (unit >= 55296 && unit <= 56319 && i + 1 < text.length) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else
+      bytes += 3;
+  }
+  return bytes;
+}
+var BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+function base64DecodedLength(text) {
+  const padding = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+  return text.length / 4 * 3 - padding;
+}
+var SYSTEM_PICTURE_THEMES = ["broadsheet", "flightdeck"];
+var systemPictureSchema = z13.object({
+  svg: z13.string().min(1).refine((v) => utf8ByteLength2(v) <= SYSTEM_DRAW_SVG_MAX_BYTES, { message: "the picture is larger than 2 MB" }),
+  png: z13.string().min(1).refine((v) => v.length % 4 === 0 && BASE64.test(v), { message: "the image is not valid base64" }).refine((v) => base64DecodedLength(v) <= SYSTEM_DRAW_PNG_MAX_BYTES, { message: "the image is larger than 8 MB" })
+}).strict();
+var systemPicturesSchema = z13.object(Object.fromEntries(SYSTEM_PICTURE_THEMES.map((theme) => [theme, systemPictureSchema]))).strict();
+var systemDrawDrawnSchema = z13.object({
+  outcome: z13.literal("drawn"),
+  mermaid: z13.string().min(1).refine((v) => utf8ByteLength2(v) <= SYSTEM_DRAW_MERMAID_MAX_BYTES, {
+    message: "the diagram text is larger than 256 KB"
+  }),
+  pictures: systemPicturesSchema
+}).strict();
+var systemDrawRefusedSchema = z13.object({
+  outcome: z13.literal("refused"),
+  reason: z13.string().min(1)
+}).strict();
+var systemDrawUnavailableSchema = z13.object({
+  outcome: z13.literal("unavailable")
+}).strict();
+var systemDrawResultSchema = z13.discriminatedUnion("outcome", [
+  systemDrawDrawnSchema,
+  systemDrawRefusedSchema,
+  systemDrawUnavailableSchema
+]);
+
 // dist/engagement-credential.js
 import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { platform as platform2 } from "node:os";
@@ -1375,8 +1718,8 @@ var ENV_FILENAME = ENGAGEMENT_ENV_FILENAME;
 var HALFCYCLE_DIR = HALFCYCLE_DIR_NAME;
 var InvalidEngagementIdError = class extends Error {
   constructor(engagementId) {
-    const shown = JSON.stringify(engagementId.length > 80 ? `${engagementId.slice(0, 80)}\u2026` : engagementId);
-    super(`${shown} is not a Halfcycle project id, so it cannot name a folder on this machine and nothing was written. A project id looks like 3f2a1c4e-8b7d-4e2f-9a61-0c5d7e8f9b10. If it is the "${PIN_ENGAGEMENT_ID_FIELD}" in .halfcycle/bundle.json, delete that file and run "npx halfcycle" again: this repository is then set up as a new Halfcycle project.`);
+    const shown2 = JSON.stringify(engagementId.length > 80 ? `${engagementId.slice(0, 80)}\u2026` : engagementId);
+    super(`${shown2} is not a Halfcycle project id, so it cannot name a folder on this machine and nothing was written. A project id looks like 3f2a1c4e-8b7d-4e2f-9a61-0c5d7e8f9b10. If it is the "${PIN_ENGAGEMENT_ID_FIELD}" in .halfcycle/bundle.json, delete that file and run "npx halfcycle" again: this repository is then set up as a new Halfcycle project.`);
     this.name = "InvalidEngagementIdError";
   }
 };
@@ -1700,7 +2043,7 @@ var UnreadableManifestError = class extends Error {
   }
 };
 var HEX64 = /^[0-9a-f]{64}$/;
-function isRecord(value) {
+function isRecord2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function stringArray(value, field) {
@@ -1721,7 +2064,7 @@ function bool(value, field) {
   return value;
 }
 function appendedTextRecord(value, field) {
-  if (!isRecord(value))
+  if (!isRecord2(value))
     throw new UnreadableManifestError(`"${field}" is not an object`);
   onlyKeys(value, ["created", "appended"], `"${field}"`);
   return {
@@ -1741,7 +2084,7 @@ function parseManifest(text) {
   } catch {
     throw new UnreadableManifestError("it is not valid JSON");
   }
-  if (!isRecord(raw))
+  if (!isRecord2(raw))
     throw new UnreadableManifestError("it is not a JSON object");
   onlyKeys(raw, ["format", "files", "createdDirs", "leftAlone", "settings", "mcp", "gitignore", "gitattributes"], "the manifest");
   if (raw["format"] !== INSTALL_MANIFEST_FORMAT) {
@@ -1750,7 +2093,7 @@ function parseManifest(text) {
   if (!Array.isArray(raw["files"]))
     throw new UnreadableManifestError('"files" is not a list');
   const files = raw["files"].map((entry) => {
-    if (!isRecord(entry) || typeof entry["path"] !== "string") {
+    if (!isRecord2(entry) || typeof entry["path"] !== "string") {
       throw new UnreadableManifestError('a "files" entry has no path');
     }
     if (entry["perMachine"] === true) {
@@ -1764,7 +2107,7 @@ function parseManifest(text) {
     return { path: entry["path"], sha256: entry["sha256"] };
   });
   const s = raw["settings"];
-  if (!isRecord(s))
+  if (!isRecord2(s))
     throw new UnreadableManifestError('"settings" is missing');
   onlyKeys(s, [
     "created",
@@ -1791,7 +2134,7 @@ function parseManifest(text) {
   let mcp;
   if (raw["mcp"] !== void 0) {
     const m = raw["mcp"];
-    if (!isRecord(m))
+    if (!isRecord2(m))
       throw new UnreadableManifestError('"mcp" is not an object');
     onlyKeys(m, ["created", "adopted", "mcpServersCreated", "entrySha256"], '"mcp"');
     if (m["entrySha256"] !== void 0 && (typeof m["entrySha256"] !== "string" || !HEX64.test(m["entrySha256"]))) {
@@ -2097,6 +2440,8 @@ var WRITE_ALLOWLIST = [
   BUNDLE_PIN_REL,
   ".halfcycle/bin",
   "docs/build-records",
+  // Architecture pictures the draw command writes from Halfcycle's answer. The installer never writes here; keep the entry so this path stays declared as one Halfcycle writes.
+  "docs/diagrams",
   "test/fixtures/captured",
   MCP_REGISTRATION_REL,
   ".gitattributes",
@@ -3324,14 +3669,14 @@ async function bindLoopback(env = process.env, engagementId) {
     else
       pending = callback;
   }, engagementId));
-  const bindProblem = await new Promise((resolve4) => {
+  const bindProblem = await new Promise((resolve5) => {
     const onError = (err) => {
-      resolve4(`${err.code ?? "bind failed"} on ${LOOPBACK_REDIRECT_HOST}:${wanted.port}`);
+      resolve5(`${err.code ?? "bind failed"} on ${LOOPBACK_REDIRECT_HOST}:${wanted.port}`);
     };
     server.once("error", onError);
     server.listen({ host: LOOPBACK_REDIRECT_HOST, port: wanted.port }, () => {
       server.removeListener("error", onError);
-      resolve4(null);
+      resolve5(null);
     });
   });
   if (bindProblem !== null) {
@@ -3347,9 +3692,9 @@ async function bindLoopback(env = process.env, engagementId) {
     bound: true,
     target: { port: address.port, state },
     boundAddress: address.address,
-    waitForCallback: ({ timeoutMs, onStillWaiting, stillWaitingMs = DEFAULT_STILL_WAITING_MS }) => new Promise((resolve4) => {
+    waitForCallback: ({ timeoutMs, onStillWaiting, stillWaitingMs = DEFAULT_STILL_WAITING_MS }) => new Promise((resolve5) => {
       if (pending !== null) {
-        resolve4(pending);
+        resolve5(pending);
         return;
       }
       const startedAt = Date.now();
@@ -3360,7 +3705,7 @@ async function bindLoopback(env = process.env, engagementId) {
         clearTimeout(timer);
         deliver = null;
         abandon = null;
-        resolve4(value);
+        resolve5(value);
       };
       const timer = setTimeout(() => finish(null), Math.max(0, timeoutMs));
       deliver = finish;
@@ -3374,9 +3719,9 @@ async function bindLoopback(env = process.env, engagementId) {
   };
 }
 function closeServer(server) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     server.closeAllConnections();
-    server.close(() => resolve4());
+    server.close(() => resolve5());
   });
 }
 
@@ -3399,7 +3744,7 @@ function defaultWrite(text) {
   process.stdout.write(text);
 }
 function defaultSleep(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
 }
 function browserOpenCommand(os, url) {
   if (os === "darwin")
@@ -3446,12 +3791,12 @@ async function openBrowser(url, env = process.env, os = platform3(), spawnImpl =
     };
   }
   const { command, args: args2, windowsVerbatimArguments } = browserOpenCommand(os, url);
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     let child;
     try {
       child = spawnImpl(command, args2, { stdio: "ignore", env, windowsVerbatimArguments });
     } catch {
-      resolve4({ opened: false, reason: `${command} could not be run` });
+      resolve5({ opened: false, reason: `${command} could not be run` });
       return;
     }
     let settled = false;
@@ -3460,7 +3805,7 @@ async function openBrowser(url, env = process.env, os = platform3(), spawnImpl =
         return;
       settled = true;
       clearTimeout(timer);
-      resolve4(attempt);
+      resolve5(attempt);
     };
     const timer = setTimeout(() => {
       child.unref();
@@ -3605,17 +3950,17 @@ async function pollBesideLoopback(serviceUrl, started, wake, deps) {
       continue;
     }
     if (sleep === void 0) {
-      await new Promise((resolve4) => {
-        const timer = setTimeout(resolve4, started.pollIntervalMs);
+      await new Promise((resolve5) => {
+        const timer = setTimeout(resolve5, started.pollIntervalMs);
         interrupt = () => {
           clearTimeout(timer);
-          resolve4();
+          resolve5();
         };
       });
     } else {
-      await new Promise((resolve4) => {
-        interrupt = resolve4;
-        void sleep(started.pollIntervalMs).then(resolve4);
+      await new Promise((resolve5) => {
+        interrupt = resolve5;
+        void sleep(started.pollIntervalMs).then(resolve5);
       });
     }
     interrupt = null;
@@ -4237,9 +4582,9 @@ function wrongAccountVisibility(act) {
 async function askLine(question2) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    return await new Promise((resolve4) => {
-      rl.once("close", () => resolve4(""));
-      rl.question(question2).then(resolve4, () => resolve4(""));
+    return await new Promise((resolve5) => {
+      rl.once("close", () => resolve5(""));
+      rl.question(question2).then(resolve5, () => resolve5(""));
     });
   } finally {
     rl.close();
@@ -5098,10 +5443,14 @@ function assertInsideOutDir(outDir, candidate, identity) {
     throw new InvalidPhaseIdentityError(identity, BUILD_RECORD_DIR);
   }
 }
-function createExclusiveOnDisk(path, text) {
+function createExclusiveOnDisk(path, data) {
+  const bytes = typeof data === "string" ? Buffer.from(data, "utf-8") : data;
   const fd = openSync(path, "wx");
   try {
-    writeSync(fd, text);
+    let written = 0;
+    while (written < bytes.length) {
+      written += writeSync(fd, bytes, written, bytes.length - written);
+    }
   } catch (err) {
     closeSync(fd);
     rmSync3(path, { force: true });
@@ -5218,6 +5567,22 @@ function replaceOne(io, tmp, finalPath, text) {
 
 // dist/build-record/obtain.js
 import { relative as relative3 } from "node:path";
+
+// dist/missing-route.js
+var MESSAGE = {
+  GET: /^Route GET .* not found\.$/s,
+  POST: /^Route POST .* not found\.$/s
+};
+function isMissingRoute(method, status, body) {
+  if (status !== 404 || typeof body !== "object" || body === null)
+    return false;
+  const { error, message } = body;
+  if (error !== "Not Found" || typeof message !== "string")
+    return false;
+  return MESSAGE[method].test(message);
+}
+
+// dist/build-record/obtain.js
 var REFUSAL_FOLLOW_UP = {
   "still-open": "Nothing was written. The record is produced when the phase closes.",
   "reopened": "Nothing was written. A new record is produced when the phase closes again.",
@@ -5229,12 +5594,6 @@ var REFUSAL_REASONS = phaseRecordRefusalReasonSchema.options;
 function buildRecordUrl(credential, phase) {
   return `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/phases/${encodeURIComponent(phase)}/build-record`;
 }
-function isMissingRoute(status, body) {
-  if (status !== 404 || typeof body !== "object" || body === null)
-    return false;
-  const { error, message } = body;
-  return error === "Not Found" && typeof message === "string" && /^Route GET .* not found\.$/s.test(message);
-}
 async function obtainBuildRecord(credential, repoRoot, phase, io = NODE_RECORD_PAIR_IO) {
   const url = buildRecordUrl(credential, phase);
   let res;
@@ -5291,7 +5650,7 @@ async function obtainBuildRecord(credential, repoRoot, phase, io = NODE_RECORD_P
       headline: latestCloseHeadline(answer.record)
     };
   }
-  if (isMissingRoute(res.status, raw)) {
+  if (isMissingRoute("GET", res.status, raw)) {
     return { kind: "unavailable", why: "this Halfcycle service does not provide Build Records yet." };
   }
   const message = typeof raw === "object" && raw !== null && typeof raw.message === "string" ? raw.message : null;
@@ -5532,12 +5891,705 @@ function describeIssuePath(path) {
   return path.map(String).join(".") || "(the close)";
 }
 
+// dist/system-report.js
+import { execFileSync as execFileSync5 } from "node:child_process";
+import { readFileSync as readFileSync9 } from "node:fs";
+import { join as join10 } from "node:path";
+var SYSTEM_DESCRIPTION_REL = "docs/system.json";
+function readDescriptionFile(repoRoot) {
+  let text;
+  try {
+    text = readFileSync9(join10(repoRoot, SYSTEM_DESCRIPTION_REL), "utf-8");
+  } catch (err) {
+    const code = err.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? { kind: "missing" } : { kind: "unreadable" };
+  }
+  try {
+    return { kind: "read", value: JSON.parse(text) };
+  } catch (err) {
+    return { kind: "not-json", error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function problemPlace(raw, path) {
+  if (path === "")
+    return SYSTEM_DESCRIPTION_REL;
+  const [list, index] = path.split(".");
+  const position = Number(index);
+  if (!Number.isInteger(position) || position < 0)
+    return path;
+  const items = typeof raw === "object" && raw !== null ? raw[list ?? ""] : void 0;
+  const item = Array.isArray(items) ? items[position] : void 0;
+  const fields = typeof item === "object" && item !== null ? item : {};
+  if (list === "parts") {
+    const id = fields["id"];
+    return typeof id === "string" && id !== "" ? `${path} (part "${id}")` : `${path} (part ${position + 1})`;
+  }
+  if (list === "connections") {
+    const from = fields["from"];
+    const to = fields["to"];
+    return typeof from === "string" && typeof to === "string" ? `${path} (connection "${from}" to "${to}")` : `${path} (connection ${position + 1})`;
+  }
+  return path;
+}
+function problemLines(raw, problems) {
+  return problems.map((p) => `  ${problemPlace(raw, p.path)}: ${p.message}
+`).join("");
+}
+var listTrackedFiles = (repoRoot) => {
+  try {
+    const out = execFileSync5("git", ["-C", repoRoot, "ls-files", "-z"], {
+      encoding: "utf-8",
+      env: gitEnvForNamedRepo(),
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 256 * 1024 * 1024
+    });
+    return out.split("\0").filter((p) => p !== "");
+  } catch {
+    return null;
+  }
+};
+function unownedPatterns(description, tracked) {
+  if (tracked === null)
+    return null;
+  const found = [];
+  for (const part of description.parts) {
+    for (const pattern of part.owns) {
+      const alone = {
+        format: description.format,
+        parts: [{ ...part, owns: [pattern] }],
+        connections: []
+      };
+      if (!tracked.some((path) => ownerOf(path, alone) !== null))
+        found.push({ partId: part.id, pattern });
+    }
+  }
+  return found;
+}
+function unownedPatternLines(unowned) {
+  return unowned.map((u) => `halfcycle system: warning: "${u.pattern}" (part "${u.partId}") matches no file in this repository. Correct the path, or remove it if the code moved.
+`).join("");
+}
+function systemReportUrl(credential) {
+  return `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/system`;
+}
+function serviceHost(serviceUrl) {
+  try {
+    return new URL(serviceUrl).host;
+  } catch {
+    return serviceUrl;
+  }
+}
+async function reportSystemDescription(credential, description) {
+  let res;
+  let text;
+  try {
+    res = await fetch(systemReportUrl(credential), {
+      method: "POST",
+      headers: { authorization: `Bearer ${credential.token}`, "content-type": "application/json" },
+      body: JSON.stringify(description)
+    });
+    text = await res.text();
+  } catch {
+    return {
+      kind: "unavailable",
+      why: `could not reach Halfcycle at ${serviceHost(credential.serviceUrl)}. Check this machine's connection, then run this again.`
+    };
+  }
+  let raw = null;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    raw = null;
+  }
+  const parsed = systemReportResultSchema.safeParse(raw);
+  if (parsed.success) {
+    const answer = parsed.data;
+    if (answer.outcome === "recorded") {
+      return { kind: "recorded", version: answer.version, reportedAt: answer.reportedAt };
+    }
+    if (answer.outcome === "refused")
+      return { kind: "refused", problems: answer.problems };
+    return {
+      kind: "unavailable",
+      why: "Halfcycle could not record it just now. Nothing was recorded; run this again in a minute."
+    };
+  }
+  if (isMissingRoute("POST", res.status, raw))
+    return { kind: "no-route" };
+  const message = typeof raw === "object" && raw !== null && typeof raw.message === "string" ? raw.message : null;
+  if (res.ok) {
+    return {
+      kind: "unavailable",
+      why: "Halfcycle sent an answer this command could not read. Nothing was recorded; try again later."
+    };
+  }
+  return {
+    kind: "unavailable",
+    why: `Halfcycle answered ${res.status}${message === null ? "." : `: ${message}`}`
+  };
+}
+async function checkAndReportDescription(repoRoot, deps, verb, beforeSend = () => null) {
+  const p = `halfcycle ${verb}:`;
+  const file = readDescriptionFile(repoRoot);
+  if (file.kind === "missing") {
+    return {
+      kind: "stopped",
+      stderr: `${p} there is no ${SYSTEM_DESCRIPTION_REL} in this project yet. Run the Layer 2 architecture step to write it, then run this again.
+`
+    };
+  }
+  if (file.kind === "unreadable") {
+    return {
+      kind: "stopped",
+      stderr: `${p} ${SYSTEM_DESCRIPTION_REL} could not be read. Check that it is a file you can open, then run this again.
+`
+    };
+  }
+  if (file.kind === "not-json") {
+    return {
+      kind: "stopped",
+      stderr: `${p} ${SYSTEM_DESCRIPTION_REL} is not valid JSON (${file.error}). Fix it, then run this again. Nothing was sent.
+`
+    };
+  }
+  const checked = checkSystemDescription(file.value);
+  if (!checked.ok) {
+    const n = checked.problems.length;
+    return {
+      kind: "stopped",
+      stderr: `${p} ${SYSTEM_DESCRIPTION_REL} has ${n} ${n === 1 ? "problem" : "problems"}, so nothing was sent:
+` + problemLines(file.value, checked.problems)
+    };
+  }
+  const unowned = unownedPatterns(checked.description, deps.listTracked(repoRoot));
+  const warnings = unowned === null ? "" : unownedPatternLines(unowned);
+  const refusal = beforeSend();
+  if (refusal !== null)
+    return { kind: "stopped", stderr: warnings + refusal };
+  let credential;
+  try {
+    credential = deps.readCredential(repoRoot);
+  } catch {
+    return {
+      kind: "stopped",
+      stderr: warnings + `${p} this project is not connected to Halfcycle on this machine. Run ${HALFCYCLE_COMMAND} here first, then run this again. Nothing was sent.
+`
+    };
+  }
+  const outcome = await deps.report(credential, checked.description);
+  switch (outcome.kind) {
+    case "recorded":
+      return { kind: "recorded", version: outcome.version, credential, warnings };
+    case "refused": {
+      const n = outcome.problems.length;
+      return {
+        kind: "stopped",
+        stderr: warnings + `${p} Halfcycle refused ${SYSTEM_DESCRIPTION_REL} (${n} ${n === 1 ? "problem" : "problems"}); nothing was recorded:
+` + problemLines(file.value, outcome.problems)
+      };
+    }
+    case "no-route":
+      return { kind: "no-route", warnings };
+    case "unavailable":
+      return { kind: "stopped", stderr: warnings + `${p} ${outcome.why}
+` };
+  }
+}
+async function runSystem(repoRoot, deps) {
+  const stage = await checkAndReportDescription(repoRoot, deps, "system");
+  switch (stage.kind) {
+    case "stopped":
+      return { stdout: "", stderr: stage.stderr, exitCode: 1 };
+    case "no-route":
+      return {
+        stdout: "",
+        stderr: stage.warnings + "halfcycle system: this Halfcycle service cannot take a system description yet. Nothing was recorded.\n",
+        exitCode: 1
+      };
+    case "recorded":
+      return {
+        stdout: `[halfcycle] System description recorded: version ${stage.version}.
+`,
+        stderr: stage.warnings,
+        exitCode: 0
+      };
+  }
+}
+
+// dist/draw/write.js
+import { closeSync as closeSync2, lstatSync as lstatSync2, mkdirSync as mkdirSync7, openSync as openSync2, readFileSync as readFileSync10, readSync, realpathSync as realpathSync3, rmSync as rmSync4 } from "node:fs";
+import { dirname as dirname5, isAbsolute as isAbsolute3, join as join11, relative as relative4, resolve as resolve3, sep } from "node:path";
+var DOCS_DIR = "docs";
+var DIAGRAMS_DIR = "diagrams";
+var DIAGRAM_DIR_REL = `${DOCS_DIR}/${DIAGRAMS_DIR}`;
+var ARCHITECTURE_NAME = "architecture";
+var PICTURE_NAMES = {
+  broadsheet: ARCHITECTURE_NAME,
+  flightdeck: `${ARCHITECTURE_NAME}.flightdeck`
+};
+var EMBEDDED_LOOK = "broadsheet";
+var DIAGRAM_MARKER_LINE = SYSTEM_DIAGRAM_MARKER_LINE;
+var PNG_SIGNATURE = Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function svgOf(look) {
+  return `${look}.svg`;
+}
+function pngOf(look) {
+  return `${look}.png`;
+}
+var DIAGRAM_FILES = [
+  ...SYSTEM_PICTURE_THEMES.map(svgOf),
+  ...SYSTEM_PICTURE_THEMES.map(pngOf),
+  "mmd"
+];
+var FILE_NAMES = Object.fromEntries([
+  ...SYSTEM_PICTURE_THEMES.flatMap((look) => [
+    [svgOf(look), `${PICTURE_NAMES[look]}.svg`],
+    [pngOf(look), `${PICTURE_NAMES[look]}.png`]
+  ]),
+  ["mmd", `${ARCHITECTURE_NAME}.mmd`]
+]);
+var EMBED_IMAGE_REL = `${DIAGRAMS_DIR}/${FILE_NAMES[pngOf(EMBEDDED_LOOK)]}`;
+function diagramPaths(repoRoot) {
+  const root = resolve3(repoRoot);
+  const dir = join11(root, DOCS_DIR, DIAGRAMS_DIR);
+  const file = Object.fromEntries(DIAGRAM_FILES.map((which) => [which, join11(dir, FILE_NAMES[which])]));
+  return { repoRoot: root, dir, file };
+}
+function diagramRel(which) {
+  return `${DIAGRAM_DIR_REL}/${FILE_NAMES[which]}`;
+}
+var DIAGRAM_FILES_AS_LISTED = [
+  ...SYSTEM_PICTURE_THEMES.flatMap((look) => [pngOf(look), svgOf(look)]),
+  "mmd"
+];
+function spokenList(items) {
+  if (items.length <= 1)
+    return items.join("");
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function lstatOrNull2(path) {
+  try {
+    return lstatSync2(path);
+  } catch {
+    return null;
+  }
+}
+function isInside(outer, inner) {
+  const rel = relative4(outer, inner);
+  return rel === "" || !isAbsolute3(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+}
+function checkDiagramPlace(paths) {
+  let root;
+  try {
+    root = realpathSync3(paths.repoRoot);
+  } catch {
+    return { ok: false, why: `the folder ${paths.repoRoot} could not be opened. Check the path, then run this again.` };
+  }
+  let ancestor = paths.dir;
+  while (lstatOrNull2(ancestor) === null) {
+    const parent = dirname5(ancestor);
+    if (parent === ancestor)
+      break;
+    ancestor = parent;
+  }
+  let real;
+  try {
+    real = realpathSync3(ancestor);
+  } catch {
+    return {
+      ok: false,
+      why: `${DIAGRAM_DIR_REL} leads to a place that does not exist. Remove the link in the way, then run this again.`
+    };
+  }
+  if (!isInside(root, real)) {
+    return {
+      ok: false,
+      why: `${DIAGRAM_DIR_REL} leads outside this repository, so nothing was written. Remove the link in the way, then run this again.`
+    };
+  }
+  let isFolder = false;
+  try {
+    isFolder = lstatSync2(real).isDirectory();
+  } catch {
+    isFolder = false;
+  }
+  if (!isFolder) {
+    const name = relative4(root, real).split("\\").join("/");
+    return {
+      ok: false,
+      why: `${name === "" ? "this repository" : name} is not a folder, so ${DIAGRAM_DIR_REL} cannot be made. Move it, then run this again.`
+    };
+  }
+  return { ok: true };
+}
+function startsWithMarkerLine(bytes) {
+  const head = Buffer.from(bytes.subarray(0, DIAGRAM_MARKER_LINE.length + 2)).toString("utf-8");
+  return head.startsWith(`${DIAGRAM_MARKER_LINE}
+`) || head.startsWith(`${DIAGRAM_MARKER_LINE}\r
+`);
+}
+function readHead(path) {
+  const fd = openSync2(path, "r");
+  try {
+    const head = Buffer.alloc(DIAGRAM_MARKER_LINE.length + 2);
+    const got = readSync(fd, head, 0, head.length, 0);
+    return head.subarray(0, got);
+  } finally {
+    closeSync2(fd);
+  }
+}
+function readExistingSet(paths) {
+  const found = Object.fromEntries(DIAGRAM_FILES.map((which) => [which, null]));
+  for (const which of DIAGRAM_FILES) {
+    const stat = lstatOrNull2(paths.file[which]);
+    if (stat === null)
+      continue;
+    if (!stat.isFile())
+      return { ok: false, inTheWay: which, temp: false };
+    try {
+      found[which] = readFileSync10(paths.file[which]);
+    } catch {
+      return { ok: false, inTheWay: which, temp: false };
+    }
+  }
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    const svg = found[svgOf(look)];
+    if (svg !== null && !startsWithMarkerLine(svg))
+      return { ok: false, inTheWay: svgOf(look), temp: false };
+  }
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    if (found[pngOf(look)] !== null && found[svgOf(look)] === null)
+      return { ok: false, inTheWay: pngOf(look), temp: false };
+  }
+  if (found.mmd !== null && found[svgOf(EMBEDDED_LOOK)] === null)
+    return { ok: false, inTheWay: "mmd", temp: false };
+  const temp = Object.fromEntries(DIAGRAM_FILES.map((which) => [which, null]));
+  for (const which of DIAGRAM_FILES) {
+    const stat = lstatOrNull2(tempPath(paths, which));
+    if (stat === null)
+      continue;
+    if (!stat.isFile())
+      return { ok: false, inTheWay: which, temp: true };
+    try {
+      temp[which] = readHead(tempPath(paths, which));
+    } catch {
+      return { ok: false, inTheWay: which, temp: true };
+    }
+  }
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    const svg = temp[svgOf(look)];
+    if (svg !== null && !startsWithMarkerLine(svg))
+      return { ok: false, inTheWay: svgOf(look), temp: true };
+  }
+  const markedSvgBeside = (look) => found[svgOf(look)] !== null || temp[svgOf(look)] !== null;
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    if (temp[pngOf(look)] !== null && !markedSvgBeside(look))
+      return { ok: false, inTheWay: pngOf(look), temp: true };
+  }
+  if (temp.mmd !== null && !markedSvgBeside(EMBEDDED_LOOK))
+    return { ok: false, inTheWay: "mmd", temp: true };
+  return { ok: true, existing: found, ourTemps: DIAGRAM_FILES.filter((which) => temp[which] !== null) };
+}
+function tempPath(paths, which) {
+  return `${paths.file[which]}.tmp`;
+}
+function inTheWayLine(which, temp = false) {
+  return `${diagramRel(which)}${temp ? ".tmp" : ""} is already there and was not drawn by this command. Move it or delete it, then run this again. Nothing was written.`;
+}
+function checkPictures(drawn) {
+  const set = {};
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    const picture = drawn.pictures[look];
+    const pngFor = diagramRel(pngOf(look));
+    const svgFor = diagramRel(svgOf(look));
+    const png = Buffer.from(picture.png, "base64");
+    if (png.length > SYSTEM_DRAW_PNG_MAX_BYTES)
+      return { ok: false, why: `the image for ${pngFor} is larger than 8 MB` };
+    if (png.length < PNG_SIGNATURE.length || !PNG_SIGNATURE.every((b, i) => png[i] === b)) {
+      return { ok: false, why: `the image for ${pngFor} is not a PNG` };
+    }
+    const svg = Buffer.from(picture.svg, "utf-8");
+    if (svg.length > SYSTEM_DRAW_SVG_MAX_BYTES)
+      return { ok: false, why: `the picture for ${svgFor} is larger than 2 MB` };
+    const body = picture.svg.endsWith("\n") ? picture.svg.slice(0, -1) : picture.svg;
+    if (!picture.svg.startsWith(`${DIAGRAM_MARKER_LINE}
+<svg`) || !body.endsWith("</svg>")) {
+      return { ok: false, why: `the picture for ${svgFor} is not a complete SVG drawn by Halfcycle` };
+    }
+    set[pngOf(look)] = png;
+    set[svgOf(look)] = svg;
+  }
+  const mmd = Buffer.from(drawn.mermaid, "utf-8");
+  if (mmd.length > SYSTEM_DRAW_MERMAID_MAX_BYTES)
+    return { ok: false, why: "the diagram text is larger than 256 KB" };
+  if (!drawn.mermaid.startsWith("flowchart"))
+    return { ok: false, why: "the diagram text is not a Mermaid flowchart" };
+  set.mmd = mmd;
+  return { ok: true, set };
+}
+function removeQuietly(path) {
+  try {
+    rmSync4(path, { force: true });
+  } catch {
+    return;
+  }
+}
+function sameBytes(a, b) {
+  return a !== null && Buffer.from(a).equals(b);
+}
+function writeDiagramSet(repoRoot, set, io = NODE_RECORD_PAIR_IO) {
+  const paths = diagramPaths(repoRoot);
+  const place = checkDiagramPlace(paths);
+  if (!place.ok)
+    return { kind: "unsafe", why: place.why };
+  const read = readExistingSet(paths);
+  if (!read.ok)
+    return { kind: "in-the-way", file: read.inTheWay, temp: read.temp };
+  const existing = read.existing;
+  const changed = DIAGRAM_FILES.filter((which) => !sameBytes(existing[which], set[which]));
+  if (changed.length === 0)
+    return { kind: "up-to-date" };
+  try {
+    mkdirSync7(paths.dir, { recursive: true });
+  } catch {
+    return { kind: "failed", file: changed[0], removed: [] };
+  }
+  const made = checkDiagramPlace(paths);
+  if (!made.ok)
+    return { kind: "unsafe", why: made.why };
+  const tmp = (which) => tempPath(paths, which);
+  for (const which of read.ourTemps)
+    removeQuietly(tmp(which));
+  const staged = [];
+  const clearStaged = () => {
+    for (const which of staged)
+      removeQuietly(tmp(which));
+  };
+  for (const which of changed) {
+    try {
+      io.createExclusive(tmp(which), set[which]);
+      staged.push(which);
+    } catch {
+      clearStaged();
+      return { kind: "failed", file: which, removed: [] };
+    }
+  }
+  const renamed = [];
+  for (const which of changed) {
+    try {
+      io.rename(tmp(which), paths.file[which]);
+      renamed.push(which);
+    } catch {
+      clearStaged();
+      const removed = restore(io, paths, renamed, existing);
+      return { kind: "failed", file: which, removed };
+    }
+  }
+  return { kind: "written", changed };
+}
+function restore(io, paths, renamed, existing) {
+  const removed = [];
+  for (const which of [...renamed].reverse()) {
+    const finalPath = paths.file[which];
+    const previous = existing[which];
+    const tmp = tempPath(paths, which);
+    try {
+      if (previous === null) {
+        rmSync4(finalPath, { force: true });
+        continue;
+      }
+      rmSync4(tmp, { force: true });
+      io.createExclusive(tmp, previous);
+      io.rename(tmp, finalPath);
+    } catch {
+      removeQuietly(tmp);
+      removeQuietly(finalPath);
+      removed.push(which);
+    }
+  }
+  return removed;
+}
+
+// dist/draw/index.js
+var DRAW_USAGE = `${HALFCYCLE_COMMAND} draw architecture [--repo <root>]`;
+function parseDrawArgs(argv) {
+  const positionals = [];
+  let repoRoot;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--repo") {
+      const value = argv[i + 1];
+      if (repoRoot !== void 0 || value === void 0 || value === "" || value.startsWith("-"))
+        return { ok: false };
+      repoRoot = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-"))
+      return { ok: false };
+    positionals.push(arg);
+  }
+  if (positionals.length !== 1 || positionals[0] !== "architecture")
+    return { ok: false };
+  return { ok: true, repoRoot };
+}
+function systemDrawUrl(credential) {
+  return `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/system/draw`;
+}
+function serviceHost2(serviceUrl) {
+  try {
+    return new URL(serviceUrl).host;
+  } catch {
+    return serviceUrl;
+  }
+}
+async function requestDrawing(credential, version) {
+  const body = { version, picture: "architecture" };
+  let res;
+  let text;
+  try {
+    res = await fetch(systemDrawUrl(credential), {
+      method: "POST",
+      headers: { authorization: `Bearer ${credential.token}`, "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    text = await res.text();
+  } catch {
+    return {
+      kind: "unavailable",
+      why: `could not reach Halfcycle at ${serviceHost2(credential.serviceUrl)}. Check this machine's connection, then run this again. Nothing was written.`
+    };
+  }
+  let raw = null;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    raw = null;
+  }
+  const parsed = systemDrawResultSchema.safeParse(raw);
+  if (parsed.success) {
+    const answer = parsed.data;
+    if (answer.outcome === "drawn")
+      return { kind: "drawn", drawn: answer };
+    if (answer.outcome === "refused")
+      return { kind: "refused", reason: answer.reason };
+    return {
+      kind: "unavailable",
+      why: "Halfcycle could not draw the pictures just now. Nothing was written; run this again in a minute."
+    };
+  }
+  if (isMissingRoute("POST", res.status, raw))
+    return { kind: "no-route" };
+  if (res.ok) {
+    return {
+      kind: "unavailable",
+      why: "Halfcycle sent an answer this command could not read. Nothing was written; try again later."
+    };
+  }
+  const message = typeof raw === "object" && raw !== null && typeof raw.message === "string" ? raw.message : null;
+  return {
+    kind: "unavailable",
+    why: `Halfcycle answered ${res.status}${message === null ? "." : `: ${message}`} Nothing was written.`
+  };
+}
+var P = "halfcycle draw:";
+var CANNOT_DRAW_YET = `${P} this Halfcycle service cannot draw pictures yet. Nothing was written.
+`;
+function pasteLines(mermaid) {
+  const block = mermaid.endsWith("\n") ? mermaid : `${mermaid}
+`;
+  return `
+Paste this into a document directly under docs/:
+
+![Architecture](${EMBED_IMAGE_REL})
+
+\`\`\`mermaid
+` + block + "```\n";
+}
+function localRefusal(repoRoot) {
+  const paths = diagramPaths(repoRoot);
+  const place = checkDiagramPlace(paths);
+  if (!place.ok)
+    return `${P} ${place.why}
+`;
+  const read = readExistingSet(paths);
+  if (!read.ok)
+    return `${P} ${inTheWayLine(read.inTheWay, read.temp)}
+`;
+  return null;
+}
+async function runDraw(repoRoot, deps) {
+  const stage = await checkAndReportDescription(repoRoot, deps, "draw", () => localRefusal(repoRoot));
+  if (stage.kind === "stopped")
+    return { stdout: "", stderr: stage.stderr, exitCode: 1 };
+  if (stage.kind === "no-route")
+    return { stdout: "", stderr: stage.warnings + CANNOT_DRAW_YET, exitCode: 1 };
+  const warnings = stage.warnings;
+  const outcome = await deps.draw(stage.credential, stage.version);
+  if (outcome.kind === "no-route")
+    return { stdout: "", stderr: warnings + CANNOT_DRAW_YET, exitCode: 1 };
+  if (outcome.kind === "refused") {
+    return {
+      stdout: "",
+      stderr: warnings + `${P} Halfcycle would not draw the pictures: ${outcome.reason} Nothing was written.
+`,
+      exitCode: 1
+    };
+  }
+  if (outcome.kind === "unavailable")
+    return { stdout: "", stderr: warnings + `${P} ${outcome.why}
+`, exitCode: 1 };
+  const checked = checkPictures(outcome.drawn);
+  if (!checked.ok) {
+    return {
+      stdout: "",
+      stderr: warnings + `${P} Halfcycle sent pictures this command cannot use (${checked.why}). Nothing was written; try again later.
+`,
+      exitCode: 1
+    };
+  }
+  const result = deps.write(repoRoot, checked.set);
+  switch (result.kind) {
+    case "up-to-date":
+      return {
+        stdout: `[halfcycle] The pictures in ${DIAGRAM_DIR_REL}/ are up to date.
+` + pasteLines(outcome.drawn.mermaid),
+        stderr: warnings,
+        exitCode: 0
+      };
+    case "written":
+      return {
+        stdout: `[halfcycle] Wrote ${spokenList(DIAGRAM_FILES_AS_LISTED.map(diagramRel))}.
+` + pasteLines(outcome.drawn.mermaid),
+        stderr: warnings,
+        exitCode: 0
+      };
+    case "in-the-way":
+      return { stdout: "", stderr: warnings + `${P} ${inTheWayLine(result.file, result.temp)}
+`, exitCode: 1 };
+    case "unsafe":
+      return { stdout: "", stderr: warnings + `${P} ${result.why}
+`, exitCode: 1 };
+    case "failed": {
+      const lost = result.removed.length === 0 ? "The pictures already there are as they were." : `${spokenList(result.removed.map(diagramRel))} could not be put back as ${result.removed.length === 1 ? "it was, so it was" : "they were, so they were"} removed; the other pictures are as they were.`;
+      return {
+        stdout: "",
+        stderr: warnings + `${P} ${diagramRel(result.file)} could not be written. ${lost} Check that you can write to ${DIAGRAM_DIR_REL}, then run this again.
+`,
+        exitCode: 1
+      };
+    }
+  }
+}
+
 // dist/cli-contract.js
-var CLI_VERBS = ["install", "check-drift", "build-record", "open-phase", "close-phase", "uninstall"];
+var CLI_VERBS = ["install", "check-drift", "build-record", "open-phase", "close-phase", "system", "draw", "uninstall"];
 var CONTRACTS = [
   { verb: "install", required: [], conditional: [] },
   { verb: "check-drift", required: [], conditional: [] },
   { verb: "build-record", required: [], conditional: [] },
+  { verb: "system", required: [], conditional: [] },
+  { verb: "draw", required: [], conditional: [] },
   { verb: "uninstall", required: [], conditional: [] },
   {
     verb: "open-phase",
@@ -5674,9 +6726,9 @@ function placeholderRefusal(verb, tokens) {
 }
 
 // dist/uninstall.js
-import { lstatSync as lstatSync2, readFileSync as readFileSync9, readdirSync, rmSync as rmSync4, rmdirSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { lstatSync as lstatSync3, readFileSync as readFileSync11, readdirSync, rmSync as rmSync5, rmdirSync, writeFileSync as writeFileSync6 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname5, join as join10, relative as relative4, sep } from "node:path";
+import { dirname as dirname6, join as join12, relative as relative5, sep as sep2 } from "node:path";
 var REMOVE_CREDENTIAL_FLAG = "--remove-credential";
 function parseUninstallArgs(args2) {
   let removeCredential = false;
@@ -5693,7 +6745,7 @@ function parseUninstallArgs(args2) {
 }
 function lexists(path) {
   try {
-    lstatSync2(path);
+    lstatSync3(path);
     return true;
   } catch {
     return false;
@@ -5702,9 +6754,9 @@ function lexists(path) {
 function symlinkOnPath(root, rel) {
   let current = root;
   for (const segment of rel.split("/")) {
-    current = join10(current, segment);
+    current = join12(current, segment);
     try {
-      if (lstatSync2(current).isSymbolicLink())
+      if (lstatSync3(current).isSymbolicLink())
         return true;
     } catch {
       return false;
@@ -5724,13 +6776,13 @@ function readMergedJson(targetRepo, rule) {
   const { rel } = rule;
   if (symlinkOnPath(targetRepo, rel))
     return { state: "symlink" };
-  const path = join10(targetRepo, rel);
+  const path = join12(targetRepo, rel);
   if (!lexists(path))
     return { state: "absent" };
   let text;
   let value;
   try {
-    text = readFileSync9(path, "utf-8");
+    text = readFileSync11(path, "utf-8");
   } catch {
     text = "";
   }
@@ -5747,15 +6799,15 @@ function readMergedJson(targetRepo, rule) {
 }
 function validate(options, rules) {
   const { targetRepo, removeCredential, home } = options;
-  const manifestPath = join10(targetRepo, INSTALL_MANIFEST_REL);
-  const pinPath = join10(targetRepo, BUNDLE_PIN_REL);
+  const manifestPath = join12(targetRepo, INSTALL_MANIFEST_REL);
+  const pinPath = join12(targetRepo, BUNDLE_PIN_REL);
   if (symlinkOnPath(targetRepo, INSTALL_MANIFEST_REL) || symlinkOnPath(targetRepo, BUNDLE_PIN_REL)) {
     throw new Refusal(`.halfcycle, or a file Halfcycle keeps in it, is a symbolic link here, so nothing was followed and nothing was removed.`);
   }
   let manifest = null;
   if (lexists(manifestPath)) {
     try {
-      manifest = parseManifest(readFileSync9(manifestPath, "utf-8"));
+      manifest = parseManifest(readFileSync11(manifestPath, "utf-8"));
     } catch (err) {
       const why = err instanceof UnreadableManifestError ? err.message : "it could not be read";
       throw new Refusal(`${INSTALL_MANIFEST_REL} cannot be read (${why}), so nothing was removed. Restore it from git, or run "${HALFCYCLE_COMMAND}" once to rewrite it, then run "${HALFCYCLE_COMMAND} uninstall" again.`);
@@ -5765,7 +6817,7 @@ function validate(options, rules) {
   let pinReadable = true;
   if (lexists(pinPath)) {
     try {
-      const pin = JSON.parse(readFileSync9(pinPath, "utf-8"));
+      const pin = JSON.parse(readFileSync11(pinPath, "utf-8"));
       const id = isPlainObject2(pin) ? pin[PIN_ENGAGEMENT_ID_FIELD] : void 0;
       engagementId = typeof id === "string" && id !== "" ? id : void 0;
     } catch {
@@ -5789,8 +6841,8 @@ function validate(options, rules) {
       throw new Refusal(`the project id in ${BUNDLE_PIN_REL} is not a valid Halfcycle project id, so it cannot name a folder on this machine. Nothing was removed, here or under ~/.halfcycle.`);
     }
     if (engagementId !== void 0) {
-      const expectedParent = join10(home ?? homedir2(), HALFCYCLE_DIR_NAME, ENGAGEMENTS_DIR_NAME);
-      if (dirname5(engagementStateDir(engagementId, home)) !== expectedParent) {
+      const expectedParent = join12(home ?? homedir2(), HALFCYCLE_DIR_NAME, ENGAGEMENTS_DIR_NAME);
+      if (dirname6(engagementStateDir(engagementId, home)) !== expectedParent) {
         throw new Refusal(`the project id in ${BUNDLE_PIN_REL} does not name a folder under ~/.halfcycle/engagements. Nothing was removed.`);
       }
     }
@@ -5813,10 +6865,10 @@ function mergedFileRules(writeSet) {
 function writeBack(targetRepo, rel, current, next, lists, name) {
   if (next === current)
     return;
-  const path = join10(targetRepo, rel);
+  const path = join12(targetRepo, rel);
   try {
     if (next === null) {
-      rmSync4(path);
+      rmSync5(path);
       name(lists.removed, rel, rel);
     } else {
       writeFileSync6(path, next, "utf-8");
@@ -5831,7 +6883,7 @@ function noRecord(targetRepo, writeSet) {
   const claim = (rel, header, lines) => {
     let text;
     try {
-      text = symlinkOnPath(targetRepo, rel) ? "" : readFileSync9(join10(targetRepo, rel), "utf-8");
+      text = symlinkOnPath(targetRepo, rel) ? "" : readFileSync11(join12(targetRepo, rel), "utf-8");
     } catch {
       text = "";
     }
@@ -6057,7 +7109,7 @@ function lastOccurrence(text, block) {
 }
 function coveredPathExists(targetRepo, line) {
   const path = line.trim().replace(/^\//, "").replace(/\/$/, "");
-  return path !== "" && lexists(join10(targetRepo, path));
+  return path !== "" && lexists(join12(targetRepo, path));
 }
 function uninstall(options) {
   const result = {
@@ -6137,7 +7189,7 @@ function uninstall(options) {
   const gitattributes = manifest.gitattributes ?? { created: false, appended: [] };
   trimAppendedFile(targetRepo, gitattributes, deleteWhenEmpty(gitattributes.created), gitattributesRules(writeSet), result, name);
   const foundNothing = result.removed.length + result.restored.length + result.kept.length + result.failed.length === 0 && result.keptIgnoreLines.length === 0;
-  if (checked.manifest === null && !lexists(join10(targetRepo, BUNDLE_PIN_REL)) && foundNothing) {
+  if (checked.manifest === null && !lexists(join12(targetRepo, BUNDLE_PIN_REL)) && foundNothing) {
     return { outcome: "not-installed", exitCode: 0, ...result, credential: nothingToSay };
   }
   const credential = handleCredential(options, checked);
@@ -6145,7 +7197,7 @@ function uninstall(options) {
   if (result.failed.length === 0 && !credentialFailed) {
     removeInstalledFile(targetRepo, BUNDLE_PIN_REL, recorded.get(BUNDLE_PIN_REL), writeSet, result, name);
     try {
-      rmSync4(join10(targetRepo, INSTALL_MANIFEST_REL), { force: true });
+      rmSync5(join12(targetRepo, INSTALL_MANIFEST_REL), { force: true });
       named.add(INSTALL_MANIFEST_REL);
     } catch {
       name(result.failed, INSTALL_MANIFEST_REL, INSTALL_MANIFEST_REL);
@@ -6180,7 +7232,7 @@ function applyMergedJson(targetRepo, rule, file, deleteWhenEmpty, lists, name, e
     return;
   const empty = Object.keys(value).length === 0 && deleteWhenEmpty;
   writeBack(targetRepo, rel, file.text, empty ? null : inLineEndingOf(file.text, serializeJson(value)), lists, name);
-  if (adopted && lexists(join10(targetRepo, rel))) {
+  if (adopted && lexists(join12(targetRepo, rel))) {
     name(lists.leftAlone, `${rel} (Halfcycle's hooks were taken out. There is no record of this file from before the install, so a permission rule or "$schema" Halfcycle added may still be there \u2014 it cannot be told apart from your own)`, rel);
   }
 }
@@ -6193,10 +7245,10 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
     name(lists.leftAlone, `${path} (a symbolic link, or inside one \u2014 not followed)`, path);
     return;
   }
-  const abs = join10(targetRepo, path);
+  const abs = join12(targetRepo, path);
   let isFile;
   try {
-    isFile = lstatSync2(abs).isFile();
+    isFile = lstatSync3(abs).isFile();
   } catch {
     return;
   }
@@ -6207,7 +7259,7 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
   if (!writeSet.ownedDirs.has(path.slice(0, path.lastIndexOf("/")))) {
     let bytes;
     try {
-      bytes = readFileSync9(abs);
+      bytes = readFileSync11(abs);
     } catch {
       name(lists.failed, path, path);
       return;
@@ -6218,7 +7270,7 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
     }
   }
   try {
-    rmSync4(abs);
+    rmSync5(abs);
     name(lists.removed, path, path);
   } catch {
     name(lists.failed, path, path);
@@ -6227,9 +7279,9 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
 function removeEmptyDir(targetRepo, dir, writeSet, lists, name) {
   if (!writeSet.dirs.has(dir) || symlinkOnPath(targetRepo, dir))
     return;
-  const abs = join10(targetRepo, dir);
+  const abs = join12(targetRepo, dir);
   try {
-    if (!lstatSync2(abs).isDirectory() || readdirSync(abs).length > 0)
+    if (!lstatSync3(abs).isDirectory() || readdirSync(abs).length > 0)
       return;
   } catch {
     return;
@@ -6246,10 +7298,10 @@ function trimAppendedFile(targetRepo, rec, deleteWhenEmpty, rules, lists, name)
     name(lists.leftAlone, `${rel} (a symbolic link \u2014 not followed)`, rel);
     return [];
   }
-  const path = join10(targetRepo, rel);
+  const path = join12(targetRepo, rel);
   let before;
   try {
-    before = readFileSync9(path, "utf-8");
+    before = readFileSync11(path, "utf-8");
   } catch {
     return [];
   }
@@ -6277,10 +7329,10 @@ function handleCredential(options, checked) {
   if (!lexists(dir))
     return { kind: "not-held", dir };
   try {
-    if (lstatSync2(dir).isSymbolicLink())
+    if (lstatSync3(dir).isSymbolicLink())
       return { kind: "failed", dir, reason: "it is a symbolic link" };
-    rmSync4(engagementEnvPath(engagementId, home), { force: true });
-    rmSync4(notThisAccountMarkerPath(engagementId, home), { force: true });
+    rmSync5(engagementEnvPath(engagementId, home), { force: true });
+    rmSync5(notThisAccountMarkerPath(engagementId, home), { force: true });
     if (readdirSync(dir).length === 0)
       rmdirSync(dir);
   } catch (err) {
@@ -6293,16 +7345,16 @@ function filesUnder(root, rel) {
   const walk = (dirRel) => {
     let names;
     try {
-      if (!lstatSync2(join10(root, dirRel)).isDirectory())
+      if (!lstatSync3(join12(root, dirRel)).isDirectory())
         return;
-      names = readdirSync(join10(root, dirRel));
+      names = readdirSync(join12(root, dirRel));
     } catch {
       return;
     }
     for (const entry of names.sort()) {
       const childRel = `${dirRel}/${entry}`;
       try {
-        if (lstatSync2(join10(root, childRel)).isDirectory())
+        if (lstatSync3(join12(root, childRel)).isDirectory())
           walk(childRel);
         else
           out.push(childRel);
@@ -6316,9 +7368,9 @@ function filesUnder(root, rel) {
 }
 function shownPath(path, home) {
   const base = home ?? homedir2();
-  const rel = relative4(base, path);
-  const under = rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep);
-  return `${under ? `~/${rel.split(sep).join("/")}` : path}/`;
+  const rel = relative5(base, path);
+  const under = rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep2);
+  return `${under ? `~/${rel.split(sep2).join("/")}` : path}/`;
 }
 function renderUninstallReport(result, home) {
   if (result.outcome === "refused") {
@@ -6374,8 +7426,8 @@ function renderUninstallReport(result, home) {
 }
 
 // dist/banner-facts.js
-import { readFileSync as readFileSync10 } from "node:fs";
-import { basename as basename3, join as join11, resolve as resolve3 } from "node:path";
+import { readFileSync as readFileSync12 } from "node:fs";
+import { basename as basename3, join as join13, resolve as resolve4 } from "node:path";
 var BRAND_URL = "halfcycle.ai";
 var TAGLINE = [
   "Fewer cycles.",
@@ -6388,7 +7440,7 @@ var TAGLINE_NARROW = [
 ];
 function bundleVersion() {
   try {
-    const pkg = JSON.parse(readFileSync10(join11(BUNDLE_ROOT, "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync12(join13(BUNDLE_ROOT, "package.json"), "utf-8"));
     return typeof pkg.version === "string" ? pkg.version : void 0;
   } catch {
     return void 0;
@@ -6467,7 +7519,7 @@ function openingBannerContent(projectDir, env = process.env, probes = REAL_PROBE
 }
 function safeBasename(dir) {
   try {
-    const name = basename3(resolve3(dir)).trim();
+    const name = basename3(resolve4(dir)).trim();
     return name === "" ? "project" : name;
   } catch {
     return "project";
@@ -6528,6 +7580,10 @@ var USAGE = `  ${HALFCYCLE_COMMAND} [install] [target-repo] [engagement-id] [sel
   ${HALFCYCLE_COMMAND} close-phase <phase> --verdict <clean|defects> --actor "\u2026" [--finding "\u2026"]\u2026 [--override --reason "\u2026"] [--repo <root>]
          [--thesis "\u2026"] [--outcome "\u2026"] [--deviation "\u2026"]\u2026
          close the phase and write its Build Record into docs/build-records/
+  ${HALFCYCLE_COMMAND} system [--repo <root>]
+         check docs/system.json, the description of your system, and send it to Halfcycle
+  ${DRAW_USAGE}
+         draw the architecture pictures from docs/system.json into docs/diagrams/
   ${HALFCYCLE_COMMAND} uninstall [${REMOVE_CREDENTIAL_FLAG}]
          take out what the installer added to this project, keeping anything you changed
          ${REMOVE_CREDENTIAL_FLAG}: also remove this machine's credential for the project, which every
@@ -6540,7 +7596,7 @@ var USAGE = `  ${HALFCYCLE_COMMAND} [install] [target-repo] [engagement-id] [sel
 `;
 function isHalfcycleMonorepo(dir) {
   try {
-    const pkg = JSON.parse(readFileSync11(join12(dir, "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync13(join14(dir, "package.json"), "utf-8"));
     return pkg.name === "halfcycle-monorepo";
   } catch {
     return false;
@@ -6548,8 +7604,8 @@ function isHalfcycleMonorepo(dir) {
 }
 function isHomeFolder(dir) {
   try {
-    const target = realpathSync3(dir);
-    const home = realpathSync3(homedir3());
+    const target = realpathSync4(dir);
+    const home = realpathSync4(homedir3());
     return process.platform === "win32" ? target.toLowerCase() === home.toLowerCase() : target === home;
   } catch {
     return false;
@@ -6976,6 +8032,43 @@ ${USAGE}`);
     }
     return;
   }
+  if (cmd === "system") {
+    const repoRoot = flagValue(rest, "--repo") ?? process.cwd();
+    const run = await runSystem(repoRoot, {
+      readCredential: (root) => readRepoCredential(root),
+      listTracked: listTrackedFiles,
+      report: reportSystemDescription
+    });
+    if (run.stdout !== "")
+      process.stdout.write(run.stdout);
+    if (run.stderr !== "")
+      process.stderr.write(run.stderr);
+    process.exitCode = run.exitCode;
+    return;
+  }
+  if (cmd === "draw") {
+    const parsed = parseDrawArgs(rest);
+    if (!parsed.ok) {
+      process.stderr.write(`halfcycle draw: usage: ${DRAW_USAGE}
+`);
+      process.exitCode = 2;
+      return;
+    }
+    const repoRoot = parsed.repoRoot ?? process.cwd();
+    const run = await runDraw(repoRoot, {
+      readCredential: (root) => readRepoCredential(root),
+      listTracked: listTrackedFiles,
+      report: reportSystemDescription,
+      draw: requestDrawing,
+      write: (root, set) => writeDiagramSet(root, set)
+    });
+    if (run.stdout !== "")
+      process.stdout.write(run.stdout);
+    if (run.stderr !== "")
+      process.stderr.write(run.stderr);
+    process.exitCode = run.exitCode;
+    return;
+  }
   if (cmd === "open-phase") {
     const repoRoot = flagValue(rest, "--repo") ?? process.cwd();
     const toProjectScope = rest.includes("--none");