@jstn-sdk/ma 0.1.13 → 0.14.0

package/src/runtime/codeburn-core.js

@@ -0,0 +1,112 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+const execFileAsync = promisify(execFile);
+export const codeburnSchemaVersion = "0.1.0";
+
+export function getCodeburnRoot() {
+  return getRuntimeSubsystemPath("context");
+}
+
+export function getCodeburnLogPath() {
+  return getRuntimeSubsystemPath("context", "codeburn-usage.json");
+}
+
+export function createDefaultCodeburnUsage() {
+  return { schemaVersion: codeburnSchemaVersion, entries: [], totalTokens: 0, totalCost: 0 };
+}
+
+function validateUsage(value) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    value.schemaVersion !== codeburnSchemaVersion ||
+    !Array.isArray(value.entries) ||
+    !Number.isFinite(value.totalTokens) ||
+    !Number.isFinite(value.totalCost)
+  ) {
+    throw new Error("codeburn usage has an invalid schema");
+  }
+  return value;
+}
+
+export async function seedCodeburnArtifacts() {
+  await ensureDir(getCodeburnRoot());
+  await writeFileIfMissing(
+    getCodeburnLogPath(),
+    `${JSON.stringify(createDefaultCodeburnUsage(), null, 2)}\n`,
+  );
+}
+
+export async function loadCodeburnUsage() {
+  return validateUsage(await readJson(getCodeburnLogPath()));
+}
+
+function parseCodeburnOutput(output) {
+  const text = String(output ?? "").trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : (parsed.entries ?? [parsed]);
+  } catch {
+    const jsonLine = text
+      .split("\n")
+      .map((line) => line.trim())
+      .reverse()
+      .find((line) => line.startsWith("{") || line.startsWith("["));
+    if (!jsonLine) throw new Error("codeburn returned no JSON usage data");
+    const parsed = JSON.parse(jsonLine);
+    return Array.isArray(parsed) ? parsed : (parsed.entries ?? [parsed]);
+  }
+}
+
+function normalizeEntry(entry) {
+  const inputTokens = Number(entry.inputTokens ?? entry.input_tokens ?? 0);
+  const outputTokens = Number(entry.outputTokens ?? entry.output_tokens ?? 0);
+  const tokens = Number(
+    entry.totalTokens ?? entry.total_tokens ?? entry.tokens ?? inputTokens + outputTokens,
+  );
+  const cost = Number(entry.totalCost ?? entry.total_cost ?? entry.cost ?? 0);
+  return {
+    provider: entry.provider ?? null,
+    model: entry.model ?? entry.modelName ?? null,
+    sessionId: entry.sessionId ?? entry.session_id ?? null,
+    tokens: Number.isFinite(tokens) && tokens >= 0 ? tokens : 0,
+    cost: Number.isFinite(cost) && cost >= 0 ? cost : 0,
+  };
+}
+
+export async function syncCodeburnUsage({
+  cwd = process.cwd(),
+  command,
+  args,
+  exec = execFileAsync,
+} = {}) {
+  const existing = await loadCodeburnUsage();
+  const executable = command ?? process.env.MA_CODEBURN_BIN ?? "npx";
+  const commandArgs = args ?? ["--yes", "codeburn", "usage", "--json"];
+  try {
+    const result = await exec(executable, commandArgs, { cwd, encoding: "utf8", timeout: 15_000 });
+    const entries = parseCodeburnOutput(result.stdout ?? result);
+    const normalized = entries
+      .filter((entry) => entry && typeof entry === "object")
+      .map(normalizeEntry);
+    const usage = {
+      schemaVersion: codeburnSchemaVersion,
+      entries: normalized,
+      totalTokens: normalized.reduce((sum, entry) => sum + entry.tokens, 0),
+      totalCost: normalized.reduce((sum, entry) => sum + entry.cost, 0),
+      syncedAt: new Date().toISOString(),
+    };
+    await writeJson(getCodeburnLogPath(), usage);
+    return { available: true, usage };
+  } catch (error) {
+    return {
+      available: false,
+      usage: existing,
+      reason: error instanceof Error ? error.message : "codeburn unavailable",
+    };
+  }
+}

package/src/runtime/context-authority.js

