claude-tempo 0.26.0-beta.2 → 0.26.0-beta.4

package/CLAUDE.md

@@ -20,12 +20,15 @@ src/
 ├── cli.ts             # CLI entry point (claude-tempo command)
 ├── daemon.ts          # Daemon entry point — runs Temporal workers as a detached background process
 ├── cli/
-│   ├── commands.ts    # CLI command implementations (up, start, conduct, status, stop, upgrade, …)
-│   ├── config-command.ts # config subcommand (interactive + set/show)
-│   ├── daemon.ts      # Daemon management utilities (start, stop, status, logs, isDaemonRunning)
+│   ├── commands.ts    # CLI command implementations (up, start, conduct, status, stop, …)
+│   ├── config-command.ts # config subcommand (interactive + set/show) — crash-proof for show/set
+│   ├── daemon.ts      # Daemon management utilities (start, stop, status, heartbeat, isDaemonRunning)
+│   ├── daemon-command.ts # daemon subcommand handler — crash-proof, no Temporal deps
+│   ├── help-text.ts   # help output — crash-proof, no Temporal deps
 │   ├── mcp.ts         # MCP server registration helpers (init, global vs project)
 │   ├── output.ts      # Shared CLI output formatting helpers
-│   └── preflight.ts   # Environment preflight checks
+│   ├── preflight.ts   # Environment preflight checks
+│   └── upgrade-command.ts # upgrade subcommand — crash-proof; dynamic-imports Temporal only for active-session warning
 ├── adapters/
 │   ├── README.md      # Adapter contract documentation
 │   ├── index.ts       # Adapter registry bootstrap + barrel exports
@@ -44,6 +47,7 @@ src/
 │   ├── session.ts     # claude-session workflow
 │   ├── scheduler.ts   # durable scheduler workflow (one per ensemble)
 │   ├── maestro.ts     # Maestro workflows — per-ensemble hub and global hub
+│   ├── attachment-math.ts # Pure CAN-boundary lease-extension helper (no Temporal imports)
 │   ├── maestro-signals.ts / scheduler-signals.ts / signals.ts   # Signal/query/update type defs
 │   └── index.ts       # Workflow re-exports for worker bundle
 ├── activities/
@@ -73,7 +77,7 @@ src/
 │   ├── components/    # Ink components — see docs/tui.md for inventory
 │   └── utils/         # format, platform, theme, fullscreen, history
 ├── utils/
-│   ├── validation.ts / worktree.ts / safe-path.ts / duration.ts
+│   ├── validation.ts / worktree.ts / safe-path.ts / duration.ts / search-attributes.ts
 ├── types.ts           # Shared type definitions
 ├── git-info.ts        # Git repository detection helper
 └── config.ts          # Env var handling
@@ -86,7 +90,7 @@ touching `src/tui/`.
 
 ```bash
 npm install
-npm run build    # compiles TS + pre-bundles workflow code into workflow-bundle.js
+npm run build    # compiles TS, scripts/*.ts → dist/scripts/, and pre-bundles workflow code into workflow-bundle.js
 npm test
 ```
 
@@ -113,6 +117,7 @@ daemon worker notes, `npx ts-node` dev runner).
 - **Part**: A player's description of what it's working on
 - **Outbox**: Outbound requests (cue, report, recruit, restart, detach, destroy, …) go through the session's workflow outbox instead of directly signaling other workflows. The dispatch loop processes entries via activities, decoupling tools from cross-workflow signaling.
 - **Attachment phase** (v0.26): Seven phases tracked on the session workflow — `booting → attached → processing | awaiting → draining → detached → gone`. The phase is authoritative for lifecycle truth: adapters drive it via `claimAttachment` / `adapterExited` / `forceDetach` / `destroy`, and the workflow publishes it on the `ClaudeTempoAttachmentState` search attribute. Replaced the v0.25 `ClaudeTempoStatus` heuristic (removed in v0.26). See [docs/concepts.md](docs/concepts.md) for the phase table and [docs/ops/v0.26-migration.md](docs/ops/v0.26-migration.md) for the upgrade path.
