agileflow 4.0.0-alpha.22 → 4.0.0-alpha.24

package/package.json

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

@@ -1136,6 +1136,59 @@ async function runInternalRestoreWindow(deps = {}) {
   }
 }
 
+/**
+ * Hidden subcommand wired to tmux's window-linked / window-unlinked /
+ * window-renamed hooks. Queries the named session's current window
+ * layout and patches the registry's `windows` array so restore can
+ * later replay every tab in its original cwd.
+ *
+ * Silent on every failure path: this runs in the background on every
+ * tab change, so noise here would clutter the user's terminal. If the
+ * session no longer exists or tmux is gone, we just no-op.
+ *
+ * @param {string} sessionName
+ * @param {{ runner?: ReturnType<typeof defaultTmuxRunner> }} [deps]
+ * @returns {Promise<void>}
+ */
+async function runInternalSnapshotSession(sessionName, deps = {}) {
+  if (!sessionName) return;
+  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 || "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+  /** @type {import("../../runtime/launch/session-registry.js").WindowSnapshot[]} */
+  const windows = [];
+  for (const line of lines) {
+    const parts = line.split(DELIM);
+    if (parts.length !== 3) continue;
+    const index = Number(parts[0]);
+    if (!Number.isFinite(index)) continue;
+    const name = parts[1];
+    const cwd = parts[2];
+    if (!cwd) continue;
+    windows.push({ index, name, cwd });
+  }
+  try {
+    const {
+      updateSession,
+    } = require("../../runtime/launch/session-registry.js");
+    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.
+  }
+}
+
 /**
  * Auto-restore check on bare `agileflow launch`. Fires only when:
  *   - tmux is available (we use sessionExists to count alive sessions)
@@ -1353,6 +1406,14 @@ async function launch(sub, nameArg, _options) {
       await runInternalRestoreWindow({ targetSession: nameArg || "" });
       return;
     }
+    if (sub === "__snapshot-session") {
+      // Hidden subcommand invoked from tmux hooks (window-linked,
+      // window-unlinked, window-renamed). Queries the current window
+      // layout for the named session and writes it to the registry's
+      // `windows` field so restore can replay every tab.
+      await runInternalSnapshotSession(nameArg || "");
+      return;
+    }
     if (sub && sub !== "setup") {
       fail(
         new OperationFailedError(`unknown launch subcommand: ${sub}`, {

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

@@ -23,6 +23,7 @@ const {
   createSession,
   applyKeybindPreset,
   applyTabFormat,
+  installSessionHooks,
   detectTmuxVersion,
   defaultRunner,
 } = require("./tmux.js");
@@ -194,6 +195,7 @@ async function runParallelSpawn(opts) {
     applyTabFormat(sessionName, runner, {
       tmuxVersion: detectTmuxVersion(runner),
     });
+    installSessionHooks(sessionName, runner);
 
     // Swap the user's tmux client to the new session. If switch-client
     // fails the session is still alive — surface its name so the user

package/src/runtime/launch/restore.js

@@ -20,6 +20,7 @@ const {
   createSession,
   applyKeybindPreset,
   applyTabFormat,
+  installSessionHooks,
   detectTmuxVersion,
 } = require("./tmux.js");
 const { loadRegistry } = require("./session-registry.js");
@@ -126,7 +127,36 @@ function runRestore(opts) {
     runner.runSync(["set-option", "-t", entry.name, "status", "1"]);
     applyTabFormat(entry.name, runner, {
       tmuxVersion: detectTmuxVersion(runner),
+      agileflowBin,
     });
+    // Replay saved tabs (windows) if we have any from the last hook
+    // snapshot. The first window already exists (createSession opened
+    // it running __exec), so we skip it. Each restored window is
+    // opened with `new-window -t session -c cwd -n name` and only
+    // gets a shell — restoring the original CLI is out of scope (we
+    // don't know what command was running, and respawning Claude in
+    // every tab would be surprising). Users can re-run agileflow in
+    // any tab manually.
+    if (Array.isArray(entry.windows) && entry.windows.length > 1) {
+      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];
+        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);
+      }
+      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
+    // a partial mid-replay state.
+    installSessionHooks(entry.name, runner, { agileflowBin });
     result.restored++;
     log(`agileflow launch: restored session ${entry.name} (${entry.cwd})`);
   }

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

@@ -117,6 +117,11 @@ function withRegistryLock(home, fn) {
  * @property {string} branch
  * @property {string} base
  *
+ * @typedef {Object} WindowSnapshot
+ * @property {number} index               - tmux window index at snapshot time
+ * @property {string} name                - tmux #W (window name)
+ * @property {string} cwd                 - pane's cwd
+ *
  * @typedef {Object} SessionEntry
  * @property {string} name
  * @property {string} cli
@@ -128,6 +133,14 @@ function withRegistryLock(home, fn) {
  *                                           are pre-selected in the auto-
  *                                           restore picker
  * @property {WorktreeMeta} [worktree]
+ * @property {WindowSnapshot[]} [windows]  - last-known tab layout, written
+ *                                           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.
  *
  * @typedef {Object} RegistryShape
  * @property {1} version
@@ -192,6 +205,22 @@ function loadRegistry(home) {
     if (typeof s.name !== "string" || !s.name) continue;
     if (typeof s.cli !== "string" || !s.cli) continue;
     if (typeof s.cwd !== "string" || !s.cwd) continue;
+    /** @type {WindowSnapshot[] | undefined} */
+    let windows;
+    if (Array.isArray(s.windows)) {
+      windows = [];
+      for (const w of s.windows) {
+        if (!w || typeof w !== "object") continue;
+        if (typeof w.name !== "string") continue;
+        if (typeof w.cwd !== "string" || !w.cwd) continue;
+        windows.push({
+          index: Number.isFinite(w.index) ? Number(w.index) : 0,
+          name: w.name,
+          cwd: w.cwd,
+        });
+      }
+      if (windows.length === 0) windows = undefined;
+    }
     sane.push({
       name: s.name,
       cli: s.cli,
@@ -207,6 +236,9 @@ function loadRegistry(home) {
               base: String(s.worktree.base || ""),
             }
           : undefined,
+      windows,
+      windowsCapturedAt:
+        typeof s.windowsCapturedAt === "number" ? s.windowsCapturedAt : 0,
     });
   }
   return { version: 1, sessions: sane };
