claude-tempo 0.27.0 → 0.28.0-beta.2

package/CLAUDE.md

@@ -76,7 +76,6 @@ src/
 │   └── helpers.ts     # Zod/MCP tool registration wrapper
 ├── tui/
 │   ├── App.tsx / store.ts / commands.ts   # TUI root, state, slash commands
-│   ├── client.ts                          # Backward-compat shim → src/client/
 │   ├── components/    # Ink components — see docs/tui.md for inventory
 │   └── utils/         # format, platform, theme, fullscreen, history
 ├── utils/
@@ -108,6 +107,13 @@ npm test
 > surveys or migrations, always grep **both** `test/` and `tests/` or you will miss
 > mocks and assertions that only live in one directory.
 
+> **Test-only hooks live with the module they reset and follow the
+> `__<verb><Noun>ForTests` naming convention** — see
+> [docs/adr/0006-test-hooks-naming.md](docs/adr/0006-test-hooks-naming.md). The
+> double-underscore prefix telegraphs "test escape hatch, do not call from
+> production code"; the hook's doc-comment should restate that explicitly. Hooks
+> are never surfaced through barrels or `TempoClient`.
+
 See [docs/development.md](docs/development.md) for full setup (Temporal dev server command,
 daemon worker notes, `npx ts-node` dev runner).
 

package/dist/adapters/base.d.ts

@@ -14,6 +14,35 @@
  */
 import type { Client, WorkflowHandle } from '@temporalio/client';
 import type { AdapterClass, AdapterDescriptor, AttachmentToken, AttachmentPhase, DetachReason } from '../types';
+/** Snapshot of adapter state included in every telemetry frame. */
+interface AdapterTelemetrySnapshot {
+    attachmentId: string | null;
+    workflowId: string | null;
+    runId: string | null;
+    heartbeatsSent: number;
+    phaseTicksDone: number;
+}
+/**
+ * Build the structured frame emitted by every lifecycle handler. Pure
+ * function — exposed for unit tests that don't want to spawn a child
+ * process.
+ */
+export declare function buildProcessTerminatingFrame(signal: string, errorMessage?: string, snapshot?: AdapterTelemetrySnapshot[]): string;
+/**
+ * Install the process-lifecycle telemetry handlers. Idempotent. Skipped
+ * by default in test environments (see {@link shouldInstallLifecycleTelemetry}).
+ *
+ * Production callers (and the first `startV2Lifecycle()` call on any
+ * adapter) invoke without arguments. Unit tests pass `{ force: true }`
+ * to bypass the env gate.
+ */
+export declare function installProcessLifecycleTelemetry(opts?: {
+    force?: boolean;
+}): void;
+/** Test-only — uninstall handlers + reset state. */
+export declare function _resetProcessLifecycleTelemetryForTest(): void;
+/** Test-only — direct access to the live-adapter set. */
+export declare function _liveAdaptersForTest(): ReadonlySet<BaseAttachment>;
 /**
  * Override bundle for the reconnect loop timing (#201). Production defaults are
  * tuned for laptop-sleep cycles (15-min elapsed budget, 10s base, 60s cap). Tests
@@ -124,6 +153,13 @@ export declare abstract class BaseAttachment {
     onPhaseChange(listener: (phase: AttachmentPhase) => void): () => void;
     /** Subscribe to lease-revocation events (§9.3 split-brain resolution). */
     onLeaseRevoked(listener: (reason: DetachReason) => void): () => void;
+    /**
+     * Hypothesis A telemetry — capture the adapter state included in
+     * process-lifecycle log frames. Public so the module-level
+     * `snapshotLiveAdapters()` helper can read private fields without an
+     * `any` cast; consumers other than the telemetry path should not call it.
+     */
+    _captureTelemetrySnapshot(): AdapterTelemetrySnapshot;
     /**
      * Subscribe to terminal events — `WorkflowNotFound` (§9.4) and phase `gone`.
      * Terminal fires at most once per instance. Subclasses stop delivery + exit.
@@ -216,7 +252,55 @@ export declare abstract class BaseAttachment {
      * once per terminal — not on every tick.
      */
     private findCanSuccessorRunId;
