@blackbelt-technology/pi-agent-dashboard 0.4.0 → 0.4.2

package/packages/server/src/browser-handlers/session-action-handler.ts

@@ -168,7 +168,7 @@ export async function handleSendPrompt(
   msg: Extract<BrowserToServerMessage, { type: "send_prompt" }>,
   ctx: BrowserHandlerContext,
 ): Promise<void> {
-  const { sessionManager, piGateway, headlessPidRegistry, pendingResumeRegistry, pendingDashboardSpawns, broadcast } = ctx;
+  const { sessionManager, piGateway, headlessPidRegistry, pendingResumeRegistry, pendingResumeIntents, pendingDashboardSpawns, broadcast } = ctx;
 
   // Intercept `/reload` on active headless sessions — forward the request to
   // our kill-and-respawn handler instead of routing the prompt to the bridge
@@ -194,6 +194,11 @@ export async function handleSendPrompt(
       sessionFile: promptSession.sessionFile,
     });
     if (alreadyResuming) return;
+    // Tag the resume intent as "front" so the upcoming ended→alive
+    // transition surfaces this card at the top of the alive tier. The
+    // user is actively typing into this session; surfacing it matches
+    // their mental model. See change: differentiate-resume-intent-by-trigger.
+    pendingResumeIntents?.record(msg.sessionId, "front");
     sessionManager.update(msg.sessionId, { resuming: true });
     broadcast({ type: "session_updated", sessionId: msg.sessionId, updates: { resuming: true } });
     const autoResumeConfig = loadConfig();