@@ -0,0 +1,40 @@
+export const contextAuthorityOrder = [
+  "source_truth",
+  "verified_evidence",
+  "hook_evidence",
+  "generated_context",
+  "vault_note",
+  "learning_memory",
+  "external_reference",
+  "stale",
+];
+
+export function createFreshness({
+  sourceHash = null,
+  sourceFiles = [],
+  checkedAt = new Date().toISOString(),
+  status = "fresh",
+} = {}) {
+  return {
+    status,
+    stale: status === "stale",
+    checkedAt,
+    sourceHash,
+    sourceFiles: [...sourceFiles],
+    changedFiles: [...sourceFiles],
+  };
+}
+
+export function resolveContextConflict(candidates = []) {
+  return (
+    [...candidates]
+      .filter((candidate) => candidate && typeof candidate === "object")
+      .sort((left, right) => {
+        const authority =
+          contextAuthorityOrder.indexOf(left.authority) -
+          contextAuthorityOrder.indexOf(right.authority);
+        if (authority !== 0) return authority;
+        return Number(Boolean(left.freshness?.stale)) - Number(Boolean(right.freshness?.stale));
+      })[0] ?? null
+  );
+}

package/src/runtime/context-economy-core.js

@@ -184,6 +184,46 @@ export function createMcpDescriptorEconomy({ name, description, inputSchema = {}
   };
 }
 
