@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/scripts/skill-conflicts.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+/** Workspace vs packaged repo skill content conflicts (warn-only). */
+import fs from "node:fs";
+import path from "node:path";
+import { isRecord } from "./hook-input.ts";
+
+/** The workspace skills dir codex and antigravity read; sync fills it with links. */
+export const WORKSPACE_SKILLS_REL = ".agents/skills";
+/** The stock skills, under the stock root (this repo, or the installed package). */
+export const STOCK_SKILLS_REL = "agents/skills";
+export const PACKAGED_SKILLS_REL: string = path.join(
+  "node_modules",
+  "@workerstack",
+  "repo",
+  ...STOCK_SKILLS_REL.split("/"),
+);
+
+export function listSkillDirNames(skillsRoot: string): string[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+  } catch (err) {
+    if (isRecord(err) && err.code === "ENOENT") return [];
+    throw err;
+  }
+  const out: string[] = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory() || ent.name.startsWith(".")) continue;
+    const skillMd = path.join(skillsRoot, ent.name, "SKILL.md");
+    try {
+      if (!fs.statSync(skillMd).isFile()) continue;
+    } catch {
+      continue;
+    }
+    out.push(ent.name);
+  }
+  out.sort((a, b) => a.localeCompare(b));
+  return out;
+}
+
+function readSkillMd(skillsRoot: string, name: string): Buffer | null {
+  const abs = path.join(skillsRoot, name, "SKILL.md");
+  try {
+    return fs.readFileSync(abs);
+  } catch {
+    return null;
+  }
+}
+
+/** Names in both trees whose SKILL.md bytes differ. */
+export interface SkillConflict {
+  name: string;
+  workspacePath: string;
+  packagedPath: string;
+}
+
+export function findSkillContentConflicts({
+  workspaceSkillsDir,
+  packagedSkillsDir,
+}: { workspaceSkillsDir?: string; packagedSkillsDir?: string } = {}): SkillConflict[] {
+  if (!workspaceSkillsDir || !packagedSkillsDir) return [];
+  const packaged = listSkillDirNames(packagedSkillsDir);
+  if (!packaged.length) return [];
+  const conflicts: SkillConflict[] = [];
+  for (const name of packaged) {
+    const ws = readSkillMd(workspaceSkillsDir, name);
+    if (ws == null) continue;
+    const pkg = fs.readFileSync(path.join(packagedSkillsDir, name, "SKILL.md"));
+    if (Buffer.compare(ws, pkg) !== 0) {
+      conflicts.push({
+        name,
+        workspacePath: path.join(workspaceSkillsDir, name, "SKILL.md"),
+        packagedPath: path.join(packagedSkillsDir, name, "SKILL.md"),
+      });
+    }
+  }
+  return conflicts;
+}
+
+export function formatSkillConflictWarn(name: string): string {
+  return `skill \`${name}\` differs from packaged repo; re-init overwrites`;
+}

package/cli/scripts/speak.ts

