ai-or-die 0.1.73 → 0.1.75

package/bin/ai-or-die.js

@@ -43,7 +43,9 @@ program
   .option('--no-sticky-notes', 'disable per-tab AI session summaries + auto tab titles (on by default)')
   .option('--sticky-notes-model-dir <path>', 'custom directory for the sticky-note model file')
   .option('--sticky-notes-model <url>', 'override the sticky-note model GGUF download URL')
-  .option('--sticky-notes-threads <number>', 'CPU threads for sticky-note inference (default: auto, max 4)');
+  .option('--sticky-notes-threads <number>', 'CPU threads for sticky-note inference (default: auto, max 4)')
+  .option('--no-keepalive', 'disable keeping the machine awake while the server runs (Windows only; on by default)')
+  .option('--keepalive-display', 'also keep the display on (default keeps the system awake but lets the monitor sleep)');
 
 // Auto-open is OFF by default and opt-in via --open. Legacy callers may still pass
 // --no-open (the old opt-out flag); filter it out so it parses harmlessly as a no-op.
@@ -123,6 +125,12 @@ async function main() {
       stickyNotesModelDir: options.stickyNotesModelDir || process.env.STICKY_NOTES_MODEL_DIR,
       stickyNotesModel: options.stickyNotesModel || process.env.STICKY_NOTES_MODEL,
       stickyNotesThreads: options.stickyNotesThreads || process.env.STICKY_NOTES_THREADS,
+      // Keep the host awake while the server runs (Windows only; on by default;
+      // --no-keepalive / AIORDIE_DISABLE_KEEPALIVE=1 disables). System-awake by
+      // default; --keepalive-display / AIORDIE_KEEPALIVE_DISPLAY=1 also holds
+      // the display on.
+      keepalive: options.keepalive !== false && process.env.AIORDIE_DISABLE_KEEPALIVE !== '1',
+      keepaliveDisplay: options.keepaliveDisplay === true || process.env.AIORDIE_KEEPALIVE_DISPLAY === '1',
     };
 
     console.log('Starting ai-or-die...');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.73",