+export function createBudgetedContext({ items = [], budgetChars = 12000, topic } = {}) {
+  const candidates = items
+    .filter((item) => item && typeof item.id === "string" && typeof item.text === "string")
+    .map((item, index) => ({ ...item, tier: item.tier ?? index }));
+  const topical = topic
+    ? candidates.filter((item) =>
+        `${item.topic ?? ""} ${item.id}`.toLowerCase().includes(topic.toLowerCase()),
+      )
+    : candidates;
+  const pool = topical.length > 0 ? topical : candidates;
+  let remaining = Math.max(0, budgetChars);
+  const loaded = [];
+  const skipped = candidates
+    .filter((item) => !pool.includes(item))
+    .map((item) => ({ id: item.id, reason: "topic_mismatch" }));
+  const context = {};
+
+  for (const item of [...pool].sort((left, right) => left.tier - right.tier)) {
+    const view = createContextEconomyView({ text: item.text, level: "budgeted_context" });
+    if (view.output_chars <= remaining) {
+      context[item.id] = view.output;
+      remaining -= view.output_chars;
+      loaded.push(item.id);
+    } else {
+      skipped.push({ id: item.id, reason: "budget_exhausted" });
+    }
+  }
+
+  return {
+    record_type: "budgeted_context",
+    budget_chars: budgetChars,
+    used_chars: budgetChars - remaining,
+    topic: topic ?? null,
+    loaded,
+    skipped,
+    fallback_expanded: Boolean(topic && topical.length === 0),
+    context,
+  };
+}
+
 export function validateContextEconomyCore(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error("Context Economy core must be an object");

package/src/runtime/continuity-graph.js

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const continuityGraphSchemaVersion = "0.1.0";
+
+export function getContinuityGraphPath() {
+  return getRuntimeSubsystemPath("memory", "graph.json");
+}
+
+export function createDefaultContinuityGraph() {
+  return {
+    schemaVersion: continuityGraphSchemaVersion,
+    record_type: "continuity_knowledge_graph",
+    humanReadableMirror: ".ma/memory/notes.md",
+    nodes: [],
+    edges: [],
+    lastUpdatedAt: null,
+  };
+}
+
+export function validateContinuityGraph(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("continuity graph must be an object");
+  }
+  if (value.schemaVersion !== continuityGraphSchemaVersion) {
+    throw new Error(`Unsupported continuity graph schemaVersion: ${value.schemaVersion}`);
+  }
+  if (value.record_type !== "continuity_knowledge_graph") {
+    throw new Error("continuity graph has an invalid record_type");
+  }
+  if (!Array.isArray(value.nodes) || !Array.isArray(value.edges)) {
+    throw new Error("continuity graph requires nodes and edges arrays");
+  }
+  for (const node of value.nodes) {
+    if (
+      !node ||
+      typeof node !== "object" ||
+      typeof node.id !== "string" ||
+      typeof node.type !== "string" ||
+      typeof node.label !== "string" ||
+      typeof node.scope !== "string" ||
+      !Number.isInteger(node.mentions) ||
+      node.mentions < 0
+    ) {
+      throw new Error("continuity graph contains an invalid node");
+    }
+  }
+  const nodeIds = new Set(value.nodes.map((node) => node.id));
+  for (const edge of value.edges) {
+    if (
+      !edge ||
+      typeof edge !== "object" ||
+      typeof edge.id !== "string" ||
+      typeof edge.source !== "string" ||
+      typeof edge.target !== "string" ||
+      typeof edge.relation !== "string" ||
+      !nodeIds.has(edge.source) ||
+      !nodeIds.has(edge.target)
+    ) {
+      throw new Error("continuity graph contains an invalid edge");
+    }
+  }
+  return value;
+}
+
+export async function seedContinuityGraphArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("memory"));
+  await writeFileIfMissing(
+    getContinuityGraphPath(),
+    `${JSON.stringify(createDefaultContinuityGraph(), null, 2)}\n`,
+  );
+}
+
+export async function loadContinuityGraph() {
+  return validateContinuityGraph(await readJson(getContinuityGraphPath()));
+}
+
+function stableId(prefix, value) {
+  return `${prefix}:${createHash("sha256").update(value).digest("hex").slice(0, 16)}`;
+}
+
+function deriveEntities(content, explicit = []) {
+  const values = [
+    ...explicit,
+    ...(content.match(/`([^`]+)`|#([a-z][\w-]*)|\b[A-Z][A-Za-z0-9_-]{2,}\b/g) ?? []),
+  ]
+    .map((value) => value.replaceAll("`", "").replace(/^#/, "").trim().toLowerCase())
+    .filter((value) => value.length >= 3 && value.length <= 80);
+  return [...new Set(values)].slice(0, 32);
+}
+
+export function mergeContinuityGraph(
+  graph,
+  { content, scope, timestamp, entities = [], relationships = [] },
+) {
+  const next = validateContinuityGraph(graph);
+  const noteId = stableId("note", `${timestamp}\0${scope}\0${content}`);
+  const entityNames = deriveEntities(content, entities);
+  const nodes = [...next.nodes];
+  const edges = [...next.edges];
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const edgeKeys = new Set(edges.map((edge) => `${edge.source}\0${edge.target}\0${edge.relation}`));
+  const addNode = (node) => {
+    const existing = nodeById.get(node.id);
+    if (existing) {
+      existing.updatedAt = timestamp;
+      existing.mentions = (existing.mentions ?? 0) + (node.mentions ?? 0);
+      return;
+    }
+    nodeById.set(node.id, node);
+    nodes.push(node);
+  };
+  const addEdge = (source, target, relation) => {
+    const key = `${source}\0${target}\0${relation}`;
+    if (source === target || edgeKeys.has(key)) return;
+    edgeKeys.add(key);
+    edges.push({ id: stableId("edge", key), source, target, relation, updatedAt: timestamp });
+  };
+
+  addNode({
+    id: noteId,
+    type: "session",
+    label: `${scope} note`,
+    scope,
+    mentions: 1,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  });
+  const entityIds = entityNames.map((name) => {
+    const id = stableId("entity", name);
+    addNode({
+      id,
+      type: "entity",
+      label: name,
+      scope,
+      mentions: 1,
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    });
+    addEdge(noteId, id, "mentions");
+    return id;
+  });
+  for (let index = 0; index < entityIds.length; index += 1) {
+    for (let other = index + 1; other < entityIds.length; other += 1)
+      addEdge(entityIds[index], entityIds[other], "co_occurs");
+  }
+  for (const relationship of relationships) {
+    if (!relationship || typeof relationship !== "object") continue;
+    const from = stableId("entity", String(relationship.from ?? "").toLowerCase());
+    const to = stableId("entity", String(relationship.to ?? "").toLowerCase());
+    if (nodeById.has(from) && nodeById.has(to) && relationship.relation)
+      addEdge(from, to, String(relationship.relation));
+  }
+  return {
+    ...next,
+    nodes: nodes.slice(-1000),
+    edges: edges.slice(-4000),
+    lastUpdatedAt: timestamp,
+  };
+}
+
+export function queryContinuityGraph(graph, { nodeId, label, depth = 2, limit = 100 } = {}) {
+  const value = validateContinuityGraph(graph);
+  const normalizedLabel = label?.trim().toLowerCase();
+  const boundedLimit = Math.max(1, Math.min(Number(limit) || 100, 1000));
+  const starts = value.nodes.filter(
+    (node) =>
+      node.id === nodeId || (normalizedLabel && node.label.toLowerCase() === normalizedLabel),
+  );
+  if (starts.length === 0) return { nodes: [], edges: [], depth: 0 };
+  const included = new Set(starts.map((node) => node.id));
+  let frontier = [...included];
+  const maxDepth = Math.max(0, Math.min(Number(depth) || 0, 5));
+  for (let level = 0; level < maxDepth; level += 1) {
+    const next = [];
+    for (const edge of value.edges) {
+      if (frontier.includes(edge.source) && !included.has(edge.target)) next.push(edge.target);
+      if (frontier.includes(edge.target) && !included.has(edge.source)) next.push(edge.source);
+    }
+    frontier = [...new Set(next)].slice(0, boundedLimit);
+    frontier.forEach((id) => {
+      included.add(id);
+    });
+    if (frontier.length === 0) break;
+  }
+  const nodes = value.nodes.filter((node) => included.has(node.id)).slice(0, boundedLimit);
+  const ids = new Set(nodes.map((node) => node.id));
+  return {
+    nodes,
+    edges: value.edges.filter((edge) => ids.has(edge.source) && ids.has(edge.target)),
+    depth: maxDepth,
+  };
+}
+
+export async function mergeContinuityGraphEntry(entry) {
+  const graph = await loadContinuityGraph();
+  const next = mergeContinuityGraph(graph, entry);
+  await writeJson(getContinuityGraphPath(), next);
+  return next;
+}

package/src/runtime/continuity-notes.js

@@ -1,8 +1,25 @@
 import fs from "node:fs/promises";
-import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import path from "node:path";
+import {
+  ensureDir,
+  readJson,
+  writeFileIfMissing,
+  writeJson,
+  writeTextAtomically,
+} from "../fs-utils.js";
 import { getRuntimeSubsystemPath } from "../paths.js";
+import { mergeContinuityGraphEntry, seedContinuityGraphArtifacts } from "./continuity-graph.js";
 import { guardLeaderMutation } from "./runtime-state.js";
 
+export const knowledgeScopes = ["personal/local", "project-shared", "team/process", "session-only"];
+let continuityWriteQueue = Promise.resolve();
+const scopeFiles = {
+  "personal/local": "personal.md",
+  "project-shared": "notes.md",
+  "team/process": "team.md",
+  "session-only": "session.md",
+};
+
 export function getContinuityRoot() {
   return getRuntimeSubsystemPath("memory");
 }
@@ -21,6 +38,13 @@ export async function seedContinuityArtifacts() {
     getContinuityNotesPath(),
     "# Continuity Notes\n\nNo continuity notes captured yet.\n",
   );
+  await seedContinuityGraphArtifacts();
+  for (const file of ["personal.md", "team.md", "session.md"]) {
+    await writeFileIfMissing(
+      path.join(getContinuityRoot(), file),
+      `# ${file.replace(".md", "")} knowledge\n\nNo notes captured yet.\n`,
+    );
+  }
   await writeFileIfMissing(
     getContinuityIndexPath(),
     `${JSON.stringify(
@@ -28,6 +52,7 @@ export async function seedContinuityArtifacts() {
         schemaVersion: "0.1.0",
         sessionCount: 0,
         lastUpdatedAt: null,
+        knowledgeScopes,
       },
       null,
       2,
@@ -36,7 +61,17 @@ export async function seedContinuityArtifacts() {
 }
 
 export async function loadContinuityNotes() {
-  return fs.readFile(getContinuityNotesPath(), "utf8");
+  return loadScopedKnowledge({ scopes: ["project-shared", "team/process"] });
+}
+
+export async function loadScopedKnowledge({ scopes = ["project-shared", "team/process"] } = {}) {
+  const selected = scopes.filter((scope) => knowledgeScopes.includes(scope));
+  const notes = await Promise.all(
+    selected.map((scope) =>
+      fs.readFile(path.join(getContinuityRoot(), scopeFiles[scope]), "utf8").catch(() => ""),
+    ),
+  );
+  return notes.filter(Boolean).join("\n\n");
 }
 
 export async function loadContinuityIndex() {
@@ -47,33 +82,43 @@ export async function storeContinuityNote(content, options = {}) {
   const guard = await guardLeaderMutation({
     actor: options.actor,
     kind: "memory-note-write",
-    payload: { content },
+    payload: { content, scope: options.scope ?? "session-only" },
   });
   if (!guard.allowed) {
     return { proposed: true, proposalPath: guard.proposalPath };
   }
 
-  const note = content.trim();
-  if (!note) {
-    throw new Error("memory.store_note requires non-empty content");
-  }
-
-  const [existingNotes, existingIndex] = await Promise.all([
-    loadContinuityNotes(),
-    loadContinuityIndex(),
-  ]);
-  const timestamp = new Date().toISOString();
-  const nextNotes = `${existingNotes.trimEnd()}\n\n## ${timestamp}\n\n${note}\n`;
-  const nextIndex = {
-    ...existingIndex,
-    sessionCount: existingIndex.sessionCount + 1,
-    lastUpdatedAt: timestamp,
-  };
-
-  await Promise.all([
-    fs.writeFile(getContinuityNotesPath(), nextNotes),
-    writeJson(getContinuityIndexPath(), nextIndex),
-  ]);
-
-  return { proposed: false, proposalPath: null, index: nextIndex };
+  const operation = continuityWriteQueue.then(async () => {
+    const note = content.trim();
+    if (!note) throw new Error("memory.store_note requires non-empty content");
+    const scope = options.scope ?? "project-shared";
+    if (!knowledgeScopes.includes(scope)) throw new Error(`Unsupported knowledge scope: ${scope}`);
+    const [existingNotes, existingIndex] = await Promise.all([
+      fs.readFile(path.join(getContinuityRoot(), scopeFiles[scope]), "utf8").catch(() => ""),
+      loadContinuityIndex(),
+    ]);
+    const timestamp = new Date().toISOString();
+    const nextNotes = `${existingNotes.trimEnd()}\n\n## ${timestamp}\n\n${note}\n`;
+    const nextIndex = {
+      ...existingIndex,
+      sessionCount: existingIndex.sessionCount + 1,
+      lastUpdatedAt: timestamp,
+      scopeCounts: {
+        ...(existingIndex.scopeCounts ?? {}),
+        [scope]: (existingIndex.scopeCounts?.[scope] ?? 0) + 1,
+      },
+    };
+    await writeTextAtomically(path.join(getContinuityRoot(), scopeFiles[scope]), nextNotes);
+    await writeJson(getContinuityIndexPath(), nextIndex);
+    await mergeContinuityGraphEntry({
+      content: note,
+      scope,
+      timestamp,
+      entities: options.entities,
+      relationships: options.relationships,
+    });
+    return { proposed: false, proposalPath: null, index: nextIndex };
+  });
+  continuityWriteQueue = operation.catch(() => {});
+  return operation;
 }

package/src/runtime/detached-provider.js

@@ -11,7 +11,10 @@ export function getRuntimeLogsRoot() {
 export function resolveDetachedProvider() {
   const preferred = process.env.MA_DETACHED_PROVIDER ?? "";
   if (preferred === "tmux" || process.env.MA_TMUX_PROVIDER === "1") {
-    const probe = spawnSync("tmux", ["ls"], { encoding: "utf8" });
+    const probe = spawnSync("tmux", ["ls"], {
+      encoding: "utf8",
+      env: buildDetachedEnv(),
+    });
     if (!probe.error) {
       return "tmux";
     }
@@ -23,14 +26,12 @@ export function resolveDetachedProvider() {
 export async function launchDetachedTrack({ trackId, title, command, args = [] }) {
   const provider = resolveDetachedProvider();
   await ensureDir(getRuntimeLogsRoot());
-  const logPath = path.join(getRuntimeLogsRoot(), `${trackId}.log`);
+  const safeTrackId = sanitizeTrackId(trackId);
+  const logPath = path.join(getRuntimeLogsRoot(), `${safeTrackId}.log`);
+  const metadata = `title_present=${Boolean(title)}\ncommand=${commandBasename(command)}\narg_count=${args.length}\n`;
 
   if (provider !== "tmux") {
-    await fs.writeFile(
-      logPath,
-      `provider=none\ntitle=${title}\ncommand=${[command, ...args].join(" ")}\n`,
-      "utf8",
-    );
+    await fs.writeFile(logPath, `provider=none\n${metadata}`, "utf8");
     return {
       provider: "none",
       executionPane: null,
@@ -40,13 +41,12 @@ export async function launchDetachedTrack({ trackId, title, command, args = [] }
     };
   }
 
-  const sessionName = `ma_${trackId.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
-  const shellCommand = `${[command, ...args].join(" ")} > ${logPath} 2>&1`;
-  const started = spawnSync(
-    "tmux",
-    ["new-session", "-d", "-s", sessionName, "/bin/sh", "-lc", shellCommand],
-    { encoding: "utf8" },
-  );
+  const sessionName = `ma_${safeTrackId}`;
+  await fs.writeFile(logPath, `provider=tmux\n${metadata}`, "utf8");
+  const started = spawnSync("tmux", ["new-session", "-d", "-s", sessionName, command, ...args], {
+    encoding: "utf8",
+    env: buildDetachedEnv(),
+  });
 
   if (started.status !== 0) {
     await fs.writeFile(
@@ -64,6 +64,31 @@ export async function launchDetachedTrack({ trackId, title, command, args = [] }
     };
   }
 
+  const piped = spawnSync(
+    "tmux",
+    ["pipe-pane", "-t", sessionName, "-o", `cat >> ${quoteForShell(logPath)}`],
+    { encoding: "utf8", env: buildDetachedEnv() },
+  );
+  if (piped.status !== 0) {
+    spawnSync("tmux", ["kill-session", "-t", sessionName], {
+      encoding: "utf8",
+      env: buildDetachedEnv(),
+    });
+    await fs.writeFile(
+      logPath,
+      `provider=tmux\nstatus=failed\nstderr=${piped.stderr ?? ""}\n`,
+      "utf8",
+    );
+    return {
+      provider: "tmux",
+      executionPane: sessionName,
+      pid: null,
+      logPath,
+      started: false,
+      error: piped.stderr?.trim() || "tmux log pipe failed",
+    };
+  }
+
   return {
     provider: "tmux",
     executionPane: sessionName,
@@ -72,3 +97,46 @@ export async function launchDetachedTrack({ trackId, title, command, args = [] }
     started: true,
   };
 }
+
+const detachedEnvKeys = [
+  "PATH",
+  "HOME",
+  "USERPROFILE",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "LANG",
+  "LC_ALL",
+  "SYSTEMROOT",
+  "COMSPEC",
+  "MA_ROOT",
+];
+
+function buildDetachedEnv() {
+  return Object.fromEntries(
+    detachedEnvKeys
+      .filter((key) => process.env[key] !== undefined)
+      .map((key) => [key, process.env[key]]),
+  );
+}
+
+function sanitizeTrackId(trackId) {
+  const safe = String(trackId ?? "")
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return safe || "track";
+}
+
+function commandBasename(command) {
+  return (
+    String(command ?? "")
+      .split(/[\\/]/)
+      .pop() || "unknown"
+  );
+}
+
+function quoteForShell(value) {
+  // The provider command never enters a shell; this quote is only for tmux's
+  // fixed `cat >> path` pipe command.
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}

package/src/runtime/doctor-report.js

@@ -0,0 +1,18 @@
+export function summarizeDoctorStatuses(statuses) {
+  if (statuses.some((status) => status.kind === "BLOCKED")) return "BLOCKED";
+  if (statuses.some((status) => status.kind === "WARN")) return "READY_WITH_WARNINGS";
+  return "READY";
+}
+
+export function printDoctorStatuses(title, statuses, write = console.log) {
+  write(title);
+  write("=".repeat(title.length));
+  for (const status of statuses) {
+    const label = status.kind.padEnd(7, " ");
+    write(`${label} ${status.label}${status.detail ? `: ${status.detail}` : ""}`);
+  }
+  const result = summarizeDoctorStatuses(statuses);
+  write("");
+  write(`Result: ${result}`);
+  return result;
+}