create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/lib/serial-task-queue.js

@@ -0,0 +1,64 @@
+'use strict';
+
+class SerialTaskQueue {
+  constructor(name = 'serial-task-queue') {
+    this.name = name;
+    this._tail = Promise.resolve();
+    this._active = null;
+    this._pending = 0;
+  }
+
+  run(label, fn) {
+    if (typeof fn !== 'function') throw new TypeError('SerialTaskQueue.run requires a function');
+    const taskLabel = label || 'task';
+    this._pending += 1;
+    const runTask = async () => {
+      this._pending -= 1;
+      this._active = taskLabel;
+      try {
+        return await fn();
+      } finally {
+        this._active = null;
+      }
+    };
+    const job = this._tail.then(runTask, runTask);
+    this._tail = job.catch(() => {});
+    return job;
+  }
+
+  async drain(timeoutMs = 5000) {
+    const timeout = Math.max(0, Number(timeoutMs) || 0);
+    if (timeout === 0) {
+      await this._tail;
+      return { ok: true, timedOut: false };
+    }
+    let timer = null;
+    try {
+      return await Promise.race([
+        this._tail.then(() => ({ ok: true, timedOut: false })),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve({
+            ok: false,
+            timedOut: true,
+            active: this._active,
+            pending: this._pending,
+          }), timeout);
+          if (typeof timer.unref === 'function') timer.unref();
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  getState() {
+    return {
+      name: this.name,
+      active: this._active,
+      pending: this._pending,
+      idle: !this._active && this._pending === 0,
+    };
+  }
+}
+
+module.exports = { SerialTaskQueue };

package/template/claude-task-manager/lib/server-listeners.js

@@ -37,8 +37,247 @@ function listenerUrl(listener, hostOverride = '') {
   return `${listener.scheme}://${host}:${listener.port}/`;
 }
 
+// Errors that mean "the bind address is not currently assigned to any local
+// interface" — typically because Tailscale logged out, a NIC was unplugged, or
+// an IPv6-only address vanished. These are not permanent: a slow background
+// retry recovers automatically when the interface reappears.
+const INTERFACE_MISSING_CODES = new Set(['EADDRNOTAVAIL', 'EINVAL']);
+
+const DEFAULT_FAST_RETRY_BASE_MS = 1000;
+const DEFAULT_MAX_FAST_ATTEMPTS = 5;
+const DEFAULT_SLOW_RETRY_MS = 30_000;
+
+function classifyListenerError(err) {
+  const code = err && err.code ? String(err.code) : null;
+  const message = (err && err.message) ? String(err.message) : String(err || '');
+  if (code === 'EADDRINUSE') return { kind: 'transient-port', code, message };
+  if (code && INTERFACE_MISSING_CODES.has(code)) return { kind: 'interface-missing', code, message };
+  return { kind: 'permanent', code, message };
+}
+
+// Coordinates `listen()` retries across a set of listener entries.
+//
+// Soft-degrade policy: if the primary bind fails because its interface is
+// missing (e.g. Tailscale IP not currently assigned), the loopback fallback
+// listener — already in the same listeners array via buildCtmListenerConfigs —
+// keeps serving. The missing-interface listener is retried in the background
+// at slowRetryMs cadence so remote access is restored automatically when the
+// interface returns, without a CTM restart.
+//
+// Fatal exit (via onFatal) is only triggered when every listener has failed
+// AND no retry is pending — i.e. nothing will ever serve.
+//
+// Dependency injection (timers, logger, onFatal) makes the coordinator
+// testable without binding real ports or calling process.exit.
+function createListenerRetryCoordinator({
+  listeners,
+  logger = console,
+  onFatal = (msg) => { try { console.error(msg); } catch {} process.exit(1); },
+  setTimeoutFn = (fn, delay) => {
+    const t = setTimeout(fn, delay);
+    if (t && typeof t.unref === 'function') t.unref();
+    return t;
+  },
+  clearTimeoutFn = clearTimeout,
+  fastRetryBaseMs = DEFAULT_FAST_RETRY_BASE_MS,
+  maxFastAttempts = DEFAULT_MAX_FAST_ATTEMPTS,
+  slowRetryMs = DEFAULT_SLOW_RETRY_MS,
+} = {}) {
+  if (!Array.isArray(listeners) || listeners.length === 0) {
+    throw new Error('createListenerRetryCoordinator requires a non-empty listeners array');
+  }
+
+  const entries = listeners.map((listener) => ({
+    listener,
+    state: 'idle',
+    slowRetryTimer: null,
+    everListening: false,
+    everFailed: false,
+    // True once we've logged the current "interface missing" outage. Gates the
+    // slow-retry warning to ONE line per outage episode instead of every
+    // slowRetryMs tick (otherwise a logged-out Tailscale floods the log forever).
+    interfaceMissingLogged: false,
+  }));
+  let fastRetryAttempts = 0;
+  let fastRetryTimer = null;
+  let started = false;
+  let stopped = false;
+
+  const fmtAddr = (l) => `${l.host}:${l.port}`;
+
+  const anyListening = () => entries.some((e) => e.state === 'listening');
+
+  const anyRetryPending = () => {
+    if (fastRetryTimer) return true;
+    for (const e of entries) {
+      if (e.state === 'pending') return true;
+      if (e.slowRetryTimer) return true;
+    }
+    return false;
+  };
+
+  function clearSlowRetry(entry) {
+    if (entry.slowRetryTimer) {
+      clearTimeoutFn(entry.slowRetryTimer);
+      entry.slowRetryTimer = null;
+    }
+  }
+
+  function startListen(entry) {
+    if (stopped) return;
+    entry.state = 'pending';
+    try {
+      entry.listener.server.listen(entry.listener.port, entry.listener.host);
+    } catch (err) {
+      // Some listen() failures throw synchronously instead of emitting 'error'.
+      // Route through the same handler so policy stays consistent.
+      handleError(entry, err);
+    }
+  }
+
+  function scheduleFastRetry() {
+    if (stopped || fastRetryTimer) return null;
+    fastRetryAttempts += 1;
+    const delay = fastRetryBaseMs * fastRetryAttempts;
+    fastRetryTimer = setTimeoutFn(() => {
+      fastRetryTimer = null;
+      if (stopped) return;
+      for (const e of entries) {
+        if (e.state === 'pending' || e.state === 'listening') continue;
+        if (e.slowRetryTimer) continue;
+        startListen(e);
+      }
+    }, delay);
+    return delay;
+  }
+
+  function scheduleSlowRetry(entry) {
+    if (stopped || entry.slowRetryTimer) return;
+    entry.slowRetryTimer = setTimeoutFn(() => {
+      entry.slowRetryTimer = null;
+      if (stopped || entry.state === 'listening') return;
+      startListen(entry);
+    }, slowRetryMs);
+  }
+
+  function maybeFatal(entry, message) {
+    if (stopped) return;
+    if (anyListening() || anyRetryPending()) {
+      logger.error(
+        `[startup] ${entry.listener.id} listener ${fmtAddr(entry.listener)} failed: ${message} — ` +
+        (anyListening() ? 'continuing on other listener(s).' : 'waiting on other listener(s).')
+      );
+      return;
+    }
+    onFatal(`[FATAL] ${entry.listener.id} listener ${fmtAddr(entry.listener)}: ${message}`);
+  }
+
+  function handleListening(entry) {
+    const isRecovery = entry.everFailed;
+    entry.state = 'listening';
+    clearSlowRetry(entry);
+    if (isRecovery) {
+      logger.log(
+        `[startup] ${entry.listener.id} listener re-bound at ${fmtAddr(entry.listener)} ` +
+        '(recovered after earlier bind failure).'
+      );
+    }
+    entry.everListening = true;
+    entry.everFailed = false;
+    // A successful (re)bind ends any outage — re-arm the one-shot warning so a
+    // future down→up→down cycle logs again.
+    entry.interfaceMissingLogged = false;
+  }
+
+  function handleError(entry, err) {
+    if (stopped) return;
+    entry.state = 'failed';
+    entry.everFailed = true;
+    const decision = classifyListenerError(err);
+
+    if (decision.kind === 'transient-port') {
+      if (fastRetryTimer) {
+        logger.error(
+          `[startup] ${entry.listener.id} ${fmtAddr(entry.listener)} EADDRINUSE; ` +
+          'covered by pending retry.'
+        );
+        return;
+      }
+      if (fastRetryAttempts >= maxFastAttempts) {
+        maybeFatal(entry, `EADDRINUSE after ${maxFastAttempts} attempts`);
+        return;
+      }
+      const delay = scheduleFastRetry();
+      logger.error(
+        `[startup] ${entry.listener.id} ${fmtAddr(entry.listener)} EADDRINUSE ` +
+        `(attempt ${fastRetryAttempts}/${maxFastAttempts}), retrying in ${delay}ms...`
+      );
+      return;
+    }
+
+    if (decision.kind === 'interface-missing') {
+      scheduleSlowRetry(entry);
+      // Log ONCE per outage episode, not on every slowRetryMs tick. The slow
+      // retry keeps running silently; handleListening() re-arms this flag when
+      // the interface returns, so a new outage logs again.
+      if (!entry.interfaceMissingLogged) {
+        entry.interfaceMissingLogged = true;
+        const tail = anyListening()
+          ? 'Other listener(s) still serving in the meantime.'
+          : 'No other listener bound yet; CTM will become reachable when the interface returns or another listener binds.';
+        logger.warn(
+          `[startup] ${entry.listener.id} listener ${fmtAddr(entry.listener)} ${decision.code}: ` +
+          `bind interface not available — retrying every ${Math.round(slowRetryMs / 1000)}s (further attempts logged once on recovery). ${tail}`
+        );
+      }
+      // Safety invariant only: never exits while this entry's slow retry is
+      // pending (anyRetryPending() is true). Checked inline so repeat failures
+      // don't re-log the "continuing on other listener(s)" line.
+      if (!anyListening() && !anyRetryPending()) {
+        onFatal(`[FATAL] ${entry.listener.id} listener ${fmtAddr(entry.listener)}: ${decision.code}: ${decision.message}`);
+      }
+      return;
+    }
+
+    maybeFatal(entry, decision.message);
+  }
+
+  function start() {
+    if (started) return;
+    started = true;
+    for (const entry of entries) {
+      entry.listener.server.on('listening', () => handleListening(entry));
+      entry.listener.server.on('error', (err) => handleError(entry, err));
+    }
+    for (const entry of entries) startListen(entry);
+  }
+
+  function stop() {
+    stopped = true;
+    if (fastRetryTimer) { clearTimeoutFn(fastRetryTimer); fastRetryTimer = null; }
+    for (const entry of entries) clearSlowRetry(entry);
+  }
+
+  function snapshot() {
+    return entries.map((e) => ({
+      id: e.listener.id,
+      state: e.state,
+      slowRetryScheduled: !!e.slowRetryTimer,
+      everListening: e.everListening,
+    }));
+  }
+
+  return { start, stop, snapshot };
+}
+
 module.exports = {
   buildCtmListenerConfigs,
   hostForUrl,
   listenerUrl,
+  classifyListenerError,
+  createListenerRetryCoordinator,
+  // Exposed for tests / callers that want to tune defaults via env:
+  DEFAULT_FAST_RETRY_BASE_MS,
+  DEFAULT_MAX_FAST_ATTEMPTS,
+  DEFAULT_SLOW_RETRY_MS,
 };

package/template/claude-task-manager/lib/session-capture.js

@@ -13,10 +13,39 @@ function toMs(value) {
   return Number.isFinite(n) && n > 0 ? n : nowMs();
 }
 
+function explicitActivityMs(input = {}) {
+  const candidates = [
+    input.lastActivity,
+    input.lastAgentOutputAt,
+    input.agentOutputAt,
+    input.lastPtyActivity,
+    input.lastJsonlActivity,
+    input.outputAt,
+  ];
+  for (const value of candidates) {
+    const n = Number(value);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return 0;
+}
+
+function isActivityBearingStatus(input = {}) {
+  const status = normalizeStatus(input.status);
+  const source = String(input.source || '').toLowerCase();
+  const reason = String(input.reason || '').toLowerCase();
+  if (reason === 'snapshot') return false;
+  if (status === 'waiting' && /waiting-for-input|terminal-prompt/.test(`${source} ${reason}`)) return false;
+  if (/pty-activity|jsonl-event|codex-jsonl-event|claude-jsonl|terminal-output|session-resumed/.test(`${source} ${reason}`)) return true;
+  if (status === 'running' && /authoritative:hook|hook|worker/.test(source)) return true;
+  return false;
+}
+
 function normalizeStatus(status) {
-  if (status === 'busy') return 'running';
-  if (status === 'waiting_input') return 'waiting';
-  if (status === 'running' || status === 'waiting' || status === 'idle' || status === 'exited') return status;
+  const text = String(status || '').trim().toLowerCase().replace(/[-\s]+/g, '_');
+  if (text === 'busy' || text === 'active' || text === 'working' || text === 'thinking') return 'running';
+  if (text === 'restoring' || text === 'resuming' || text === 'restore_starting' || text === 'restarting') return 'resuming';
+  if (text === 'waiting_input' || text === 'waiting_for_input') return 'waiting';
+  if (text === 'running' || text === 'resuming' || text === 'waiting' || text === 'idle' || text === 'exited') return text;
   return 'unknown';
 }
 
@@ -33,6 +62,8 @@ function statusFromServerMessage(msg) {
       reason: msg.reason || 'stream-status',
       timestamp: msg.timestamp,
       lastActivity: msg.lastActivity,
+      lastPtyActivity: msg.lastPtyActivity,
+      lastJsonlActivity: msg.lastJsonlActivity,
     };
   }
 
@@ -254,6 +285,8 @@ class SessionCapture extends EventEmitter {
       reason: statusEvt.reason || 'stream-status',
       timestamp: statusEvt.timestamp,
       lastActivity: statusEvt.lastActivity,
+      lastPtyActivity: statusEvt.lastPtyActivity,
+      lastJsonlActivity: statusEvt.lastJsonlActivity,
       eventCount: statusEvt.eventCount,
     });
   }
@@ -285,8 +318,10 @@ class SessionCapture extends EventEmitter {
       decisionId: input.decisionId,
     };
     record.lastUpdated = Math.max(record.lastUpdated || 0, timestamp);
-    if (input.lastActivity) record.lastActivity = Math.max(record.lastActivity || 0, input.lastActivity);
-    else record.lastActivity = Math.max(record.lastActivity || 0, timestamp);
+    const activityMs = explicitActivityMs(input) || (isActivityBearingStatus(input) ? timestamp : 0);
+    if (activityMs) {
+      record.lastActivity = Math.max(record.lastActivity || 0, activityMs);
+    }
     if (input.eventCount != null) record.eventCount = input.eventCount;
 
     const projected = this._project(record);
@@ -335,7 +370,7 @@ class SessionCapture extends EventEmitter {
         ctmSessionId: record.ctmSessionId || null,
         status: projected.status,
         captureStatus: projected.status,
-        lastActivity: record.lastActivity || record.lastUpdated || 0,
+        lastActivity: record.lastActivity || 0,
         eventCount: record.eventCount || 0,
         statusEvidence: projected.evidence,
       });