+- **Adapter heartbeat observability** (#249): After `claimAttachment`, the base adapter logs `first heartbeat scheduled in Xms` then `heartbeat#1 delivered` on the first tick. Every 10 ticks it emits `heartbeats-delivered=N / phase-ticks=N` breadcrumbs. Any silent guard trip in `tickHeartbeat` / `tickPhaseWatcher` now emits a structured `guard tripped: {stopped, reconnecting, …}` log instead of silently orphaning the timer. The phase-watcher emits `WARNING: heartbeat staleness` when `lastHeartbeatAt` falls more than 2× `heartbeatMs` behind `now`. Grep `[claude-tempo:adapter]` to confirm loop health without parsing Temporal history.
 - **Per-host task queues**: `host` param on `recruit`/`restart`/`migrate` routes to `claude-tempo-{hostname}` task queue. See [docs/concepts.md](docs/concepts.md) for cross-machine recruiting details.
 - **Wire protocol**: All signal/query/update names are documented in [`docs/WIRE-PROTOCOL.md`](docs/WIRE-PROTOCOL.md) and are stable — renaming or removing any is a breaking change. **Process**: update `docs/WIRE-PROTOCOL.md` in the same commit as any new signal, query, or update.
 - **Daemon**: Standalone background process (`src/daemon.ts`) that runs all Temporal workers. Auto-started by any `claude-tempo` command. PID at `~/.claude-tempo/daemon.pid`; logs at `~/.claude-tempo/daemon.log`.

package/dist/activities/outbox.js

@@ -51,6 +51,87 @@ const adapters_1 = require("../adapters");
 const hard_terminate_1 = require("./hard-terminate");
 const signals_1 = require("../workflows/signals");
 const log = (...args) => console.error('[claude-tempo:outbox]', ...args);
+/**
+ * Classify a Temporal client error raised by `handle.query` / `handle.signal`
+ * / `handle.executeUpdate` as retryable (transient) vs permanent (#140).
+ *
+ * ## Contract
+ * - Returns `true` → caller should **re-throw the underlying Error** so the
+ *   activity's retry policy can back off and retry (per-worker config).
+ * - Returns `false` → caller should wrap in `ApplicationFailure.nonRetryable`
+ *   so the outbox surfaces a permanent failure and stops retrying.
+ *
+ * ## Safety posture
+ * **Conservative default: unknown → non-retryable.** Over-classifying as
+ * retryable causes infinite retry loops on genuinely permanent errors. The
+ * activity will fail fast on unknown cases; a follow-up PR can whitelist more
+ * transient signatures if we see false-permanent rates in the wild.
+ *
+ * ## Why name/message sniffing, not `instanceof`
+ * Matches the established pattern in `src/adapters/terminal-error.ts`
+ * `isTerminalWorkflowError`: the Temporal Node SDK surfaces slightly different
+ * error shapes between `@temporalio/client`, the gRPC layer, and
+ * `WorkflowUpdateFailedError` wrappers. Sniffing on name + message is resilient
+ * across those shapes. Activity-side classification is kept separate here so
+ * `src/activities/` has no adapter-module dependency.
+ */
+function isRetryableTemporalError(err) {
+    // ApplicationFailure instances have already been classified by the thrower
+    // (nonRetryable=true/false). The calling code paths in this module only ask
+    // about non-ApplicationFailure errors, but this guard makes the helper safe
+    // to call unconditionally.
+    if (err instanceof activity_1.ApplicationFailure)
+        return false;
+    const e = err;
+    const name = e?.name ?? '';
+    const msg = e?.message ?? '';
+    // ── Permanent: workflow is genuinely gone or validator rejected the op. ──
+    if (name.includes('WorkflowNotFound') ||
+        name.includes('WorkflowExecutionAlreadyCompleted') ||
+        // Update rejected by the workflow-side validator (e.g. `WorkflowGone`
+        // thrown from `claimAttachment`'s validator on a destroyed session).
+        // A retry won't make the validator change its mind.
+        name.includes('WorkflowUpdateFailed') ||
+        msg.includes('WorkflowGone') ||
+        msg.includes('workflow execution already completed'))
+        return false;
+    // ── Transient: RPC / network / temporary SDK unavailability. ──
+    if (name.includes('TransportError') ||
+        name.includes('TimeoutError') ||
+        msg.includes('DEADLINE_EXCEEDED') ||
+        msg.includes('UNAVAILABLE') ||
+        msg.includes('RESOURCE_EXHAUSTED') ||
+        msg.includes('CANCELLED') ||
+        /\bECONNRESET\b/.test(msg) ||
+        /\bECONNREFUSED\b/.test(msg) ||
+        /\bETIMEDOUT\b/.test(msg) ||
+        /\bENOTFOUND\b/.test(msg) ||
+        /\bEAI_AGAIN\b/.test(msg))
+        return true;
+    // Unknown shape — stay permanent (see "Safety posture" above).
+    return false;
+}
+/**
+ * Standard shape for the 3 §8.2 deliver activities' catch-all tail.
+ * Centralises the branch so each activity body stays concise.
+ *
+ * - If `err` is already an `ApplicationFailure` (typed permanent — e.g. the
+ *   explicit "not found" / "destroyed" throws), re-throw as-is.
+ * - If `err` is retryable per {@link isRetryableTemporalError}, re-throw the
+ *   original `Error` so the activity retry policy handles it.
+ * - Otherwise wrap in `ApplicationFailure.nonRetryable` with a caller-supplied
+ *   context prefix (e.g. `Detach failed for "alice"`).
+ */
+function classifyAndRethrow(err, contextPrefix) {
+    if (err instanceof activity_1.ApplicationFailure)
+        throw err;
+    if (isRetryableTemporalError(err)) {
+        // Re-throw the original so the activity retry policy backs off and retries.
+        // Normalise non-Error throwables (extremely rare) into Error form.
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+    throw activity_1.ApplicationFailure.nonRetryable(`${contextPrefix}: ${err instanceof Error ? err.message : String(err)}`);
+}
 /**
  * Create outbox delivery activities bound to a Temporal client and config.
  * The returned object is registered with the worker as activities.
@@ -59,12 +140,20 @@ function createOutboxActivities(client, config) {
     return {
         async deliverCue(input) {
             const { ensemble, fromPlayerId, targetPlayerId, message } = input;
-            const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
-            if (!handle) {
-                throw activity_1.ApplicationFailure.nonRetryable(`No active session found for "${targetPlayerId}"`);
+            try {
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No active session found for "${targetPlayerId}"`);
+                }
+                await handle.signal('receiveMessage', { from: fromPlayerId, text: message });
+                return { success: true };
+            }
+            catch (err) {
+                // #236: transient RPC errors (e.g. DEADLINE_EXCEEDED on the signal call)
+                // retry per the activity policy; WorkflowNotFound / validator rejections
+                // stay permanent. Unknown errors default to non-retryable.
+                classifyAndRethrow(err, `Cue failed for "${targetPlayerId}"`);
             }
-            await handle.signal('receiveMessage', { from: fromPlayerId, text: message });
-            return { success: true };
         },
         async deliverReport(input) {
             const { ensemble, fromPlayerId, text, reportType } = input;
@@ -76,37 +165,44 @@ function createOutboxActivities(client, config) {
                 return { success: true };
             }
             catch (err) {
-                if (err instanceof activity_1.ApplicationFailure)
-                    throw err;
-                throw activity_1.ApplicationFailure.nonRetryable(`Failed to deliver report to conductor: ${err instanceof Error ? err.message : String(err)}`);
+                // #236: describe() / signal() hitting a transient RPC error now retries;
+                // WorkflowNotFound (conductor gone) stays permanent as before.
+                classifyAndRethrow(err, 'Failed to deliver report to conductor');
             }
         },
         async terminateSession(input) {
             const { ensemble, targetPlayerId, terminatedBy } = input;
-            const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
-            if (!handle) {
-                throw activity_1.ApplicationFailure.nonRetryable(`No active session found for "${targetPlayerId}"`);
-            }
-            // PR-C commit 4: use the V2 `destroy` update — explicit operator termination
-            // per §2.5 (abandon in-flight, phase=gone, COMPLETE). The former
-            // `updateMetadata({ status: 'terminated' })` signal path was retired.
-            await handle.executeUpdate('destroy', {
-                args: [{ reason: 'stop via tool', terminatedBy }],
-            });
-            // Notify conductor about the termination (best effort)
             try {
-                const conductorId = (0, config_1.conductorWorkflowId)(ensemble);
-                const conductorHandle = client.workflow.getHandle(conductorId);
-                await conductorHandle.signal('receiveMessage', {
-                    from: 'system',
-                    text: `Session "${targetPlayerId}" was terminated by ${terminatedBy}.`,
-                    responseRequested: false,
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No active session found for "${targetPlayerId}"`);
+                }
+                // PR-C commit 4: use the V2 `destroy` update — explicit operator termination
+                // per §2.5 (abandon in-flight, phase=gone, COMPLETE). The former
+                // `updateMetadata({ status: 'terminated' })` signal path was retired.
+                await handle.executeUpdate('destroy', {
+                    args: [{ reason: 'stop via tool', terminatedBy }],
                 });
+                // Notify conductor about the termination (best effort)
+                try {
+                    const conductorId = (0, config_1.conductorWorkflowId)(ensemble);
+                    const conductorHandle = client.workflow.getHandle(conductorId);
+                    await conductorHandle.signal('receiveMessage', {
+                        from: 'system',
+                        text: `Session "${targetPlayerId}" was terminated by ${terminatedBy}.`,
+                        responseRequested: false,
+                    });
+                }
+                catch {
+                    // Conductor may not exist — that's fine
+                }
+                return { success: true };
             }
-            catch {
-                // Conductor may not exist — that's fine
+            catch (err) {
+                // #236: transient RPC on the destroy update now retries; validator rejection
+                // (WorkflowGone, AttachmentMismatch) stays permanent.
+                classifyAndRethrow(err, `Terminate failed for "${targetPlayerId}"`);
             }
-            return { success: true };
         },
         async startRecruitedSession(input) {
             const { ensemble, targetName, workDir, isConductor, initialMessage, fromPlayerId, agent, systemPrompt, taskQueue, agentDefinition, agentDefinitionDescription, held } = input;
@@ -177,7 +273,11 @@ function createOutboxActivities(client, config) {
                 return { success: true, sessionId };
             }
             catch (err) {
-                throw activity_1.ApplicationFailure.nonRetryable(`Failed to start recruited session "${targetName}": ${err instanceof Error ? err.message : String(err)}`);
+                // #236: transient RPC during workflow.start (e.g. temporal server flap)
+                // now retries; WorkflowNotFound / validation / auth failures stay permanent.
+                // Note: this activity's pre-#236 catch was missing the ApplicationFailure
+                // passthrough guard — `classifyAndRethrow` restores it for free.
+                classifyAndRethrow(err, `Failed to start recruited session "${targetName}"`);
             }
         },
         async spawnProcess(input) {
@@ -267,7 +367,14 @@ function createOutboxActivities(client, config) {
                 return { success: true };
             }
             catch (err) {
-                throw activity_1.ApplicationFailure.nonRetryable(`Failed to spawn process for "${targetName}": ${err instanceof Error ? err.message : String(err)}`);
+                // #236: spawnProcess throws predominantly OS-side errors (ENOENT/EACCES
+                // on the claude binary, EAGAIN on process-table overflow). The classifier
+                // is tuned for Temporal RPC; OS errors don't match its transient
+                // signatures, so they still flow through as non-retryable — byte-for-byte
+                // behavior preservation. The upside of going through the helper: if a
+                // future OS error surfaces a transient shape we add to the classifier,
+                // spawnProcess benefits automatically.
+                classifyAndRethrow(err, `Failed to spawn process for "${targetName}"`);
             }
         },
         async releasePlayer(input) {
@@ -288,9 +395,9 @@ function createOutboxActivities(client, config) {
                 return { success: true };
             }
             catch (err) {
-                if (err instanceof activity_1.ApplicationFailure)
-                    throw err;
-                throw activity_1.ApplicationFailure.nonRetryable(`Release failed for "${targetPlayerId}": ${err instanceof Error ? err.message : String(err)}`);
+                // #236: transient RPC on outboxLocked query / releaseHeld signal now
+                // retries; WorkflowNotFound / not-held validation stay permanent.
+                classifyAndRethrow(err, `Release failed for "${targetPlayerId}"`);
             }
         },
         /**
@@ -318,9 +425,10 @@ function createOutboxActivities(client, config) {
                 return { success: true };
             }
             catch (err) {
-                if (err instanceof activity_1.ApplicationFailure)
-                    throw err;
-                throw activity_1.ApplicationFailure.nonRetryable(`Detach failed for "${targetPlayerId}": ${err instanceof Error ? err.message : String(err)}`);
+                // #140: re-throw transient RPC/network errors so the activity retry
+                // policy handles them; permanent cases (validator rejection, workflow
+                // gone, unknown) become `ApplicationFailure.nonRetryable`.
+                classifyAndRethrow(err, `Detach failed for "${targetPlayerId}"`);
             }
         },
         /**
@@ -359,9 +467,10 @@ function createOutboxActivities(client, config) {
                 return { success: true };
             }
             catch (err) {
-                if (err instanceof activity_1.ApplicationFailure)
-                    throw err;
-                throw activity_1.ApplicationFailure.nonRetryable(`Destroy failed for "${targetPlayerId}": ${err instanceof Error ? err.message : String(err)}`);
+                // #140: transient errors (network, RPC timeout) become retryable;
+                // permanent cases (WorkflowNotFound, validator rejection) stay
+                // non-retryable. Unknown errors default to non-retryable.
+                classifyAndRethrow(err, `Destroy failed for "${targetPlayerId}"`);
             }
         },
         /**
@@ -393,7 +502,7 @@ function createOutboxActivities(client, config) {
                         try {
                             await handle.signal(signals_1.requestDetachSignal, {
                                 reason: 'restart',
-                                deadlineMs: 5_000,
+                                deadlineMs: validation_1.DEFAULT_RESTART_DETACH_DEADLINE_MS,
                             });
                         }
                         catch {
@@ -433,7 +542,7 @@ function createOutboxActivities(client, config) {
                             host: targetHost,
                             adapterId,
                             adapterClass,
-                            leaseMs: 90_000,
+                            leaseMs: validation_1.DEFAULT_RESTART_LEASE_MS,
                         }],
                 });
                 // Step 5 — optional context replay.
@@ -503,9 +612,11 @@ function createOutboxActivities(client, config) {
                 return { success: true };
             }
             catch (err) {
-                if (err instanceof activity_1.ApplicationFailure)
-                    throw err;
-                throw activity_1.ApplicationFailure.nonRetryable(`Restart failed for "${targetPlayerId}": ${err instanceof Error ? err.message : String(err)}`);
+                // #140: the §8.2 restart algorithm fires many RPCs; any of them may
+                // hit a transient network/RPC error. Those get retried. Validator
+                // rejections (e.g. claim race), workflow-gone, and unknown errors
+                // stay permanent to avoid wedging the outbox on a dead target.
+                classifyAndRethrow(err, `Restart failed for "${targetPlayerId}"`);
             }
         },
         /**

package/dist/activities/resolve.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveSession = resolveSession;
 exports.scanEnsembleSessions = scanEnsembleSessions;
+const search_attributes_1 = require("../utils/search-attributes");
 /** Shared query for listing running session workflows. */
 const SESSION_LIST_QUERY = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
 /**
@@ -43,10 +44,7 @@ async function scanEnsembleSessions(client, ensemble) {
             const part = await handle.query('getPart');
             // Attachment phase lives in the `ClaudeTempoAttachmentState` search
             // attribute (written by the workflow on every phase transition).
-            const phaseArr = workflow.searchAttributes?.ClaudeTempoAttachmentState;
-            const phase = Array.isArray(phaseArr) && phaseArr.length > 0
-                ? phaseArr[0]
-                : undefined;
+            const phase = (0, search_attributes_1.getAttachmentPhase)(workflow);
             sessions.push({
                 workflowId: workflow.workflowId,
                 playerId: metadata.playerId,

package/dist/adapters/base.d.ts

@@ -65,6 +65,27 @@ export declare abstract class BaseAttachment {
     private stopped;
     private terminalFired;
     private knownPhase;
+    /**
+     * `true` once a heartbeat has successfully landed on the current attachment (or rebind).
+     * Cleared on `startV2Lifecycle`, reconnect-loop success, and CAN rebind so each freshly
+     * live attachment emits its own `heartbeat#1 delivered` diagnostic. Added in #249 to
+     * distinguish "claim OK but heartbeat loop died" from "adapter just hasn't ticked yet."
+     */
+    private firstHeartbeatLogged;
+    /**
+     * Monotonic heartbeat counter for the current attachment cycle. Reset on
+     * claim/reconnect/CAN-rebind. Emitted periodically (every {@link HEARTBEAT_SUMMARY_EVERY}
+     * ticks) so a long-running session leaves breadcrumbs in the log proving the loop is
+     * alive — operators can `grep 'heartbeats-delivered='` to confirm health without
+     * parsing Temporal history. Added in #249.
+     */
+    private heartbeatsSent;
+    /**
+     * Mirror of {@link heartbeatsSent} for the phase-watcher loop. Same emission cadence,
+     * same rationale — the watcher is the only self-heal surface when the heartbeat loop
+     * dies silently, so a summary log line proves it's still live too.
+     */
+    private phaseTicksDone;
     private readonly phaseChangeListeners;
     private readonly leaseRevokedListeners;
     private readonly terminalListeners;
@@ -133,17 +154,68 @@ export declare abstract class BaseAttachment {
      */
     protected stopV2Lifecycle(reason?: DetachReason, graceful?: boolean): Promise<void>;
     private scheduleHeartbeat;
+    /**
+     * Emit a loud diagnostic when a tick early-returns via one of its guard paths (#249).
+     * Pre-#249 these returns were silent — the only observable effect was "heartbeats stop
+     * arriving." Now operators can grep `adapter.*guard tripped` to confirm or rule out
+     * tick-orphan as a failure mode without needing workflow history.
+     *
+     * `terminalFired=true` / `stopped=true` guards are load-bearing on the terminal path
+     * (don't want to re-enter terminal) so they're expected during teardown; we still log
+     * them but at the same level — operators can correlate timestamps against the preceding
+     * `terminal (...) — stopping delivery poll permanently` line.
+     */
+    private logGuardTrip;
+    /**
+     * Single tick of the heartbeat loop. Try/finally scaffolding (#249) guarantees
+     * reschedule in every path except genuinely terminal state (`stopped`,
+     * `terminalFired`) or when the reconnect loop has taken ownership of scheduling
+     * (`reconnecting`). Pre-#249 the three early-return paths at the top + the
+     * handled-terminal-error path silently orphaned the timer forever; a transient
+     * `reconnecting=true` window or a null-handle race was enough to kill the loop
+     * with no log and no teardown.
+     *
+     * Handled terminals (CAN rebind, destroy) still short-circuit via `return` —
+     * the `finally` block re-checks `reconnecting` / `terminalFired` before
+     * rescheduling, so the reconnect/terminal machinery keeps ownership of
+     * whatever comes next.
+     */
     private tickHeartbeat;
     private schedulePhaseWatcher;
+    /**
+     * Single tick of the phase-watcher loop. Same orphan-resistance scaffolding as
+     * {@link tickHeartbeat} (#249): try/finally reschedule, unconditional unless
+     * `stopped` / `terminalFired` / `reconnecting`. When the heartbeat loop dies
+     * silently, the watcher is the only remaining self-heal surface — losing it
+     * too meant the adapter had no path back to a healthy state short of process
+     * restart.
+     */
     private tickPhaseWatcher;
     /**
-     * Classify an error as terminal (WorkflowNotFound / ExecutionAlreadyCompleted / phase gone).
+     * Shared error-classification path for the heartbeat + phase-watcher ticks (#226).
+     *
+     * Returns `true` if the error was a terminal-class (handled inline: CAN rebind
+     * kicked off, or destroy fired). Returns `false` when the caller should treat
+     * the error as transient and continue its backoff.
+     *
+     * Always consults `fetchHistory` on any terminal-class error, because the
+     * Temporal SDK can't distinguish CAN-close from true-complete at the error
+     * level — see {@link isTerminalWorkflowError}. The history lookup is cheap
+     * (only runs on terminal, so at most once per adapter lifetime per terminal)
+     * and safer than re-querying by workflow id (which could race a fresh session
+     * reusing the id).
+     */
+    private handleRunEndError;
+    /**
+     * Fetch the closed pinned run's history and return the runId of a CAN successor
+     * if present, else `null`. Scoped to the pinned (old) run via `this.pinnedHandle`,
+     * so it can't be fooled by a fresh session that happens to reuse the workflow id.
      *
-     * Uses name-sniffing rather than `instanceof` to avoid tight coupling to
-     * `@temporalio/client` internals — errors surface through both the Client SDK
-     * and the server's gRPC layer with slightly different shapes.
+     * Called only on the terminal path from {@link handleRunEndError}, so the cost
+     * of `fetchHistory` (a full event stream for the closed run) is paid at most
+     * once per terminal — not on every tick.
      */
-    private isWorkflowGone;
+    private findCanSuccessorRunId;
     private fireTerminal;
     /**
      * Opt-in reconnect policy. Default: return `false` — the base class behaves
@@ -194,6 +266,24 @@ export declare abstract class BaseAttachment {
      * when the reason is potentially recoverable.
      */
     private fireTerminalOrReconnect;
+    /**
+     * #226 CAN rebind. Transparently repoints `pinnedHandle` at the successor run,
+     * keeps the existing `attachmentId` / `leaseMs` (the workflow extended the lease
+     * by one heartbeat interval during the CAN transition per §2.3, so the lease is
+     * still live on the new run), notifies the subclass to restart its delivery
+     * loop, and resumes heartbeat + phase-watcher.
+     *
+     * Why this is safe without re-claiming:
+     *  - The new run carries forward `currentAttachment` verbatim from the old run.
+     *  - The adapter's `attachmentId` still matches, so the next `heartbeat` /
+     *    `markDelivered` / `adapterExited` signal on the new pinned handle will be
+     *    accepted unchanged by the workflow's handlers.
+     *  - If the lease actually did expire before we got here (e.g. adapter was
+     *    offline through multiple CAN cycles), the next phase-watcher tick on the
+     *    new pinned handle will see `phase=detached` + no current attachment and
+     *    fall through to the existing #201 reclaim path — belt-and-suspenders.
+     */
+    private runCanRebind;
     /**
      * Budget-bounded reconnect loop.
      *