+  "version": "0.1.75",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {

package/src/base-bridge.js

@@ -262,7 +262,8 @@ class BaseBridge {
       onExit = () => {},
       onError = () => {},
       cols = 80,
-      rows = 24
+      rows = 24,
+      extraEnv = null
     } = options;
 
     try {
@@ -280,7 +281,8 @@ class BaseBridge {
         ...process.env,
         TERM: 'xterm-256color',
         FORCE_COLOR: '1',
-        COLORTERM: 'truecolor'
+        COLORTERM: 'truecolor',
+        ...((extraEnv && typeof extraEnv === 'object') ? extraEnv : {})
       };
 
       const ptyProcess = spawn(this.command, args, {

package/src/keepalive-manager.js

@@ -0,0 +1,251 @@
+'use strict';
+
+const childProcess = require('child_process');
+const path = require('path');
+
+// Keep the host machine awake while the ai-or-die server runs (Windows 11).
+//
+// Mechanism: spawn ONE long-lived Windows PowerShell (5.1, in-box) helper that
+// P/Invokes SetThreadExecutionState from kernel32.dll to hold a power
+// assertion, then blocks on stdin. When the parent closes stdin (graceful
+// release) OR dies (the OS tears down the pipe -> ReadLine() returns null), the
+// helper clears the assertion and exits. Windows also drops a thread's
+// execution-state flags when the holding process dies, so even taskkill /F
+// cannot leak the assertion past reboot. No native deps, no powercfg.
+//
+// Windows-only by design; an instant no-op on macOS/Linux. See
+// docs/specs/keepalive.md and docs/adrs/0028-windows-keepalive.md.
+
+// SetThreadExecutionState flags as DECIMAL uint32 literals. PowerShell 5.1
+// parses 0x80000001 as a negative Int32 and the [uint32] cast then throws, so
+// the decimal forms are load-bearing (verified on a real Windows host):
+//   ES_CONTINUOUS       0x80000000 = 2147483648  (clear value, continuous alone)
+//   ES_SYSTEM_REQUIRED  0x00000001 -> system     = 2147483649
+//   ES_DISPLAY_REQUIRED 0x00000002 -> +display   = 2147483651
+const ES_CONTINUOUS = 2147483648;
+const ES_SYSTEM = 2147483649;
+const ES_SYSTEM_DISPLAY = 2147483651;
+
+const READY_TIMEOUT_MS = 5000;
+
+class KeepaliveManager {
+  constructor(options = {}) {
+    this._enabled = !!options.enabled;
+    this._keepDisplayOn = !!options.keepDisplayOn;
+    this._platform = options.platform || process.platform;
+    this._spawn = options.spawn || childProcess.spawn;
+    this._logger = options.logger || console;
+    this._readyTimeoutMs = options.readyTimeoutMs || READY_TIMEOUT_MS;
+
+    this._started = false;
+    this._child = null;
+    this._readyTimer = null;
+    // Stable reference so we can both add and remove the process 'exit' hook
+    // (a fresh closure each time would leak listeners across start/release).
+    this._exitHandler = null;
+    // Resolves true once the assertion is confirmed held, false on any failure
+    // (spawn error, early exit, or readiness timeout). Used only for a status
+    // log line; the lifecycle never awaits it.
+    this.ready = Promise.resolve(false);
+  }
+
+  // ---- pure builders (static so tests assert them without spawning) ----
+
+  static buildScript(displayRequired, ppid = process.pid) {
+    const assert = displayRequired ? ES_SYSTEM_DISPLAY : ES_SYSTEM;
+    return [
+      // 'Stop' is load-bearing: under Constrained Language Mode / WDAC /
+      // AppLocker / EDR, Add-Type (which writes a .cs to %TEMP% and shells to
+      // csc.exe) is blocked. With the default 'Continue', a blocked Add-Type
+      // would NOT exit -- PowerShell would fall into the infinite stdin loop
+      // and leak an immortal ~30-50MB process on every restart. 'Stop' makes
+      // the child die immediately so our handler fires and ready -> false.
+      `$ErrorActionPreference = 'Stop'`,
+      // Tag the command line with the parent PID (a trusted integer, never user
+      // input) so a stale/orphaned helper is identifiable for triage:
+      //   Get-CimInstance Win32_Process -Filter "Name='powershell.exe'"
+      `# aod-keepalive ppid=${ppid}`,
+      `Add-Type -Name P -Namespace W -MemberDefinition '[System.Runtime.InteropServices.DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint e);'`,
+      // exit 1 when the assertion is refused so the helper never blocks on
+      // stdin WITHOUT actually holding the assertion (which would otherwise
+      // latch us "started" while the machine can still sleep).
+      `if ([W.P]::SetThreadExecutionState([uint32]${assert}) -ne 0) { [Console]::Out.WriteLine('OK'); [Console]::Out.Flush() } else { [Console]::Error.WriteLine('SetThreadExecutionState returned 0'); exit 1 }`,
+      `while ($null -ne [Console]::In.ReadLine()) {}`,
+      `[void][W.P]::SetThreadExecutionState([uint32]${ES_CONTINUOUS})`,
+    ].join('\n');
+  }
+
+  static buildArgs(displayRequired, ppid = process.pid) {
+    return [
+      '-NoProfile',
+      '-NonInteractive',
+      // GPO machine-wide execution policy can otherwise block inline code /
+      // the Add-Type compilation step.
+      '-ExecutionPolicy', 'Bypass',
+      '-Command', KeepaliveManager.buildScript(displayRequired, ppid),
+    ];
+  }
+
+  // Absolute path to in-box Windows PowerShell 5.1 (PATH-hijack hardening --
+  // never resolve a bare "powershell.exe" off PATH).
+  static powershellPath() {
+    const root = process.env.SystemRoot || process.env.windir || 'C:\\Windows';
+    return path.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  }
+
+  // Acquire the wake assertion. No-op unless enabled on win32. Idempotent.
+  // Never throws -- keepalive must never break server startup.
+  start() {
+    if (this._started) return;
+    if (!this._enabled || this._platform !== 'win32') return;
+    this._started = true;
+
+    try {
+      const ps = KeepaliveManager.powershellPath();
+      const args = KeepaliveManager.buildArgs(this._keepDisplayOn);
+      const child = this._spawn(ps, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+        shell: false,
+      });
+      this._child = child;
+
+      // Never let the helper independently keep the parent's event loop alive
+      // (or revive the exit-134 native-teardown abort this repo has fought).
+      // unref() does NOT affect writability, so stdin stays usable by release()
+      // while unreferenced.
+      this._safe(() => child.unref());
+      this._safe(() => child.stdout && child.stdout.unref && child.stdout.unref());
+      this._safe(() => child.stderr && child.stderr.unref && child.stderr.unref());
+      this._safe(() => child.stdin && child.stdin.unref && child.stdin.unref());
+
+      // Capture the first stderr line so the failure warning can distinguish
+      // Constrained Language Mode (a PowerShell error) from an AV/EDR kill.
+      let firstErr = '';
+      if (child.stderr) {
+        this._safe(() => child.stderr.setEncoding && child.stderr.setEncoding('utf8'));
+        child.stderr.on('data', (d) => { if (!firstErr) firstErr = String(d).split('\n')[0].trim(); });
+        child.stderr.on('error', () => {});
+      }
+
+      // Per-start state, captured by the closures below so a stale child's
+      // late events can never mutate a newer run's state.
+      let settled = false;
+      let acquired = false;
+      let resolveReady;
+      this.ready = new Promise((res) => { resolveReady = res; });
+
+      // Declared with `let` so finishReady (defined next) can reference it and
+      // clear it; the timer is created after finishReady to keep ordering clear.
+      let timer = null;
+
+      const finishReady = (ok) => {
+        if (settled) return;
+        settled = true;
+        if (ok) acquired = true;
+        this._safe(() => clearTimeout(timer));
+        if (this._readyTimer === timer) this._readyTimer = null;
+        resolveReady(ok);
+      };
+
+      timer = setTimeout(() => finishReady(false), this._readyTimeoutMs);
+      if (timer.unref) timer.unref();
+      this._readyTimer = timer;
+
+      if (child.stdout) {
+        this._safe(() => child.stdout.setEncoding && child.stdout.setEncoding('utf8'));
+        let buf = '';
+        child.stdout.on('data', (d) => {
+          if (settled) return; // stop buffering once readiness is decided
+          buf += String(d);
+          if (/(^|\n)OK(\r?\n|$)/.test(buf)) finishReady(true);
+        });
+        child.stdout.on('error', () => {});
+      }
+
+      // Settle on 'close' (after all stdio has flushed) rather than 'exit' so
+      // firstErr is populated before the failure warning reads it. 'error'
+      // covers a spawn that never produced a process. The this._child === child
+      // guard makes a superseded/released child's late events a no-op.
+      const onGone = () => {
+        if (this._child !== child) return;
+        this._child = null;
+        this._started = false;
+        this._safe(() => clearTimeout(timer));
+        if (this._readyTimer === timer) this._readyTimer = null;
+        if (!settled) {
+          finishReady(false);
+        } else if (acquired) {
+          // Died AFTER holding the assertion (e.g. an AV/EDR kill hours in) and
+          // we did not initiate the release -> the machine can now sleep.
+          this._safe(() => this._logger.warn && this._logger.warn(
+            '⚠  keepalive: wake assertion lost — the helper exited; the machine may sleep. Restart ai-or-die or pass --no-keepalive.'));
+        }
+      };
+      child.on('error', onGone);
+      child.on('close', onGone);
+
+      // Guarantee release on EVERY exit path, including the ones that bypass
+      // close()/release(): uncaughtException and the bin outer-catch both call
+      // process.exit(1) without close(). A synchronous 'exit' hook, NOT a
+      // SIGINT/SIGTERM handler, so it cannot race the server's single
+      // handleShutdown owner -- it only closes a pipe. Re-registered idempotently
+      // (removeListener first) and removed in releaseSync to avoid leaking
+      // listeners across start/release cycles.
+      if (!this._exitHandler) {
+        this._exitHandler = () => { this._safe(() => this.releaseSync()); };
+      }
+      this._safe(() => process.removeListener('exit', this._exitHandler));
+      this._safe(() => process.once('exit', this._exitHandler));
+
+      this.ready.then((ok) => {
+        if (ok) {
+          this._safe(() => this._logger.log && this._logger.log(
+            'keepalive: holding wake assertion (system sleep prevented)'));
+        } else {
+          const hint = firstErr || 'powershell.exe unavailable or blocked (Constrained Language Mode / WDAC / AV)';
+          this._safe(() => this._logger.warn && this._logger.warn(
+            `⚠  keepalive: could not hold the wake assertion; the machine may sleep (${hint}). Disable with --no-keepalive.`));
+          // Reap a helper that timed out without exiting (e.g. SetThreadExecutionState
+          // returned 0 and it is blocked on stdin) so it cannot leak.
+          if (this._child === child) this._safe(() => this.releaseSync());
+        }
+      }).catch(() => {});
+    } catch (err) {
+      this._started = false;
+      this._child = null;
+      this._safe(() => this._logger.debug && this._logger.debug(
+        'keepalive: failed to start (continuing):', err && err.message));
+    }
+  }
+
+  // Async convenience wrapper; the real work is synchronous (just close a pipe).
+  release() {
+    this.releaseSync();
+    return Promise.resolve();
+  }
+
+  // Drop the assertion: closing stdin makes the helper hit EOF on ReadLine(),
+  // run its explicit clear, and exit; kill() is belt-and-suspenders. Idempotent
+  // and safe to call when never started or when the child is already dead (its
+  // body is fully guarded so it can never interrupt close()).
+  releaseSync() {
+    const child = this._child;
+    this._child = null;
+    this._started = false;
+    if (this._readyTimer) { this._safe(() => clearTimeout(this._readyTimer)); this._readyTimer = null; }
+    if (this._exitHandler) this._safe(() => process.removeListener('exit', this._exitHandler));
+    if (!child) return;
+    // end() sends a graceful EOF so the helper's ReadLine() returns null and the
+    // script runs its explicit ES_CONTINUOUS clear. Do NOT destroy() right after
+    // -- that would abort the pipe before the EOF flushes. kill() is the backstop.
+    this._safe(() => { if (child.stdin && !child.stdin.destroyed) child.stdin.end(); });
+    this._safe(() => child.kill());
+  }
+
+  _safe(fn) {
+    try { return fn(); } catch (_) { /* keepalive must never throw into the caller */ }
+  }
+}
+
+module.exports = KeepaliveManager;

package/src/server.js

@@ -32,6 +32,7 @@ const { isBun } = require('./utils/runtime');
 const CircularBuffer = require('./utils/circular-buffer');
 const MinHeap = require('./utils/eviction-heap');
 const RestartManager = require('./restart-manager');
+const KeepaliveManager = require('./keepalive-manager');
 
 // HOT-08: per-WebSocket-message size cap. Gates JSON.parse so a single
 // large frame can't block the event loop for tens-to-hundreds of ms.
@@ -153,6 +154,14 @@ class ClaudeCodeWebServer {
     const underTest =
       /^test/.test(process.env.npm_lifecycle_event || '') ||
       typeof global.it === 'function';
+    // CI runners must not be kept awake: the assertion can't hold in a headless
+    // CI session anyway, and spawning powershell.exe at startup races node-pty's
+    // ConPTY setup on Windows (it flaked the binary smoke test's terminal echo).
+    // GitHub Actions and most CIs set CI=true. Keep this OUT of KeepaliveManager
+    // so the unit tests (which construct it directly) still exercise win32 logic.
+    const ci = process.env.CI;
+    const isCI = (typeof ci === 'string' && ci !== '' && ci !== 'false' && ci !== '0') ||
+      !!process.env.GITHUB_ACTIONS;
     this.sttEngine = new SttEngine({
       // STT is ON by default (disable with --no-stt / STT_DISABLED=1, handled in
       // bin); an external endpoint always enables it.
@@ -222,6 +231,16 @@ class ClaudeCodeWebServer {
       onResult: (sessionId, payload) => this._onStickyNoteResult(sessionId, payload),
     });
 
+    // Keep the host machine awake for as long as the server runs (Windows 11
+    // only; instant no-op on macOS/Linux). Acquired in start() once listening,
+    // released in close() after the session-save flush. Gated on !underTest so
+    // mocha never spawns the PowerShell helper. See docs/specs/keepalive.md.
+    this.keepaliveManager = new KeepaliveManager({
+      enabled: options.keepalive !== false && !underTest && !isCI &&
+        process.env.AIORDIE_DISABLE_KEEPALIVE !== '1',
+      keepDisplayOn: !!options.keepaliveDisplay,
+    });
+
     this.sessionStore = new SessionStore(options.sessionStoreOptions);
     this.usageReader = new UsageReader(this.sessionDurationHours);
     this.usageAnalytics = new UsageAnalytics({
@@ -277,6 +296,8 @@ class ClaudeCodeWebServer {
         }
       }
       this._capClaudeNotes();
+      // Remove orphan claude-bind sidecars whose tab no longer exists.
+      this._sweepClaudeBindSidecars();
       if (sessions.size > 0) {
         console.log(`Loaded ${sessions.size} persisted sessions`);
       }
@@ -470,6 +491,8 @@ class ClaudeCodeWebServer {
     // Hard timeout: if close() hangs, force exit (protects unsupervised mode)
     const forceExitTimer = setTimeout(() => {
       console.error(`Shutdown timed out after 15s, forcing exit (code ${exitCode})`);
+      // Drop the keep-awake assertion before a hard exit in case close() hung.
+      try { this.keepaliveManager.releaseSync(); } catch (_) { /* ignore */ }
       process.exit(exitCode);
     }, 15000);
     forceExitTimer.unref();
@@ -1351,6 +1374,7 @@ class ClaudeCodeWebServer {
       // Stop + tear down the summariser so an in-flight inference is discarded.
       this.stickyNoteSummarizer.cancel(sessionId);
       this._stickyJsonl.delete(sessionId);
+      this._removeClaudeBindSidecar(session);
       if (this._foregroundSessionId === sessionId) this._foregroundSessionId = null;
 
       this.claudeSessions.delete(sessionId);
@@ -3311,6 +3335,9 @@ class ClaudeCodeWebServer {
           reject(err);
         } else {
           this.server = server;
+          // Now listening — hold the OS awake for the server's lifetime
+          // (Windows only; no-op elsewhere; never throws).
+          this.keepaliveManager.start();
           resolve(server);
         }
       });
@@ -3963,6 +3990,12 @@ class ClaudeCodeWebServer {
       // process; their session.liveCwd stays null. We pass the OSC 7
       // hooks only when starting a Terminal session so the other bridges
       // remain a true no-op.
+      const terminalExtraEnv = {};
+      if (toolName === 'terminal') {
+        const sidecarPath = this._prepareClaudeBindSidecar(sessionId, session);
+        if (sidecarPath) terminalExtraEnv.AIORDIE_CLAUDE_BIND = sidecarPath;
+      }
+
       const osc7Hooks = (toolName === 'terminal') ? {
         validatePath: (p) => this.validatePath(p),
         onCwdChange: (cwd, prev) => {
@@ -4039,7 +4072,13 @@ class ClaudeCodeWebServer {
           this.broadcastToSession(sessionId, { type: 'error', message: error.message });
           this.broadcastSessionActivity(sessionId, 'session_error');
         },
-        ...options
+        ...options,
+        extraEnv: toolName === 'terminal'
+          ? {
+              ...((options.extraEnv && typeof options.extraEnv === 'object') ? options.extraEnv : {}),
+              ...terminalExtraEnv,
+            }
+          : options.extraEnv
       });
 
       session.lastActivity = new Date();
@@ -4256,13 +4295,57 @@ class ClaudeCodeWebServer {
   async _pumpStickyJsonl(sessionId, cwd) {
     let binding = this._stickyJsonl.get(sessionId);
     binding && (binding._ticks = (binding._ticks || 0) + 1);
+    const session = this.claudeSessions.get(sessionId);
 
-    // Periodically (or while unbound) reconcile the binding. A tab STAYS on its
-    // bound session while that file is alive and not owned by another tab; it
-    // only moves to a newer unowned session once its own has gone quiet (an
-    // in-session /resume) — so a third, unrelated session can't steal an active
-    // tab. agent-*.jsonl is excluded by findActiveSessions.
-    if (!binding || binding._ticks % 5 === 0) {
+    // DETERMINISTIC SIDECAR BINDING (terminal tabs launched via github-router).
+    // ai-or-die set AIORDIE_CLAUDE_BIND=<sidecar> on the shell; github-router's
+    // SessionStart/SessionEnd hook writes the ACTIVE claude session id +
+    // transcript path there on every startup / resume / clear / compact. When a
+    // sidecar exists it is AUTHORITATIVE: bind directly to that transcript by
+    // exact path and skip the cwd+mtime inference entirely. Survives in-session
+    // /resume, /clear and exit→relaunch, and works even when liveCwd is null
+    // (cmd.exe / no OSC 7) — the case the inference path gets wrong.
+    const sidecar = session ? await this._readClaudeBindSidecar(session) : null;
+    if (sidecar) {
+      session._sidecarSeen = true;
+      // A SessionEnd record is intentionally NOT acted on: an in-session /resume
+      // or /clear writes end-then-start, and the following start drives the
+      // rebind; a terminal end (logout / prompt_input_exit) means claude exited,
+      // and the PTY onExit flips session.active=false so _pollStickyJsonl stops
+      // pumping this tab. So we keep the current binding (note frozen at its last
+      // state) and only (re)bind on a start with a NEW claude session id.
+      if (
+        sidecar.event !== 'end' &&
+        sidecar.claudeSessionId &&
+        sidecar.transcriptPath &&
+        (!binding || binding.claudeSessionId !== sidecar.claudeSessionId)
+      ) {
+        const stp = await this._statQuiet(sidecar.transcriptPath);
+        if (stp) {
+          this._bindStickyJsonl(sessionId, {
+            file: sidecar.transcriptPath,
+            sessionId: sidecar.claudeSessionId,
+            mtimeMs: stp.mtimeMs,
+            size: stp.size,
+          });
+          binding = this._stickyJsonl.get(sessionId);
+          session.claudePinnedSessionId = sidecar.claudeSessionId;
+          this.sessionStore.markDirty();
+        }
+        // transcript not created yet → wait for a later tick (never inference).
+      }
+      // Pinned tabs never run the mtime inference / resume-follow below.
+    } else if (session && session._sidecarSeen) {
+      // Previously sidecar-managed but the file is momentarily absent/unreadable
+      // → keep the current binding; do NOT fall back to mtime inference (which
+      // could grab a stranger session). Wait for the next sidecar write.
+    } else if (!binding || binding._ticks % 5 === 0) {
+      // INFERENCE FALLBACK (no sidecar — e.g. claude launched without
+      // github-router). Periodically (or while unbound) reconcile the binding. A
+      // tab STAYS on its bound session while that file is alive and not owned by
+      // another tab; it only moves to a newer unowned session once its own has
+      // gone quiet (an in-session /resume) — so a third, unrelated session can't
+      // steal an active tab. agent-*.jsonl is excluded by findActiveSessions.
       const candidates = await StickyNoteJsonl.findActiveSessions(cwd, { projectsDir: this._stickyProjectsDir });
       const ownedByOthers = this._ownedClaudeSessions(sessionId);
       // Only (re)bind to a session being ACTIVELY written (recent mtime). A fresh
@@ -4275,7 +4358,6 @@ class ClaudeCodeWebServer {
       // the recency gate, so a restart / lost binding can re-resume an idle-but-
       // live session. A FRESH tab has no own-session, so it still won't adopt a
       // stale stranger session in the project.
-      const session = this.claudeSessions.get(sessionId);
       const ownClaudeSession = session && session.stickyClaudeSessionId;
       const eligible = (c) => !ownedByOthers.has(c.sessionId) && (freshlyActive(c) || c.sessionId === ownClaudeSession);
       const currentValid =
@@ -4384,9 +4466,99 @@ class ClaudeCodeWebServer {
     for (const [sid, b] of this._stickyJsonl) {
       if (sid !== exceptSessionId && b && b.claudeSessionId) owned.add(b.claudeSessionId);
     }
+    // Also reserve every OTHER tab's pinned (sidecar) claude session, so an
+    // unpinned tab's inference fallback can never adopt a pinned tab's session
+    // even in the window before that tab has finished binding.
+    for (const [sid, s] of this.claudeSessions) {
+      if (sid !== exceptSessionId && s && s.claudePinnedSessionId) owned.add(s.claudePinnedSessionId);
+    }
     return owned;
   }
 
+  /** Absolute path to this server's per-tab claude-bind sidecar directory. */
+  _claudeBindSidecarDir() {
+    const base = (this.sessionStore && this.sessionStore.storageDir) || path.join(os.homedir(), '.ai-or-die');
+    return path.join(base, 'claude-bindings');
+  }
+
+  /**
+   * Allocate (and record on the session) the per-tab sidecar path that
+   * github-router's SessionStart/SessionEnd hook writes the active claude
+   * session id + transcript path into. Returns the absolute path, or null on
+   * failure (the tab then degrades to the inference fallback). Best-effort mkdir.
+   */
+  _prepareClaudeBindSidecar(sessionId, session) {
+    try {
+      const dir = this._claudeBindSidecarDir();
+      try { fs.mkdirSync(dir, { recursive: true }); } catch (_) { /* best-effort */ }
+      const file = path.join(dir, `${sessionId}.json`);
+      // Clear any stale sidecar from a previous run/launch so this fresh terminal
+      // start waits for github-router's next SessionStart write instead of binding
+      // to a dead session's transcript. (Runs before any github-router launch in
+      // this shell, so it can't race the hook.)
+      try { fs.unlinkSync(file); } catch (_) { /* none / best-effort */ }
+      if (session) {
+        session.claudeBindSidecar = file;
+        session._sidecarSeen = false;
+      }
+      return file;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /**
+   * Read + parse the tab's sidecar (written atomically by github-router's hook).
+   * Returns the parsed record `{claudeSessionId, transcriptPath, cwd, event,
+   * source?, reason?}` or null (no file / unreadable / malformed). The file is
+   * tiny, so we re-read every tick (no mtime cache: a SessionEnd→SessionStart
+   * rewrite on /resume can land in the same mtime tick, and a cache keyed on
+   * mtime would then serve the stale record and never rebind). Never throws — any
+   * error yields null so the poll is unaffected.
+   */
+  async _readClaudeBindSidecar(session) {
+    if (!session || !session.claudeBindSidecar) return null;
+    let raw;
+    try {
+      raw = await fs.promises.readFile(session.claudeBindSidecar, 'utf8');
+    } catch (_) {
+      return null; // no sidecar yet (claude not launched via github-router, or pending)
+    }
+    try {
+      const obj = JSON.parse(raw);
+      if (!obj || typeof obj !== 'object' || typeof obj.claudeSessionId !== 'string') return null;
+      return obj;
+    } catch (_) {
+      return null; // mid-write / malformed → skip this tick
+    }
+  }
+
+  /** Best-effort: delete a tab's sidecar file (on session close). */
+  _removeClaudeBindSidecar(session) {
+    const file = session && session.claudeBindSidecar;
+    if (!file) return;
+    try { fs.unlinkSync(file); } catch (_) { /* already gone / best-effort */ }
+  }
+
+  /**
+   * Startup sweep: remove orphan sidecar files (`<sessionId>.json`) whose tab is
+   * no longer in the active session set. Best-effort, bounded, never fatal.
+   */
+  _sweepClaudeBindSidecars() {
+    try {
+      const dir = this._claudeBindSidecarDir();
+      let entries;
+      try { entries = fs.readdirSync(dir); } catch (_) { return; } // no dir → nothing to sweep
+      for (const name of entries) {
+        if (!name.endsWith('.json')) continue;
+        const sid = name.slice(0, -'.json'.length);
+        if (this.claudeSessions.has(sid)) continue; // live tab → keep
+        try { fs.unlinkSync(path.join(dir, name)); } catch (_) { /* best-effort */ }
+      }
+    } catch (_) { /* never fatal */ }
+  }
+
+
   /**
    * Bind a tab to a claude transcript and resume its durable note. Binds near the
    * end of the file so the first summary uses recent context, not the whole
@@ -5301,8 +5473,11 @@ class ClaudeCodeWebServer {
   }
 
   async close() {
-    // Save sessions before closing
-    await this.saveSessionsToDisk(true);
+    // Save sessions before closing. Guarded so a save error can't abort close()
+    // before the teardown below (incl. the keep-awake release at the end) runs;
+    // handleShutdown already persisted sessions on the signal path, and wraps
+    // its own save the same way.
+    try { await this.saveSessionsToDisk(true); } catch (_) { /* ignore */ }
 
     // Tear down the STT (sherpa-onnx) native worker. close() is the cleanup path
     // shared by the signal handler (handleShutdown -> close) AND direct close()
@@ -5415,6 +5590,14 @@ class ClaudeCodeWebServer {
       }
     }
 
+    // Release the Windows keep-awake assertion LAST. Held through the session
+    // save + native-engine teardown above so an already-idle laptop cannot
+    // sleep mid-flush (the exact data-loss window this feature prevents).
+    // Idempotent and a no-op when keepalive was never started (non-win32 /
+    // disabled / under test). The process.once('exit') hook + the force-exit
+    // timer cover any path that skips close().
+    try { this.keepaliveManager.releaseSync(); } catch (_) { /* ignore */ }
+
     // Clear all data
     this.claudeSessions.clear();
     this.webSocketConnections.clear();

package/src/sticky-note-jsonl.js

@@ -2,10 +2,20 @@
 
 // Read clean conversation turns from a Claude Code session JSONL transcript.
 //
-// `github-router claude` runs the normal claude CLI with CLAUDE_CONFIG_DIR=$HOME/.claude,
-// so each session writes ~/.claude/projects/<cwd-slug>/<sessionId>.jsonl — a complete,
-// structured log (the same source claude uses for --resume). We summarise THIS instead
-// of scraping the Ink TUI (which repaints in place and can't be scraped).
+// claude writes ~/.claude/projects/<cwd-slug>/<sessionId>.jsonl — a complete,
+// structured log (the same source claude uses for --resume). We summarise THIS
+// instead of scraping the Ink TUI (which repaints in place and can't be scraped).
+// When launched under github-router, CLAUDE_CONFIG_DIR points at a per-launch
+// mirror whose `projects` subdir is a junction back to the real ~/.claude/projects,
+// so transcripts still land here.
+//
+// Binding a tab to ITS transcript is done two ways (see src/server.js
+// `_pumpStickyJsonl`): (1) PRIMARY — a per-tab sidecar written by github-router's
+// SessionStart/SessionEnd hook names the exact active session id + transcript
+// path (deterministic; survives /resume, /clear, relaunch); (2) FALLBACK — when
+// no sidecar exists (claude launched without github-router), newest-mtime
+// inference over the cwd's project dir. This module only READS a resolved file;
+// `findActiveSessions`/`findActiveSession` serve the fallback path.
 //
 // Signal we keep: user `string`/`text` prompts, assistant `text` replies, and the NAMES
 // of tools the assistant ran. We skip `thinking`, `tool_result`, metadata line types, and

package/src/utils/session-store.js

@@ -232,6 +232,11 @@ class SessionStore {
                 // the durable per-claude-session note store can be rebuilt after a
                 // restart and resume when that session reopens.
                 stickyClaudeSessionId: session.stickyClaudeSessionId || null,
+                // The claude sessionId pinned via the github-router SessionStart
+                // hook sidecar (terminal tabs). Persisted so the ownership
+                // reservation (_ownedClaudeSessions) survives a restart; the
+                // durable note itself resumes via stickyClaudeSessionId above.
+                claudePinnedSessionId: session.claudePinnedSessionId || null,
                 autoTitle: session.autoTitle || null,
                 nameIsUserSet: session.nameIsUserSet || false,
                 stickyNotesEnabled: session.stickyNotesEnabled !== false