@@ -403,7 +438,7 @@ class SessionCapture extends EventEmitter {
       ctmSessionId: record.ctmSessionId || null,
       agentSessionId: record.agentSessionId || null,
       status: normalizeStatus(status),
-      lastActivity: record.lastActivity || record.lastUpdated || 0,
+      lastActivity: record.lastActivity || 0,
       evidence: evidence.map((ev) => ({
         source: ev.source,
         status: ev.status,

package/template/claude-task-manager/lib/session-content-backfill.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// Background migration: backfill session_message_rows for EXISTING sessions whose rows are
+// not yet complete. Source = the existing (small, ≤24 MB) blob; over-cap sessions ('[]')
+// stay on the JSONL render path (the gate keeps them off rows) until re-imported. Idempotent,
+// bounded, resumable — and the render gate (db.sessionContentRowsAvailable) keeps a
+// half-migrated session on the blob path, so a sweep in progress never breaks reads.
+//
+// `db` is the better-sqlite3 handle (dbModule.getDb()); `replaceSessionMessageRows` is the
+// db.js writer (operates on the same handle). Passed in so this stays unit-testable in
+// isolation.
+
+// Sessions with a real blob whose row count is below the conversation's message count.
+function findUnbackfilledSessions(db, limit = 50) {
+  const lim = Math.max(1, Math.min(100000, Number(limit) || 50));
+  return db.prepare(`
+    SELECT sc.ctm_session_id AS id
+    FROM session_conversations sc
+    WHERE sc.extracted_source_len > 0
+      AND sc.messages IS NOT NULL AND sc.messages != '[]' AND length(sc.messages) > 2
+      AND (SELECT COUNT(*) FROM session_message_rows r WHERE r.ctm_session_id = sc.ctm_session_id) < sc.extracted_source_len
+    LIMIT ?
+  `).all(lim).map(r => r.id);
+}
+
+// Backfill one session's rows from its blob. Returns rows written (0 if no parseable blob).
+function backfillSessionContentRows(db, sessionId, replaceSessionMessageRows) {
+  const row = db.prepare('SELECT messages FROM session_conversations WHERE ctm_session_id = ?').get(sessionId);
+  if (!row || !row.messages) return 0;
+  let msgs;
+  try { msgs = JSON.parse(row.messages); } catch { return 0; }
+  if (!Array.isArray(msgs) || msgs.length === 0) return 0;
+  return replaceSessionMessageRows(sessionId, msgs);
+}
+
+// Disk reclaim: sessions whose faithful rows are COMPLETE (count >= extracted_source_len > 0 — the
+// same gate as sessionContentRowsAvailable) but whose blob is still present. Once rows serve the
+// render, the blob is dead weight; nulling it reclaims disk. Reversible: re-import from the JSONL
+// rebuilds it. Excludes already-empty/over-cap blobs.
+function findReclaimableSessions(db, limit = 50) {
+  const lim = Math.max(1, Math.min(100000, Number(limit) || 50));
+  return db.prepare(`
+    SELECT sc.ctm_session_id AS id
+    FROM session_conversations sc
+    WHERE sc.messages IS NOT NULL AND sc.messages != '[]' AND length(sc.messages) > 2
+      AND sc.extracted_source_len > 0
+      AND (SELECT COUNT(*) FROM session_message_rows r WHERE r.ctm_session_id = sc.ctm_session_id) >= sc.extracted_source_len
+    LIMIT ?
+  `).all(lim).map(r => r.id);
+}
+
+// Null the blob (messages='[]') for complete-rows sessions. Bounded + idempotent. The caller only
+// runs this when blob retirement is active (CTM_DUAL_WRITE_BLOB=0) — otherwise the next import would
+// just rewrite the blob, so reclaiming would be pointless churn.
+function reclaimRetiredBlobs(db, { limit = 50 } = {}) {
+  const ids = findReclaimableSessions(db, limit);
+  let reclaimed = 0;
+  const upd = db.prepare("UPDATE session_conversations SET messages = '[]' WHERE ctm_session_id = ? AND messages != '[]'");
+  for (const id of ids) {
+    try { if (upd.run(id).changes > 0) reclaimed++; }
+    catch (e) { console.error('[blob-reclaim] session', String(id).slice(0, 8), 'failed:', e.message); }
+  }
+  return { swept: ids.length, reclaimed, remaining: findReclaimableSessions(db, 1).length };
+}
+
+// One bounded sweep. Safe to call repeatedly (idempotent); converges as sessions complete. When blob
+// retirement is active, the same sweep also reclaims disk from complete-rows sessions (one off-thread
+// pass does both — no extra scheduler job).
+function runContentRowsBackfillSweep(db, replaceSessionMessageRows, { limit = 50 } = {}) {
+  const ids = findUnbackfilledSessions(db, limit);
+  let migrated = 0, rows = 0;
+  for (const id of ids) {
+    try {
+      const n = backfillSessionContentRows(db, id, replaceSessionMessageRows);
+      if (n > 0) { migrated++; rows += n; }
+    } catch (e) {
+      console.error('[content-backfill] session', String(id).slice(0, 8), 'failed:', e.message);
+    }
+  }
+  let reclaimed = 0;
+  if (process.env.CTM_DUAL_WRITE_BLOB === '0') {
+    try { reclaimed = reclaimRetiredBlobs(db, { limit }).reclaimed; }
+    catch (e) { console.error('[blob-reclaim] sweep failed:', e.message); }
+  }
+  let droppedLegacy = null;
+  if (process.env.CTM_RETIRE_LEGACY_STORES === '1') {
+    try { const r = retireLegacyStores(db); if (r.dropped.length) droppedLegacy = r.dropped; }
+    catch (e) { console.error('[retire-legacy] sweep failed:', e.message); }
+  }
+  return { swept: ids.length, migrated, rows, reclaimed, droppedLegacy, remaining: findUnbackfilledSessions(db, 1).length };
+}
+
+// Drop the fully-retired legacy message stores once migration is COMPLETE (every eligible session
+// has rows, so the search/freshness/reference readers never need the legacy fallback). The readers
+// are independently guarded against a missing table, so a drop mid-process can't blank results.
+// Gated by the caller on CTM_RETIRE_LEGACY_STORES=1. Reversible: set CTM_DUAL_WRITE_SESSION_MESSAGES=1
+// + re-run the legacy backfill, or re-import from the JSONL.
+function retireLegacyStores(db) {
+  const status = getSessionRowsStatus(db);
+  if (!status.complete) return { dropped: [], reason: 'migration_incomplete', remaining: status.remaining };
+  const dropped = [];
+  for (const t of ['session_messages_fts', 'session_messages']) {
+    try {
+      if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(t)) {
+        db.exec(`DROP TABLE IF EXISTS ${t}`);
+        dropped.push(t);
+      }
+    } catch (e) { console.error('[retire-legacy] drop', t, 'failed:', e.message); }
+  }
+  return { dropped };
+}
+
+// Migration completeness (for /api/ctm/session-rows-status + the cutover gate).
+function getSessionRowsStatus(db) {
+  const total = Number(db.prepare(
+    "SELECT COUNT(*) AS c FROM session_conversations WHERE extracted_source_len > 0 AND messages != '[]' AND length(messages) > 2"
+  ).get().c);
+  const remaining = findUnbackfilledSessions(db, 100000).length;
+  const reclaimable = findReclaimableSessions(db, 100000).length;
+  return { total, migrated: total - remaining, remaining, complete: remaining === 0, reclaimable };
+}
+
+module.exports = {
+  findUnbackfilledSessions,
+  backfillSessionContentRows,
+  runContentRowsBackfillSweep,
+  findReclaimableSessions,
+  reclaimRetiredBlobs,
+  retireLegacyStores,
+  getSessionRowsStatus,
+};