@@ -231,12 +236,17 @@ export async function handleResumeSession(
   msg: Extract<BrowserToServerMessage, { type: "resume_session" }>,
   ctx: BrowserHandlerContext,
 ): Promise<void> {
-  const { ws, sessionManager, pendingForkRegistry, headlessPidRegistry, pendingDashboardSpawns, sendTo } = ctx;
+  const { ws, sessionManager, pendingForkRegistry, headlessPidRegistry, pendingDashboardSpawns, pendingResumeIntents, sendTo } = ctx;
   const session = sessionManager.get(msg.sessionId);
   if (!session) {
     sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session not found" });
     return;
   }
+  // Resolve placement intent. Old browsers omit the field; default to
+  // "front" so they keep getting today's behavior. Drag-to-resume sends
+  // "keep" so the dropped slot is preserved through the resume round-trip.
+  // See change: differentiate-resume-intent-by-trigger.
+  const placement: "front" | "keep" = msg.placement ?? "front";
   if (!session.sessionFile) {
     sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session file is unknown (pre-migration session)" });
     return;
@@ -264,6 +274,15 @@ export async function handleResumeSession(
     }
   }
 
+  // Tag the user-resume intent BEFORE spawning so the `onChange`
+  // ended→alive branch in `server.ts` can distinguish a user-initiated
+  // resume from a bridge auto-reattach on dashboard reboot, and choose
+  // placement (front vs. keep) appropriately. The fork path also tags
+  // but the tag is harmless: forks create new session ids that never
+  // appear in the ended→alive branch.
+  // See changes: preserve-session-order-on-reboot,
+  //              differentiate-resume-intent-by-trigger.
+  pendingResumeIntents?.record(msg.sessionId, placement);
   const resumeConfig = loadConfig();
   const result = await spawnPiSession(session.cwd, {
     sessionFile: forkSessionFile,
@@ -283,10 +302,17 @@ export async function handleSpawnSession(
   msg: Extract<BrowserToServerMessage, { type: "spawn_session" }>,
   ctx: BrowserHandlerContext,
 ): Promise<void> {
-  const { ws, headlessPidRegistry, pendingDashboardSpawns, sendTo } = ctx;
+  const { ws, headlessPidRegistry, pendingDashboardSpawns, pendingAttachRegistry, sendTo } = ctx;
   const config = loadConfig();
   const strategy = config.spawnStrategy ?? "tmux";
 
+  // Queue the optional attach intent BEFORE awaiting the spawn so a fast
+  // bridge `session_register` cannot lose the intent. See change:
+  // add-folder-task-checker-and-spawn-attach.
+  if (typeof msg.attachProposal === "string" && msg.attachProposal.length > 0) {
+    pendingAttachRegistry?.enqueue(msg.cwd, msg.attachProposal);
+  }
+
   // Catch both thrown exceptions and { success: false } results; surface as
   // spawn_error so the UI can render a retryable banner instead of failing
   // silently. Previous behaviour left the user staring at an empty state

package/packages/server/src/browser-handlers/session-meta-handler.ts

@@ -3,6 +3,7 @@
  */
 import type { BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
 import type { BrowserHandlerContext } from "./handler-context.js";
+import { attachRenameTarget, detachShouldClearName } from "../proposal-attach-naming.js";
 
 export function handleRenameSession(
   msg: Extract<BrowserToServerMessage, { type: "rename_session" }>,
@@ -33,28 +34,61 @@ export function handleUnhideSession(
   ctx.broadcast({ type: "session_updated", sessionId: msg.sessionId, updates });
 }
 
+/**
+ * Shared attach-proposal apply logic. Used by both:
+ *   - the browser-initiated `handleAttachProposal` flow, and
+ *   - the spawn-with-attach pop-on-register flow in `pi-gateway.ts`
+ *     (see change: add-folder-task-checker-and-spawn-attach).
+ *
+ * Idempotent: calling twice with the same `changeName` is safe — the auto-rename
+ * is gated by `attachRenameTarget` which short-circuits when the witness equality
+ * already holds (see ./proposal-attach-naming.ts).
+ */
+export function applyAttachProposal(
+  sessionId: string,
+  changeName: string,
+  ctx: Pick<BrowserHandlerContext, "sessionManager" | "piGateway" | "broadcast">,
+): void {
+  const { sessionManager, piGateway, broadcast } = ctx;
+  const session = sessionManager.get(sessionId);
+  const updates: Record<string, unknown> = { attachedProposal: changeName };
+
+  const newName = attachRenameTarget(session, changeName);
+  if (newName !== undefined) {
+    updates.name = newName;
+    piGateway.sendToSession(sessionId, { type: "rename_session", sessionId, name: newName });
+  }
+  sessionManager.update(sessionId, updates);
+  broadcast({ type: "session_updated", sessionId, updates });
+}
+
 export function handleAttachProposal(
   msg: Extract<BrowserToServerMessage, { type: "attach_proposal" }>,
   ctx: BrowserHandlerContext,
 ): void {
-  const { sessionManager, piGateway, broadcast } = ctx;
-  const updates: Record<string, unknown> = { attachedProposal: msg.changeName };
-  const session = sessionManager.get(msg.sessionId);
-  if (session && !session.name?.trim()) {
-    updates.name = msg.changeName;
-    piGateway.sendToSession(msg.sessionId, { type: "rename_session", sessionId: msg.sessionId, name: msg.changeName });
-  }
-  sessionManager.update(msg.sessionId, updates);
-  broadcast({ type: "session_updated", sessionId: msg.sessionId, updates });
+  applyAttachProposal(msg.sessionId, msg.changeName, ctx);
 }
 
 export function handleDetachProposal(
   msg: Extract<BrowserToServerMessage, { type: "detach_proposal" }>,
   ctx: BrowserHandlerContext,
 ): void {
-  const updates = { attachedProposal: null, openspecPhase: null, openspecChange: null };
-  ctx.sessionManager.update(msg.sessionId, updates);
-  ctx.broadcast({ type: "session_updated", sessionId: msg.sessionId, updates });
+  const { sessionManager, piGateway, broadcast } = ctx;
+  const session = sessionManager.get(msg.sessionId);
+
+  // Idempotent auto-revert (see change: fix-mobile-attach-proposal-display).
+  // See design.md decision matrix and ./proposal-attach-naming.ts.
+  const updates: Record<string, unknown> = {
+    attachedProposal: null,
+    openspecPhase: null,
+    openspecChange: null,
+  };
+  if (detachShouldClearName(session)) {
+    updates.name = undefined;
+    piGateway.sendToSession(msg.sessionId, { type: "rename_session", sessionId: msg.sessionId, name: "" });
+  }
+  sessionManager.update(msg.sessionId, updates);
+  broadcast({ type: "session_updated", sessionId: msg.sessionId, updates });
 }
 
 export function handleFetchContent(

package/packages/server/src/browser-handlers/subscription-handler.ts

@@ -55,6 +55,47 @@ async function sendEventBatches(
   return stored.length > 0 ? stored[stored.length - 1].seq : 0;
 }
 
+/**
+ * Replay extension-declared UI state to a single browser. Sends:
+ *
+ *   1. one `ui_modules_list` (when modules exist)                  — Phase 1
+ *   2. one `ui_data_list` per cached `(event, items)` entry         — Phase 1
+ *   3. one `ext_ui_decorator` per cached `Session.uiDecorators` entry — Phase 2
+ *
+ * Replay decorator messages NEVER carry `removed: true` — only live entries
+ * are replayed; deleted entries are already absent from the cache.
+ *
+ * Called immediately after every `replayPendingUiRequests` site so the full
+ * replay ordering is:
+ *
+ *   events → pending UI requests → ui_modules_list → ui_data_list → ext_ui_decorator
+ *
+ * Exported so unit tests can drive it without standing up a full subscribe
+ * pipeline. See changes: add-extension-ui-modal, add-extension-ui-decorations.
+ */
+export function replayUiState(
+  ws: WebSocket,
+  sessionId: string,
+  ctx: Pick<BrowserHandlerContext, "sessionManager" | "sendTo">,
+): void {
+  const { sessionManager, sendTo } = ctx;
+  const session = sessionManager.get(sessionId);
+  if (!session) return;
+  if (session.uiModules && session.uiModules.length > 0) {
+    sendTo(ws, { type: "ui_modules_list", sessionId, modules: session.uiModules } as any);
+  }
+  if (session.uiDataMap) {
+    for (const [event, items] of Object.entries(session.uiDataMap)) {
+      sendTo(ws, { type: "ui_data_list", sessionId, event, items } as any);
+    }
+  }
+  if (session.uiDecorators) {
+    for (const descriptor of Object.values(session.uiDecorators)) {
+      sendTo(ws, { type: "ext_ui_decorator", sessionId, descriptor } as any);
+    }
+  }
+}
+
 export function handleSubscribe(
   msg: Extract<BrowserToServerMessage, { type: "subscribe" }>,
   subs: Set<string>,
@@ -85,6 +126,7 @@ export function handleSubscribe(
       sendEventBatches(ws, msg.sessionId, events, sendTo).then((lastSent) => {
         clearReplaying(ws, msg.sessionId, lastSent);
         replayPendingUiRequests(ws, msg.sessionId);
+        replayUiState(ws, msg.sessionId, ctx);
       });
     } else {
       let events = eventStore.getEvents(msg.sessionId, lastSeq + 1);
@@ -97,10 +139,12 @@ export function handleSubscribe(
         sendEventBatches(ws, msg.sessionId, events, sendTo).then((lastSent) => {
           clearReplaying(ws, msg.sessionId, lastSent);
           replayPendingUiRequests(ws, msg.sessionId);
+          replayUiState(ws, msg.sessionId, ctx);
         });
       } else {
         sendEventBatches(ws, msg.sessionId, events, sendTo).then(() => {
           replayPendingUiRequests(ws, msg.sessionId);
+          replayUiState(ws, msg.sessionId, ctx);
         });
       }
     }
@@ -113,7 +157,7 @@ export function handleSubscribe(
         events: [],
         isLast: false,
       });
-      directoryService.loadSessionEvents(msg.sessionId, session.sessionFile).then(async (result) => {
+      directoryService.loadSessionEvents(msg.sessionId, session.sessionFile, session.contextWindow).then(async (result) => {
         if (result.success) {
           for (const evt of result.events) {
             eventStore.insertEvent(msg.sessionId, evt);
@@ -130,6 +174,7 @@ export function handleSubscribe(
           for (const sub of subscribers) {
             await sendEventBatches(sub, msg.sessionId, stored, sendTo);
             replayPendingUiRequests(sub, msg.sessionId);
+            replayUiState(sub, msg.sessionId, ctx);
           }
         } else {
           sendTo(ws, { type: "event_replay", sessionId: msg.sessionId, events: [], isLast: true });

package/packages/server/src/cli.ts

@@ -18,6 +18,7 @@
 import { createServer, type ServerConfig } from "./server.js";
 import { loadConfig, ensureConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+import { spawnNodeScript } from "@blackbelt-technology/pi-dashboard-shared/platform/node-spawn.js";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import fs from "node:fs";
@@ -51,6 +52,37 @@ import {
 } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
 import type { DashboardServer } from "./server.js";
 import { updateBootstrapCompatibility } from "./pi-version-skew.js";
+import type { BootstrapStateStore } from "./bootstrap-state.js";
+
+/**
+ * Emit a stderr warning at CLI startup when the resolved pi version is
+ * below `piCompatibility.minimum` (blocking) or below `.recommended`
+ * (advisory). Reads from the already-populated `bootstrapState` so no
+ * additional I/O happens here. See change: warn-pi-version-skew-in-cli.
+ */
+function logCompatibilityWarning(store: BootstrapStateStore): void {
+  const s = store.get();
+  const c = s.compatibility;
+  if (!c || !c.current) return;
+  // Below minimum: `updateBootstrapCompatibility` sets `error.message`.
+  // We treat the presence of a blocking error + upgradeRecommended as the
+  // below-minimum signal; `upgradeRecommended` alone means below-recommended.
+  if (s.error?.message && c.upgradeRecommended) {
+    console.error(
+      `[bootstrap] ⚠ pi ${c.current} is below the required minimum ${c.minimum}.`,
+    );
+    console.error(
+      `[bootstrap]   All pi-dependent features (sessions, resources, openspec) will return 503.`,
+    );
+    console.error(`[bootstrap]   Run: pi-dashboard upgrade-pi`);
+    return;
+  }
+  if (c.upgradeRecommended) {
+    console.warn(
+      `[bootstrap] pi ${c.current} is below the recommended ${c.recommended} — consider running \`pi-dashboard upgrade-pi\``,
+    );
+  }
+}
 
 const SUBCOMMANDS = ["start", "stop", "restart", "status", "upgrade-pi"] as const;
 type Subcommand = (typeof SUBCOMMANDS)[number];
@@ -191,6 +223,7 @@ async function runDegradedModeBootstrap(server: DashboardServer): Promise<void>
         "package.json",
       );
       updateBootstrapCompatibility(server.bootstrapState, serverPkg);
+      logCompatibilityWarning(server.bootstrapState);
     } catch (err) {
       console.warn("[bootstrap] version-skew check failed (non-fatal):", err);
     }
@@ -226,12 +259,11 @@ async function runDegradedModeBootstrap(server: DashboardServer): Promise<void>
       return;
     }
 
-    // Rescan registry so pi is re-resolved after the fresh install.
-    // If `rescan` is not exposed, the resolver's strategy chain re-runs
-    // on the next `resolve()` call anyway; we just want fresh timing.
-    type Rescannable = { rescan?: (name: string) => void };
-    const maybeRescan = (registry as unknown as Rescannable).rescan;
-    if (typeof maybeRescan === "function") maybeRescan.call(registry, "pi");
+    // Post-install registry rescan + openspec/pi-resources force-refresh
+    // are now centralized in server.ts's bootstrapState.subscribe hook,
+    // which fires on every installing → ready transition (this caller +
+    // triggerUpgradePi + triggerRetry).
+    // See change: fix-openspec-buttons-after-bootstrap-install.
 
     // Attempt bridge registration. Failures are non-fatal per spec §10.3.
     let bridgeErr: string | undefined;
@@ -260,6 +292,7 @@ async function runDegradedModeBootstrap(server: DashboardServer): Promise<void>
         "package.json",
       );
       updateBootstrapCompatibility(server.bootstrapState, serverPkg);
+      logCompatibilityWarning(server.bootstrapState);
     } catch (err) {
       console.warn("[bootstrap] version-skew check failed (non-fatal):", err);
     }
@@ -339,21 +372,31 @@ async function cmdStart(config: ServerConfig): Promise<void> {
     `\n[${new Date().toISOString()}] pi-dashboard start (parent pid ${process.pid}, port ${config.port})\n`,
   );
 
-  // tsLoader is a file:// URL (required on Windows for node --import).
-  // See change: fix-windows-server-parity.
-  const child = spawn(process.execPath, ["--import", tsLoader, cliPath, ...args], {
-    detached: true,
-    stdio: ["ignore", logFd, logFd],
-    env: { ...process.env },
+  // Both tsLoader and cliPath are wrapped as file:// URLs by spawnNodeScript.
+  // Required on Windows for node --import (see change: fix-windows-entry-script-url).
+  const child = spawnNodeScript({
+    loader: tsLoader,
+    entry: cliPath,
+    args,
+    spawnOptions: {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: { ...process.env },
+    },
   });
   child.unref();
   // Close the parent's copy of the fd — child has its own via stdio inheritance.
   try { fs.closeSync(logFd); } catch { /* ignore */ }
 
-  // Wait for dashboard to become available (up to 5 seconds)
-  const deadline = Date.now() + 5000;
+  // Wait for dashboard to become available. Windows + jiti cold-start can
+  // take 10s+ (TS compile on first boot, native module loads). 30s is the
+  // outer bound — if the server isn't up by then, something's genuinely wrong.
+  const READINESS_TIMEOUT_MS = 30_000;
+  const deadline = Date.now() + READINESS_TIMEOUT_MS;
   let started = false;
   while (Date.now() < deadline) {
+    // Also bail if the child has already exited (fast-path crash detection).
+    if (child.exitCode !== null) break;
     await new Promise((r) => setTimeout(r, 300));
     const status = await isDashboardRunning(config.port);
     if (status.running) {
@@ -366,7 +409,10 @@ async function cmdStart(config: ServerConfig): Promise<void> {
     const pid = readPid();
     console.log(`Dashboard server started (pid ${pid ?? child.pid}) at http://localhost:${config.port}`);
   } else {
-    console.error("Failed to start dashboard server (timed out after 5s)");
+    const reason = child.exitCode !== null
+      ? `child process exited with code ${child.exitCode}`
+      : `timed out after ${READINESS_TIMEOUT_MS / 1000}s`;
+    console.error(`Failed to start dashboard server (${reason})`);
     console.error(`Check logs at ${path.join(logDir, "server.log")}`);
     process.exit(1);
   }

package/packages/server/src/directory-service.ts

@@ -18,6 +18,8 @@ import {
   pollOpenSpecAsync,
   runOpenSpecList,
   runOpenSpecStatus,
+  createFsProbeFactory,
+  createFsSpecsProbeFactory,
 } from "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js";
 import { DEFAULT_OPENSPEC_POLL, type OpenSpecPollConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { createSemaphore, type Semaphore } from "@blackbelt-technology/pi-dashboard-shared/semaphore.js";
@@ -46,7 +48,7 @@ export interface DirectoryAddedResult {
 export interface DirectoryService {
   knownDirectories(): string[];
   discoverSessions(cwd: string): DiscoveredSession[];
-  loadSessionEvents(sessionId: string, sessionFile: string): Promise<LoadResult>;
+  loadSessionEvents(sessionId: string, sessionFile: string, knownContextWindow?: number): Promise<LoadResult>;
   getOpenSpecData(cwd: string): OpenSpecData | undefined;
   /** Force refresh: bypasses the mtime gate. Still honors the semaphore. */
   refreshOpenSpec(cwd: string): Promise<OpenSpecData>;
@@ -86,6 +88,66 @@ function statMtimeOr(p: string): number | undefined {
   }
 }
 
+/**
+ * Maximum mtime across a fixed list of paths. Missing paths (ENOENT) are
+ * skipped — they don't poison the result. Returns `undefined` only when
+ * every input is missing.
+ *
+ * Used by the change-detection gate to catch in-place file edits that
+ * don't bump any parent directory's mtime on POSIX. See change:
+ * fix-openspec-mtime-gate-blind-spots.
+ */
+export function effectiveMtimeOr(paths: string[]): number | undefined {
+  let max: number | undefined;
+  for (const p of paths) {
+    const m = statMtimeOr(p);
+    if (m === undefined) continue;
+    if (max === undefined || m > max) max = m;
+  }
+  return max;
+}
+
+/**
+ * File set tracked by the per-change effective-mtime computation.
+ *
+ * The base set covers the change directory itself plus the three top-level
+ * artifact files. The `specs/` fan-out catches multi-spec authoring:
+ *
+ *   - `<change>/specs/`               — advances on capability dir create/remove
+ *   - `<change>/specs/<cap>/`         — advances when `spec.md` is created inside
+ *   - `<change>/specs/<cap>/spec.md`  — advances on in-place edits
+ *
+ * `readdirSync` is wrapped in try/catch so missing `specs/` (or any fs error)
+ * yields an empty fan-out rather than throwing.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+function perChangeArtifactPaths(changesRoot: string, name: string): string[] {
+  const dir = path.join(changesRoot, name);
+  const base = [
+    dir,
+    path.join(dir, "tasks.md"),
+    path.join(dir, "proposal.md"),
+    path.join(dir, "design.md"),
+  ];
+  const specsDir = path.join(dir, "specs");
+  const specsExtras: string[] = [specsDir];
+  try {
+    const entries = fs.readdirSync(specsDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        const capDir = path.join(specsDir, e.name);
+        specsExtras.push(capDir);
+        specsExtras.push(path.join(capDir, "spec.md"));
+      }
+    }
+  } catch {
+    // ENOENT, permission denied, etc. — leave specsExtras with just specsDir
+    // (its own statMtimeOr will return undefined and be excluded from max).
+  }
+  return [...base, ...specsExtras];
+}
+
 // ── Per-directory cache ────────────────────────────────────────────
 type PerChangeEntry = {
   mtimeMs: number | undefined;
@@ -137,7 +199,7 @@ export function createDirectoryService(
     return discoverSessionsForCwd(cwd);
   }
 
-  async function loadSessionEvents(sessionId: string, sessionFile: string): Promise<LoadResult> {
+  async function loadSessionEvents(sessionId: string, sessionFile: string, knownContextWindow?: number): Promise<LoadResult> {
     if (loadingSet.has(sessionId)) {
       return { success: false, events: [], error: "already_loading" };
     }
@@ -145,7 +207,9 @@ export function createDirectoryService(
     try {
       const { loadSessionEntries } = await import("./session-file-reader.js");
       const entries = loadSessionEntries(sessionFile);
-      const eventMessages = replayEntriesAsEvents(sessionId, entries);
+      // Pass persisted contextWindow so replay's stats_update events use the
+      // real value instead of inferContextWindow(modelId)'s 200k Claude default.
+      const eventMessages = replayEntriesAsEvents(sessionId, entries, knownContextWindow);
       const events = eventMessages.map((m) => m.event);
       return { success: true, events };
     } catch (err: any) {
@@ -181,8 +245,21 @@ export function createDirectoryService(
     }
 
     // ── Step 1: list (gated) ──
+    //
+    // The list-step gate signal must catch in-place edits to <change>/tasks.md
+    // because `completedTasks` / `totalTasks` are derived from those files. POSIX
+    // dir-mtime alone misses these edits (it only advances on entry create/
+    // delete/rename), so we union the parent-dir mtime with each known
+    // tasks.md file's mtime. See change: fix-openspec-mtime-gate-blind-spots.
     let listResult: typeof cache.listResult = cache.listResult;
-    const listCacheValid = gateEnabled && cache.listMtimeMs === rootMtime && cache.listResult !== undefined;
+    let listSignal: number | undefined = rootMtime;
+    if (cache.listResult !== undefined) {
+      const taskFiles = cache.listResult.map((c) =>
+        path.join(changesRoot, c.name, "tasks.md"),
+      );
+      listSignal = effectiveMtimeOr([changesRoot, ...taskFiles]) ?? rootMtime;
+    }
+    const listCacheValid = gateEnabled && cache.listMtimeMs === listSignal && cache.listResult !== undefined;
     if (!listCacheValid) {
       const raw = await semaphore.run(() => runOpenSpecList(cwd));
       if (!raw || !Array.isArray(raw.changes)) {
@@ -195,7 +272,12 @@ export function createDirectoryService(
         return empty;
       }
       listResult = raw.changes;
-      cache.listMtimeMs = rootMtime;
+      // Recompute the signal against the freshly returned change set so the
+      // cache stamps the same shape we'll compare against on the next tick.
+      const taskFiles = (listResult ?? []).map((c) =>
+        path.join(changesRoot, c.name, "tasks.md"),
+      );
+      cache.listMtimeMs = effectiveMtimeOr([changesRoot, ...taskFiles]) ?? rootMtime;
       cache.listResult = listResult;
     }
 
@@ -206,14 +288,27 @@ export function createDirectoryService(
     }
 
     // ── Step 2: per-change status (gated) ──
+    //
+    // TOCTOU note: we capture the file-aware effective mtime BEFORE invoking
+    // `openspec status` and stamp THAT value into the cache. If a tracked
+    // artifact file is written during the CLI invocation, the post-call mtime
+    // will differ from `preCallMtime` and we discard this tick's status for
+    // that change — leaving the prior cache entry (if any) untouched so the
+    // next gated tick re-polls naturally. See change:
+    // fix-openspec-mtime-gate-toctou.
     const statusResults = new Map<string, { artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null>();
+    const preCallMtimes = new Map<string, number | undefined>();
+    const racyNames = new Set<string>();
 
     await Promise.all((listResult ?? []).map(async (c) => {
-      const changeDir = path.join(changesRoot, c.name);
-      const changeMtime = statMtimeOr(changeDir);
+      // File-aware effective mtime: catches in-place edits to tasks.md /
+      // proposal.md / design.md that POSIX dir-mtime misses. See change:
+      // fix-openspec-mtime-gate-blind-spots.
+      const preCallMtime = effectiveMtimeOr(perChangeArtifactPaths(changesRoot, c.name));
+      preCallMtimes.set(c.name, preCallMtime);
       const cached = cache.changes.get(c.name);
 
-      if (gateEnabled && cached && cached.mtimeMs !== undefined && cached.mtimeMs === changeMtime) {
+      if (gateEnabled && cached && cached.mtimeMs !== undefined && cached.mtimeMs === preCallMtime) {
         // Cache hit. Reuse the artifacts/isComplete from the cached OpenSpecChange.
         statusResults.set(c.name, {
           artifacts: cached.change.artifacts.map((a) => ({ id: a.id, status: a.status })),
@@ -223,17 +318,51 @@ export function createDirectoryService(
       }
 
       const status = await semaphore.run(() => runOpenSpecStatus(cwd, c.name));
+
+      // TOCTOU check. If any tracked artifact path was written between the
+      // pre-call stat and now, the CLI's view of disk is stale relative to
+      // the mtime we'd stamp — discard. See change: fix-openspec-mtime-gate-toctou.
+      const postCallMtime = effectiveMtimeOr(perChangeArtifactPaths(changesRoot, c.name));
+      if (preCallMtime !== postCallMtime) {
+        if (typeof process !== "undefined" && /pi-dashboard|openspec-poll/.test(process.env?.DEBUG ?? "")) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[fix-openspec-mtime-gate-toctou] discarded racy status for ${c.name} (pre=${preCallMtime} post=${postCallMtime})`,
+          );
+        }
+        racyNames.add(c.name);
+        if (cached) {
+          // Reuse the prior cached status so buildOpenSpecData doesn't render
+          // an empty artifact list for this tick. Cache entry is preserved
+          // unchanged below by skipping the stamping loop for racy names.
+          statusResults.set(c.name, {
+            artifacts: cached.change.artifacts.map((a) => ({ id: a.id, status: a.status })),
+            ...(cached.change.isComplete !== undefined ? { isComplete: cached.change.isComplete } : {}),
+          });
+        }
+        return;
+      }
       statusResults.set(c.name, status);
     }));
 
     // ── Step 3: build + cache + return ──
-    const data = buildOpenSpecData({ changes: listResult ?? [] }, statusResults);
-
-    // Update per-change cache with the mtimes we just observed.
+    const data = buildOpenSpecData(
+      { changes: listResult ?? [] },
+      statusResults,
+      createFsProbeFactory(cwd),
+      createFsSpecsProbeFactory(cwd),
+    );
+
+    // Stamp the cache with the pre-call mtime — i.e. the mtime that
+    // demonstrably reflects the file state observed by the CLI. Skip racy
+    // names so the next gated tick re-polls. See change:
+    // fix-openspec-mtime-gate-toctou.
     for (const change of data.changes) {
-      const changeDir = path.join(changesRoot, change.name);
-      const changeMtime = statMtimeOr(changeDir);
-      cache.changes.set(change.name, { mtimeMs: changeMtime, change });
+      if (racyNames.has(change.name)) continue;
+      const stampMtime = preCallMtimes.has(change.name)
+        ? preCallMtimes.get(change.name)
+        : effectiveMtimeOr(perChangeArtifactPaths(changesRoot, change.name));
+      cache.changes.set(change.name, { mtimeMs: stampMtime, change });
     }
     cache.data = data;
     caches.set(cwd, cache);
@@ -242,6 +371,14 @@ export function createDirectoryService(
 
   async function refreshOpenSpec(cwd: string): Promise<OpenSpecData> {
     try {
+      // User-initiated refresh bypasses the gate. The gate is heuristic; the
+      // CLI is authoritative. When the user clicks the OpenSpec refresh icon
+      // they expect fresh data, never silently-cached data — force-mode is
+      // the user's escape hatch when the gate's heuristic is wrong, while
+      // periodic paths (`pollDirectoryGated`, `onDirectoryAdded`,
+      // `handleOpenSpecBulkArchive` post-archive refresh) stay gated.
+      // See changes: fix-openspec-mtime-gate-toctou (re-introduced force=true),
+      // fix-openspec-mtime-gate-blind-spots (initial removal of force=true).
       return await pollOne(cwd, true);
     } catch {
       // Fall back to the legacy monolithic path so "refresh" never silently fails.
@@ -383,9 +520,13 @@ export function createDirectoryService(
     },
 
     async onDirectoryAdded(cwd: string): Promise<DirectoryAddedResult> {
+      // Internal path — use the gated poll, not the user-facing
+      // `refreshOpenSpec` (which now bypasses the gate). For a freshly-added
+      // directory the cache is empty, so the gate lets the CLI run anyway.
+      // See change: fix-openspec-mtime-gate-toctou.
       const [sessions, openspecData] = await Promise.all([
         discoverSessions(cwd),
-        refreshOpenSpec(cwd),
+        pollDirectoryGated(cwd),
       ]);
       return { sessions, openspecData };
     },