@blackbelt-technology/pi-agent-dashboard 0.4.5 → 0.5.0

package/packages/shared/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Barrel re-exports for selected shared symbols. Most consumers import
+ * directly from per-file paths (`@blackbelt-technology/pi-dashboard-shared/<file>.js`)
+ * via the package's `exports` map. This barrel exists for symbols that
+ * would otherwise be cumbersome to wire — currently the doctor core.
+ *
+ * Added by change: doctor-rich-output.
+ */
+export * from "./doctor-core.js";

package/packages/shared/src/installable-list.ts

@@ -0,0 +1,152 @@
+/**
+ * installable-list.ts — types and helpers for ~/.pi/dashboard/installable.json.
+ *
+ * This file describes the set of packages the dashboard needs installed.
+ * Electron seeds the file on first run; Bridge / Standalone ignore it (file-absent
+ * path is a no-op in the server bootstrap). The server reads it during bootstrap.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type InstallableKind = "npm" | "pi-extension";
+
+export interface InstallablePackage {
+  name: string;
+  /** Semver range or "*". */
+  version: string;
+  required: boolean;
+  kind: InstallableKind;
+  deprecated?: boolean;
+  defaultOff?: boolean;
+}
+
+export interface InstallableList {
+  version: string;
+  packages: InstallablePackage[];
+}
+
+export interface MergeResult {
+  list: InstallableList;
+  warnings: string[];
+}
+
+const VALID_KINDS: ReadonlySet<string> = new Set<InstallableKind>(["npm", "pi-extension"]);
+
+function defaultConfigDir(): string {
+  return path.join(os.homedir(), ".pi", "dashboard");
+}
+
+function installablePath(configDir: string): string {
+  return path.join(configDir, "installable.json");
+}
+
+/**
+ * Read `~/.pi/dashboard/installable.json` (or `configDir/installable.json`).
+ *
+ * Returns `null` when the file is absent. Logs a warning and drops entries
+ * with an invalid `kind` field. Does NOT create the file.
+ */
+export async function readInstallableList(
+  configDir?: string,
+): Promise<InstallableList | null> {
+  const dir = configDir ?? defaultConfigDir();
+  const filePath = installablePath(dir);
+
+  let raw: string;
+  try {
+    raw = await fs.promises.readFile(filePath, "utf-8");
+  } catch (err: any) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+
+  const parsed = JSON.parse(raw) as InstallableList;
+
+  const validPackages: InstallablePackage[] = [];
+  for (const pkg of parsed.packages ?? []) {
+    if (!VALID_KINDS.has(pkg.kind)) {
+      console.warn(
+        `[installable-list] Dropping entry "${pkg.name}" with unknown kind "${pkg.kind}".`,
+      );
+      continue;
+    }
+    validPackages.push(pkg);
+  }
+
+  return { version: parsed.version, packages: validPackages };
+}
+
+/**
+ * Atomically write `list` to `configDir/installable.json`.
+ * Writes a temp file then renames so readers never see a partial write.
+ */
+export async function writeInstallableList(
+  list: InstallableList,
+  configDir?: string,
+): Promise<void> {
+  const dir = configDir ?? defaultConfigDir();
+  const filePath = installablePath(dir);
+  const tmpPath = filePath + ".tmp." + process.pid;
+
+  await fs.promises.mkdir(dir, { recursive: true });
+  await fs.promises.writeFile(tmpPath, JSON.stringify(list, null, 2), "utf-8");
+  await fs.promises.rename(tmpPath, filePath);
+}
+
+/**
+ * Pure merge: reconcile a user's `existing` list against the `bundled` defaults.
+ *
+ * Rules:
+ * - Package in both: keep user's pinned version (user wins); emit a warning when
+ *   the bundled default differs.
+ * - Package in existing but NOT in bundled: keep it, set `deprecated: true`, emit warning.
+ * - New `required: true` package in bundled: add it.
+ * - New `required: false` package in bundled: add it with `defaultOff: true`.
+ * - Result version marker comes from `bundled.version`.
+ */
+export function mergeInstallableList(
+  existing: InstallableList,
+  bundled: InstallableList,
+): MergeResult {
+  const warnings: string[] = [];
+  const bundledMap = new Map(bundled.packages.map((p) => [p.name, p]));
+  const existingMap = new Map(existing.packages.map((p) => [p.name, p]));
+
+  const merged: InstallablePackage[] = [];
+
+  // Walk existing packages.
+  for (const pkg of existing.packages) {
+    const bundledPkg = bundledMap.get(pkg.name);
+    if (!bundledPkg) {
+      // Dropped in bundled → deprecate.
+      warnings.push(
+        `Package "${pkg.name}" is no longer in the bundled list and has been marked deprecated.`,
+      );
+      merged.push({ ...pkg, deprecated: true });
+    } else {
+      // Present in both → user version wins.
+      if (pkg.version !== bundledPkg.version) {
+        warnings.push(
+          `Package "${pkg.name}" is pinned at "${pkg.version}" (bundled default: "${bundledPkg.version}"). User pin preserved.`,
+        );
+      }
+      merged.push({ ...pkg });
+    }
+  }
+
+  // Walk bundled packages not yet in existing.
+  for (const bundledPkg of bundled.packages) {
+    if (existingMap.has(bundledPkg.name)) continue;
+    if (!bundledPkg.required) {
+      merged.push({ ...bundledPkg, defaultOff: true });
+    } else {
+      merged.push({ ...bundledPkg });
+    }
+  }
+
+  return {
+    list: { version: bundled.version, packages: merged },
+    warnings,
+  };
+}