@@ -0,0 +1,370 @@
+#!/usr/bin/env bun
+/** Text-to-speech (output only). Providers: elevenlabs, openai. */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveRoots } from "./workspace-root.ts";
+import { loadOptionalConsumerEnv } from "./doctor.ts";
+import { isRecord } from "./hook-input.ts";
+import { readEnv } from "../env.ts";
+import type { Env } from "../env.ts";
+
+export type Provider = "elevenlabs" | "openai";
+
+export interface SpeakCfg {
+  filePath: string;
+  providerPref: string;
+  elevenlabs: { apiKey: string; voiceId: string; modelId: string };
+  openai: { apiKey: string; voice: string; model: string };
+}
+
+/** The slice of a fetch Response this script reads. */
+export interface FetchResult {
+  ok?: boolean;
+  status?: number;
+  text?: () => Promise<string>;
+  json?: () => Promise<unknown>;
+  arrayBuffer?: () => Promise<ArrayBuffer | Uint8Array>;
+  body?: unknown;
+}
+
+export interface FetchInit {
+  method?: string | undefined;
+  headers?: Record<string, string> | undefined;
+  body?: string | undefined;
+}
+
+export type FetchFn = (url: string, init: FetchInit) => Promise<FetchResult>;
+
+export interface ParsedArgv {
+  _: string[];
+  flags: Record<string, string>;
+}
+
+export interface SpeakLog {
+  log(msg: string): void;
+  error(msg: string): void;
+}
+
+export interface SpeakMainOpts {
+  env?: Env | undefined;
+  home?: string | undefined;
+  cwd?: string | undefined;
+  fetchFn?: FetchFn | undefined;
+  log?: SpeakLog | undefined;
+  spawn?: SpeakSpawn | undefined;
+}
+
+interface ProviderOpts {
+  provider?: string | undefined;
+  cfg: SpeakCfg;
+  fetchFn?: FetchFn | undefined;
+}
+
+export interface SayOpts extends ProviderOpts {
+  text?: string | undefined;
+  voice?: string | undefined;
+  out?: string | undefined;
+  play?: boolean | string | undefined;
+  cwd?: string | undefined;
+  spawn?: SpeakSpawn | undefined;
+}
+
+export const DEFAULT_ELEVEN_VOICE = "JBFqnCBsd6RMkjVDRZzb";
+export const DEFAULT_ELEVEN_MODEL = "eleven_multilingual_v2";
+export const DEFAULT_OPENAI_VOICE = "coral";
+export const DEFAULT_OPENAI_MODEL = "gpt-4o-mini-tts";
+export const OPENAI_VOICES: string[] = [
+  "alloy",
+  "ash",
+  "ballad",
+  "coral",
+  "echo",
+  "fable",
+  "nova",
+  "onyx",
+  "sage",
+  "shimmer",
+];
+export const USAGE =
+  "usage: speak whoami | voices | say --text T [--provider elevenlabs|openai] [--voice ID] [--out path] [--play]";
+const ELEVEN_API = "https://api.elevenlabs.io/v1";
+const OPENAI_API = "https://api.openai.com/v1";
+export const SETUP = "bun repo setup speak";
+export const SPEAK_DIR = ".tmp/repo/speak";
+export const NEED_KEY =
+  "missing ELEVENLABS_API_KEY or OPENAI_API_KEY (or ~/.workerstack/speak.json). setup: bun repo setup speak";
+export const NEED_ELEVEN =
+  "missing ELEVENLABS_API_KEY (or ~/.workerstack/speak.json elevenlabs.apiKey). setup: bun repo setup speak";
+export const NEED_OPENAI =
+  "missing OPENAI_API_KEY (or ~/.workerstack/speak.json openai.apiKey). setup: bun repo setup speak";
+
+export function formatHttpError(status: unknown, body: unknown, provider: string): string {
+  const n = Number(status);
+  const raw = String(body || "");
+  if (/missing_permissions/i.test(raw)) {
+    return `${provider} key present but missing permission (${n || status}). setup: ${SETUP}`;
+  }
+  const auth = n === 401 || n === 403 || /unauthorized|invalid.?api.?key|authentication/i.test(raw);
+  if (auth) {
+    return `${provider} key missing or rejected (${n || status}). setup: ${SETUP}`;
+  }
+  return `${status} ${raw.slice(0, 200)}`.trim();
+}
+
+export function parseArgv(argv: unknown): ParsedArgv {
+  const out: ParsedArgv = { _: [], flags: {} };
+  const args: string[] = Array.isArray(argv) ? argv.filter((a): a is string => typeof a === "string") : [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!; // i < args.length
+    if (a === "--") {
+      out._.push(...args.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("--") && a.length > 2) {
+      const key = a.slice(2);
+      const nxt = args[i + 1];
+      if (nxt && !nxt.startsWith("--")) {
+        out.flags[key] = nxt;
+        i += 1;
+      } else out.flags[key] = "1";
+    } else out._.push(a);
+  }
+  return out;
+}
+
+function readJson(p: string): Record<string, unknown> {
+  try {
+    const j: unknown = JSON.parse(fs.readFileSync(p, "utf8"));
+    if (isRecord(j)) return j;
+  } catch {
+    /* none */
+  }
+  return {};
+}
+
+function str(v: unknown, fallback = ""): string {
+  const s = String(v ?? "").trim();
+  return s || fallback;
+}
+
+export function loadCfg({ env = readEnv(), home = os.homedir() }: { env?: Env; home?: string } = {}): SpeakCfg {
+  const filePath = path.join(home, ".workerstack", "speak.json");
+  const file = readJson(filePath);
+  const eleven = isRecord(file.elevenlabs) ? file.elevenlabs : {};
+  const openai = isRecord(file.openai) ? file.openai : {};
+  return {
+    filePath,
+    providerPref: str(env.SPEAK_PROVIDER || file.provider).toLowerCase(),
+    elevenlabs: {
+      apiKey: str(env.ELEVENLABS_API_KEY || eleven.apiKey || file.apiKey),
+      voiceId: str(env.ELEVENLABS_VOICE_ID || eleven.voiceId || file.voiceId, DEFAULT_ELEVEN_VOICE),
+      modelId: str(env.ELEVENLABS_MODEL_ID || eleven.modelId || file.modelId, DEFAULT_ELEVEN_MODEL),
+    },
+    openai: {
+      apiKey: str(env.OPENAI_API_KEY || openai.apiKey),
+      voice: str(env.OPENAI_TTS_VOICE || openai.voice, DEFAULT_OPENAI_VOICE),
+      model: str(env.OPENAI_TTS_MODEL || openai.model, DEFAULT_OPENAI_MODEL),
+    },
+  };
+}
+
+export function resolveProvider(cfg: SpeakCfg | null | undefined, flagProvider?: string): Provider {
+  const want = str(flagProvider || (cfg && cfg.providerPref)).toLowerCase();
+  if (want && want !== "elevenlabs" && want !== "openai") {
+    throw new Error("provider must be elevenlabs or openai");
+  }
+  if (want === "elevenlabs") {
+    if (!cfg?.elevenlabs.apiKey) throw new Error(NEED_ELEVEN);
+    return "elevenlabs";
+  }
+  if (want === "openai") {
+    if (!cfg?.openai.apiKey) throw new Error(NEED_OPENAI);
+    return "openai";
+  }
+  if (cfg?.elevenlabs.apiKey) return "elevenlabs";
+  if (cfg?.openai.apiKey) return "openai";
+  throw new Error(NEED_KEY);
+}
+
+interface ApiOpts {
+  method?: string | undefined;
+  headers?: Record<string, string> | undefined;
+  body?: Record<string, unknown> | undefined;
+  raw?: boolean | undefined;
+  fetchFn?: FetchFn | undefined;
+}
+
+async function apiFetch(url: string, opts: ApiOpts & { raw: true }): Promise<Buffer>;
+async function apiFetch(url: string, opts: ApiOpts): Promise<unknown>;
+async function apiFetch(url: string, { method = "GET", headers, body, raw, fetchFn }: ApiOpts): Promise<unknown> {
+  // The global fetch returns a full Response, which carries every FetchResult field.
+  const fn: FetchFn | undefined = fetchFn || (globalThis.fetch as FetchFn | undefined);
+  if (typeof fn !== "function") throw new Error("fetch is not available");
+  const res = await fn(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res || !res.ok) {
+    const status = res && res.status != null ? res.status : "err";
+    let t = "";
+    try {
+      t = res && typeof res.text === "function" ? await res.text() : "";
+    } catch {
+      /* none */
+    }
+    const provider = url.includes("elevenlabs") ? "elevenlabs" : "openai";
+    throw new Error(formatHttpError(status, t, provider));
+  }
+  if (raw) {
+    if (typeof res.arrayBuffer === "function") {
+      return Buffer.from(new Uint8Array(await res.arrayBuffer()));
+    }
+    if (Buffer.isBuffer(res.body)) return res.body;
+    return Buffer.from(Array.isArray(res.body) ? (res.body as number[]) : []);
+  }
+  if (typeof res.json === "function") return res.json();
+  return {};
+}
+
+export async function whoami({ provider, cfg, fetchFn }: ProviderOpts): Promise<string> {
+  const p = resolveProvider(cfg, provider);
+  if (p === "elevenlabs") {
+    try {
+      const u = await apiFetch(`${ELEVEN_API}/user`, {
+        headers: { "xi-api-key": cfg.elevenlabs.apiKey },
+        fetchFn,
+      });
+      const user = isRecord(u) ? u : {};
+      const email = user.email ? String(user.email) : "ok";
+      const tier = isRecord(user.subscription) && user.subscription.tier ? String(user.subscription.tier) : "-";
+      return `elevenlabs  ${email}  tier=${tier}`;
+    } catch (e) {
+      const msg = errMessage(e);
+      if (/missing permission/i.test(msg)) {
+        return "elevenlabs  ok (scoped key; whoami needs user_read). voices/say still work";
+      }
+      throw e;
+    }
+  }
+  await apiFetch(`${OPENAI_API}/models`, {
+    headers: { Authorization: `Bearer ${cfg.openai.apiKey}` },
+    fetchFn,
+  });
+  return "openai ok";
+}
+
+export async function voices({ provider, cfg, fetchFn }: ProviderOpts): Promise<string> {
+  const p = resolveProvider(cfg, provider);
+  if (p === "openai") return OPENAI_VOICES.join("\n");
+  const j = await apiFetch(`${ELEVEN_API}/voices`, {
+    headers: { "xi-api-key": cfg.elevenlabs.apiKey },
+    fetchFn,
+  });
+  const list: unknown[] = isRecord(j) && Array.isArray(j.voices) ? j.voices : [];
+  return list.map((v) => (isRecord(v) ? `${v.voice_id}  ${v.name}` : "undefined  undefined")).join("\n");
+}
+
+function errMessage(e: unknown): string {
+  const m = isRecord(e) ? e.message : undefined;
+  return String(m || e);
+}
+
+/** The speaker edge: plays one audio file with the platform's player. */
+export type SpeakSpawn = (cmd: string, args: string[], opts: { stdio: "ignore" }) => unknown;
+
+export function playPath(dest: string, spawn: SpeakSpawn, platform: NodeJS.Platform = process.platform): void {
+  const bin = platform === "darwin" ? "afplay" : "ffplay";
+  const args = platform === "darwin" ? [dest] : ["-nodisp", "-autoexit", dest];
+  spawn(bin, args, { stdio: "ignore" });
+}
+
+export async function say({
+  text,
+  voice,
+  out,
+  play,
+  provider,
+  cfg,
+  cwd = process.cwd(),
+  fetchFn,
+  spawn = spawnSync,
+}: SayOpts): Promise<string> {
+  if (!str(text)) throw new Error("say needs --text");
+  const p = resolveProvider(cfg, provider);
+  let buf: Buffer;
+  if (p === "elevenlabs") {
+    const id = str(voice, cfg.elevenlabs.voiceId);
+    buf = await apiFetch(`${ELEVEN_API}/text-to-speech/${encodeURIComponent(id)}?output_format=mp3_44100_128`, {
+      method: "POST",
+      headers: {
+        "xi-api-key": cfg.elevenlabs.apiKey,
+        "Content-Type": "application/json",
+      },
+      body: { text: str(text), model_id: cfg.elevenlabs.modelId },
+      raw: true,
+      fetchFn,
+    });
+  } else {
+    const v = str(voice, cfg.openai.voice);
+    buf = await apiFetch(`${OPENAI_API}/audio/speech`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${cfg.openai.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: { model: cfg.openai.model, input: str(text), voice: v },
+      raw: true,
+      fetchFn,
+    });
+  }
+  const dest = str(out) || path.join(resolveRoots({}, { cwd }).root, SPEAK_DIR, `say-${Date.now()}.mp3`);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, buf);
+  if (play === true || play === "true" || play === "1") playPath(dest, spawn);
+  return dest;
+}
+
+export async function main(argv: string[], opts: SpeakMainOpts = {}): Promise<number> {
+  const { _, flags } = parseArgv(argv);
+  if (!opts.env) await loadOptionalConsumerEnv();
+  const env = opts.env || readEnv();
+  const home = opts.home || os.homedir();
+  const cwd = opts.cwd || process.cwd();
+  const fetchFn = opts.fetchFn || (globalThis.fetch as FetchFn | undefined);
+  const log: SpeakLog = opts.log || console;
+  const cfg = loadCfg({ env, home });
+  const verb = String(_[0] || "").toLowerCase();
+  try {
+    if (verb === "whoami") {
+      log.log(await whoami({ provider: flags.provider, cfg, fetchFn }));
+      return 0;
+    }
+    if (verb === "voices") {
+      log.log(await voices({ provider: flags.provider, cfg, fetchFn }));
+      return 0;
+    }
+    if (verb === "say") {
+      const dest = await say({
+        text: flags.text,
+        voice: flags.voice,
+        out: flags.out,
+        play: flags.play,
+        provider: flags.provider,
+        cfg,
+        cwd,
+        fetchFn,
+        spawn: opts.spawn,
+      });
+      log.log(dest);
+      return 0;
+    }
+    log.error(USAGE);
+    return 1;
+  } catch (e) {
+    log.error(errMessage(e));
+    return 1;
+  }
+}