+    /**
+     * Fire the terminal hook — the adapter is going dark and won't recover.
+     *
+     * #258: emits a structured log line on every fire so the next post-CAN
+     * silence incident is unambiguous in logs. Pre-#258, a `fireTerminal`
+     * from an unexpected source (the root cause was a silent destroy from
+     * the reconnect-loop pre-check on a transient terminal-class error) was
+     * indistinguishable from process death in workflow history — both produced
+     * "no further heartbeats." The structured log includes:
+     *
+     *   - `reason` — the existing DetachReason
+     *   - `callsite` — the calling function or rationale (passed by every
+     *     callsite so the source is grep-able without parsing stack traces)
+     *   - `attachmentId` / `workflowId` / `runId` — for cross-referencing
+     *     against workflow history when bisecting an incident
+     *   - `heartbeatsSent` / `phaseTicksDone` — the existing #249 counters
+     *     so an operator can correlate "loop alive at N heartbeats, then
+     *     terminal fired at this callsite" without external context
+     *
+     * Idempotent — repeat calls (e.g. reconnect-exhausted re-fires after
+     * destroy) early-return without re-logging. The first fire wins.
+     */
     private fireTerminal;
+    /**
+     * #258 tiebreaker: confirm whether a workflow is genuinely terminal after
+     * the reconnect-loop pre-check threw a terminal-class error. Used to
+     * distinguish a real workflow-gone state from a transient gRPC /
+     * visibility-API blip that classified as terminal.
+     *
+     * Returns:
+     *  - `{ kind: 'running', statusName }` — workflow is alive (any
+     *    non-terminal status). Caller should treat the original error as
+     *    transient and continue the reconnect loop.
+     *  - `{ kind: 'terminal', statusName }` — workflow is in a terminal
+     *    status (`COMPLETED` / `FAILED` / `CANCELLED` / `TERMINATED` /
+     *    `CONTINUED_AS_NEW` / `TIMED_OUT`). Caller should fire destroy.
+     *  - `{ kind: 'describe-threw' }` — `describe()` itself failed. Treat
+     *    as terminal (fire destroy) — consistent with pre-#258 semantics
+     *    when classification is ambiguous, and avoids spinning forever on
+     *    a workflow we can't reach.
+     *  - `{ kind: 'timed-out' }` — `describe()` exceeded
+     *    {@link DESCRIBE_TIMEOUT_MS}. Treat as terminal (fire destroy) —
+     *    same rationale: prefer clean shutdown to a hung loop.
+     *
+     * The unpinned handle follows any CAN chain to the latest run, so
+     * `desc.status.name === 'CONTINUED_AS_NEW'` here means the workflow
+     * id itself is closed (no successor) — genuinely terminal.
+     */
+    private confirmWorkflowTerminal;
     /**
      * Opt-in reconnect policy. Default: return `false` — the base class behaves
      * exactly as it did before #201 (fire terminal, tear down). Subclasses that

package/dist/adapters/base.js

@@ -1,9 +1,174 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdapterRegistry = exports.BaseAttachment = void 0;
+exports.buildProcessTerminatingFrame = buildProcessTerminatingFrame;
+exports.installProcessLifecycleTelemetry = installProcessLifecycleTelemetry;
+exports._resetProcessLifecycleTelemetryForTest = _resetProcessLifecycleTelemetryForTest;
+exports._liveAdaptersForTest = _liveAdaptersForTest;
 const signals_1 = require("../workflows/signals");
 const terminal_error_1 = require("./terminal-error");
 const log = (...args) => console.error('[claude-tempo:adapter]', ...args);
+// ── Hypothesis A telemetry (#258 follow-up) ─────────────────────────────
+//
+// The structured `terminal fire` log shipped in #258 made the next
+// adapter-silence incident self-describing — but only for cases where
+// `fireTerminal` actually fires. Hypothesis A (process death — crash, OOM,
+// Windows sleep, terminal close, SIGKILL) wouldn't produce that log
+// because the process never reached the code path. The handlers below
+// close that gap: a future #258 recurrence with no `fireTerminal` log AND
+// no `adapter-process-terminating` log narrows to a distinct hypothesis
+// (likely SIGKILL / abrupt OS termination — file separately).
+//
+// Design tenets:
+//   - **Idempotent registration**: a module-level boolean ensures multiple
+//     adapter instances spawning in the same process never double-register
+//     handlers. Repeated `installProcessLifecycleTelemetry()` calls no-op.
+//   - **Additive only**: every `process.on(...)` call appends; nothing
+//     calls `removeAllListeners`. Coexists with the test-cleanup chain in
+//     `test/helpers.ts` (#312) and the daemon's own SIGTERM/SIGINT
+//     shutdown function.
+//   - **Synchronous logging on terminal signals**: process termination
+//     doesn't await async log flushes. `console.error` to stderr is
+//     synchronous on POSIX + Windows, which is enough.
+//   - **No behavior change on uncaughtException**: we register
+//     `uncaughtExceptionMonitor` (Node 13.7+) to telemeter without
+//     suppressing Node's default crash. If the runtime predates that
+//     event, we fall back to `uncaughtException` + `process.exit(1)`
+//     which preserves "don't swallow."
+//   - **Test gating**: mocha defines `it` globally (vitest with
+//     `globals: false` does not). Skip auto-install whenever the test
+//     framework signal is present so we don't fight the existing zombie
+//     reap in `test/helpers.ts`. The unit tests for these handlers spawn
+//     a dedicated child Node process where the gate doesn't fire.
+/**
+ * Live adapters in this process. Populated by `startV2Lifecycle` after a
+ * successful claim; emptied on `stopV2Lifecycle` and `fireTerminal`.
+ * Each lifecycle handler iterates this set to build the per-adapter
+ * snapshot in the structured log.
+ */
+const liveAdapters = new Set();
+let processLifecycleTelemetryInstalled = false;
+let processLifecycleHandlerRefs = [];
+/**
+ * Should `installProcessLifecycleTelemetry()` actually wire up handlers?
+ *
+ * - Forced on by `CLAUDE_TEMPO_LIFECYCLE_TELEMETRY=1` (used by the
+ *   child-process tests for these handlers — see
+ *   `test/adapter-process-lifecycle-telemetry.test.ts`).
+ * - Forced off by `CLAUDE_TEMPO_LIFECYCLE_TELEMETRY=0`.
+ * - Off when running under mocha (detected via `globalThis.it` —
+ *   mocha defines this; vitest with `globals: false` does not).
+ * - Off when `NODE_ENV === 'test'` — belt and suspenders.
+ * - Otherwise on.
+ */
+function shouldInstallLifecycleTelemetry(force) {
+    if (force)
+        return true;
+    const flag = process.env.CLAUDE_TEMPO_LIFECYCLE_TELEMETRY;
+    if (flag === '1' || flag === 'true')
+        return true;
+    if (flag === '0' || flag === 'false')
+        return false;
+    // Mocha exposes BDD globals (`it`, `describe`, …) on the global object;
+    // our vitest config opts out of globals so it doesn't trigger this gate.
+    if (typeof globalThis.it === 'function')
+        return false;
+    if (process.env.NODE_ENV === 'test')
+        return false;
+    return true;
+}
+function snapshotLiveAdapters() {
+    const out = [];
+    for (const adapter of liveAdapters) {
+        out.push(adapter._captureTelemetrySnapshot());
+    }
+    return out;
+}
+/**
+ * Build the structured frame emitted by every lifecycle handler. Pure
+ * function — exposed for unit tests that don't want to spawn a child
+ * process.
+ */
+function buildProcessTerminatingFrame(signal, errorMessage, snapshot = snapshotLiveAdapters()) {
+    return JSON.stringify({
+        event: 'adapter-process-terminating',
+        signal,
+        ...(errorMessage !== undefined ? { errorMessage } : {}),
+        adapterCount: snapshot.length,
+        adapters: snapshot,
+    });
+}
+function emitTerminatingLog(signal, errorMessage) {
+    // `console.error` synchronously writes to stderr on POSIX + Windows.
+    // The `[claude-tempo:adapter]` prefix matches the rest of the adapter
+    // logs so a single grep surfaces both the existing `terminal fire`
+    // line and these new lifecycle lines for the same incident.
+    log(`adapter-process-terminating: ${buildProcessTerminatingFrame(signal, errorMessage)}`);
+}
+/**
+ * Install the process-lifecycle telemetry handlers. Idempotent. Skipped
+ * by default in test environments (see {@link shouldInstallLifecycleTelemetry}).
+ *
+ * Production callers (and the first `startV2Lifecycle()` call on any
+ * adapter) invoke without arguments. Unit tests pass `{ force: true }`
+ * to bypass the env gate.
+ */
+function installProcessLifecycleTelemetry(opts = {}) {
+    if (processLifecycleTelemetryInstalled)
+        return;
+    if (!shouldInstallLifecycleTelemetry(opts.force === true))
+        return;
+    processLifecycleTelemetryInstalled = true;
+    const handlers = [];
+    // `exit` — synchronous, last chance. Don't do async work; just log.
+    const onExit = () => emitTerminatingLog('exit');
+    process.on('exit', onExit);
+    handlers.push({ event: 'exit', handler: onExit });
+    // `beforeExit` — event loop is empty but Node hasn't exited yet.
+    const onBeforeExit = () => emitTerminatingLog('beforeExit');
+    process.on('beforeExit', onBeforeExit);
+    handlers.push({ event: 'beforeExit', handler: onBeforeExit });
+    // SIGTERM — graceful termination request (kill, supervisord, systemd).
+    const onSigterm = () => emitTerminatingLog('SIGTERM');
+    process.on('SIGTERM', onSigterm);
+    handlers.push({ event: 'SIGTERM', handler: onSigterm });
+    // SIGINT — Ctrl+C from a controlling terminal.
+    const onSigint = () => emitTerminatingLog('SIGINT');
+    process.on('SIGINT', onSigint);
+    handlers.push({ event: 'SIGINT', handler: onSigint });
+    // `uncaughtExceptionMonitor` lets us telemeter without suppressing
+    // Node's default crash behavior. The default action runs unchanged:
+    // print stack, exit non-zero. The codebase's `engines` requirement
+    // (Node 20+) guarantees this event is available — Node 13.7+.
+    const onUncaughtMonitor = (err) => {
+        emitTerminatingLog('uncaughtException', err instanceof Error ? err.message : String(err));
+    };
+    process.on('uncaughtExceptionMonitor', onUncaughtMonitor);
+    handlers.push({ event: 'uncaughtExceptionMonitor', handler: onUncaughtMonitor });
+    // `unhandledRejection` — log only. Adding a listener prevents Node's
+    // default crash on unhandled promise rejections (Node 15+); that's
+    // intentional per the brief ("log + don't crash").
+    const onUnhandled = (reason) => {
+        const msg = reason instanceof Error ? reason.message : String(reason);
+        emitTerminatingLog('unhandledRejection', msg);
+    };
+    process.on('unhandledRejection', onUnhandled);
+    handlers.push({ event: 'unhandledRejection', handler: onUnhandled });
+    processLifecycleHandlerRefs = handlers;
+}
+/** Test-only — uninstall handlers + reset state. */
+function _resetProcessLifecycleTelemetryForTest() {
+    for (const { event, handler } of processLifecycleHandlerRefs) {
+        process.off(event, handler);
+    }
+    processLifecycleHandlerRefs = [];
+    processLifecycleTelemetryInstalled = false;
+    liveAdapters.clear();
+}
+/** Test-only — direct access to the live-adapter set. */
+function _liveAdaptersForTest() {
+    return liveAdapters;
+}
 /** Backoff tuning for the heartbeat + phase-watcher loops on transient errors. */
 const LOOP_BACKOFF_FACTOR = 1.5;
 const LOOP_BACKOFF_MAX_MS = 30_000;
