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

package/packages/extension/src/bridge.ts

@@ -34,7 +34,7 @@ import { scanChildProcesses } from "./process-scanner.js";
 import type { BridgeContext } from "./bridge-context.js";
 import { filterHiddenCommands, extractFirstMessage, getCurrentModelString } from "./bridge-context.js";
 import { sendStateSync as _sendStateSync, replaySessionEntries as _replaySessionEntries, handleSessionChange as _handleSessionChange } from "./session-sync.js";
-import { sendModelUpdateIfChanged as _sendModelUpdateIfChanged, sendSessionNameIfChanged as _sendSessionNameIfChanged, sendGitInfoIfChanged as _sendGitInfoIfChanged } from "./model-tracker.js";
+import { sendModelUpdateIfChanged as _sendModelUpdateIfChanged, sendSessionNameIfChanged as _sendSessionNameIfChanged, sendGitInfoIfChanged as _sendGitInfoIfChanged, sendJjStateIfChanged as _sendJjStateIfChanged, resetReconnectCaches as _resetReconnectCaches } from "./model-tracker.js";
 import { registerFlowEventListeners, FLOW_EVENT_MAP, SUBAGENT_EVENT_MAP } from "./flow-event-wiring.js";
 import { refreshUiModules, subscribeUiInvalidate, handleUiManagement, type UiModulesBridgeCtx } from "./ui-modules.js";
 