package/cli/scripts/strategy.ts

@@ -0,0 +1,168 @@
+/**
+ * The strategy domain: how a plan or roadmap gets implemented, and the things that follow from it.
+ *
+ *   closing line   the one line that asks for approval or a handoff, rendered and parsed here and nowhere else
+ *   approval       what a reply `y`, `y <strategy>`, `h`, `h fast` or `h deep` means
+ *   session stamp  which plan this session reviews; the plan file is the truth, the stamp only points at it
+ *   mode           how a session handles a question: ask, auto or away
+ *
+ * Node builtins and `canonicalPath` only.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { canonicalPath } from "./workspace-root.ts";
+
+type Strategy = "default" | "review-fast" | "review-deep";
+type ReviewStrategy = Exclude<Strategy, "default">;
+type Approvable = { kind: "plan" | "roadmap"; serial: number; strategy: Strategy };
+type Approval =
+  | { kind: "approve"; strategy: Strategy | null }
+  | { kind: "handoff"; strategy: Strategy | null }
+  | { kind: "unknown"; word: string };
+export type ActiveReview = { plan: string; serial: number; strategy: ReviewStrategy };
+
+export const STRATEGIES: readonly Strategy[] = ["default", "review-fast", "review-deep"];
+
+export const MODES = ["ask", "auto", "away"] as const;
+export type Mode = (typeof MODES)[number];
+
+/** @param v @returns */
+export function parseMode(v: unknown): Mode | null {
+  return MODES.find((m) => m === v) ?? null;
+}
+
+/**
+ * Harnesses whose child and parent payloads differ by a marker the gate reads, so the review deny is enforced.
+ * Phase 6 probe (live, 2026-11-07):
+ *   claude  child has agent_id and agent_type; Grok's wire shape is Claude's (`harnessOf` says claude), and its child
+ *           has subagentType, so "claude" covers Grok too
+ *   codex   child has agent_id and agent_type
+ *   antigravity, cursor  a child carries no marker; it only has a different session id. Not enforced.
+ */
+export const ENFORCED_HARNESSES: ReadonlySet<"claude" | "codex" | "antigravity" | "cursor"> = new Set<
+  "claude" | "codex" | "antigravity" | "cursor"
+>(["claude", "codex"]);
+
+/** @param v @returns */
+export function parseStrategy(v: unknown): Strategy | null {
+  return STRATEGIES.find((s) => s === v) ?? null;
+}
+
+/**
+ * The implementer agent for a review strategy. review-fast starts fast and escalates; there is no attempt 3.
+ * @param s
+ * @param attempt
+ * @returns
+ */
+export function implementerOf(s: ReviewStrategy, attempt: 1 | 2): "implementer-fast" | "implementer-deep" {
+  return s === "review-fast" && attempt === 1 ? "implementer-fast" : "implementer-deep";
+}
+
+const itemText = (i: Approvable) => `${i.kind} ${i.serial} (strategy: ${i.strategy})`;
+
+const HANDOFFS = '"h" / "h fast" / "h deep" for a fresh session';
+const handoffStrategy = (w: string): Strategy | null =>
+  w === "fast" ? "review-fast" : w === "deep" ? "review-deep" : null;
+
+/**
+ * The only renderer of the approval line. The first `or` list holds every strategy not held by all items;
+ * the second offers a handoff to a fresh session.
+ * @param items
+ */
+export function closingLine(items: Approvable[]) {
+  if (!items.length) throw new Error("closingLine needs at least one item");
+  const others = STRATEGIES.filter((s) => !items.every((i) => i.strategy === s));
+  return `Reply "y" to run ${items.map(itemText).join(", then ")}, or ${others.map((s) => `"y ${s}"`).join(" / ")}, or ${HANDOFFS}.`;
+}
+
+const CLOSING_RE =
+  /^Reply "y" to run ((?:plan|roadmap) \d+ \(strategy: [a-z-]+\)(?:, then (?:plan|roadmap) \d+ \(strategy: [a-z-]+\))*), or /;
+const ITEM_RE = /^(plan|roadmap) (\d+) \(strategy: ([a-z-]+)\)$/;
+
+/**
+ * The items a closing line names, or null unless the line is exactly what `closingLine` renders for them.
+ * Markdown around the line (bold, backticks, a quote marker) is ignored.
+ * @param line
+ * @returns
+ */
+export function parseClosingLine(line: string): Approvable[] | null {
+  const text = String(line)
+    .replace(/^[\s`*_>]+/, "")
+    .replace(/[\s`*_]+$/, "");
+  const m = CLOSING_RE.exec(text);
+  if (!m) return null;
+  const items: Approvable[] = [];
+  for (const part of (m[1] /* group 1 is not optional in CLOSING_RE */ as string).split(", then ")) {
+    const it = ITEM_RE.exec(part);
+    const kind = it?.[1];
+    const strategy = parseStrategy(it?.[3]);
+    if (!it || (kind !== "plan" && kind !== "roadmap") || !strategy) return null;
+    items.push({ kind, serial: Number(it[2]), strategy });
+  }
+  return closingLine(items) === text ? items : null;
+}
+
+/**
+ * A reply of `y` (keep each file's strategy) or `y <strategy>`, or a handoff `h` (keep) or `h fast` / `h deep`.
+ * Null when the prompt is neither a y nor an h reply.
+ * @param prompt
+ * @returns
+ */
+export function parseApproval(prompt: string): Approval | null {
+  const m = /^([yh])(?:\s+(\S+))?$/i.exec(String(prompt).trim());
+  if (!m) return null;
+  const kind = m[1]?.toLowerCase() === "h" ? "handoff" : "approve";
+  const word = m[2];
+  if (word === undefined) return { kind, strategy: null };
+  const strategy = kind === "handoff" ? handoffStrategy(word.toLowerCase()) : parseStrategy(word.toLowerCase());
+  return strategy ? { kind, strategy } : { kind: "unknown", word };
+}
+
+/** @param root @param sid */
+export function stampPath(root: string, sid: string): string {
+  return path.join(root, ".tmp", "repo", "sessions", String(sid).replace(/[^\w-]/g, ""), "strategy.json");
+}
+
+/**
+ * Point the session at a plan. Same content every time; a temp file in the same directory, then a rename,
+ * so a reader never sees half a stamp.
+ * @param root @param sid @param planAbs
+ */
+export function writeStamp(root: string, sid: string, planAbs: string): void {
+  const dest = stampPath(root, sid);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify({ plan: canonicalPath(path.resolve(planAbs)) })}\n`);
+    fs.renameSync(tmp, dest);
+  } catch (err) {
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * The review this session runs: the stamped plan, when its own frontmatter says in-progress and review-*.
+ * @param root @param sid
+ * @returns
+ */
+export function activeReview(root: string, sid: string): ActiveReview | null {
+  try {
+    const stamp = JSON.parse(fs.readFileSync(stampPath(root, sid), "utf8"));
+    const plan = typeof stamp === "object" && stamp !== null && "plan" in stamp ? stamp.plan : null;
+    if (typeof plan !== "string") return null;
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(fs.readFileSync(plan, "utf8"));
+    if (!m) return null;
+    const fm: Record<string, string> = {};
+    for (const line of (m[1] /* group 1 is not optional in the frontmatter regex */ as string).split(/\r?\n/)) {
+      const kv = /^([a-z]+):\s*(.*)$/.exec(line);
+      if (kv)
+        fm[kv[1] /* both groups always match */ as string] = (kv[2] /* both groups always match */ as string).trim();
+    }
+    const strategy = parseStrategy(fm.strategy);
+    if (fm.status !== "in-progress" || !strategy || strategy === "default") return null;
+    return { plan, serial: Number(fm.serial), strategy };
+  } catch {
+    return null;
+  }
+}