agent-tempo 1.7.0 → 2.0.0-beta.2

package/dist/upgrade/from-upgrade.js

@@ -0,0 +1,330 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONSUMED_SNAPSHOT_FILENAME = void 0;
+exports.planRecreation = planRecreation;
+exports.collectUndeliveredCues = collectUndeliveredCues;
+exports.archiveSnapshot = archiveSnapshot;
+exports.runFromUpgrade = runFromUpgrade;
+/**
+ * #786 — `agent-tempo up --from-upgrade` (the 2.0 side of the cutover).
+ *
+ * After `upgrade-to-2` (#785) has snapshotted continuity and destroyed every
+ * 1.x run, a fresh 2.0 daemon boots cleanly (the boot guard sees zero
+ * un-stamped workflows). This module is what `up --from-upgrade` then runs: it
+ * reads `upgrade-snapshot-v1.json` and recreates a fresh protocol-2 workflow
+ * for every player in the snapshot ROSTER.
+ *
+ * Each recreated session carries the structural identity needed to exist as a
+ * protocol-2 workflow (`ensemble`, `playerId`, `workDir`, `agentType`,
+ * `isConductor`, plus the cheap structural memo: gitRoot/playerType) AND the
+ * continuity the snapshot captured. The workflow self-stamps the
+ * `AgentTempoProtocol` memo on start (and we seed it here too, so the row is
+ * stamped even before the first workflow task runs).
+ *
+ * **Continuity seeding (the #786 fast-follow — a non-droppable beta.1 gate):**
+ *   - **#334 state slots** — seeded onto each session's `playerState` so the
+ *     player's own curated context survives the cutover.
+ *   - **`sessionId`** — seeded onto `metadata.sessionId` so the first re-attach
+ *     can `--resume` into the original adapter conversation.
+ *   - **Non-default recruit `model`** — seeded onto `metadata.model` so an
+ *     ad-hoc claude-api / opencode / pi player is recreated on the SAME model.
+ *   - **Durable schedules + scheduler** — for any ensemble with captured
+ *     schedules, the per-ensemble `agentSchedulerWorkflow` is recreated and
+ *     seeded with the schedule entries (the #786 MVP correctly skipped it since
+ *     it is lazily created; we recreate it here only when there is intent to
+ *     restore). Empty-schedule ensembles get NO scheduler — it would just
+ *     self-terminate after its 30s empty grace.
+ *
+ * **Re-attach is a SEPARATE operator step — `up --from-upgrade` does NOT
+ * re-spawn adapters.** Every recreated session lands in the `booting` phase
+ * (no `currentAttachment`, stale-detection suppressed) — a durable skeleton
+ * with continuity seeded, awaiting an adapter. Auto-spawning N adapters across
+ * hosts during a migration is surprising and risky (terminals popping,
+ * cross-host spawns); the snapshot is about durable continuity, not live
+ * process resurrection. The operator brings each session live on their own
+ * schedule via `restart` / `restore` (which honour the seeded `sessionId` for
+ * `--resume`). This is flagged for the migration note in the docs.
+ *
+ * **Undelivered cues are surfaced for REVIEW only — NEVER redelivered**
+ * (replaying stale cues into fresh sessions is worse than operator triage,
+ * #785 §4). The caller prints them; this module just collects them.
+ *
+ * **Archive-on-success:** the snapshot is renamed to
+ * `upgrade-snapshot-v1.consumed.json` only when every workflow was recreated
+ * without error. On any partial failure the snapshot is left PRISTINE so the
+ * operator can fix the cause and re-run (recreation is idempotent via
+ * `USE_EXISTING`).
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const client_1 = require("@temporalio/client");
+const config_1 = require("../config");
+const search_attributes_1 = require("../utils/search-attributes");
+const constants_1 = require("../constants");
+const default_part_1 = require("../utils/default-part");
+const snapshot_v1_1 = require("./snapshot-v1");
+/** Filename the consumed snapshot is archived to on success. */
+exports.CONSUMED_SNAPSHOT_FILENAME = 'upgrade-snapshot-v1.consumed.json';
+/**
+ * Pure planner: turn a snapshot into the list of protocol-2 workflows to
+ * recreate. One `agentMaestroWorkflow` per ensemble (so the ensemble is
+ * coordinated + discoverable) plus one `agentSessionWorkflow` per roster player
+ * (conductor via {@link conductorWorkflowId}, others via
+ * {@link sessionWorkflowId}). Structural essentials only — see the module
+ * header. Exported so the recreation set is unit-testable without Temporal.
+ */
+function planRecreation(snapshot, opts) {
+    const specs = [];
+    for (const ensemble of snapshot.ensembles) {
+        // Per-ensemble maestro hub — structural coordination workflow. Recreated so
+        // the ensemble is observable; idempotent via USE_EXISTING at start time.
+        specs.push({
+            workflowId: (0, config_1.maestroWorkflowId)(ensemble.name),
+            workflowType: 'agentMaestroWorkflow',
+            ensemble: ensemble.name,
+            args: [{ ensemble: ensemble.name }],
+            searchAttributes: { AgentTempoEnsemble: [ensemble.name] },
+            memo: { [search_attributes_1.MEMO_KEYS.protocol]: constants_1.PROTOCOL_VERSION },
+        });
+        for (const player of ensemble.players) {
+            const workflowId = player.isConductor
+                ? (0, config_1.conductorWorkflowId)(ensemble.name)
+                : (0, config_1.sessionWorkflowId)(ensemble.name, player.playerId);
+            const playerHostname = player.hostname || opts.hostname;
+            const autoSummary = (0, default_part_1.defaultPart)({
+                playerType: player.playerType,
+                isConductor: player.isConductor,
+                workDir: player.workDir,
+                adapterType: player.agentType,
+            });
+            const playerState = seedPlayerState(player, snapshot.createdAt);
+            const input = {
+                metadata: {
+                    playerId: player.playerId,
+                    ensemble: ensemble.name,
+                    hostname: playerHostname,
+                    workDir: player.workDir,
+                    isConductor: player.isConductor,
+                    agentType: player.agentType,
+                    ...(player.gitRoot ? { gitRoot: player.gitRoot } : {}),
+                    ...(player.playerType ? { playerType: player.playerType } : {}),
+                    // Resume pointer — lets the first re-attach `--resume` into the
+                    // original adapter conversation (#785 continuity).
+                    ...(player.sessionId ? { sessionId: player.sessionId } : {}),
+                    // Non-default recruit model — ad-hoc claude-api/opencode/pi players
+                    // are recreated on the SAME model (#131 / #449 / #734).
+                    ...(player.model ? { model: player.model } : {}),
+                },
+                // Carried so the stamp is in history from run 1; the workflow also
+                // upserts it authoritatively from the constant.
+                protocol: constants_1.PROTOCOL_VERSION,
+                autoSummary,
+                // #334 saveable-state slots — the player's own curated continuity.
+                // Omitted entirely for the no-state case (mirrors the workflow's
+                // populated-only CAN carry idiom).
+                ...(playerState ? { playerState } : {}),
+                // Recreated skeletons have no live adapter yet — suppress stale
+                // detection until one attaches (mirrors recruit / lineup pre-create).
+                disableStaleDetection: true,
+                temporalConfig: {
+                    temporalAddress: opts.temporalAddress,
+                    temporalNamespace: opts.temporalNamespace,
+                    taskQueue: opts.taskQueue,
+                },
+            };
+            specs.push({
+                workflowId,
+                workflowType: 'agentSessionWorkflow',
+                ensemble: ensemble.name,
+                playerId: player.playerId,
+                args: [input],
+                searchAttributes: {
+                    AgentTempoHostname: [playerHostname],
+                    AgentTempoEnsemble: [ensemble.name],
+                    AgentTempoPlayerId: [player.playerId],
+                },
+                memo: {
+                    ...(player.gitRoot ? { [search_attributes_1.MEMO_KEYS.gitRoot]: player.gitRoot } : {}),
+                    ...(player.playerType ? { [search_attributes_1.MEMO_KEYS.playerType]: player.playerType } : {}),
+                    [search_attributes_1.MEMO_KEYS.isConductor]: player.isConductor,
+                    [search_attributes_1.MEMO_KEYS.part]: autoSummary,
+                    [search_attributes_1.MEMO_KEYS.workDir]: player.workDir,
+                    [search_attributes_1.MEMO_KEYS.agentType]: player.agentType,
+                    // Seed the protocol stamp on the START memo so the boot guard sees a
+                    // stamped row even before the workflow's first task runs.
+                    [search_attributes_1.MEMO_KEYS.protocol]: constants_1.PROTOCOL_VERSION,
+                },
+            });
+        }
+        // Per-ensemble scheduler — recreated ONLY when there is captured intent to
+        // restore. The scheduler is lazily created (it self-terminates after a 30s
+        // empty grace), so seeding an empty one is pointless; we recreate it solely
+        // to re-home the durable schedule entries (#785 §4). The scheduler workflow
+        // self-stamps the protocol memo on start; we also seed it on the START memo
+        // so the boot guard sees a stamped row immediately.
+        if (ensemble.schedules.length > 0) {
+            specs.push({
+                workflowId: (0, config_1.schedulerWorkflowId)(ensemble.name),
+                workflowType: 'agentSchedulerWorkflow',
+                ensemble: ensemble.name,
+                args: [{ ensemble: ensemble.name, entries: ensemble.schedules.map(toScheduleEntry) }],
+                searchAttributes: { AgentTempoEnsemble: [ensemble.name] },
+                memo: { [search_attributes_1.MEMO_KEYS.protocol]: constants_1.PROTOCOL_VERSION },
+            });
+        }
+    }
+    return specs;
+}
+/**
+ * Convert a player's captured #334 state slots (`key → content`) into the
+ * `playerState` map the session workflow seeds at boot. `save_state` is
+ * owner-only, so `savedBy` is the player itself; `savedAt` uses the snapshot's
+ * freeze time (the best available timestamp — the original per-slot write time
+ * is not captured in the v1 contract). Returns `undefined` for the common
+ * no-state case so the field is omitted from the seed input.
+ */
+function seedPlayerState(player, frozenAt) {
+    const keys = Object.keys(player.stateSlots);
+    if (keys.length === 0)
+        return undefined;
+    const out = {};
+    for (const key of keys) {
+        out[key] = { content: player.stateSlots[key], savedAt: frozenAt, savedBy: player.playerId };
+    }
+    return out;
+}
+/**
+ * Convert a captured {@link SnapshotSchedule} (a frozen, decoupled copy) back
+ * into a live {@link ScheduleEntry} for the recreated scheduler. `firedCount`
+ * is not part of the durable-intent contract (it is a runtime accumulator), so
+ * it resets to 0 — the recreated schedule starts a fresh fire history.
+ */
+function toScheduleEntry(s) {
+    return {
+        name: s.name,
+        message: s.message,
+        target: s.target,
+        createdBy: s.createdBy,
+        nextFireAt: s.nextFireAt,
+        type: s.type,
+        firedCount: 0,
+        ...(s.interval !== undefined ? { interval: s.interval } : {}),
+        ...(s.cronExpression ? { cronExpression: s.cronExpression } : {}),
+        ...(s.timezone ? { timezone: s.timezone } : {}),
+        ...(s.until ? { until: s.until } : {}),
+        ...(s.remainingCount !== undefined ? { remainingCount: s.remainingCount } : {}),
+    };
+}
+/** Collect every undelivered cue across the snapshot (review only). */
+function collectUndeliveredCues(snapshot) {
+    const out = [];
+    for (const ensemble of snapshot.ensembles) {
+        for (const player of ensemble.players) {
+            for (const msg of player.undeliveredMessages) {
+                out.push({
+                    ensemble: ensemble.name,
+                    playerId: player.playerId,
+                    from: msg.from,
+                    text: msg.text,
+                    timestamp: msg.timestamp,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Archive the consumed snapshot: `upgrade-snapshot-v1.json` →
+ * `upgrade-snapshot-v1.consumed.json`. Overwrites a prior `.consumed.json`
+ * from an earlier run (rename is atomic on the same volume). Returns the
+ * archive path.
+ */
+function archiveSnapshot(home) {
+    const from = (0, snapshot_v1_1.snapshotPath)(home);
+    const to = (0, path_1.join)(home, exports.CONSUMED_SNAPSHOT_FILENAME);
+    (0, fs_1.renameSync)(from, to);
+    return to;
+}
+/**
+ * Recreate protocol-2 workflows from the on-disk upgrade snapshot.
+ *
+ * Returns a structured result; never throws on a per-workflow failure (those
+ * are collected in {@link FromUpgradeResult.failures}). A malformed snapshot
+ * DOES throw (via `readSnapshot` → `SnapshotValidationError`) — a corrupt
+ * continuity file is a loud failure, never a silent skip.
+ */
+async function runFromUpgrade(client, opts) {
+    const log = opts.log ?? (() => { });
+    const snapshot = (0, snapshot_v1_1.readSnapshot)(opts.home); // throws (loud) on a malformed file
+    if (!snapshot) {
+        return {
+            ok: false,
+            snapshotFound: false,
+            ensemblesRecreated: 0,
+            workflowsCreated: 0,
+            failures: [],
+            undeliveredCues: [],
+            archived: false,
+        };
+    }
+    const specs = planRecreation(snapshot, {
+        hostname: opts.hostname ?? (0, os_1.hostname)(),
+        taskQueue: opts.taskQueue,
+        temporalAddress: opts.temporalAddress,
+        temporalNamespace: opts.temporalNamespace,
+    });
+    const failures = [];
+    let created = 0;
+    for (const spec of specs) {
+        try {
+            await client.workflow.start(spec.workflowType, {
+                workflowId: spec.workflowId,
+                taskQueue: opts.taskQueue,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                args: spec.args,
+                // Idempotent re-run: an already-recreated workflow is left as-is.
+                workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+                searchAttributes: spec.searchAttributes,
+                memo: spec.memo,
+            });
+            created++;
+            log(`from-upgrade: recreated ${spec.workflowType} ${spec.workflowId}`);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            failures.push({ workflowId: spec.workflowId, error });
+            log(`from-upgrade: FAILED to recreate ${spec.workflowId}: ${error}`);
+        }
+    }
+    const undeliveredCues = collectUndeliveredCues(snapshot);
+    // Archive ONLY on full success — leave the snapshot pristine on partial fail
+    // so the operator can fix the cause and re-run.
+    let archived = false;
+    let archivePath;
+    if (failures.length === 0) {
+        try {
+            archivePath = archiveSnapshot(opts.home);
+            archived = true;
+            log(`from-upgrade: archived snapshot → ${exports.CONSUMED_SNAPSHOT_FILENAME}`);
+        }
+        catch (err) {
+            // Recreation succeeded but the archive rename failed (e.g. a lock on
+            // Windows). Don't fail the run — surface it so the operator can move the
+            // file manually (a re-run is a harmless idempotent no-op).
+            log(`from-upgrade: WARNING — recreation succeeded but archiving ${snapshot_v1_1.SNAPSHOT_FILENAME} ` +
+                `failed: ${err instanceof Error ? err.message : String(err)}. ` +
+                `Move it aside manually so a future boot doesn't re-read it.`);
+        }
+    }
+    return {
+        ok: failures.length === 0,
+        snapshotFound: true,
+        ensemblesRecreated: snapshot.ensembles.length,
+        workflowsCreated: created,
+        failures,
+        undeliveredCues,
+        archived,
+        ...(archivePath ? { archivePath } : {}),
+    };
+}

package/dist/upgrade/phase-engine.js

@@ -245,7 +245,10 @@ async function enumerateEnsembleNames(deps) {
 }
 async function fetchHostProfiles(deps, queryTimeoutMs) {
     try {
-        return (await (0, query_timeout_1.queryHandleWithTimeout)(deps.client.workflow.getHandle(config_1.GLOBAL_MAESTRO_WORKFLOW_ID), maestro_signals_1.hostProfilesQuery, { timeoutMs: queryTimeoutMs }));
+        // 2.0 (#788): legacy `hostProfilesQuery` removed — use the combined
+        // existence+profiles query and take the profiles map.
+        const result = (await (0, query_timeout_1.queryHandleWithTimeout)(deps.client.workflow.getHandle(config_1.GLOBAL_MAESTRO_WORKFLOW_ID), maestro_signals_1.hostProfilesWithExistenceQuery, { timeoutMs: queryTimeoutMs }));
+        return result.profiles;
     }
     catch {
         return {};

package/dist/utils/duration.d.ts

@@ -20,11 +20,8 @@ export declare function formatDurationMs(ms: number): string;
  *
  * `now` is injectable for deterministic tests; defaults to `Date.now()`.
  *
- * **Why a second time helper exists** (the TUI has `formatRelativeTime`
- * in `src/tui/utils/format.ts` doing roughly the same thing):
- * `src/tui/` carries Ink/React transitive imports the headless tools layer
- * mustn't take on. This helper has zero dependencies and is freely
- * importable by any layer. Consolidation across the two homes is tracked
- * as future deduplication work, not in scope here.
+ * This helper has zero dependencies and is freely importable by any layer.
+ * (It once co-existed with the TUI's `formatRelativeTime`; the Ink TUI was
+ * deleted in #789, so this is now the single relative-time helper.)
  */
 export declare function formatTimeAgo(iso: string, now?: number): string;

package/dist/utils/duration.js

@@ -45,12 +45,9 @@ function formatDurationMs(ms) {
  *
  * `now` is injectable for deterministic tests; defaults to `Date.now()`.
  *
- * **Why a second time helper exists** (the TUI has `formatRelativeTime`
- * in `src/tui/utils/format.ts` doing roughly the same thing):
- * `src/tui/` carries Ink/React transitive imports the headless tools layer
- * mustn't take on. This helper has zero dependencies and is freely
- * importable by any layer. Consolidation across the two homes is tracked
- * as future deduplication work, not in scope here.
+ * This helper has zero dependencies and is freely importable by any layer.
+ * (It once co-existed with the TUI's `formatRelativeTime`; the Ink TUI was
+ * deleted in #789, so this is now the single relative-time helper.)
  */
 function formatTimeAgo(iso, now = Date.now()) {
     const t = Date.parse(iso);

package/dist/utils/format-hosts.d.ts

@@ -4,7 +4,7 @@
  * Single source of truth consumed by:
  *   - `src/tools/hosts.ts` (MCP tool) — formatted text in `ok(...)` payload
  *   - `src/cli/commands.ts` (CLI `hosts` command) — stdout table
- *   - `src/tui/commands.ts` (TUI `/hosts` slash) — overlay content
+ *   - `src/pi/mission-control/` (command-center `/hosts` board command) — board text
  *
  * Pure: no Temporal, no I/O, no ANSI colors (the CLI can wrap lines in
  * color downstream if desired; the formatter emits plain strings so

package/dist/utils/format-hosts.js

@@ -40,8 +40,6 @@ function formatSingleHost(host) {
         bits.push(`workers: ${workerBits.length > 0 ? workerBits.join('+') : 'none'}`);
         if (inst.lastAccessTime)
             bits.push(`last seen ${inst.lastAccessTime}`);
-        if (inst.legacy)
-            bits.push('legacy-identity');
         lines.push(`  - ${bits.join(' · ')}`);
     }
     // Profile (capability).

package/dist/utils/grpc-shutdown-guard.js

@@ -54,10 +54,6 @@ const handler = (err) => {
     if (isBenignChannelShutdown(err)) {
         // A Temporal gRPC retry timer fired after we closed the connection. The
         // result we cared about was already captured (or degraded). Drop it.
-        if (process.env.CLAUDE_TEMPO_DEBUG) {
-            // eslint-disable-next-line no-console
-            console.error('[agent-tempo] ignored post-shutdown gRPC channel error (benign Temporal retry-after-close race)');
-        }
         return;
     }
     // Not ours — restore default crash behavior. Throwing from inside an

package/dist/utils/hosts.d.ts

@@ -54,26 +54,20 @@ export interface ParsedIdentity {
     hostname: string;
     pid: number;
     version: string;
-    /** `true` when the identity was in the legacy `<pid>@<hostname>` SDK-default shape. */
-    legacy: boolean;
 }
 /**
  * Parse a Temporal poller identity back into the daemon that emitted it.
  *
  * Returns `null` for opaque / third-party identities (e.g. Temporal's own
- * system pollers or an unrelated worker sharing the namespace). Callers
- * skip those silently.
+ * system pollers, an unrelated worker sharing the namespace, or an SDK
+ * worker that left the default `<pid>@<hostname>` identity). Callers skip
+ * those silently.
  *
- * The v1.0 format (`agent-tempo:<hostname>:<pid>:<version>`) is
+ * The agent-tempo format (`agent-tempo:<hostname>:<pid>:<version>`) is
  * guaranteed to have exactly 4 colon-delimited segments because every
  * component has its own validation: hostname passes `PLAYER_NAME_REGEX`
  * (no colons possible), pid is numeric, and version is a semver-ish
  * string (no colons).
- *
- * Pre-v1.0 daemons emitted a `claude-tempo:` prefix. Under the v1.0 hard
- * break those daemons can't reach v1.x task queues anyway, but if one does
- * surface in a host listing we tag it `legacy: true` so operators can
- * distinguish a still-running old daemon from a fresh v1.x worker.
  */
 export declare function parseIdentity(identity: string): ParsedIdentity | null;
 interface RawPoller {

package/dist/utils/hosts.js

@@ -43,41 +43,26 @@ function __resetHostsCacheForTests() {
  * Parse a Temporal poller identity back into the daemon that emitted it.
  *
  * Returns `null` for opaque / third-party identities (e.g. Temporal's own
- * system pollers or an unrelated worker sharing the namespace). Callers
- * skip those silently.
+ * system pollers, an unrelated worker sharing the namespace, or an SDK
+ * worker that left the default `<pid>@<hostname>` identity). Callers skip
+ * those silently.
  *
- * The v1.0 format (`agent-tempo:<hostname>:<pid>:<version>`) is
+ * The agent-tempo format (`agent-tempo:<hostname>:<pid>:<version>`) is
  * guaranteed to have exactly 4 colon-delimited segments because every
  * component has its own validation: hostname passes `PLAYER_NAME_REGEX`
  * (no colons possible), pid is numeric, and version is a semver-ish
  * string (no colons).
- *
- * Pre-v1.0 daemons emitted a `claude-tempo:` prefix. Under the v1.0 hard
- * break those daemons can't reach v1.x task queues anyway, but if one does
- * surface in a host listing we tag it `legacy: true` so operators can
- * distinguish a still-running old daemon from a fresh v1.x worker.
  */
 function parseIdentity(identity) {
-    if (identity.startsWith('agent-tempo:') || identity.startsWith('claude-tempo:')) {
-        const legacy = identity.startsWith('claude-tempo:');
-        const parts = identity.split(':');
-        if (parts.length === 4) {
-            const [, hostname, pidStr, version] = parts;
-            const pid = Number(pidStr);
-            if (hostname.length > 0 && Number.isFinite(pid) && pid > 0 && version.length > 0) {
-                return { hostname, pid, version, legacy };
-            }
-        }
+    if (!identity.startsWith('agent-tempo:'))
         return null;
-    }
-    // Legacy SDK default format: `<pid>@<hostname>`
-    const legacyMatch = identity.match(/^(\d+)@(.+)$/);
-    if (legacyMatch) {
-        const pid = Number(legacyMatch[1]);
-        const hostname = legacyMatch[2];
-        if (Number.isFinite(pid) && pid > 0 && hostname.length > 0) {
-            return { hostname, pid, version: 'unknown', legacy: true };
-        }
+    const parts = identity.split(':');
+    if (parts.length !== 4)
+        return null;
+    const [, hostname, pidStr, version] = parts;
+    const pid = Number(pidStr);
+    if (hostname.length > 0 && Number.isFinite(pid) && pid > 0 && version.length > 0) {
+        return { hostname, pid, version };
     }
     return null;
 }
@@ -192,7 +177,6 @@ async function listHosts(client, opts = {}) {
                 hasWorkflowWorker: false,
                 hasActivityWorker: false,
                 hasHostQueueWorker: false,
-                ...(ident.legacy ? { legacy: true } : {}),
             };
             byPid.set(pid, inst);
         }

package/dist/utils/orphan-guard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * #704 Item 1b — late-orphan self-tombstone discriminator (pure).
+ *
+ * A recruited process can launch LONG after its recruit was cancelled (a slow /
+ * wedged cold start). When it finally boots and reaches the workflow-start site
+ * (`server.ts`), this predicate decides whether it is an ORPHAN of a cancelled
+ * recruit (→ self-exit, do not re-register) or a legitimate (re-)start (→ proceed).
+ *
+ * The discriminator is the **running-run × close-reason PAIR**:
+ *   - If a RUNNING run exists for the derived id, this process is NOT an orphan —
+ *     every managed re-creation (recruit / restart / migrate / up) pre-creates a
+ *     RUNNING run before its process boots, so a legit reuse is seen as RUNNING and
+ *     simply attaches via `USE_EXISTING`. Never self-exit.
+ *   - Otherwise, the most-recent run is CLOSED. Self-exit ONLY when it closed with a
+ *     typed tombstone reason (`destroyed` | `boot-timeout`) within a generous TTL.
+ *     The TTL bounds a stale tombstone so a much-later legit manual reuse of the
+ *     same name isn't blocked forever (the observed orphan spawn delay was ~100min).
+ *
+ * Pure + dependency-free so it unit-tests without a live Temporal env; `server.ts`
+ * supplies the `describe()`-derived inputs.
+ */
+export interface OrphanTombstoneInput {
+    /** `describe().status.name` — e.g. `'RUNNING'`, `'COMPLETED'`, `'TERMINATED'`. */
+    statusName: string;
+    /** `describe().memo?.[MEMO_KEYS.closeReason]` — the typed close reason, if any. */
+    closeReason: unknown;
+    /** `describe().closeTime?.getTime() ?? 0` — ms epoch of run close, `0` if open/unknown. */
+    closeTimeMs: number;
+}
+/**
+ * Returns true iff the booting process should self-exit as a late orphan.
+ *
+ * @param input      the `describe()`-derived run state for the derived workflow id
+ * @param ttlMs      how long a tombstone is honored (ms); `> 0`
+ * @param nowMs      current wall-clock ms (`Date.now()`)
+ */
+export declare function shouldSelfExitAsOrphan(input: OrphanTombstoneInput, ttlMs: number, nowMs: number): boolean;

package/dist/utils/orphan-guard.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldSelfExitAsOrphan = shouldSelfExitAsOrphan;
+/** Close reasons that tombstone a derived id against orphan re-registration. */
+const TOMBSTONE_REASONS = new Set(['destroyed', 'boot-timeout']);
+/**
+ * Returns true iff the booting process should self-exit as a late orphan.
+ *
+ * @param input      the `describe()`-derived run state for the derived workflow id
+ * @param ttlMs      how long a tombstone is honored (ms); `> 0`
+ * @param nowMs      current wall-clock ms (`Date.now()`)
+ */
+function shouldSelfExitAsOrphan(input, ttlMs, nowMs) {
+    // A running run means a legit (re-)creation already exists — attach, don't exit.
+    if (input.statusName === 'RUNNING')
+        return false;
+    // Only a typed tombstone close-reason qualifies.
+    if (typeof input.closeReason !== 'string' || !TOMBSTONE_REASONS.has(input.closeReason)) {
+        return false;
+    }
+    // Bound staleness: a tombstone older than the TTL is released so a legit
+    // much-later reuse of the same derived id isn't blocked.
+    if (!(input.closeTimeMs > 0))
+        return false;
+    return nowMs - input.closeTimeMs <= ttlMs;
+}