@@ -180,6 +180,7 @@ function initBridge(pi: ExtensionAPI) {
   const trackedPgids = new Set<number>(); // PGIDs captured during bash tool calls
   let lastGitBranch: string | undefined;
   let lastGitPrNumber: number | undefined;
+  let lastJjStateJson: string | undefined; // see change: add-jj-workspace-plugin
   let lastSessionName: string | undefined;
   let cachedHasUI: boolean | undefined = prev.hasUI;
   let cachedModelRegistry: any | undefined = prev.modelRegistry;
@@ -469,7 +470,23 @@ function initBridge(pi: ExtensionAPI) {
     }),
     onReconnect: safe(() => {
       if (!isActive()) return; // Stale listener guard
+      // Reset caches that aren't persisted server-side so the upcoming
+      // 30s tick (and the inline calls below) re-emit the live state.
+      // See change: add-jj-workspace-plugin.
+      const _bc = syncBc();
+      _resetReconnectCaches(_bc);
+      applyBc(_bc);
       sendStateSync();
+      // Force-emit jj/git state for the active session’s cwd. The bridge
+      // doesn't have direct ctx here, so we walk the active session.
+      try {
+        const activeId = (pi as any).getCurrentSessionId?.();
+        const activeCtx = activeId ? (pi as any).getCtx?.(activeId) : (cachedCtx as any);
+        if (activeCtx?.cwd) {
+          sendGitInfoIfChanged(activeCtx.cwd);
+          sendJjStateIfChanged(activeCtx.cwd);
+        }
+      } catch { /* probe failure non-fatal */ }
       replaySessionEntries();
       // Re-send pending PromptBus requests so dashboard dialogs survive browser refresh.
       // Synchronous within this tick to prevent TUI respond() from interleaving.
@@ -611,6 +628,7 @@ function initBridge(pi: ExtensionAPI) {
       lastModel, lastThinkingLevel,
       lastSessionFile, lastSessionDir, lastFirstMessage,
       lastGitBranch, lastGitPrNumber, lastSessionName,
+      lastJjStateJson,
       hasRegisteredOnce,
     };
   }
@@ -628,6 +646,7 @@ function initBridge(pi: ExtensionAPI) {
     lastGitBranch = bc.lastGitBranch;
     lastGitPrNumber = bc.lastGitPrNumber;
     lastSessionName = bc.lastSessionName;
+    lastJjStateJson = bc.lastJjStateJson;
     hasRegisteredOnce = bc.hasRegisteredOnce;
   }
 
@@ -637,6 +656,7 @@ function initBridge(pi: ExtensionAPI) {
   function sendModelUpdateIfChanged() { const bc = syncBc(); _sendModelUpdateIfChanged(bc); applyBc(bc); }
   function sendSessionNameIfChanged() { const bc = syncBc(); _sendSessionNameIfChanged(bc); applyBc(bc); }
   function sendGitInfoIfChanged(cwd: string) { const bc = syncBc(); _sendGitInfoIfChanged(bc, cwd); applyBc(bc); }
+  function sendJjStateIfChanged(cwd: string) { const bc = syncBc(); _sendJjStateIfChanged(bc, cwd); applyBc(bc); }
 
   // Forward all pi core events to the dashboard.
   // Events with special enrichment logic:
@@ -836,7 +856,13 @@ function initBridge(pi: ExtensionAPI) {
     // ── PromptBus setup ──
     // Create bus with dashboard connection wiring.
     // Replaces the old ui-proxy race pattern.
+    // Convert seconds → milliseconds for PromptBus.
+    // Values <= 0 (e.g. -1) are passed through as-is to signal infinite wait.
+    const askUserTimeoutMs = config.askUserPromptTimeoutSeconds > 0
+      ? config.askUserPromptTimeoutSeconds * 1000
+      : -1;
     promptBus = new PromptBus({
+      timeoutMs: askUserTimeoutMs,
       onDashboardRequest: (prompt, component, placement) => {
         connection.send({
           type: "prompt_request" as any,
@@ -1225,8 +1251,9 @@ function initBridge(pi: ExtensionAPI) {
       }
     }).catch(() => { stopSpinner(); });
 
-    // Send initial git info
+    // Send initial git + jj info
     sendGitInfoIfChanged(ctx.cwd);
+    sendJjStateIfChanged(ctx.cwd);
 
     // Start metrics monitor and heartbeat
     startMetricsMonitor();
@@ -1240,10 +1267,11 @@ function initBridge(pi: ExtensionAPI) {
     }, HEARTBEAT_INTERVAL);
     getBridgeState().timers!.push(heartbeatTimer);
 
-    // Start git info + name/model polling
+    // Start git + jj + name/model polling
     gitPollTimer = setInterval(() => {
       if (!isActive()) return;
       sendGitInfoIfChanged(ctx.cwd);
+      sendJjStateIfChanged(ctx.cwd);
       sendSessionNameIfChanged();
       sendModelUpdateIfChanged();
     }, GIT_POLL_INTERVAL);
@@ -1287,6 +1315,7 @@ function initBridge(pi: ExtensionAPI) {
     if (gitPollTimer) clearInterval(gitPollTimer);
     gitPollTimer = setInterval(() => {
       sendGitInfoIfChanged(ctx.cwd);
+      sendJjStateIfChanged(ctx.cwd);
     }, GIT_POLL_INTERVAL);
   }
 

package/packages/extension/src/model-tracker.ts

@@ -4,7 +4,7 @@
  */
 import type { BridgeContext } from "./bridge-context.js";
 import { getCurrentModelString } from "./bridge-context.js";
-import { gatherGitInfo } from "./git-info.js";
+import { gatherGitInfo, gatherJjInfo } from "./vcs-info.js";
 
 /**
  * Send model_update if model or thinking level has changed since last send.
@@ -54,3 +54,37 @@ export function sendGitInfoIfChanged(bc: BridgeContext, cwd: string): void {
     ...info,
   });
 }
+
+/**
+ * Reset the change-detection caches that aren't persisted on the server
+ * side, so a server-restart-driven reconnect re-sends them. `gitBranch`
+ * is already persisted to `.meta.json` so it's tolerable for a tick of
+ * staleness; `jjState` is intentionally NOT persisted (live tool state)
+ * and must be re-emitted on every reconnect.
+ * See change: add-jj-workspace-plugin.
+ */
+export function resetReconnectCaches(bc: BridgeContext): void {
+  bc.lastJjStateJson = undefined;
+  // Defensive: also reset git so a reconnect through a stale state cache
+  // doesn't surface stale branch info if .meta.json wasn't persisted yet.
+  bc.lastGitBranch = undefined;
+  bc.lastGitPrNumber = undefined;
+}
+
+/**
+ * Send jj_state_update if the cwd's jj state has changed since last send.
+ * Sends `null` to clear when the session leaves a jj repo (cwd switch).
+ * No-op when there's nothing to clear and nothing to send.
+ * See change: add-jj-workspace-plugin.
+ */
+export function sendJjStateIfChanged(bc: BridgeContext, cwd: string): void {
+  const state = gatherJjInfo(cwd);
+  const nextJson = state ? JSON.stringify(state) : "";
+  if (nextJson === (bc.lastJjStateJson ?? "")) return;
+  bc.lastJjStateJson = nextJson;
+  bc.connection.send({
+    type: "jj_state_update",
+    sessionId: bc.sessionId,
+    jjState: state ?? null,
+  });
+}

package/packages/extension/src/prompt-bus.ts

@@ -112,9 +112,10 @@ export class PromptBus {
 
     return new Promise<PromptResponse>((resolve) => {
       const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-      const timer = setTimeout(() => {
-        this.cancel(id);
-      }, timeoutMs);
+      // timeoutMs <= 0 means infinite — never fire a cancellation timer.
+      const timer = timeoutMs > 0
+        ? setTimeout(() => { this.cancel(id); }, timeoutMs)
+        : (null as unknown as ReturnType<typeof setTimeout>);
 
       // Distribute to all adapters and collect claims
       const claims: PendingPrompt["claims"] = [];

package/packages/extension/src/session-sync.ts

@@ -6,7 +6,7 @@ import type { BridgeContext } from "./bridge-context.js";
 import { getCurrentModelString, extractFirstMessage, filterHiddenCommands } from "./bridge-context.js";
 import { detectSessionSource } from "./source-detector.js";
 import { replayEntriesAsEvents } from "@blackbelt-technology/pi-dashboard-shared/state-replay.js";
-import { gatherGitInfo } from "./git-info.js";
+import { gatherGitInfo, gatherJjInfo } from "./vcs-info.js";
 import type { FlowInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 
 /**

package/packages/extension/src/vcs-info.ts

@@ -0,0 +1,184 @@
+/**
+ * VCS info gathering — detects git branch/remote/PR AND jj workspace state.
+ * Delegates to shared platform tool modules so there's no inline execSync
+ * and every call benefits from the runner's safety defaults (windowsHide,
+ * timeout, tolerated exit codes).
+ *
+ * jj probing is fast-path-gated: when `<cwd>/.jj/` doesn't exist, NO `jj`
+ * subprocess is spawned. Only sessions inside a jj repo pay the probe cost.
+ *
+ * See changes: platform-command-executor, add-jj-workspace-plugin.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+import * as git from "@blackbelt-technology/pi-dashboard-shared/platform/git.js";
+import * as jj from "@blackbelt-technology/pi-dashboard-shared/platform/jj.js";
+import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+import type { JjState } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import { buildGitLinks, type GitLinks } from "./git-link-builder.js";
+
+export interface GitInfo {
+  gitBranch: string;
+  gitBranchUrl?: string;
+  gitPrNumber?: number;
+  gitPrUrl?: string;
+}
+
+/** Detect the current git branch. Returns short SHA for detached HEAD. */
+export function detectBranch(cwd: string): string | undefined {
+  const ref = git.currentBranchOr({ cwd });
+  if (!ref) return undefined;
+  if (ref === "HEAD") {
+    // Detached HEAD — return short commit SHA
+    return git.headShaOr({ cwd, short: true }) ?? "HEAD";
+  }
+  return ref;
+}
+
+/** Detect the remote origin URL. */
+export function detectRemoteUrl(cwd: string): string | undefined {
+  return git.remoteUrlOr({ cwd });
+}
+
+/** Detect the PR number via gh CLI (best effort). */
+export function detectPrNumber(cwd: string): number | undefined {
+  return git.prNumberOr({ cwd });
+}
+
+/** Gather all git info for a directory. Returns undefined if not a git repo. */
+export function gatherGitInfo(cwd: string): GitInfo | undefined {
+  const branch = detectBranch(cwd);
+  if (!branch) return undefined;
+
+  const remoteUrl = detectRemoteUrl(cwd);
+  const prNumber = detectPrNumber(cwd);
+
+  const links: GitLinks = remoteUrl ? buildGitLinks(remoteUrl, branch, prNumber) : {};
+
+  return {
+    gitBranch: branch,
+    gitBranchUrl: links.branchUrl,
+    gitPrNumber: prNumber,
+    gitPrUrl: links.prUrl,
+  };
+}
+
+// ── Jujutsu probing ────────────────────────────────────────────────────────
+
+/**
+ * Module-level cache: result of resolving `jj` once per process. The tool
+ * registry already memoizes resolutions, but reading it on every probe tick
+ * adds noise to traces. Single read on first probe, sticky for the process.
+ */
+let jjAvailable: boolean | undefined;
+
+function isJjResolvable(): boolean {
+  if (jjAvailable !== undefined) return jjAvailable;
+  try {
+    const reg = getDefaultRegistry();
+    const res = reg.resolve("jj");
+    jjAvailable = res.ok;
+  } catch {
+    jjAvailable = false;
+  }
+  return jjAvailable;
+}
+
+/**
+ * Test-only hook to reset the jj-availability cache.
+ * Production code MUST NOT call this.
+ */
+export function _resetJjAvailableForTests(): void {
+  jjAvailable = undefined;
+}
+
+/**
+ * Gather jj workspace state for a directory.
+ * Returns `undefined` when:
+ *   - `jj` is not resolvable via the tool registry, OR
+ *   - `.jj/` does not exist in cwd (fast path, no subprocess spawn).
+ *
+ * Returns a populated `JjState` when both conditions are met. Errors during
+ * `jj` invocation surface in `lastError` rather than throwing; the rest of
+ * the fields fall back to undefined / empty.
+ *
+ * Per spec scenario "Non-jj cwd incurs no jj subprocess cost".
+ */
+export function gatherJjInfo(cwd: string): JjState | undefined {
+  if (!isJjResolvable()) return undefined;
+  if (!existsSync(path.join(cwd, ".jj"))) return undefined;
+
+  const isColocated = existsSync(path.join(cwd, ".git"));
+
+  // Resolve workspace name + root. Errors are caught and surfaced via
+  // lastError so callers always get *some* JjState rather than nothing.
+  let workspaceName: string | undefined;
+  let workspaceRoot: string | undefined;
+  let lastError: string | undefined;
+
+  const rootResult = jj.workspaceRoot({ cwd });
+  if (rootResult.ok) {
+    workspaceRoot = rootResult.value;
+  } else if (rootResult.error.kind !== "not-found") {
+    lastError = describeJjError(rootResult.error);
+  }
+
+  // Workspace name: parse `jj workspace list` and match by working-copy
+  // path. The CLI does not include the path in list output, so we fall
+  // back to identifying the workspace via the `<name>@` revset matching
+  // the workspace root. For now: if there's only one workspace, use
+  // its name; otherwise default to "default" if found, else first entry.
+  // (Multi-workspace name disambiguation tracked as Phase 4 follow-up.)
+  const listResult = jj.workspaceList({ cwd });
+  if (listResult.ok) {
+    const entries = jj.parseWorkspaceList(listResult.value);
+    if (entries.length === 1) {
+      workspaceName = entries[0]?.name;
+    } else if (entries.length > 1) {
+      workspaceName = entries.find((e) => e.name === "default")?.name
+        ?? entries[0]?.name;
+    }
+  } else if (listResult.error.kind !== "not-found" && !lastError) {
+    lastError = describeJjError(listResult.error);
+  }
+
+  return {
+    isJjRepo: true,
+    isColocated,
+    workspaceName,
+    workspaceRoot,
+    lastError,
+  };
+}
+
+function describeJjError(
+  error: { kind: string; [k: string]: unknown },
+): string {
+  if (error.kind === "timeout") return "jj probe timed out";
+  if (error.kind === "exit") {
+    const stderr = typeof error.stderr === "string" ? error.stderr.trim() : "";
+    return stderr.split("\n")[0] || `jj exited ${String(error.code)}`;
+  }
+  if (error.kind === "spawn-failure") {
+    return typeof error.message === "string" ? error.message : "spawn failed";
+  }
+  return error.kind;
+}
+
+// ── Combined VCS gather ────────────────────────────────────────────────────
+
+export interface VcsInfo {
+  git?: GitInfo;
+  jj?: JjState;
+}
+
+/**
+ * Convenience helper that gathers both git and jj info in one call.
+ * Used by the bridge's per-session 30 s probe tick.
+ */
+export function gatherVcsInfo(cwd: string): VcsInfo {
+  return {
+    git: gatherGitInfo(cwd),
+    jj: gatherJjInfo(cwd),
+  };
+}

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-server",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Dashboard server for monitoring and interacting with pi agent sessions",
   "type": "module",
   "repository": {
@@ -31,9 +31,9 @@
     "postinstall": "node scripts/fix-pty-permissions.cjs"
   },
   "dependencies": {
-    "@blackbelt-technology/dashboard-plugin-runtime": "^0.4.5",
-    "@blackbelt-technology/pi-dashboard-extension": "^0.4.5",
-    "@blackbelt-technology/pi-dashboard-shared": "^0.4.5",
+    "@blackbelt-technology/dashboard-plugin-runtime": "^0.4.6",
+    "@blackbelt-technology/pi-dashboard-extension": "^0.4.6",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.4.6",
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.0.0",

package/packages/server/src/__tests__/is-unread-trigger.test.ts

@@ -67,8 +67,10 @@ describe("isUnreadTrigger", () => {
         isUnreadTrigger(
           "agent_end",
           { status: "streaming", currentTool: null },
-          // @ts-expect-error simulating the broader status union
-          { status: "ended", currentTool: null },
+          // The status union is currently "streaming" | "idle" | "active";
+          // "ended" is not in the union but is a valid runtime value
+          // upstream, so we cast for the simulation.
+          { status: "ended" as unknown as "idle", currentTool: null },
         ),
       ).toBe(false);
     });

package/packages/server/src/__tests__/jj-routes.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Unit tests for the jj REST routes module — focused on the pure helpers
+ * (`checkInitColocatedPreconditions`) and validation logic. Full route
+ * integration tests are deferred until the test harness wires up a live
+ * Fastify instance + browserGateway mock.
+ *
+ * See change: add-jj-workspace-plugin.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+const { statusPorcelain } = vi.hoisted(() => ({
+  statusPorcelain: vi.fn(),
+}));
+
+vi.mock("@blackbelt-technology/pi-dashboard-shared/platform/git.js", async () => {
+  const real = await vi.importActual<
+    typeof import("@blackbelt-technology/pi-dashboard-shared/platform/git.js")
+  >("@blackbelt-technology/pi-dashboard-shared/platform/git.js");
+  return { ...real, statusPorcelain };
+});
+
+import { checkInitColocatedPreconditions } from "../routes/jj-routes.js";
+
+describe("checkInitColocatedPreconditions", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "jj-routes-test-"));
+    statusPorcelain.mockReset();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns INVALID_CWD when cwd is empty", () => {
+    expect(checkInitColocatedPreconditions("")?.code).toBe("INVALID_CWD");
+  });
+
+  it("returns INVALID_CWD when cwd does not exist", () => {
+    expect(checkInitColocatedPreconditions("/nonexistent/path/12345")?.code).toBe("INVALID_CWD");
+  });
+
+  it("returns ALREADY_JJ when .jj/ exists", () => {
+    fs.mkdirSync(path.join(tmpDir, ".jj"));
+    expect(checkInitColocatedPreconditions(tmpDir)?.code).toBe("ALREADY_JJ");
+  });
+
+  it("returns NOT_GIT_REPO when neither .jj/ nor .git/ exist", () => {
+    expect(checkInitColocatedPreconditions(tmpDir)?.code).toBe("NOT_GIT_REPO");
+  });
+
+  it("returns DIRTY_INDEX when git status has staged entries", () => {
+    fs.mkdirSync(path.join(tmpDir, ".git"));
+    statusPorcelain.mockReturnValue({
+      ok: true,
+      value: "M  src/foo.ts\nA  src/bar.ts\n",
+    });
+    const result = checkInitColocatedPreconditions(tmpDir);
+    expect(result?.code).toBe("DIRTY_INDEX");
+    expect(result?.message).toContain("2 entries");
+  });
+
+  it("returns null on clean .git/ tree (working-tree dirt is fine)", () => {
+    fs.mkdirSync(path.join(tmpDir, ".git"));
+    // Lines starting with " M" (space then M) are working-tree-only changes.
+    // Lines starting with "??" are untracked files. Both are SAFE per spec
+    // scenario "Init allowed on unstaged dirty working tree".
+    statusPorcelain.mockReturnValue({
+      ok: true,
+      value: " M src/working-tree-mod.ts\n?? src/new-untracked.ts\n",
+    });
+    expect(checkInitColocatedPreconditions(tmpDir)).toBeNull();
+  });
+
+  it("returns null on totally clean tree", () => {
+    fs.mkdirSync(path.join(tmpDir, ".git"));
+    statusPorcelain.mockReturnValue({ ok: true, value: "" });
+    expect(checkInitColocatedPreconditions(tmpDir)).toBeNull();
+  });
+
+  it("returns null when statusPorcelain itself fails (defensive: don't refuse on probe error)", () => {
+    fs.mkdirSync(path.join(tmpDir, ".git"));
+    statusPorcelain.mockReturnValue({
+      ok: false,
+      error: { kind: "not-found", binary: "git" },
+    });
+    expect(checkInitColocatedPreconditions(tmpDir)).toBeNull();
+  });
+});

package/packages/server/src/__tests__/openspec-tasks-parser.test.ts

@@ -69,6 +69,53 @@ describe("parseTasksMarkdown", () => {
     const tasks = parseTasksMarkdown("- [ ] 1.1 Loose task");
     expect(tasks[0].group).toBe("");
   });
+
+  // ─── relax-tasks-parser-id-optional ───────────────────────────────────────
+  // The parser MUST accept top-level checkboxes with or without a `1.1`-style
+  // numeric id prefix. Id-less lines get a synthesized `L<line>` id.
+
+  it("parses id-less checkboxes with synthesized L<line> ids", () => {
+    const md = [
+      "## 1. Workflow matrix", // line 1
+      "",                       // line 2
+      "- [ ] Verify runner image",  // line 3
+      "- [x] Add matrix row",       // line 4
+    ].join("\n");
+    const tasks = parseTasksMarkdown(md);
+    expect(tasks).toEqual([
+      { id: "L3", text: "Verify runner image", done: false, line: 3, group: "1. Workflow matrix" },
+      { id: "L4", text: "Add matrix row", done: true, line: 4, group: "1. Workflow matrix" },
+    ]);
+  });
+
+  it("parses files mixing id-ed and id-less checkboxes", () => {
+    const md = [
+      "## 1. Mix",          // 1
+      "",                    // 2
+      "- [ ] 1.1 Has id",   // 3
+      "- [x] No id here",   // 4
+      "- [ ] 1.3 Skipped 1.2 on purpose", // 5
+    ].join("\n");
+    const tasks = parseTasksMarkdown(md);
+    expect(tasks).toEqual([
+      { id: "1.1", text: "Has id", done: false, line: 3, group: "1. Mix" },
+      { id: "L4", text: "No id here", done: true, line: 4, group: "1. Mix" },
+      { id: "1.3", text: "Skipped 1.2 on purpose", done: false, line: 5, group: "1. Mix" },
+    ]);
+  });
+
+  it("still ignores indented checkboxes (id-less or id-ed)", () => {
+    const md = [
+      "## G",
+      "  - [ ] indented id-less",
+      "  - [ ] 1.1 indented id-ed",
+      "- [ ] top-level id-less",
+    ].join("\n");
+    const tasks = parseTasksMarkdown(md);
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0].id).toBe("L4");
+    expect(tasks[0].text).toBe("top-level id-less");
+  });
 });
 
 describe("readTasks + toggleTask (writer)", () => {
@@ -175,4 +222,71 @@ describe("readTasks + toggleTask (writer)", () => {
     const after = fs.readFileSync(tasksFile, "utf-8");
     expect(after).toBe(weirdMd.replace("- [ ] 1.1 Task one", "- [x] 1.1 Task one"));
   });
+
+  // ─── relax-tasks-parser-id-optional ───────────────────────────────────────
+
+  describe("id-less round-trip", () => {
+    const idlessMd = [
+      "## 1. Workflow matrix",     // 1
+      "",                            // 2
+      "- [ ] Verify runner image",  // 3
+      "- [x] Add matrix row",       // 4
+      "",                            // 5
+      "## 2. Verify rename behavior", // 6
+      "- [ ] Inspect releases",      // 7
+    ].join("\n");
+
+    beforeEach(() => {
+      fs.writeFileSync(tasksFile, idlessMd, "utf-8");
+    });
+
+    it("toggle ticks an id-less task addressed by L<line>, no synthetic id leaks into the file", async () => {
+      const result = await toggleTask(tmpDir, CWD_CHANGE[1], "L3", true, 3);
+      expect(result).toEqual({
+        id: "L3",
+        text: "Verify runner image",
+        done: true,
+        line: 3,
+        group: "1. Workflow matrix",
+      });
+      const after = fs.readFileSync(tasksFile, "utf-8");
+      // CRITICAL: line shape preserved — no "L3" appears in the file body
+      expect(after).toBe(idlessMd.replace("- [ ] Verify runner image", "- [x] Verify runner image"));
+      expect(after).not.toContain("L3");
+    });
+
+    it("toggle unticks an id-less task addressed by L<line>", async () => {
+      const result = await toggleTask(tmpDir, CWD_CHANGE[1], "L4", false, 4);
+      expect(result.done).toBe(false);
+      const after = fs.readFileSync(tasksFile, "utf-8");
+      expect(after).toBe(idlessMd.replace("- [x] Add matrix row", "- [ ] Add matrix row"));
+      expect(after).not.toContain("L4");
+    });
+
+    it("toggle of id-less line with wrong synthesized id throws LineMismatchError", async () => {
+      // Line 3 is id-less; passing L99 (or any other L<n>) must reject
+      await expect(toggleTask(tmpDir, CWD_CHANGE[1], "L99", true, 3)).rejects.toBeInstanceOf(
+        LineMismatchError,
+      );
+      expect(fs.readFileSync(tasksFile, "utf-8")).toBe(idlessMd);
+    });
+
+    it("toggle of id-less line with a numeric-style id throws LineMismatchError", async () => {
+      // Line 3 has no numeric id; passing "1.1" must reject
+      await expect(toggleTask(tmpDir, CWD_CHANGE[1], "1.1", true, 3)).rejects.toBeInstanceOf(
+        LineMismatchError,
+      );
+      expect(fs.readFileSync(tasksFile, "utf-8")).toBe(idlessMd);
+    });
+
+    it("toggle of id-ed line addressed by L<n> throws LineMismatchError", async () => {
+      // Switch fixture to id-ed for this case
+      fs.writeFileSync(tasksFile, initialMd, "utf-8");
+      // Line 3 has id "1.1"; addressing it as "L3" must reject
+      await expect(toggleTask(tmpDir, CWD_CHANGE[1], "L3", true, 3)).rejects.toBeInstanceOf(
+        LineMismatchError,
+      );
+      expect(fs.readFileSync(tasksFile, "utf-8")).toBe(initialMd);
+    });
+  });
 });