package/packages/shared/src/launch-source-flag.ts

@@ -0,0 +1,14 @@
+/**
+ * Feature flag for the LaunchSource V2 resolver.
+ * Default: true (Phase C cutover). Set LAUNCH_SOURCE_V2=false to revert to
+ * the legacy wizard + mode.json path for debugging.
+ *
+ * TODO: remove LAUNCH_SOURCE_V2 flag in follow-up change after Phase C ships
+ * without regressions for one release cycle. The flag and its CI matrix
+ * entry should be deleted at that point.
+ */
+export function isLaunchSourceV2Enabled(env: Record<string, string | undefined>): boolean {
+  const val = env["LAUNCH_SOURCE_V2"];
+  if (val === undefined) return true; // default ON in Phase C
+  return val === "true" || val === "1";
+}

package/packages/shared/src/launch-source-types.ts

@@ -0,0 +1,18 @@
+/**
+ * LaunchSource — discriminated union describing how the dashboard server was (or should be) started.
+ *
+ * "attach"      — a server is already running; Electron attaches to it.
+ * "devMonorepo" — running from a checked-out monorepo (dev workflow).
+ * "piExtension" — the pi bridge extension owns a server package in node_modules.
+ * "npmGlobal"   — `pi-dashboard` is installed globally via npm.
+ * "extracted"   — bundled Electron resources provide the server (managed install).
+ */
+
+export type SourceKind = "attach" | "devMonorepo" | "piExtension" | "npmGlobal" | "extracted";
+
+export type LaunchSource =
+  | { kind: "attach"; url: string; starter: "Bridge" | "Standalone" | "Electron" }
+  | { kind: "devMonorepo"; cliPath: string; cwd: string }
+  | { kind: "piExtension"; cliPath: string; cwd: string }
+  | { kind: "npmGlobal"; cliPath: string; cwd: string }
+  | { kind: "extracted"; cliPath: string; cwd: string; didExtract?: boolean };

package/packages/shared/src/openspec-activity-detector.ts

@@ -40,6 +40,22 @@ const CLI_ARCHIVE_RE = /openspec\s+archive\s+["']?([^\s"']+)["']?/;
 /** Regex to match openspec new change "name" (positional arg) */
 const CLI_NEW_CHANGE_RE = /openspec\s+new\s+change\s+["']?([^\s"']+)["']?/;
 