@@ -26,6 +191,31 @@ const RECONNECT_TOTAL_BUDGET_MS = 15 * 60_000;
 const RECONNECT_BASE_MS = 10_000;
 const RECONNECT_MAX_MS = 60_000;
 const RECONNECT_BACKOFF_FACTOR = 1.5;
+/**
+ * #258: tiebreaker timeout for the `describe()` confirmation that gates
+ * `fireTerminal('destroy')` from the reconnect-loop pre-check. The Temporal
+ * SDK's per-call default is conservative (10s+); we'd rather conclude
+ * "describe is hung, treat as terminal" in 3s than freeze the reconnect
+ * loop on a slow visibility-API call.
+ */
+const DESCRIBE_TIMEOUT_MS = 3_000;
+/**
+ * Workflow execution statuses that are unambiguously terminal — used by
+ * the #258 `describe()` tiebreaker to decide whether a transient
+ * pre-check error reflects a genuinely-gone workflow (fire destroy) or a
+ * transient blip (continue the loop). Anything not in this set, including
+ * `RUNNING`, `PAUSED`, `UNSPECIFIED`, and `UNKNOWN`, is treated as
+ * non-terminal — conservatively keeps the loop alive when classification
+ * is ambiguous.
+ */
+const TERMINAL_WORKFLOW_STATUSES = new Set([
+    'COMPLETED',
+    'FAILED',
+    'CANCELLED',
+    'TERMINATED',
+    'CONTINUED_AS_NEW',
+    'TIMED_OUT',
+]);
 /**
  * Abstract base class for session adapters.
  *
@@ -142,6 +332,21 @@ class BaseAttachment {
                 this.leaseRevokedListeners.splice(i, 1);
         };
     }
+    /**
+     * Hypothesis A telemetry — capture the adapter state included in
+     * process-lifecycle log frames. Public so the module-level
+     * `snapshotLiveAdapters()` helper can read private fields without an
+     * `any` cast; consumers other than the telemetry path should not call it.
+     */
+    _captureTelemetrySnapshot() {
+        return {
+            attachmentId: this.token?.attachmentId ?? null,
+            workflowId: this.pinnedHandle?.workflowId ?? null,
+            runId: this.token?.runId ?? null,
+            heartbeatsSent: this.heartbeatsSent,
+            phaseTicksDone: this.phaseTicksDone,
+        };
+    }
     /**
      * Subscribe to terminal events — `WorkflowNotFound` (§9.4) and phase `gone`.
      * Terminal fires at most once per instance. Subclasses stop delivery + exit.
@@ -187,6 +392,13 @@ class BaseAttachment {
                 }],
         });
         this.pinnedHandle = this.client.workflow.getHandle(workflowId, this.token.runId);
+        // Hypothesis A telemetry — register this adapter so a future process-
+        // lifecycle handler (exit / SIGTERM / uncaughtException / …) can
+        // include its state in the structured log. `installProcessLifecycleTelemetry`
+        // is idempotent + env-gated; first call wires the handlers, subsequent
+        // calls no-op.
+        liveAdapters.add(this);
+        installProcessLifecycleTelemetry();
         // #249: reset the per-attachment diagnostic counters so the next tick emits
         // `heartbeat#1 delivered` on the freshly live lease. Without this reset a
         // renewal path (e.g. restart → renewed claim) would never re-log first-heartbeat.
@@ -211,6 +423,10 @@ class BaseAttachment {
         if (this.stopped)
             return;
         this.stopped = true;
+        // Hypothesis A telemetry — keep `liveAdapters` accurate so a subsequent
+        // process-lifecycle handler firing after stop doesn't include a
+        // already-torn-down adapter in its frame.
+        liveAdapters.delete(this);
         if (this.heartbeatTimer) {
             clearTimeout(this.heartbeatTimer);
             this.heartbeatTimer = null;
@@ -416,7 +632,7 @@ class BaseAttachment {
                 }
                 // Phase `gone` is terminal — workflow destroyed. Never recoverable.
                 if (info.phase === 'gone') {
-                    this.fireTerminal('destroy');
+                    this.fireTerminal('destroy', 'tickPhaseWatcher:phase-gone');
                     return;
                 }
             }
@@ -460,7 +676,7 @@ class BaseAttachment {
         }
         // No CAN event in the closed run's history → truly terminal (COMPLETED /
         // TERMINATED / FAILED / workflow-id GC'd).
-        this.fireTerminal('destroy');
+        this.fireTerminal('destroy', 'handleRunEndError:no-can-successor');
         return true;
     }
     /**
@@ -491,11 +707,44 @@ class BaseAttachment {
             return null;
         }
     }
-    fireTerminal(reason) {
+    /**
+     * Fire the terminal hook — the adapter is going dark and won't recover.
+     *
+     * #258: emits a structured log line on every fire so the next post-CAN
+     * silence incident is unambiguous in logs. Pre-#258, a `fireTerminal`
+     * from an unexpected source (the root cause was a silent destroy from
+     * the reconnect-loop pre-check on a transient terminal-class error) was
+     * indistinguishable from process death in workflow history — both produced
+     * "no further heartbeats." The structured log includes:
+     *
+     *   - `reason` — the existing DetachReason
+     *   - `callsite` — the calling function or rationale (passed by every
+     *     callsite so the source is grep-able without parsing stack traces)
+     *   - `attachmentId` / `workflowId` / `runId` — for cross-referencing
+     *     against workflow history when bisecting an incident
+     *   - `heartbeatsSent` / `phaseTicksDone` — the existing #249 counters
+     *     so an operator can correlate "loop alive at N heartbeats, then
+     *     terminal fired at this callsite" without external context
+     *
+     * Idempotent — repeat calls (e.g. reconnect-exhausted re-fires after
+     * destroy) early-return without re-logging. The first fire wins.
+     */
+    fireTerminal(reason, callsite = 'unspecified') {
         if (this.terminalFired)
             return;
         this.terminalFired = true;
         this.stopped = true;
+        // Hypothesis A telemetry — same reasoning as `stopV2Lifecycle`.
+        liveAdapters.delete(this);
+        log(`terminal fire:`, JSON.stringify({
+            reason,
+            callsite,
+            attachmentId: this.token?.attachmentId ?? null,
+            workflowId: this.pinnedHandle?.workflowId ?? null,
+            runId: this.token?.runId ?? null,
+            heartbeatsSent: this.heartbeatsSent,
+            phaseTicksDone: this.phaseTicksDone,
+        }));
         if (this.heartbeatTimer) {
             clearTimeout(this.heartbeatTimer);
             this.heartbeatTimer = null;
@@ -514,6 +763,56 @@ class BaseAttachment {
             }
         }
     }
