agent-tempo 1.7.0 → 2.0.0-beta.2

package/dist/tools/stage.js

@@ -1,10 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildStageTool = buildStageTool;
+exports.buildStageAliasTools = buildStageAliasTools;
 const zod_1 = require("zod");
 const descriptor_1 = require("./descriptor");
+const action_guard_1 = require("./action-guard");
+const stages_1 = require("./stages");
+const cancel_stage_1 = require("./cancel-stage");
 const validation_1 = require("../utils/validation");
-function buildStageTool(handle, getPlayerId) {
+/**
+ * Internal create-only descriptor (the legacy bare-`stage` behaviour). Its
+ * `.handler` is reused verbatim by the canonical {@link buildStageTool} under
+ * `action="create"`. Not exported — the canonical tool is the public surface.
+ */
+function buildStageCreateTool(handle, getPlayerId) {
     return {
         name: 'stage',
         description: 'Create a pipeline stage tracking N players. When all players report, a completion message is auto-injected. Conductor only.',
@@ -31,3 +40,78 @@ function buildStageTool(handle, getPlayerId) {
         },
     };
 }
+/**
+ * Canonical `stage` tool (#793 merge) — **reused** name, so `action` defaults to
+ * `'create'` for backward-compat. Actions: `create | list | cancel` (all CRUD
+ * peers on the same StageEntry — see #793 brief §4). Conductor-only (gated in
+ * server-tools.ts).
+ *
+ * The legacy `stages` / `cancel_stage` names stay registered as forwarding
+ * aliases ({@link buildStageAliasTools}); there is no alias for `create` — the
+ * bare `stage` IS create.
+ */
+function buildStageTool(handle, getPlayerId) {
+    const create = buildStageCreateTool(handle, getPlayerId);
+    const list = (0, stages_1.buildStagesTool)(handle);
+    const cancel = (0, cancel_stage_1.buildCancelStageTool)(handle);
+    return {
+        name: 'stage',
+        description: 'Track a fan-out/fan-in pipeline stage across N players (conductor only). ' +
+            'action="create" (default) opens a stage (name + players[, failurePolicy]); ' +
+            'action="list" shows all stages and per-player report status; ' +
+            'action="cancel" cancels a named stage.',
+        params: {
+            action: zod_1.z.enum(['create', 'list', 'cancel']).optional().describe('Which stage operation to perform (defaults to "create" when omitted)'),
+            // create / cancel:
+            name: zod_1.z.string().max(validation_1.STAGE_NAME_MAX).optional().describe('create/cancel: the stage name'),
+            // create:
+            players: zod_1.z.array(zod_1.z.string().regex(validation_1.PLAYER_NAME_REGEX)).min(1).max(validation_1.STAGE_PLAYERS_MAX).optional().describe('create: player names to track in this stage'),
+            failurePolicy: zod_1.z.enum(['halt', 'continue']).optional().describe('create: "halt" (default) fails the stage on a blocker; "continue" waits for all players.'),
+        },
+        handler: async (args) => {
+            const action = args.action ?? 'create';
+            switch (action) {
+                case 'create': {
+                    const m = (0, action_guard_1.firstMissing)(args, ['name', 'players']);
+                    if (m)
+                        return (0, descriptor_1.fail)(`stage action="create" requires "${m}".`);
+                    return create.handler(args);
+                }
+                case 'list':
+                    return list.handler(args);
+                case 'cancel': {
+                    const m = (0, action_guard_1.firstMissing)(args, ['name']);
+                    if (m)
+                        return (0, descriptor_1.fail)(`stage action="cancel" requires "${m}".`);
+                    return cancel.handler(args);
+                }
+                default:
+                    return (0, descriptor_1.fail)(`Unknown stage action: ${String(action)}. Expected create | list | cancel.`);
+            }
+        },
+    };
+}
+/**
+ * Legacy forwarding aliases — `stages` → list, `cancel_stage` → cancel. Each
+ * keeps its exact original schema + handler; description gains a deprecation
+ * note. No alias for `create` — the bare `stage` IS create. Explicit object
+ * literals (see #793 brief §6 drift note).
+ */
+function buildStageAliasTools(handle) {
+    const list = (0, stages_1.buildStagesTool)(handle);
+    const cancel = (0, cancel_stage_1.buildCancelStageTool)(handle);
+    return [
+        {
+            name: 'stages',
+            description: 'DEPRECATED — use `stage` with action="list". ' + list.description,
+            params: list.params,
+            handler: list.handler,
+        },
+        {
+            name: 'cancel_stage',
+            description: 'DEPRECATED — use `stage` with action="cancel". ' + cancel.description,
+            params: cancel.params,
+            handler: cancel.handler,
+        },
+    ];
+}

package/dist/tools/state.d.ts

@@ -0,0 +1,14 @@
+import { Client, WorkflowHandle } from '@temporalio/client';
+import { Config } from '../config';
+import { type TempoToolDescriptor } from './descriptor';
+/**
+ * Canonical `state` tool. Dispatches on `action`; per-action required fields are
+ * runtime-guarded.
+ */
+export declare function buildStateTool(client: Client, config: Config, handle: WorkflowHandle, getPlayerId: () => string): TempoToolDescriptor;
+/**
+ * Legacy forwarding aliases — `save_state` / `fetch_state` / `clear_state`.
+ * Each keeps its exact original schema + handler; description gains a
+ * deprecation note. Explicit object literals (see §6 drift note).
+ */
+export declare function buildStateAliasTools(client: Client, config: Config, handle: WorkflowHandle, getPlayerId: () => string): TempoToolDescriptor[];

package/dist/tools/state.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStateTool = buildStateTool;
+exports.buildStateAliasTools = buildStateAliasTools;
+/**
+ * `state` — canonical multi-action player saveable-state tool (#793 merge).
+ *
+ * Merges the three legacy tools (`save_state` / `fetch_state` / `clear_state`)
+ * into ONE canonical tool with a flat `{ action, ...optional fields }` shape
+ * (see docs/design/793-tool-family-merge-brief.md §2). The canonical name is
+ * **net-new**, so `action` is REQUIRED.
+ *
+ * Legacy tools stay registered as forwarding aliases
+ * ({@link buildStateAliasTools}); both paths reuse the legacy handler bodies, so
+ * behaviour (owner-only write, self-or-peer read, idempotent clear) is identical.
+ */
+const zod_1 = require("zod");
+const descriptor_1 = require("./descriptor");
+const action_guard_1 = require("./action-guard");
+const validation_1 = require("../utils/validation");
+const save_state_1 = require("./save-state");
+const fetch_state_1 = require("./fetch-state");
+const clear_state_1 = require("./clear-state");
+/**
+ * Canonical `state` tool. Dispatches on `action`; per-action required fields are
+ * runtime-guarded.
+ */
+function buildStateTool(client, config, handle, getPlayerId) {
+    const save = (0, save_state_1.buildSaveStateTool)(handle, getPlayerId);
+    const fetch = (0, fetch_state_1.buildFetchStateTool)(client, config, handle, getPlayerId);
+    const clear = (0, clear_state_1.buildClearStateTool)(handle);
+    return {
+        name: 'state',
+        description: 'Curated per-player state slots that survive restart (you choose what context persists). ' +
+            'action="save" writes your own slot (content[, key]); ' +
+            'action="fetch" reads a slot for yourself or a peer (key/playerId, defaults to your own "main"); ' +
+            'action="clear" empties one of your slots. save/clear are owner-only.',
+        params: {
+            action: zod_1.z.enum(['save', 'fetch', 'clear']).describe('Which state operation to perform'),
+            // save:
+            content: zod_1.z.string().min(1).max(validation_1.PLAYER_STATE_CONTENT_MAX).optional().describe('save: the state body to store (≤32 KiB)'),
+            // save / fetch / clear:
+            key: zod_1.z.string().regex(validation_1.PLAYER_STATE_KEY_REGEX).max(validation_1.PLAYER_STATE_KEY_MAX).optional().describe('Slot key (defaults to "main")'),
+            // fetch:
+            playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional().describe('fetch: peer to read from (defaults to yourself)'),
+        },
+        handler: async (args) => {
+            const action = args.action;
+            switch (action) {
+                case 'save': {
+                    const m = (0, action_guard_1.firstMissing)(args, ['content']);
+                    if (m)
+                        return (0, descriptor_1.fail)(`state action="save" requires "${m}".`);
+                    return save.handler(args);
+                }
+                case 'fetch':
+                    return fetch.handler(args);
+                case 'clear':
+                    return clear.handler(args);
+                default:
+                    return (0, descriptor_1.fail)(`Unknown state action: ${String(action)}. Expected save | fetch | clear.`);
+            }
+        },
+    };
+}
+/**
+ * Legacy forwarding aliases — `save_state` / `fetch_state` / `clear_state`.
+ * Each keeps its exact original schema + handler; description gains a
+ * deprecation note. Explicit object literals (see §6 drift note).
+ */
+function buildStateAliasTools(client, config, handle, getPlayerId) {
+    const save = (0, save_state_1.buildSaveStateTool)(handle, getPlayerId);
+    const fetch = (0, fetch_state_1.buildFetchStateTool)(client, config, handle, getPlayerId);
+    const clear = (0, clear_state_1.buildClearStateTool)(handle);
+    return [
+        {
+            name: 'save_state',
+            description: 'DEPRECATED — use `state` with action="save". ' + save.description,
+            params: save.params,
+            handler: save.handler,
+        },
+        {
+            name: 'fetch_state',
+            description: 'DEPRECATED — use `state` with action="fetch". ' + fetch.description,
+            params: fetch.params,
+            handler: fetch.handler,
+        },
+        {
+            name: 'clear_state',
+            description: 'DEPRECATED — use `state` with action="clear". ' + clear.description,
+            params: clear.params,
+            handler: clear.handler,
+        },
+    ];
+}

package/dist/types.d.ts

@@ -57,6 +57,19 @@ export interface AdapterDescriptor {
     blocksOnLLMTurn: boolean;
     /** Heartbeat cadence in milliseconds. Interactive: 60_000; SDK: 30_000. */
     heartbeatMs: number;
+    /**
+     * #704 — True iff the adapter can park pre-attach on a blocking launch-time
+     * dialog (the interactive `claude-code` dev-channels acknowledgment, which
+     * requires a human click). When true, the booting attach-timeout watchdog is
+     * DISARMED for this adapter: a recruit waiting on a human is not a hang the
+     * watchdog should false-kill (an operator-away false-kill is worse than the
+     * hang — see docs/design/704-is-demo-companion-brief.md). Headless adapters
+     * (no dialog) omit this / set false → the watchdog arms. The property is the
+     * contract, not the adapter name: a future interactive adapter inherits the
+     * disarm by setting it. Interactive arming returns once #890 dissolves the
+     * dialog. Optional; absent ⇒ falsy ⇒ armed.
+     */
+    canBlockOnDialog?: boolean;
 }
 /**
  * Reason an attachment detached or was detached. Used for audit and UX messaging.
@@ -85,7 +98,7 @@ export interface AdapterDescriptor {
  * When not opted in, the base class fires the reason as terminal just like any
  * other non-recoverable lease loss.
  */
-export type DetachReason = 'user-stop' | 'restart' | 'heartbeat-timeout' | 'superseded' | 'agent-exited' | 'spawn-failed' | 'destroy' | 'force' | 'reconnect-exhausted' | 'continued-as-new';
+export type DetachReason = 'user-stop' | 'restart' | 'heartbeat-timeout' | 'superseded' | 'agent-exited' | 'spawn-failed' | 'destroy' | 'force' | 'reconnect-exhausted' | 'continued-as-new' | 'boot-timeout';
 /**
  * Workflow-emitted directive to the attached adapter. Delivered via {@link AttachmentInfo}
  * polling (no reverse-RPC surface in Temporal).
@@ -178,6 +191,23 @@ export interface SessionMetadata {
     playerTypeDescription?: string;
     /** Player ID of who recruited this player. */
     recruitedBy?: string;
+    /**
+     * #704 — resolved at spawn time from the adapter descriptor's
+     * {@link AdapterDescriptor.canBlockOnDialog}. Threaded onto durable metadata
+     * (and carried across continueAsNew) so the session workflow can decide
+     * whether to ARM the booting attach-timeout watchdog WITHOUT importing the
+     * client-side adapter registry (workflows are sandboxed). True ⇒ interactive
+     * adapter that can park on a launch dialog ⇒ watchdog DISARMED. Absent/false
+     * ⇒ headless ⇒ ARMED.
+     */
+    canBlockOnDialog?: boolean;
+    /**
+     * #704 — optional override (ms) for the booting attach-timeout deadline,
+     * resolved from `AGENT_TEMPO_BOOTING_DEADLINE_MS` at spawn time. Workflows
+     * can't read process.env, so the override rides durable metadata. Absent ⇒
+     * the workflow's 180s default applies.
+     */
+    bootingDeadlineMs?: number;
     /** Worktree path if this session was spawned in an isolated worktree. */
     worktreePath?: string;
     /**
@@ -290,7 +320,7 @@ export interface HostProfile {
  */
 export interface InstanceInfo {
     pid: number;
-    /** Parsed from worker identity. `'unknown'` for legacy-format identities (`<pid>@<hostname>`). */
+    /** Parsed from the `agent-tempo:<hostname>:<pid>:<version>` worker identity. */
     version: string;
     /** Raw `poller.identity` as Temporal returned it. */
     identity: string;
@@ -300,8 +330,6 @@ export interface InstanceInfo {
     hasActivityWorker: boolean;
     /** `true` when the per-host activity queue (`agent-tempo-<hostname>`) has a live poller. Controls `HostInfo.recruitReady`. */
     hasHostQueueWorker: boolean;
-    /** Set only when identity was in the legacy `<pid>@<hostname>` form. */
-    legacy?: true;
 }
 /**
  * Joined liveness + capability view returned by `src/utils/hosts.ts`.
@@ -346,6 +374,16 @@ export interface PlayerStateEntry {
 }
 export interface SessionInput {
     metadata: SessionMetadata;
+    /**
+     * #786 — 2.0 cutover protocol stamp. Set to `PROTOCOL_VERSION` (2) at every
+     * 2.0 start site so it's in history from run 1 and survives `continueAsNew`
+     * (carried by the `...input` spread at the CAN site). The workflow ALSO upserts
+     * the `AgentTempoProtocol` memo authoritatively from the constant — a 2.0
+     * bundle always stamps 2 regardless of input — so a 1.x run (which never sets
+     * this) is detectable by the boot guard. Optional only for type back-compat
+     * across the cutover; 2.0 always sets it.
+     */
+    protocol?: number;
     /** Restored from continue-as-new */
     part?: string;
     /** Restored from continue-as-new (undelivered only) */
@@ -728,9 +766,10 @@ export interface ResetOutboxEntry extends OutboxEntryBase {
 }
 export type OutboxEntry = CueOutboxEntry | RecruitOutboxEntry | ReportOutboxEntry | StopOutboxEntry | ReleaseOutboxEntry | SpawnOutboxEntry | DetachOutboxEntry | DestroyOutboxEntry | RestartOutboxEntry | ResetOutboxEntry;
 /**
- * Pending reset flag set on a session workflow by `deliverReset`, polled by the
- * Pi extension via `pendingResetQuery` and cleared via `ackResetSignal(resetId)`
- * after the extension performs the wipe. Single-slot, latest-wins.
+ * Pending reset flag set on a session workflow by `deliverReset`, read by the
+ * Pi extension off the combined `pendingIntake` query and cleared via
+ * `ackResetSignal(resetId)` after the extension performs the wipe. Single-slot,
+ * latest-wins.
  */
 export interface PendingReset {
     /** Correlation id (the originating outbox entry id). Ack clears only on match. */
@@ -865,6 +904,14 @@ export interface MaestroPlayerInfo {
      * surfaces that want to show "last active 12s ago" per player.
      */
     lastActivityAt?: string;
+    /**
+     * #886 slice 2 — `true` when this row came from a DEGRADED observation scan
+     * (the workflow was listed but its metadata extraction failed, so non-identity
+     * fields are best-effort blanks). Surfaces to the dashboard/board so the
+     * player renders as "uncertain" rather than vanishing — preventing roster
+     * flapping (contra #777). Absent / `false` on healthy rows.
+     */
+    degraded?: boolean;
 }
 /** A message relayed through the global Maestro for dashboard visibility. */
 export interface MaestroRelayMessage {

package/dist/upgrade/boot-guard.d.ts

@@ -0,0 +1,95 @@
+/**
+ * #786 — the 2.0 cutover BOOT GUARD (the keystone's centerpiece).
+ *
+ * A 2.0 Temporal worker can never deterministically replay a 1.x-recorded
+ * workflow history — the bundle's command stream has diverged, so a replay
+ * faults (or, worse, silently corrupts) deep inside a workflow task. The
+ * `upgrade-to-2` cutover (#785) exists to destroy every 1.x run before a 2.0
+ * daemon ever polls. This guard is the enforcement: a 2.0 daemon REFUSES to
+ * register workers if visibility still shows ANY Running agent-tempo workflow
+ * that lacks the protocol-2 stamp.
+ *
+ * **Stamp source of truth:** every 2.0 workflow upserts the
+ * `AgentTempoProtocol` memo = {@link PROTOCOL_VERSION} early + unconditionally
+ * on every run (incl. continueAsNew successors) — see `src/workflows/*` and
+ * `src/constants.ts`. The memo rides the visibility list result directly
+ * ({@link getWorkflowProtocol} reads it off the row), so the scan needs NO
+ * per-workflow query. A 1.x run never executes that upsert, so its memo is
+ * `undefined` → un-stamped → the guard refuses.
+ *
+ * **FAIL-CLOSED (the #845 partial-scan lesson):** the scan is bounded by the
+ * `protocolGuardBoot` visibility budget. A timeout or any scan error is NOT a
+ * best-effort partial — it means "couldn't prove the cutover is clean," and an
+ * unverified scan must NEVER be read as clean. Both refuse with
+ * {@link ProtocolGuardResult.reason} = `'scan-incomplete'`; the daemon retries
+ * on the next boot. The cost of a false-refuse (one retry) is trivial next to
+ * the cost of a false-proceed (deterministic history corruption).
+ *
+ * This module is daemon-side (it holds a Temporal client), distinct from the
+ * deliberately SDK-free `snapshot-v1.ts` cross-release contract.
+ */
+import type { Client, WorkflowExecutionInfo } from '@temporalio/client';
+/**
+ * The four agent-tempo workflow types. A Running workflow of any of these is
+ * an agent-tempo coordination workflow that a 2.0 worker would have to replay
+ * — so all four must be protocol-2 stamped before boot.
+ */
+export declare const AGENT_TEMPO_WORKFLOW_TYPES: readonly ["agentSessionWorkflow", "agentMaestroWorkflow", "agentSchedulerWorkflow", "agentGlobalMaestroWorkflow"];
+/** A Running workflow that failed the protocol-2 stamp check. */
+export interface ProtocolOffender {
+    workflowId: string;
+    /** Workflow type name from the visibility row (best-effort). */
+    workflowType?: string;
+    /** The stamp read from the row's memo — `undefined` for an un-stamped 1.x run. */
+    protocol: number | undefined;
+}
+/** Outcome of {@link checkProtocolGuard}. */
+export interface ProtocolGuardResult {
+    /** `true` → every Running agent-tempo workflow is protocol-2 stamped (or none exist). */
+    ok: boolean;
+    /**
+     * Why boot was refused. Only set when `ok` is `false`.
+     *   - `'unstamped'` — at least one Running workflow lacks the protocol-2 stamp
+     *     (a 1.x run survived the cutover). See {@link offenders}.
+     *   - `'scan-incomplete'` — the visibility scan timed out or errored before
+     *     completing, so cleanliness could not be PROVEN (fail-closed).
+     */
+    reason?: 'unstamped' | 'scan-incomplete';
+    /** Number of Running agent-tempo workflows examined before the result. */
+    scanned: number;
+    /** Un-stamped offenders (only when `reason === 'unstamped'`). */
+    offenders: ProtocolOffender[];
+    /** Operator-facing explanation (always set on refusal). */
+    message?: string;
+}
+/** Injectable seams for {@link checkProtocolGuard} — production callers omit. */
+export interface ProtocolGuardDeps {
+    /**
+     * Returns the visibility iterable for the guard query. Defaults to
+     * `client.workflow.list({ query })`. Tests inject a crafted async iterable
+     * of `WorkflowExecutionInfo`-shaped rows (only `workflowId`, `type`, `memo`
+     * are read) without a live Temporal connection.
+     */
+    listWorkflows?: (query: string) => AsyncIterable<WorkflowExecutionInfo>;
+    /** Scan deadline. Default {@link VISIBILITY_DEADLINES_MS.protocolGuardBoot}. */
+    deadlineMs?: number;
+    /** Injectable clock — forwarded to {@link iterateWithDeadline}. Default `Date.now`. */
+    now?: () => number;
+    /** Log sink. Default no-op (the daemon caller logs the structured result). */
+    log?: (...args: unknown[]) => void;
+}
+/**
+ * Build the namespace-scoped visibility query for the guard. The client is
+ * already namespace-scoped, so no namespace clause is needed. Exposed for
+ * test introspection.
+ */
+export declare function buildProtocolGuardQuery(): string;
+/**
+ * Scan every Running agent-tempo workflow and verify each carries the
+ * protocol-2 stamp. See the module header for the fail-closed contract.
+ *
+ * Never throws — every failure (un-stamped run, scan timeout, scan error) is
+ * returned as a structured `ok: false` result so the daemon caller decides how
+ * to surface it (it prints + `process.exit(1)`).
+ */
+export declare function checkProtocolGuard(client: Client, deps?: ProtocolGuardDeps): Promise<ProtocolGuardResult>;

package/dist/upgrade/boot-guard.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TEMPO_WORKFLOW_TYPES = void 0;
+exports.buildProtocolGuardQuery = buildProtocolGuardQuery;
+exports.checkProtocolGuard = checkProtocolGuard;
+const constants_1 = require("../constants");
+const search_attributes_1 = require("../utils/search-attributes");
+const visibility_deadline_1 = require("../utils/visibility-deadline");
+/**
+ * The four agent-tempo workflow types. A Running workflow of any of these is
+ * an agent-tempo coordination workflow that a 2.0 worker would have to replay
+ * — so all four must be protocol-2 stamped before boot.
+ */
+exports.AGENT_TEMPO_WORKFLOW_TYPES = [
+    'agentSessionWorkflow',
+    'agentMaestroWorkflow',
+    'agentSchedulerWorkflow',
+    'agentGlobalMaestroWorkflow',
+];
+/**
+ * Build the namespace-scoped visibility query for the guard. The client is
+ * already namespace-scoped, so no namespace clause is needed. Exposed for
+ * test introspection.
+ */
+function buildProtocolGuardQuery() {
+    const types = exports.AGENT_TEMPO_WORKFLOW_TYPES.map((t) => `"${t}"`).join(', ');
+    return `WorkflowType IN (${types}) AND ExecutionStatus = "Running"`;
+}
+/**
+ * Scan every Running agent-tempo workflow and verify each carries the
+ * protocol-2 stamp. See the module header for the fail-closed contract.
+ *
+ * Never throws — every failure (un-stamped run, scan timeout, scan error) is
+ * returned as a structured `ok: false` result so the daemon caller decides how
+ * to surface it (it prints + `process.exit(1)`).
+ */
+async function checkProtocolGuard(client, deps = {}) {
+    const log = deps.log ?? (() => { });
+    const deadlineMs = deps.deadlineMs ?? visibility_deadline_1.VISIBILITY_DEADLINES_MS.protocolGuardBoot;
+    const query = buildProtocolGuardQuery();
+    const listWorkflows = deps.listWorkflows ?? ((q) => client.workflow.list({ query: q }));
+    const offenders = [];
+    let scanned = 0;
+    try {
+        for await (const wf of (0, visibility_deadline_1.iterateWithDeadline)(listWorkflows(query), deadlineMs, 'protocolGuardBoot', deps.now)) {
+            scanned++;
+            const protocol = (0, search_attributes_1.getWorkflowProtocol)(wf);
+            if (protocol !== constants_1.PROTOCOL_VERSION) {
+                offenders.push({
+                    workflowId: wf.workflowId,
+                    // `WorkflowExecutionInfo.type` is the workflow type name string.
+                    workflowType: wf.type,
+                    protocol,
+                });
+            }
+        }
+    }
+    catch (err) {
+        // FAIL-CLOSED: a timeout OR any other scan error means we could not prove
+        // the namespace is clean. Refuse — never proceed on an unverified scan.
+        const kind = (0, visibility_deadline_1.isVisibilityTimeout)(err) ? 'timed out' : 'failed';
+        const detail = err instanceof Error ? err.message : String(err);
+        const message = `agent-tempo 2.0 boot guard could NOT verify a clean cutover — the ` +
+            `protocol scan ${kind} after ${scanned} workflow(s): ${detail}. ` +
+            `Refusing to boot (fail-closed): a 2.0 worker cannot safely replay a ` +
+            `1.x history. Retry once the Temporal namespace is responsive; if this ` +
+            `persists, run \`agent-tempo upgrade-to-2\` to complete the cutover.`;
+        log(`[boot-guard] scan-incomplete: ${message}`);
+        return { ok: false, reason: 'scan-incomplete', scanned, offenders, message };
+    }
+    if (offenders.length > 0) {
+        const sample = offenders
+            .slice(0, 5)
+            .map((o) => `  - ${o.workflowId} (protocol=${o.protocol ?? 'v1/unset'})`)
+            .join('\n');
+        const more = offenders.length > 5 ? `\n  …and ${offenders.length - 5} more` : '';
+        const message = `agent-tempo 2.0 boot guard REFUSED to boot: ${offenders.length} of ` +
+            `${scanned} Running agent-tempo workflow(s) are not protocol-${constants_1.PROTOCOL_VERSION} ` +
+            `(2.0) stamped — these are pre-cutover 1.x runs that a 2.0 worker cannot ` +
+            `safely replay:\n${sample}${more}\n` +
+            `Complete the cutover with \`agent-tempo upgrade-to-2\` (it snapshots ` +
+            `continuity, then destroys the 1.x runs), then restart the daemon.`;
+        log(`[boot-guard] unstamped: refusing (${offenders.length}/${scanned} un-stamped)`);
+        return { ok: false, reason: 'unstamped', scanned, offenders, message };
+    }
+    log(`[boot-guard] clean: ${scanned} Running agent-tempo workflow(s), all protocol-${constants_1.PROTOCOL_VERSION} stamped`);
+    return { ok: true, scanned, offenders: [] };
+}

package/dist/upgrade/from-upgrade.d.ts

@@ -0,0 +1,95 @@
+import { Client } from '@temporalio/client';
+import type { ScheduleEntry, SessionInput } from '../types';
+import { type UpgradeSnapshot } from './snapshot-v1';
+/** Args shape for the recreated per-ensemble scheduler workflow. Mirrors
+ *  `SchedulerInput` (declared in `../workflows/scheduler`, which we deliberately
+ *  do NOT import here — it pulls `@temporalio/workflow` into the Node reader). */
+interface SchedulerStartArgs {
+    ensemble: string;
+    entries: ScheduleEntry[];
+}
+/** Filename the consumed snapshot is archived to on success. */
+export declare const CONSUMED_SNAPSHOT_FILENAME = "upgrade-snapshot-v1.consumed.json";
+/** A single workflow to recreate — pure plan output (no Temporal I/O). */
+export interface RecreateSpec {
+    workflowId: string;
+    workflowType: 'agentSessionWorkflow' | 'agentMaestroWorkflow' | 'agentSchedulerWorkflow';
+    ensemble: string;
+    /** Present for session workflows. */
+    playerId?: string;
+    /** `args[0]` for the workflow start call. */
+    args: [SessionInput] | [{
+        ensemble: string;
+    }] | [SchedulerStartArgs];
+    searchAttributes: Record<string, string[]>;
+    memo: Record<string, unknown>;
+}
+/** An undelivered inbox cue, surfaced for operator review (never redelivered). */
+export interface UndeliveredCueReview {
+    ensemble: string;
+    playerId: string;
+    from: string;
+    text: string;
+    timestamp: string;
+}
+/** Result of {@link runFromUpgrade}. */
+export interface FromUpgradeResult {
+    /** `true` when a snapshot existed AND every workflow recreated cleanly. */
+    ok: boolean;
+    /** `false` when no `upgrade-snapshot-v1.json` was present (nothing to do). */
+    snapshotFound: boolean;
+    ensemblesRecreated: number;
+    workflowsCreated: number;
+    /** Per-workflow failures (empty on full success). */
+    failures: {
+        workflowId: string;
+        error: string;
+    }[];
+    /** Undelivered cues for operator review (surfaced, NOT redelivered). */
+    undeliveredCues: UndeliveredCueReview[];
+    /** `true` when the snapshot was archived to `.consumed.json` (success only). */
+    archived: boolean;
+    archivePath?: string;
+}
+/** Plan inputs — the Temporal coordinates the recreated workflows need. */
+export interface PlanRecreationOpts {
+    hostname: string;
+    taskQueue: string;
+    temporalAddress: string;
+    temporalNamespace: string;
+}
+/**
+ * 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.
+ */
+export declare function planRecreation(snapshot: UpgradeSnapshot, opts: PlanRecreationOpts): RecreateSpec[];
+/** Collect every undelivered cue across the snapshot (review only). */
+export declare function collectUndeliveredCues(snapshot: UpgradeSnapshot): UndeliveredCueReview[];
+/**
+ * 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.
+ */
+export declare function archiveSnapshot(home: string): string;
+/**
+ * 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.
+ */
+export declare function runFromUpgrade(client: Client, opts: {
+    home: string;
+    taskQueue: string;
+    temporalAddress: string;
+    temporalNamespace: string;
+    hostname?: string;
+    log?: (...args: unknown[]) => void;
+}): Promise<FromUpgradeResult>;
+export {};