agileflow 4.0.0-alpha.23 → 4.0.0-alpha.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "4.0.0-alpha.23",
+  "version": "4.0.0-alpha.25",
   "description": "AI-driven agile development toolkit for Claude Code — skills-first architecture with opt-in plugins (v4)",
   "keywords": [
     "agile",

package/src/cli/commands/launch.js

@@ -1155,6 +1155,11 @@ async function runInternalSnapshotSession(sessionName, deps = {}) {
   const runner = deps.runner || defaultTmuxRunner();
   const DELIM = "\x1f";
   const fmt = `#{window_index}${DELIM}#{window_name}${DELIM}#{pane_current_path}`;
+  // Capture timestamp BEFORE list-windows so concurrent subprocesses
+  // produce a stable ordering. The registry rejects writes whose
+  // capturedAt is older than what's already stored — without this,
+  // out-of-order lock acquisition can clobber newer state with older.
+  const capturedAt = Date.now();
   const result = runner.runSync(["list-windows", "-t", sessionName, "-F", fmt]);
   if (result.status !== 0) return;
   const lines = (result.stdout || "")
@@ -1177,7 +1182,7 @@ async function runInternalSnapshotSession(sessionName, deps = {}) {
     const {
       updateSession,
     } = require("../../runtime/launch/session-registry.js");
-    updateSession(sessionName, { windows });
+    updateSession(sessionName, { windows, windowsCapturedAt: capturedAt });
   } catch {
     // Registry might not exist or session might have been forgotten;
     // either way we can't usefully recover. Stay silent.

package/src/runtime/launch/parallel-session.js

@@ -140,6 +140,10 @@ async function runParallelSpawn(opts) {
       cli: cliId,
       cwd: targetCwd,
       uuid: null,
+      // Same as the engine path: new-session puts the wrapper at
+      // window-index 0 before our base-index=1 setting takes effect
+      // on subsequently-created windows. Restore skips this index.
+      wrapperWindowIndex: 0,
       worktree: worktree
         ? { path: worktree.path, branch: worktree.branch, base: worktree.base }
         : undefined,

package/src/runtime/launch/restore.js

@@ -12,6 +12,7 @@
  * Returns counts so the caller can show a "restored N of M" summary.
  */
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 
 const {
@@ -26,6 +27,63 @@ const {
 const { loadRegistry } = require("./session-registry.js");
 const { resolveAgileflowBin } = require("./alias-installer.js");
 
+const RESTORE_LOCK_FILE = "launch-restore.lock";
+const RESTORE_LOCK_STALE_MS = 30000;
+
+/**
+ * O_EXCL lock around the entire restore operation so two concurrent
+ * `agileflow launch restore` invocations don't race on createSession
+ * and produce duplicate-session errors plus wasted hook installation
+ * work. Same pattern as the registry lock but on a separate file so
+ * it doesn't block snapshot writes from running sessions.
+ *
+ * @template T
+ * @param {string | undefined} home
+ * @param {() => T} fn
+ * @returns {T}
+ */
+function withRestoreLock(home, fn) {
+  const dir = path.join(home || os.homedir(), ".agileflow");
+  fs.mkdirSync(dir, { recursive: true });
+  const lockFile = path.join(dir, RESTORE_LOCK_FILE);
+  let lockFd = null;
+  try {
+    lockFd = fs.openSync(lockFile, "wx");
+  } catch (err) {
+    if (err && err.code === "EEXIST") {
+      // Check for stale lock (process crashed mid-restore).
+      try {
+        const stat = fs.statSync(lockFile);
+        if (Date.now() - (stat.mtimeMs || 0) > RESTORE_LOCK_STALE_MS) {
+          fs.unlinkSync(lockFile);
+          lockFd = fs.openSync(lockFile, "wx");
+        }
+      } catch {
+        /* fall through to throw */
+      }
+    }
+    if (lockFd === null) {
+      throw new Error(
+        "another `agileflow launch restore` is already in progress",
+      );
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try {
+      fs.closeSync(lockFd);
+    } catch {
+      /* swallow */
+    }
+    try {
+      fs.unlinkSync(lockFile);
+    } catch {
+      /* swallow */
+    }
+  }
+}
+
 /**
  * @typedef {Object} RestoreResult
  * @property {number} restored
@@ -49,6 +107,11 @@ const { resolveAgileflowBin } = require("./alias-installer.js");
  * @returns {RestoreResult}
  */
 function runRestore(opts) {
+  return withRestoreLock(opts.home, () => runRestoreInner(opts));
+}
+
+/** @param {Parameters<typeof runRestore>[0]} opts */
+function runRestoreInner(opts) {
   const runner = opts.runner || defaultRunner();
   const existsSync = opts.existsSync || ((p) => fs.existsSync(p));
   const log =
@@ -141,17 +204,26 @@ function runRestore(opts) {
       const sorted = entry.windows
         .slice()
         .sort((a, b) => (a.index || 0) - (b.index || 0));
-      // Skip the first — already created by new-session.
-      for (let i = 1; i < sorted.length; i++) {
-        const w = sorted[i];
+      // Skip the wrapper window specifically — new-session already
+      // recreated it. Tracked by wrapperWindowIndex (set at session-
+      // creation time, defaults to 0) so a user who reordered windows
+      // doesn't lose a real tab to "first index = wrapper" assumption.
+      const wrapperIdx =
+        typeof entry.wrapperWindowIndex === "number"
+          ? entry.wrapperWindowIndex
+          : 0;
+      let replayed = 0;
+      for (const w of sorted) {
+        if (w.index === wrapperIdx) continue;
         if (!existsSync(w.cwd)) continue;
         const args = ["new-window", "-t", entry.name, "-c", w.cwd];
         if (w.name) args.push("-n", w.name);
         runner.runSync(args);
+        replayed++;
+      }
+      if (replayed > 0) {
+        log(`agileflow launch: replayed ${replayed} tab(s) for ${entry.name}`);
       }
-      log(
-        `agileflow launch: replayed ${sorted.length - 1} tab(s) for ${entry.name}`,
-      );
     }
     // Install hooks AFTER replay so the new-window calls above don't
     // each fire window-linked and overwrite the saved snapshot with

package/src/runtime/launch/session-registry.js

@@ -137,6 +137,17 @@ function withRegistryLock(home, fn) {
  *                                           by tmux hooks; replayed on
  *                                           restore so reboots bring back
  *                                           every tab in its original cwd
+ * @property {number} [windowsCapturedAt]  - epoch ms when `windows` was
+ *                                           captured. Newer captures
+ *                                           always win when concurrent
+ *                                           hook subprocesses race.
+ * @property {number} [wrapperWindowIndex] - tmux window index that holds
+ *                                           the agileflow __exec wrapper
+ *                                           (the window created by
+ *                                           new-session). Replay skips
+ *                                           THIS index so the user's
+ *                                           tabs don't get a duplicate
+ *                                           wrapper. Defaults to 0.
  *
  * @typedef {Object} RegistryShape
  * @property {1} version
@@ -233,6 +244,10 @@ function loadRegistry(home) {
             }
           : undefined,
       windows,
+      windowsCapturedAt:
+        typeof s.windowsCapturedAt === "number" ? s.windowsCapturedAt : 0,
+      wrapperWindowIndex:
+        typeof s.wrapperWindowIndex === "number" ? s.wrapperWindowIndex : 0,
     });
   }
   return { version: 1, sessions: sane };
@@ -324,6 +339,16 @@ function recordSession(entry, home) {
         : previous
           ? previous.windows
           : undefined;
+    // Preserve wrapperWindowIndex across re-records. It's set once at
+    // session creation (when new-session puts the wrapper at index 0
+    // before we change base-index) and never changes for the life of
+    // the session entry.
+    const wrapperWindowIndex =
+      typeof entry.wrapperWindowIndex === "number"
+        ? entry.wrapperWindowIndex
+        : previous && typeof previous.wrapperWindowIndex === "number"
+          ? previous.wrapperWindowIndex
+          : 0;
     filtered.push({
       name: entry.name,
       cli: entry.cli,
@@ -333,6 +358,7 @@ function recordSession(entry, home) {
       pinned,
       worktree: entry.worktree,
       windows,
+      wrapperWindowIndex,
     });
     writeRegistry({ version: 1, sessions: filtered }, home);
   });
@@ -369,7 +395,22 @@ function updateSession(name, patch, home) {
         if (patch.worktree !== undefined) s.worktree = patch.worktree;
         if (patch.pinned !== undefined) s.pinned = patch.pinned === true;
         if (patch.windows !== undefined) {
-          s.windows = Array.isArray(patch.windows) ? patch.windows : undefined;
+          // Stale-snapshot guard: hooks fire on every tab change, so
+          // when the user spams Alt+t multiple subprocesses can race.
+          // Lock acquisition isn't FIFO so an older capture can be
+          // committed after a newer one. Reject any update whose
+          // capturedAt timestamp is older than what's already stored.
+          const incomingTs =
+            typeof patch.windowsCapturedAt === "number"
+              ? patch.windowsCapturedAt
+              : Date.now();
+          if (!s.windowsCapturedAt || incomingTs >= s.windowsCapturedAt) {
+            s.windows = Array.isArray(patch.windows)
+              ? patch.windows
+              : undefined;
+            s.windowsCapturedAt = incomingTs;
+          }
+          // else: silently drop the stale write
         }
         updated = true;
       }

package/src/runtime/launch/tmux.js

@@ -344,9 +344,35 @@ function applyTabFormat(sessionName, runner, opts = {}) {
  */
 function installSessionHooks(sessionName, runner, opts = {}) {
   const agileflowBin = opts.agileflowBin || resolveAgileflowBin();
-  const snapshotCmd = `run-shell -b '${agileflowBin} launch __snapshot-session ${sessionName}'`;
+  // Double-quote the binary path and session name so paths with
+  // spaces (e.g., /Users/x with space/agileflow) work. The shell
+  // command is itself wrapped in double quotes for run-shell to
+  // accept it as a single argument.
+  const shellCmd = `"${agileflowBin}" launch __snapshot-session "${sessionName}"`;
+  const snapshotCmd = `run-shell -b "${shellCmd.replace(/"/g, '\\"')}"`;
+  /** @type {Array<{ event: string, stderr: string }>} */
+  const failures = [];
   for (const event of ["window-linked", "window-unlinked", "window-renamed"]) {
-    runner.runSync(["set-hook", "-t", sessionName, event, snapshotCmd]);
+    const r = runner.runSync([
+      "set-hook",
+      "-t",
+      sessionName,
+      event,
+      snapshotCmd,
+    ]);
+    if (r.status !== 0) {
+      failures.push({ event, stderr: (r.stderr || "").trim() });
+    }
+  }
+  if (failures.length > 0) {
+    // eslint-disable-next-line no-console
+    console.error(
+      `agileflow launch: tab persistence — ${failures.length} of 3 tmux hooks failed to install:`,
+    );
+    for (const f of failures) {
+      // eslint-disable-next-line no-console
+      console.error(`  ${f.event}: ${f.stderr || "(no error message)"}`);
+    }
   }
 }
 
@@ -701,6 +727,10 @@ async function launchInTmux(opts) {
     cli: cliId,
     cwd,
     uuid: null,
+    // new-session creates the wrapper at index 0 (default base-index
+    // before we change it). Restore replay skips this index so we
+    // don't duplicate the wrapper window.
+    wrapperWindowIndex: 0,
   });
   const create = createSession(
     {