@@ -288,6 +320,16 @@ function recordSession(entry, home) {
         : previous
           ? previous.pinned === true
           : false;
+    // Preserve the last-known windows snapshot across re-records.
+    // Restore re-records sessions on the way back from disk and we
+    // don't want the windows array to be silently dropped before
+    // we get a chance to replay it.
+    const windows =
+      entry.windows !== undefined
+        ? entry.windows
+        : previous
+          ? previous.windows
+          : undefined;
     filtered.push({
       name: entry.name,
       cli: entry.cli,
@@ -296,6 +338,7 @@ function recordSession(entry, home) {
       lastSeen: entry.lastSeen || new Date().toISOString(),
       pinned,
       worktree: entry.worktree,
+      windows,
     });
     writeRegistry({ version: 1, sessions: filtered }, home);
   });
@@ -331,6 +374,24 @@ function updateSession(name, patch, home) {
         if (patch.cwd !== undefined) s.cwd = patch.cwd;
         if (patch.worktree !== undefined) s.worktree = patch.worktree;
         if (patch.pinned !== undefined) s.pinned = patch.pinned === true;
+        if (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

@@ -193,6 +193,7 @@ function detectTmuxVersion(runner) {
  * @param {{
  *   tmuxVersion?: { major: number, minor: number } | null,
  *   theme?: Partial<typeof tabs.DEFAULT_TAB_THEME>,
+ *   agileflowBin?: string,
  * }} [opts]
  * @returns {{ applied: boolean, stderr: string }}
  */
@@ -323,6 +324,58 @@ function applyTabFormat(sessionName, runner, opts = {}) {
   };
 }
 
+/**
+ * Install per-session tmux hooks that fire whenever the window layout
+ * changes (new tab, close, rename). Each hook invokes the
+ * `__snapshot-session` callback so the registry's `windows` array
+ * stays current — that's what restore replays after a reboot.
+ *
+ * Kept separate from `applyTabFormat` so the restore path can replay
+ * the saved windows BEFORE installing hooks (otherwise the new-window
+ * calls during replay would fire window-linked, clobbering the saved
+ * snapshot with a partial mid-replay state).
+ *
+ * Scoped per-session via `-t` so non-AgileFlow sessions on the same
+ * tmux server aren't touched.
+ *
+ * @param {string} sessionName
+ * @param {TmuxRunner} runner
+ * @param {{ agileflowBin?: string }} [opts]
+ */
+function installSessionHooks(sessionName, runner, opts = {}) {
+  const agileflowBin = opts.agileflowBin || resolveAgileflowBin();
+  // 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"]) {
+    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)"}`);
+    }
+  }
+}
+
 /**
  * Create a new detached tmux session that immediately runs `bin args...`.
  * Returns the runner's exit status (0 on success).
@@ -651,6 +704,7 @@ async function launchInTmux(opts) {
     // tmux's default green status bar entirely.
     runner.runSync(["set-option", "-t", base, "status", "1"]);
     applyTabFormat(base, runner, { tmuxVersion });
+    installSessionHooks(base, runner);
     log(`agileflow launch: resuming session ${base}`);
     return attachSession(base, runner);
   }
@@ -716,6 +770,7 @@ async function launchInTmux(opts) {
       }
       runner.runSync(["set-option", "-t", name, "status", "1"]);
       applyTabFormat(name, runner, { tmuxVersion });
+      installSessionHooks(name, runner);
       return attachSession(name, runner);
     }
 
@@ -759,6 +814,7 @@ module.exports = {
   substituteBinding,
   detectTmuxVersion,
   applyTabFormat,
+  installSessionHooks,
   KEYBIND_PRESET_BINDINGS,
   defaultRunner,
 };