+    /**
+     * #258 tiebreaker: confirm whether a workflow is genuinely terminal after
+     * the reconnect-loop pre-check threw a terminal-class error. Used to
+     * distinguish a real workflow-gone state from a transient gRPC /
+     * visibility-API blip that classified as terminal.
+     *
+     * Returns:
+     *  - `{ kind: 'running', statusName }` — workflow is alive (any
+     *    non-terminal status). Caller should treat the original error as
+     *    transient and continue the reconnect loop.
+     *  - `{ kind: 'terminal', statusName }` — workflow is in a terminal
+     *    status (`COMPLETED` / `FAILED` / `CANCELLED` / `TERMINATED` /
+     *    `CONTINUED_AS_NEW` / `TIMED_OUT`). Caller should fire destroy.
+     *  - `{ kind: 'describe-threw' }` — `describe()` itself failed. Treat
+     *    as terminal (fire destroy) — consistent with pre-#258 semantics
+     *    when classification is ambiguous, and avoids spinning forever on
+     *    a workflow we can't reach.
+     *  - `{ kind: 'timed-out' }` — `describe()` exceeded
+     *    {@link DESCRIBE_TIMEOUT_MS}. Treat as terminal (fire destroy) —
+     *    same rationale: prefer clean shutdown to a hung loop.
+     *
+     * The unpinned handle follows any CAN chain to the latest run, so
+     * `desc.status.name === 'CONTINUED_AS_NEW'` here means the workflow
+     * id itself is closed (no successor) — genuinely terminal.
+     */
+    async confirmWorkflowTerminal(unpinned) {
+        let timer = null;
+        try {
+            const desc = await Promise.race([
+                unpinned.describe(),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve('timeout'), DESCRIBE_TIMEOUT_MS);
+                }),
+            ]);
+            if (desc === 'timeout')
+                return { kind: 'timed-out' };
+            const statusName = desc.status?.name ?? 'UNKNOWN';
+            if (TERMINAL_WORKFLOW_STATUSES.has(statusName)) {
+                return { kind: 'terminal', statusName };
+            }
+            return { kind: 'running', statusName };
+        }
+        catch {
+            return { kind: 'describe-threw' };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     // ───────────────────────────────────────────────────────────────────────────
     // #201 reconnect machinery. Subclasses opt in by overriding `shouldReconnect`.
     // ───────────────────────────────────────────────────────────────────────────
@@ -605,7 +904,7 @@ class BaseAttachment {
         if (this.stopped || this.terminalFired || this.reconnecting)
             return;
         if (!this.shouldReconnect(reason)) {
-            this.fireTerminal(reason);
+            this.fireTerminal(reason, 'fireTerminalOrReconnect:not-recoverable');
             return;
         }
         // Pause the heartbeat + watcher loops for the duration of the reconnect.
@@ -627,14 +926,14 @@ class BaseAttachment {
             void this.runCanRebind(canSuccessorRunId).catch((err) => {
                 log(`CAN rebind crashed:`, err?.message ?? err);
                 this.reconnecting = false;
-                this.fireTerminal('reconnect-exhausted');
+                this.fireTerminal('reconnect-exhausted', 'runCanRebind:crashed');
             });
             return;
         }
         void this.runReconnectLoop(reason).catch((err) => {
             log(`reconnect loop crashed:`, err?.message ?? err);
             this.reconnecting = false;
-            this.fireTerminal('reconnect-exhausted');
+            this.fireTerminal('reconnect-exhausted', 'runReconnectLoop:crashed');
         });
     }
     /**
@@ -658,7 +957,7 @@ class BaseAttachment {
         try {
             if (!this.client || !this.pinnedHandle || !this.token) {
                 log('runCanRebind: missing client/handle/token — firing terminal');
-                this.fireTerminal('reconnect-exhausted');
+                this.fireTerminal('reconnect-exhausted', 'runCanRebind:missing-state');
                 return;
             }
             const workflowId = this.pinnedHandle.workflowId;
@@ -735,7 +1034,7 @@ class BaseAttachment {
         try {
             if (!this.client || !this.host || !this.token || !this.pinnedHandle) {
                 log('runReconnectLoop: missing client/host/token/handle — aborting');
-                this.fireTerminal('reconnect-exhausted');
+                this.fireTerminal('reconnect-exhausted', 'runReconnectLoop:missing-state');
                 return;
             }
             const workflowId = this.pinnedHandle.workflowId;
@@ -774,14 +1073,40 @@ class BaseAttachment {
                 }
                 catch (err) {
                     if ((0, terminal_error_1.isTerminalWorkflowError)(err)) {
-                        // #226: either terminal kind inside the reconnect loop's pre-check
-                        // ends the loop. We don't recurse into another CAN rebind here —
-                        // that path is only for the pinned-handle tick ticks where we can
-                        // read the closed run's history. Inside the loop the unpinned
-                        // query has already followed any CAN chain, so a gone error means
-                        // the workflow id is truly absent.
-                        log('reconnect: workflow gone during pre-check');
-                        this.fireTerminal('destroy');
+                        // #258: ONE terminal-class pre-check error is not enough evidence
+                        // to destroy the adapter. The classifier matches phrasings
+                        // (`WorkflowNotFound`, `NOT_FOUND`, "workflow execution already
+                        // completed") that can ALSO surface from transient gRPC blips and
+                        // momentary visibility-API hiccups. Pre-#258, this branch fired
+                        // `fireTerminal('destroy')` immediately — a single transient
+                        // error orphaned the adapter for the rest of the session
+                        // (heartbeat + watcher dead via `terminalFired`, poller torn
+                        // down by `onReconnectStart` + `onTerminal` listener).
+                        //
+                        // Tiebreaker: confirm with `describe()` against the same unpinned
+                        // handle. If the workflow is genuinely gone, `describe()` will
+                        // either return a closed status (COMPLETED/TERMINATED/...) or
+                        // itself throw — fire destroy with confidence. If it returns
+                        // RUNNING (or any non-terminal status), the original error was
+                        // transient — log and continue the loop. Bounded by
+                        // `DESCRIBE_TIMEOUT_MS` so a slow visibility-API call can't hang
+                        // the reconnect path indefinitely.
+                        const errClass = err?.name ?? 'unknown';
+                        const errMsg = err?.message ?? String(err);
+                        const tiebreak = await this.confirmWorkflowTerminal(unpinned);
+                        if (tiebreak.kind === 'running') {
+                            log(`reconnect: pre-check threw ${errClass} but describe() shows ` +
+                                `${tiebreak.statusName} — treating as transient, continuing loop ` +
+                                `(originalError="${errMsg}")`);
+                            backoff = Math.min(backoff * this.reconnectBackoffFactor, this.reconnectMaxMs);
+                            continue;
+                        }
+                        const confirmDesc = tiebreak.kind === 'terminal'
+                            ? `describe() confirmed ${tiebreak.statusName}`
+                            : `describe() ${tiebreak.kind === 'describe-threw' ? 'threw' : 'timed out'}`;
+                        log(`reconnect: pre-check terminal (${errClass}) and ${confirmDesc} — firing destroy ` +
+                            `(originalError="${errMsg}")`);
+                        this.fireTerminal('destroy', 'runReconnectLoop:precheck-terminal-confirmed');
                         return;
                     }
                     backoff = Math.min(backoff * this.reconnectBackoffFactor, this.reconnectMaxMs);
@@ -790,12 +1115,12 @@ class BaseAttachment {
                 }
                 if (info.phase === 'gone') {
                     log('reconnect: phase=gone — giving up');
-                    this.fireTerminal('destroy');
+                    this.fireTerminal('destroy', 'runReconnectLoop:phase-gone');
                     return;
                 }
                 if (info.currentAttachment && info.currentAttachment.attachmentId !== oldAttachmentId) {
                     log(`reconnect: another adapter holds the lease (${info.currentAttachment.attachmentId}) — bailing`);
-                    this.fireTerminal('superseded');
+                    this.fireTerminal('superseded', 'runReconnectLoop:other-holder');
                     return;
                 }
                 if (info.phase === 'draining') {
@@ -849,7 +1174,7 @@ class BaseAttachment {
                 catch (err) {
                     if ((0, terminal_error_1.isTerminalWorkflowError)(err)) {
                         log('reconnect: workflow gone during claim');
-                        this.fireTerminal('destroy');
+                        this.fireTerminal('destroy', 'runReconnectLoop:claim-terminal');
                         return;
                     }
                     backoff = Math.min(backoff * this.reconnectBackoffFactor, this.reconnectMaxMs);
@@ -858,7 +1183,7 @@ class BaseAttachment {
             }
             // Budget exhausted — give up cleanly.
             log(`reconnect budget exhausted after ${attempt} attempt(s)`);
-            this.fireTerminal('reconnect-exhausted');
+            this.fireTerminal('reconnect-exhausted', 'runReconnectLoop:budget-exhausted');
         }
         finally {
             // Guarantee state reset regardless of which path we exited on. Safe to

package/dist/cli/daemon-command.d.ts

@@ -45,3 +45,7 @@ export interface DaemonOpts extends CliOverrides {
     force?: boolean;
 }
 export declare function daemon(opts: DaemonOpts): Promise<void>;
+/** Pretty-print a byte count as MB (rounded). Pure helper, exported for tests. */
+export declare function formatBytesAsMb(n: unknown): string;
+/** Pretty-print a millisecond uptime as `Xh Ym Zs`. Pure helper, exported for tests. */
+export declare function formatUptime(ms: unknown): string;