agileflow 4.0.0-alpha.24 → 4.0.0-alpha.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "4.0.0-alpha.24",
+  "version": "4.0.0-alpha.26",
   "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

@@ -983,7 +983,13 @@ async function runInternalCloseWindow(deps = {}) {
   const exit = deps.exit || ((code) => process.exit(code));
   // ASCII Unit Separator — never appears in a session/window name or
   // filesystem path, so splitting on it is unambiguous.
-  const DELIM = "\x1f";
+  // tmux's format-string parser escape-encodes control bytes (0x00-0x1F)
+  // into the literal 4-char `\OOO` octal sequence in output, so a
+  // 0x1f byte delimiter comes back as the text "\037" and split()
+  // never finds it. Use TAB instead — it survives format-string
+  // processing untouched, and is impossible in tmux session/window
+  // names (tmux rejects them) and rare-to-impossible in cwd paths.
+  const DELIM = "\t";
   // When the tmux keybind passes session+index positionally, target
   // that exact window. This avoids a wrong-window kill if focus shifts
   // between Alt+w being pressed and this subprocess starting.
@@ -1153,7 +1159,13 @@ async function runInternalRestoreWindow(deps = {}) {
 async function runInternalSnapshotSession(sessionName, deps = {}) {
   if (!sessionName) return;
   const runner = deps.runner || defaultTmuxRunner();
-  const DELIM = "\x1f";
+  // tmux's format-string parser escape-encodes control bytes (0x00-0x1F)
+  // into the literal 4-char `\OOO` octal sequence in output, so a
+  // 0x1f byte delimiter comes back as the text "\037" and split()
+  // never finds it. Use TAB instead — it survives format-string
+  // processing untouched, and is impossible in tmux session/window
+  // names (tmux rejects them) and rare-to-impossible in cwd paths.
+  const DELIM = "\t";
   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

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

@@ -141,6 +141,13 @@ function withRegistryLock(home, fn) {
  *                                           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
@@ -239,6 +246,8 @@ function loadRegistry(home) {
       windows,
       windowsCapturedAt:
         typeof s.windowsCapturedAt === "number" ? s.windowsCapturedAt : 0,
+      wrapperWindowIndex:
+        typeof s.wrapperWindowIndex === "number" ? s.wrapperWindowIndex : 0,
     });
   }
   return { version: 1, sessions: sane };
@@ -330,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,
@@ -339,6 +358,7 @@ function recordSession(entry, home) {
       pinned,
       worktree: entry.worktree,
       windows,
+      wrapperWindowIndex,
     });
     writeRegistry({ version: 1, sessions: filtered }, home);
   });

package/src/runtime/launch/tmux.js

@@ -352,7 +352,16 @@ function installSessionHooks(sessionName, runner, opts = {}) {
   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"]) {
+  // tmux 3.x hook names: `window-linked` and `window-unlinked` fire
+  // on add/remove. There is NO `window-renamed` event — that name is
+  // silently accepted by set-hook but never fires. The correct hook
+  // for rename is `after-rename-window` (the "after-<command>" family
+  // fires whenever the named command runs from any source).
+  for (const event of [
+    "window-linked",
+    "window-unlinked",
+    "after-rename-window",
+  ]) {
     const r = runner.runSync([
       "set-hook",
       "-t",
@@ -727,6 +736,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(
     {