+/**
+ * OpenSpec change-slug shape: lowercase kebab-case, must start with a letter,
+ * max 64 characters. Mirrors the validation enforced by `openspec new change`.
+ *
+ * Single source of truth for any code that needs to gate a captured token
+ * before treating it as an OpenSpec change name (detector + auto-attach
+ * defense-in-depth in event-wiring.ts).
+ *
+ * See change: fix-uuid-rename-bug.
+ */
+const OPENSPEC_CHANGE_SLUG_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+export function isValidOpenSpecChangeSlug(name: string): boolean {
+  return OPENSPEC_CHANGE_SLUG_RE.test(name);
+}
+
 export function detectOpenSpecActivity(
   toolName: string,
   args: Record<string, unknown> | undefined,
@@ -63,7 +79,7 @@ export function detectOpenSpecActivity(
 
     // Check for openspec change file read → change name detection (passive)
     const changeMatch = path.match(CHANGE_PATH_RE);
-    if (changeMatch) {
+    if (changeMatch && isValidOpenSpecChangeSlug(changeMatch[1])) {
       return { changeName: changeMatch[1], isActive: false };
     }
 
@@ -75,7 +91,7 @@ export function detectOpenSpecActivity(
     if (!path) return null;
 
     const changeMatch = path.match(CHANGE_PATH_RE);
-    if (changeMatch) {
+    if (changeMatch && isValidOpenSpecChangeSlug(changeMatch[1])) {
       return { changeName: changeMatch[1], isActive: true };
     }
 
@@ -94,11 +110,13 @@ export function detectOpenSpecActivity(
       if (!match) return null;
 
       const name = match[1];
-      // Reject flag-shaped tokens (e.g. `--help`, `-h`). The CLI regex capture
-      // groups use `[^\s"']+` which would otherwise treat `--help` as a change
-      // name and trigger downstream auto-attach + auto-rename.
-      // See change: fix-openspec-flag-rename-bug.
-      if (name.startsWith("-")) return null;
+      // Reject any token that is not a valid OpenSpec change slug. Subsumes the
+      // earlier `-`-prefix guard (a leading `-` fails the `[a-z]` first-char
+      // class) and additionally rejects UUIDs, mixed-case, underscored, or
+      // overlong tokens that the CLI regexes' `[^\s"']+` capture group would
+      // otherwise pass through into auto-attach + auto-rename.
+      // See changes: fix-openspec-flag-rename-bug, fix-uuid-rename-bug.
+      if (!isValidOpenSpecChangeSlug(name)) return null;
 
       return { changeName: name, isActive: true };
     }

package/packages/shared/src/platform/detached-spawn.ts

@@ -47,10 +47,18 @@ export interface SpawnDetachedOptions {
   /** Environment for the child. Defaults to `process.env` via Node. */
   env?: NodeJS.ProcessEnv;
   /**
-   * Optional file descriptor for stderr. When omitted, stderr is "ignore".
+   * Optional file descriptor for combined stdout + stderr. When omitted,
+   * BOTH stdout and stderr are "ignore".
+   *
    * Caller is responsible for `fs.openSync(logPath, "a")` and closing the
    * parent's copy after spawn (the child retains its dup via stdio
    * inheritance). File fds survive parent death; pipes do not.
+   *
+   * Routing both streams to a single fd matches what the standalone CLI
+   * (`packages/server/src/cli.ts`) does directly with raw `spawn()`. Prior
+   * to change `fix-electron-extracted-jiti-and-stdio-capture`, only stderr
+   * was captured and clean-startup `console.log` output was silently
+   * dropped (resulting in 0-byte server.log files).
    */
   logFd?: number;
   /**
@@ -123,7 +131,10 @@ export interface SpawnDetachedResult {
  */
 export async function spawnDetached(opts: SpawnDetachedOptions): Promise<SpawnDetachedResult> {
   const stdioIn: "ignore" | "pipe" = opts.stdinMode ?? "ignore";
-  const stdio: ("ignore" | "pipe" | number)[] = [stdioIn, "ignore", opts.logFd ?? "ignore"];
+  // logFd applies to BOTH stdout and stderr. See JSDoc on logFd above and
+  // change: fix-electron-extracted-jiti-and-stdio-capture.
+  const outFd: "ignore" | number = opts.logFd ?? "ignore";
+  const stdio: ("ignore" | "pipe" | number)[] = [stdioIn, outFd, outFd];
 
   let child: ChildProcess;
   let spawnError: string | null = null;

package/packages/shared/src/platform/jj.ts

@@ -0,0 +1,405 @@
+/**
+ * Jujutsu (jj) tool module — Recipe-based API for jj operations the
+ * dashboard runs from multiple call sites (bridge VCS probe, jj-plugin
+ * server routes, session-diff regime-aware enrichment).
+ *
+ * Mirror of `platform/git.ts`: every function is a thin wrapper over
+ * `run(recipe, input)`. No `child_process` imports, no `process.platform`
+ * branches, no inline shell-escape logic.
+ *
+ * **Minimum jj version**: target `>= 0.18.0` for `workspace add -r`,
+ * `op restore`, `fork_point()`, and `--no-pager`. The version is
+ * captured in tool-registry metadata only; no runtime gate yet.
+ *
+ * **Output parsing strategy**: `jj` does not have a stable `--json` flag
+ * across the commands we use. Where parsing is required (`workspaceList`,
+ * `workspaceRoot`, `version`), we parse the human-readable output with
+ * defensive regexes. Mutation commands (`workspaceAdd`, `bookmarkCreate`,
+ * etc.) just check exit codes.
+ *
+ * See change: add-jj-workspace-plugin.
+ */
+import { run, unwrap, type Recipe, type Result } from "./runner.js";
+
+// ── Recipes (pure data) ─────────────────────────────────────────────────────
+
+const JJ_TIMEOUT = 15_000;
+
+interface WithCwd {
+  cwd: string;
+}
+
+/** `jj --version` → semver string (e.g. "jj 0.18.0"). */
+export const JJ_VERSION: Recipe<{}, string | undefined> = {
+  argv: () => ["jj", "--version"],
+  parse: (out) => {
+    const m = out.match(/jj\s+([0-9]+\.[0-9]+\.[0-9]+)/);
+    return m ? m[1] : out.trim() || undefined;
+  },
+  timeout: JJ_TIMEOUT,
+};
+
+/**
+ * `jj workspace root` → absolute path of the current workspace's root.
+ * Errors when cwd is not inside a jj repo.
+ */
+export const JJ_WORKSPACE_ROOT: Recipe<WithCwd, string | undefined> = {
+  argv: () => ["jj", "workspace", "root"],
+  parse: (out) => out.trim() || undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/**
+ * `jj workspace list` → raw output, one workspace per line.
+ * Format (jj 0.18+): `<name>: <change-id-short> <commit-id-short> (...) <desc>`
+ * Caller parses via `parseWorkspaceList`.
+ */
+export const JJ_WORKSPACE_LIST: Recipe<WithCwd, string> = {
+  argv: () => ["jj", "workspace", "list", "--no-pager"],
+  parse: (out) => out,
+  timeout: JJ_TIMEOUT,
+};
+
+/**
+ * `jj workspace add <abs-path> [-r <rev>]` — non-destructive on the
+ * source workspace; creates a new working-copy commit on top of `rev`.
+ */
+export const JJ_WORKSPACE_ADD: Recipe<
+  WithCwd & { destPath: string; baseRev?: string },
+  void
+> = {
+  argv: ({ destPath, baseRev }) => {
+    const argv: string[] = ["jj", "workspace", "add", destPath];
+    if (baseRev) argv.push("-r", baseRev);
+    return argv;
+  },
+  parse: () => undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/** `jj workspace forget <name>` — detaches without deleting files on disk. */
+export const JJ_WORKSPACE_FORGET: Recipe<WithCwd & { name: string }, void> = {
+  argv: ({ name }) => ["jj", "workspace", "forget", name],
+  parse: () => undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/** `jj bookmark create <name> -r <rev>`. */
+export const JJ_BOOKMARK_CREATE: Recipe<
+  WithCwd & { name: string; rev: string },
+  void
+> = {
+  argv: ({ name, rev }) => ["jj", "bookmark", "create", name, "-r", rev],
+  parse: () => undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/**
+ * `jj bookmark list -T 'name ++ "\n"'` — list bookmark names, one per line.
+ * Used by fold-back to check whether a bookmark name already exists.
+ */
+export const JJ_BOOKMARK_LIST: Recipe<WithCwd, string> = {
+  argv: () => ["jj", "bookmark", "list", "-T", 'name ++ "\\n"', "--no-pager"],
+  parse: (out) => out,
+  timeout: JJ_TIMEOUT,
+};
+
+/** `jj git init --colocate` — converts a plain-git cwd into a jj-colocated repo. */
+export const JJ_GIT_INIT_COLOCATE: Recipe<WithCwd, void> = {
+  argv: () => ["jj", "git", "init", "--colocate"],
+  parse: () => undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/** `jj git push --bookmark <name>` — translates jj history to git refs. */
+export const JJ_GIT_PUSH: Recipe<WithCwd & { bookmark: string }, void> = {
+  argv: ({ bookmark }) => ["jj", "git", "push", "--bookmark", bookmark],
+  parse: () => undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/**
+ * `jj diff [--from R1] [--to R2] [-- <path>]` — unified diff output.
+ * Default invocation diffs the working copy (`@`) against its parent (`@-`).
+ */
+export const JJ_DIFF: Recipe<
+  WithCwd & { fromRev?: string; toRev?: string; path?: string },
+  string
+> = {
+  argv: ({ fromRev, toRev, path }) => {
+    const argv: string[] = ["jj", "diff", "--no-pager"];
+    if (fromRev) argv.push("--from", fromRev);
+    if (toRev) argv.push("--to", toRev);
+    if (path) argv.push("--", path);
+    return argv;
+  },
+  parse: (out) => out,
+  timeout: JJ_TIMEOUT,
+};
+
+/**
+ * `jj resolve --list` — newline-separated list of files with conflicts.
+ * Empty output means no conflicts; tolerated exit 1 for "nothing to resolve".
+ */
+export const JJ_RESOLVE_LIST: Recipe<WithCwd, string> = {
+  argv: () => ["jj", "resolve", "--list", "--no-pager"],
+  parse: (out) => out,
+  timeout: JJ_TIMEOUT,
+  tolerate: [1],
+};
+
+/**
+ * `jj op log -T 'id.short() ++ "\n"' --limit 1` — current op id (short).
+ * Used by fold-back to capture pre-rebase state for `op restore`.
+ */
+export const JJ_OP_LOG_HEAD: Recipe<WithCwd, string | undefined> = {
+  argv: () => [
+    "jj", "op", "log",
+    "-T", 'id.short() ++ "\\n"',
+    "--limit", "1",
+    "--no-pager",
+  ],
+  parse: (out) => out.trim().split("\n")[0]?.trim() || undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/** `jj op restore <op-id>` — undo back to the given operation. */
+export const JJ_OP_RESTORE: Recipe<WithCwd & { opId: string }, void> = {
+  argv: ({ opId }) => ["jj", "op", "restore", opId],
+  parse: () => undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/** `jj rebase -d <dest> -s <src>` — rebase src and descendants onto dest. */
+export const JJ_REBASE: Recipe<
+  WithCwd & { dest: string; src: string },
+  void
+> = {
+  argv: ({ dest, src }) => ["jj", "rebase", "-d", dest, "-s", src],
+  parse: () => undefined,
+  timeout: JJ_TIMEOUT,
+};
+
+/**
+ * `jj log -r '<revset>' -T 'change_id.short() ++ "\n"'` —
+ * list change ids matching a revset, one per line.
+ * Used to check for unfolded commits and resolve `fork_point()`.
+ */
+export const JJ_LOG_REVSET: Recipe<
+  WithCwd & { revset: string; template?: string },
+  string
+> = {
+  argv: ({ revset, template }) => [
+    "jj", "log",
+    "-r", revset,
+    "-T", template ?? 'change_id.short() ++ "\\n"',
+    "--no-pager",
+    "--no-graph",
+  ],
+  parse: (out) => out,
+  timeout: JJ_TIMEOUT,
+};
+
+// ── Registry ────────────────────────────────────────────────────────────────
+
+export const JJ_RECIPES = {
+  JJ_VERSION,
+  JJ_WORKSPACE_ROOT,
+  JJ_WORKSPACE_LIST,
+  JJ_WORKSPACE_ADD,
+  JJ_WORKSPACE_FORGET,
+  JJ_BOOKMARK_CREATE,
+  JJ_BOOKMARK_LIST,
+  JJ_GIT_INIT_COLOCATE,
+  JJ_GIT_PUSH,
+  JJ_DIFF,
+  JJ_RESOLVE_LIST,
+  JJ_OP_LOG_HEAD,
+  JJ_OP_RESTORE,
+  JJ_REBASE,
+  JJ_LOG_REVSET,
+} as const;
+
+// ── Public typed API ────────────────────────────────────────────────────────
+
+export function version(): Result<string | undefined> {
+  return run(JJ_VERSION, {}, {});
+}
+
+export function workspaceRoot(input: WithCwd): Result<string | undefined> {
+  return run(JJ_WORKSPACE_ROOT, input, { cwd: input.cwd });
+}
+
+export function workspaceList(input: WithCwd): Result<string> {
+  return run(JJ_WORKSPACE_LIST, input, { cwd: input.cwd });
+}
+
+export function workspaceAdd(
+  input: WithCwd & { destPath: string; baseRev?: string },
+): Result<void> {
+  return run(JJ_WORKSPACE_ADD, input, { cwd: input.cwd });
+}
+
+export function workspaceForget(
+  input: WithCwd & { name: string },
+): Result<void> {
+  return run(JJ_WORKSPACE_FORGET, input, { cwd: input.cwd });
+}
+
+export function bookmarkCreate(
+  input: WithCwd & { name: string; rev: string },
+): Result<void> {
+  return run(JJ_BOOKMARK_CREATE, input, { cwd: input.cwd });
+}
+
+export function bookmarkList(input: WithCwd): Result<string> {
+  return run(JJ_BOOKMARK_LIST, input, { cwd: input.cwd });
+}
+
+export function gitInitColocate(input: WithCwd): Result<void> {
+  return run(JJ_GIT_INIT_COLOCATE, input, { cwd: input.cwd });
+}
+
+export function gitPush(
+  input: WithCwd & { bookmark: string },
+): Result<void> {
+  return run(JJ_GIT_PUSH, input, { cwd: input.cwd });
+}
+
+export function diff(
+  input: WithCwd & { fromRev?: string; toRev?: string; path?: string },
+): Result<string> {
+  return run(JJ_DIFF, input, { cwd: input.cwd });
+}
+
+export function resolveList(input: WithCwd): Result<string> {
+  return run(JJ_RESOLVE_LIST, input, { cwd: input.cwd });
+}
+
+export function opLogHead(input: WithCwd): Result<string | undefined> {
+  return run(JJ_OP_LOG_HEAD, input, { cwd: input.cwd });
+}
+
+export function opRestore(
+  input: WithCwd & { opId: string },
+): Result<void> {
+  return run(JJ_OP_RESTORE, input, { cwd: input.cwd });
+}
+
+export function rebase(
+  input: WithCwd & { dest: string; src: string },
+): Result<void> {
+  return run(JJ_REBASE, input, { cwd: input.cwd });
+}
+
+export function logRevset(
+  input: WithCwd & { revset: string; template?: string },
+): Result<string> {
+  return run(JJ_LOG_REVSET, input, { cwd: input.cwd });
+}
+
+// ── Best-effort wrappers ────────────────────────────────────────────────────
+
+export function versionOr(fallback?: string): string | undefined {
+  return unwrap(version(), fallback);
+}
+
+export function workspaceRootOr(
+  input: WithCwd,
+  fallback?: string,
+): string | undefined {
+  return unwrap(workspaceRoot(input), fallback);
+}
+
+export function workspaceListOr(input: WithCwd, fallback = ""): string {
+  return unwrap(workspaceList(input), fallback);
+}
+
+export function diffOr(
+  input: WithCwd & { fromRev?: string; toRev?: string; path?: string },
+  fallback = "",
+): string {
+  return unwrap(diff(input), fallback);
+}
+
+export function resolveListOr(input: WithCwd, fallback = ""): string {
+  return unwrap(resolveList(input), fallback);
+}
+
+export function opLogHeadOr(
+  input: WithCwd,
+  fallback?: string,
+): string | undefined {
+  return unwrap(opLogHead(input), fallback);
+}
+
+export function bookmarkListOr(input: WithCwd, fallback = ""): string {
+  return unwrap(bookmarkList(input), fallback);
+}
+
+// ── Pure parsers (separate from I/O for unit testability) ───────────────────
+
+export interface JjWorkspaceEntry {
+  /** Workspace name (e.g. "default", "agent-1"). */
+  name: string;
+  /** Short change id of the workspace's working-copy commit. */
+  changeIdShort?: string;
+  /** Short commit id (the underlying git commit when colocated). */
+  commitIdShort?: string;
+  /** Working-copy description, if any. */
+  description?: string;
+}
+
+/**
+ * Parse `jj workspace list` output into structured entries.
+ * Format: `<name>: <change-id-short> <commit-id-short> [(empty)] [(no description set) | <desc>]`
+ *
+ * Defensive: skips lines that don't match the expected shape.
+ */
+export function parseWorkspaceList(raw: string): JjWorkspaceEntry[] {
+  const entries: JjWorkspaceEntry[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx <= 0) continue;
+    const name = trimmed.slice(0, colonIdx).trim();
+    const rest = trimmed.slice(colonIdx + 1).trim();
+    if (!name) continue;
+    // The remainder typically starts with two short ids separated by space.
+    const idMatch = rest.match(/^([0-9a-z]+)\s+([0-9a-f]+)/i);
+    const entry: JjWorkspaceEntry = { name };
+    if (idMatch) {
+      entry.changeIdShort = idMatch[1];
+      entry.commitIdShort = idMatch[2];
+      // Strip jj's parenthesized markers ((empty), (no description set),
+      // (conflict), etc.) and only keep what's left as the description.
+      let after = rest.slice(idMatch[0].length).trim();
+      while (/^\([^)]*\)/.test(after)) {
+        after = after.replace(/^\([^)]*\)\s*/, "");
+      }
+      if (after) {
+        entry.description = after;
+      }
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * Given a workspace root absolute path and the parsed workspace list, find
+ * the workspace name whose working copy lives at that path. Returns
+ * `undefined` if no entry matches.
+ *
+ * Note: `jj workspace list` does not include the workspace path; resolution
+ * by name happens via the bridge probe checking `<workspace-name>@` revsets
+ * separately. For the bridge's purposes, we ALSO read `.jj/repo/working_copy/`
+ * filesystem layout — this parser is a structural fallback only.
+ */
+export function findWorkspaceByName(
+  entries: readonly JjWorkspaceEntry[],
+  name: string,
+): JjWorkspaceEntry | undefined {
+  return entries.find((e) => e.name === name);
+}