agent-tempo 1.7.0 → 2.0.0-beta.1

package/dist/pi/mission-control/extension.d.ts

@@ -194,6 +194,83 @@ export declare class Controller {
     /** First whitespace-delimited token + the remainder. */
     private static splitFirst;
     cmdPlayers(ctx: McExtensionContext): Promise<void>;
+    /**
+     * Connected-host listing — reuses the shared `formatHostList` formatter (the
+     * same text the CLI `hosts` and MCP `hosts` tool render). `includeStale`
+     * surfaces hosts past their liveness window (`/hosts --all`). Returns the
+     * text so a future planner tool can reuse it (same shape as
+     * {@link ensemblesText}). NOT ensemble-scoped — the host registry is global.
+     */
+    hostsText(includeStale: boolean): Promise<{
+        ok: true;
+        text: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    cmdHosts(args: string, ctx: McExtensionContext): Promise<void>;
+    /**
+     * Full board detail — the human counterpart to the `observe_board` planner
+     * tool. Renders the live `BoardModel` (already kept current by the coarse SSE
+     * stream), so there's no extra fetch: the board IS the snapshot. Richer than
+     * the TUI `/status` overlay (phase glyphs + currentTool + context% + tail).
+     */
+    cmdStatus(ctx: McExtensionContext): void;
+    /**
+     * `/go [player]` — free HELD players. Uses the dedicated `release` route so
+     * it frees holds WITHOUT clearing the PAUSE axis (that's `/play` / `/unpause`).
+     * No arg → release all held in the ensemble; `/go <player>` releases one.
+     */
+    cmdGo(args: string, ctx: McExtensionContext): Promise<void>;
+    /**
+     * A player's attachment-lifecycle snapshot — reuses the shared
+     * `formatAttachmentInfoForDisplay` (the same text the CLI `attachment-info`
+     * and MCP `attachment_info` tool render). Returns the text so a future planner
+     * tool can reuse it (same shape as {@link hostsText}).
+     */
+    attachmentInfoText(playerId: string): Promise<{
+        ok: true;
+        text: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    cmdAttachmentInfo(args: string, ctx: McExtensionContext): Promise<void>;
+    /**
+     * A player's message timeline — reuses the shared `buildTimeline`/`formatRecall`
+     * helpers (the same render the CLI `recall` and MCP `recall` tool produce).
+     * Includes sent messages (operator wants the full picture). Pulls the full
+     * timeline via the `{ full: true }` recall route, NOT the count-only default.
+     */
+    recallText(playerId: string): Promise<{
+        ok: true;
+        text: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    cmdRecall(args: string, ctx: McExtensionContext): Promise<void>;
+    /**
+     * Active-schedule listing — renders each {@link ScheduleEntry} in the same
+     * shape the MCP `schedules` tool produces (name → target | recurrence | next).
+     */
+    schedulesText(): Promise<{
+        ok: true;
+        text: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /**
+     * `/schedule [list | delete <name>]` — list active schedules (default) or
+     * cancel one. CREATE is intentionally NOT here: there is no thin-shim create
+     * method on the client (the MCP `schedule` tool signals the scheduler workflow
+     * directly), so create stays on the MCP tool / CLI per the architect's
+     * thin-shim ruling.
+     */
+    cmdSchedule(args: string, ctx: McExtensionContext): Promise<void>;
+    /** `/unschedule <name>` — alias for `/schedule delete <name>`. */
+    cmdUnschedule(args: string, ctx: McExtensionContext): Promise<void>;
     /**
      * One-line ensembles listing — `▶` marks the board's current binding. Shared
      * by the `/ensembles` command and the `list_ensembles` planner tool. Returns

package/dist/pi/mission-control/extension.js

@@ -74,6 +74,9 @@ const inner_tail_1 = require("./inner-tail");
 const ensure_infra_1 = require("../../cli/ensure-infra");
 const zod_to_typebox_1 = require("../zod-to-typebox");
 const validation_1 = require("../../utils/validation");
+const format_hosts_1 = require("../../utils/format-hosts");
+const attachment_format_1 = require("../../utils/attachment-format");
+const recall_format_1 = require("../../utils/recall-format");
 /** The durable conductor a `/handoff` targets by default (matches catalog's conductorName default). */
 const DEFAULT_CONDUCTOR = 'conductor';
 /**
@@ -96,6 +99,34 @@ const ASK_POLL_INTERVAL_MS = 1_000;
 function mintQuestionId() {
     return `q-${crypto.randomUUID()}`;
 }
+/** Compact recurrence label for a schedule (ms interval → "5m"/"1h"/…). */
+function formatScheduleInterval(ms) {
+    if (ms >= 86_400_000)
+        return `${ms / 86_400_000}d`;
+    if (ms >= 3_600_000)
+        return `${ms / 3_600_000}h`;
+    if (ms >= 60_000)
+        return `${ms / 60_000}m`;
+    return `${ms / 1000}s`;
+}
+/**
+ * #742 — render one {@link ScheduleEntry} for the board, mirroring the MCP
+ * `schedules` tool line shape (name → target | recurrence (bounds) | next + msg
+ * preview). Kept module-local + pure so the controller test can assert it.
+ */
+function formatScheduleLine(s) {
+    const recur = s.cronExpression
+        ? `cron: ${s.cronExpression} (${s.timezone || 'UTC'})`
+        : s.interval ? `every ${formatScheduleInterval(s.interval)}` : 'one-shot';
+    const bounds = [];
+    if (s.until)
+        bounds.push(`until ${s.until}`);
+    if (s.remainingCount != null)
+        bounds.push(`${s.firedCount}/${s.firedCount + s.remainingCount} fired`);
+    const boundsStr = bounds.length ? ` (${bounds.join(', ')})` : '';
+    const msgPreview = s.message.length > 60 ? s.message.slice(0, 57) + '...' : s.message;
+    return `• ${s.name} → ${s.target} | ${recur}${boundsStr} | next: ${s.nextFireAt}\n  msg: ${msgPreview}`;
+}
 /**
  * #700 P2 — build the planner-wake injection from a resolved `answer` SSE event.
  * Pure (testable). The planner has no inbox; the SSE `answer` event is turned
@@ -344,6 +375,139 @@ class Controller {
         const ids = (0, board_1.sortedPlayerIds)(this.model);
         this.notify(ctx, ids.length ? `Players (${ids.length}): ${ids.join(', ')}` : 'No players in the ensemble.');
     }
+    // ── Hosts (#742 gap 5) ──
+    /**
+     * Connected-host listing — reuses the shared `formatHostList` formatter (the
+     * same text the CLI `hosts` and MCP `hosts` tool render). `includeStale`
+     * surfaces hosts past their liveness window (`/hosts --all`). Returns the
+     * text so a future planner tool can reuse it (same shape as
+     * {@link ensemblesText}). NOT ensemble-scoped — the host registry is global.
+     */
+    async hostsText(includeStale) {
+        const r = await this.actions.listHosts();
+        if (!r.ok)
+            return r;
+        return { ok: true, text: (0, format_hosts_1.formatHostList)(r.hosts, { includeStale }) };
+    }
+    async cmdHosts(args, ctx) {
+        const includeStale = /(?:^|\s)(?:--all|-a)(?:\s|$)/.test(args);
+        const r = await this.hostsText(includeStale);
+        this.notify(ctx, r.ok ? r.text : `hosts failed: ${r.error}`);
+    }
+    // ── Status (#742 gap 9) ──
+    /**
+     * Full board detail — the human counterpart to the `observe_board` planner
+     * tool. Renders the live `BoardModel` (already kept current by the coarse SSE
+     * stream), so there's no extra fetch: the board IS the snapshot. Richer than
+     * the TUI `/status` overlay (phase glyphs + currentTool + context% + tail).
+     */
+    cmdStatus(ctx) {
+        this.notify(ctx, (0, render_1.renderBoard)(this.model, this.localHost).join('\n'));
+    }
+    // ── Release / go (#742 gap 8) ──
+    /**
+     * `/go [player]` — free HELD players. Uses the dedicated `release` route so
+     * it frees holds WITHOUT clearing the PAUSE axis (that's `/play` / `/unpause`).
+     * No arg → release all held in the ensemble; `/go <player>` releases one.
+     */
+    async cmdGo(args, ctx) {
+        const player = args.trim().split(/\s+/).filter(Boolean)[0];
+        const label = player ? `go (release ${player})` : 'go (release held)';
+        this.report(ctx, label, await this.actions.release(player || undefined));
+    }
+    // ── Attachment-info (#742 — /attachment-info) ──
+    /**
+     * A player's attachment-lifecycle snapshot — reuses the shared
+     * `formatAttachmentInfoForDisplay` (the same text the CLI `attachment-info`
+     * and MCP `attachment_info` tool render). Returns the text so a future planner
+     * tool can reuse it (same shape as {@link hostsText}).
+     */
+    async attachmentInfoText(playerId) {
+        const r = await this.actions.attachmentInfo(playerId);
+        if (!r.ok)
+            return r;
+        return { ok: true, text: (0, attachment_format_1.formatAttachmentInfoForDisplay)(playerId, r.info).join('\n') };
+    }
+    async cmdAttachmentInfo(args, ctx) {
+        const player = args.trim().split(/\s+/).filter(Boolean)[0];
+        if (!player) {
+            this.notify(ctx, 'Usage: /attachment-info <player>');
+            return;
+        }
+        const r = await this.attachmentInfoText(player);
+        this.notify(ctx, r.ok ? r.text : `attachment-info failed: ${r.error}`);
+    }
+    // ── Recall (#742 — /recall) ──
+    /**
+     * A player's message timeline — reuses the shared `buildTimeline`/`formatRecall`
+     * helpers (the same render the CLI `recall` and MCP `recall` tool produce).
+     * Includes sent messages (operator wants the full picture). Pulls the full
+     * timeline via the `{ full: true }` recall route, NOT the count-only default.
+     */
+    async recallText(playerId) {
+        const r = await this.actions.recall(playerId);
+        if (!r.ok)
+            return r;
+        const timeline = (0, recall_format_1.buildTimeline)(r.received, r.sent, true);
+        return { ok: true, text: (0, recall_format_1.formatRecall)(timeline).text };
+    }
+    async cmdRecall(args, ctx) {
+        const player = args.trim().split(/\s+/).filter(Boolean)[0];
+        if (!player) {
+            this.notify(ctx, 'Usage: /recall <player>');
+            return;
+        }
+        const r = await this.recallText(player);
+        this.notify(ctx, r.ok ? r.text : `recall failed: ${r.error}`);
+    }
+    // ── Schedules (#742 — /schedule, /unschedule) ──
+    /**
+     * Active-schedule listing — renders each {@link ScheduleEntry} in the same
+     * shape the MCP `schedules` tool produces (name → target | recurrence | next).
+     */
+    async schedulesText() {
+        const r = await this.actions.listSchedules();
+        if (!r.ok)
+            return r;
+        if (r.schedules.length === 0)
+            return { ok: true, text: 'No active schedules.' };
+        return { ok: true, text: r.schedules.map(formatScheduleLine).join('\n') };
+    }
+    /**
+     * `/schedule [list | delete <name>]` — list active schedules (default) or
+     * cancel one. CREATE is intentionally NOT here: there is no thin-shim create
+     * method on the client (the MCP `schedule` tool signals the scheduler workflow
+     * directly), so create stays on the MCP tool / CLI per the architect's
+     * thin-shim ruling.
+     */
+    async cmdSchedule(args, ctx) {
+        const [sub, rest] = Controller.splitFirst(args);
+        if (sub === 'delete' || sub === 'rm') {
+            const name = rest.trim().split(/\s+/).filter(Boolean)[0];
+            if (!name) {
+                this.notify(ctx, 'Usage: /schedule delete <name>');
+                return;
+            }
+            this.report(ctx, `unschedule ${name}`, await this.actions.unschedule(name));
+            return;
+        }
+        if (sub === 'create' || sub === 'new' || sub === 'add') {
+            this.notify(ctx, 'Schedule creation runs through the MCP `schedule` tool / `agent-tempo schedule` CLI — the board lists and deletes only.');
+            return;
+        }
+        // Default (no arg or `list`) → list.
+        const r = await this.schedulesText();
+        this.notify(ctx, r.ok ? r.text : `schedules failed: ${r.error}`);
+    }
+    /** `/unschedule <name>` — alias for `/schedule delete <name>`. */
+    async cmdUnschedule(args, ctx) {
+        const name = args.trim().split(/\s+/).filter(Boolean)[0];
+        if (!name) {
+            this.notify(ctx, 'Usage: /unschedule <name>');
+            return;
+        }
+        this.report(ctx, `unschedule ${name}`, await this.actions.unschedule(name));
+    }
     // ── Multi-ensemble home (#790) ──
     /**
      * One-line ensembles listing — `▶` marks the board's current binding. Shared
@@ -1086,6 +1250,13 @@ function createMissionControlExtension(deps = {}) {
         pi.on('session_shutdown', () => teardown());
         // Operator commands (display-only widget → slash-commands drive everything).
         pi.registerCommand('players', { description: 'List ensemble players', handler: (_a, ctx) => ctrl.cmdPlayers(ctx) });
+        pi.registerCommand('hosts', { description: 'List connected hosts (/hosts [--all])', handler: (a, ctx) => ctrl.cmdHosts(a, ctx) });
+        pi.registerCommand('status', { description: 'Show the full board detail', handler: (_a, ctx) => ctrl.cmdStatus(ctx) });
+        pi.registerCommand('go', { description: 'Release HELD players (/go [player])', handler: (a, ctx) => ctrl.cmdGo(a, ctx) });
+        pi.registerCommand('attachment-info', { description: 'Show a player\'s attachment lifecycle (/attachment-info <player>)', handler: (a, ctx) => ctrl.cmdAttachmentInfo(a, ctx) });
+        pi.registerCommand('recall', { description: 'Show a player\'s message timeline (/recall <player>)', handler: (a, ctx) => ctrl.cmdRecall(a, ctx) });
+        pi.registerCommand('schedule', { description: 'List or delete schedules (/schedule [list | delete <name>])', handler: (a, ctx) => ctrl.cmdSchedule(a, ctx) });
+        pi.registerCommand('unschedule', { description: 'Cancel a schedule (/unschedule <name>)', handler: (a, ctx) => ctrl.cmdUnschedule(a, ctx) });
         // #790 — multi-ensemble home: list + re-bind.
         pi.registerCommand('ensembles', { description: 'List all ensembles (▶ marks the bound one)', handler: (_a, ctx) => ctrl.cmdEnsembles(ctx) });
         pi.registerCommand('ensemble', { description: 'Switch the board to another ensemble (/ensemble <name> [--force])', handler: (a, ctx) => ctrl.cmdEnsemble(a, ctx) });

package/dist/pi/workflow-client.d.ts

@@ -153,26 +153,24 @@ export declare class PiWorkflowClient {
     fetchPending(): Promise<Message[]>;
     /** Acknowledge delivered cue ids so the workflow stops re-serving them. */
     ackDelivered(messageIds: string[]): Promise<void>;
-    /**
-     * `true` until a `pendingIntake` query is rejected as unregistered — i.e.
-     * the session workflow predates #750. Cached so the pump pays the failed
-     * probe ONCE, not every tick, then sticks to the legacy two-query path for
-     * the lifetime of this client. Known cost-only staleness: the Pi client
-     * handle follows continueAsNew transparently, so a pre-#750 workflow that
-     * CANs onto a #750+ worker bundle MID-SESSION keeps paying 2 queries/tick
-     * here until the extension process restarts (fresh client → fresh probe).
-     * Benign and self-healing — correctness is unaffected either way.
-     */
-    private combinedIntakeSupported;
     /**
      * One-query intake: undelivered cues + the pending reset together —
-     * halves the pump's idle Temporal actions (2 → 1 query/tick). Falls back
-     * to the legacy `pendingMessages` + `pendingReset` pair when the workflow
-     * lacks the combined handler (pre-#750 build); genuine failures (timeouts,
-     * connection errors) propagate to the pump's existing per-tick handling.
+     * halves the pump's idle Temporal actions (2 → 1 query/tick).
+     *
+     * 2.0 (#788): the pre-#750 two-query fallback (`combinedIntakeSupported`
+     * probe + the legacy `pendingMessages` + `pendingReset` pair) is gone — the
+     * A2 clean cutover (guarded by #786) guarantees every 2.0 session workflow
+     * serves the `pendingIntake` handler, so the fallback was dead.
      */
     fetchIntake(): Promise<PendingIntake>;
-    /** Poll the workflow's single-slot pending reset (null = none). */
+    /**
+     * Poll the workflow's single-slot pending reset (null = none).
+     *
+     * 2.0 (#788): the standalone `pendingReset` query was removed — derive the
+     * reset from the combined `pendingIntake` query. Only the cue-pump's
+     * no-`intakeSource` fallback path reaches this; the primary pump path reads
+     * `pendingReset` straight off `fetchIntake`'s result.
+     */
     fetchPendingReset(): Promise<PendingReset | null>;
     /**
      * Ack a performed reset by id — the workflow clears the slot ONLY if the id

package/dist/pi/workflow-client.js

@@ -23,6 +23,7 @@ const action_counters_1 = require("../utils/action-counters");
 const search_attributes_1 = require("../utils/search-attributes");
 const config_1 = require("../config");
 const signals_1 = require("../workflows/signals");
+const constants_1 = require("../constants");
 /** Adapter identity advertised on claim. Pi interactive players are `interactive`-class. */
 const PI_ADAPTER_ID = 'pi';
 /**
@@ -160,6 +161,7 @@ class PiWorkflowClient {
                     adapterId: PI_ADAPTER_ID,
                     adapterClass: 'interactive',
                     leaseMs: this.leaseMs,
+                    protocolVersion: constants_1.PROTOCOL_VERSION, // #786 — 2.0 wire handshake
                     ...(this.expectedAttachmentId ? { expectedAttachmentId: this.expectedAttachmentId } : {}),
                 },
             ],
@@ -286,57 +288,29 @@ class PiWorkflowClient {
         await handle.signal(signals_1.markDeliveredSignal, messageIds);
     }
     // ── Combined intake (T0.3 of #747, #750) ──
-    /**
-     * `true` until a `pendingIntake` query is rejected as unregistered — i.e.
-     * the session workflow predates #750. Cached so the pump pays the failed
-     * probe ONCE, not every tick, then sticks to the legacy two-query path for
-     * the lifetime of this client. Known cost-only staleness: the Pi client
-     * handle follows continueAsNew transparently, so a pre-#750 workflow that
-     * CANs onto a #750+ worker bundle MID-SESSION keeps paying 2 queries/tick
-     * here until the extension process restarts (fresh client → fresh probe).
-     * Benign and self-healing — correctness is unaffected either way.
-     */
-    combinedIntakeSupported = true;
     /**
      * One-query intake: undelivered cues + the pending reset together —
-     * halves the pump's idle Temporal actions (2 → 1 query/tick). Falls back
-     * to the legacy `pendingMessages` + `pendingReset` pair when the workflow
-     * lacks the combined handler (pre-#750 build); genuine failures (timeouts,
-     * connection errors) propagate to the pump's existing per-tick handling.
+     * halves the pump's idle Temporal actions (2 → 1 query/tick).
+     *
+     * 2.0 (#788): the pre-#750 two-query fallback (`combinedIntakeSupported`
+     * probe + the legacy `pendingMessages` + `pendingReset` pair) is gone — the
+     * A2 clean cutover (guarded by #786) guarantees every 2.0 session workflow
+     * serves the `pendingIntake` handler, so the fallback was dead.
      */
     async fetchIntake() {
-        if (this.combinedIntakeSupported) {
-            const handle = this.requireHandle();
-            try {
-                const intake = await handle.query(signals_1.pendingIntakeQuery);
-                // Shape-guard: a real server either serves the query or rejects it
-                // as unregistered, but belt-and-braces against converter quirks /
-                // test doubles — a malformed result downgrades to the legacy pair
-                // rather than crashing the pump tick.
-                if (intake && Array.isArray(intake.messages))
-                    return intake;
-                this.combinedIntakeSupported = false;
-                log('pendingIntake returned a malformed result — falling back to the legacy pair');
-            }
-            catch (err) {
-                if (!isQueryNotRegisteredError(err))
-                    throw err;
-                this.combinedIntakeSupported = false;
-                log('pendingIntake query not registered on this workflow (pre-#750 build) — ' +
-                    'falling back to the legacy pendingMessages + pendingReset pair');
-            }
-        }
-        const [messages, pendingReset] = await Promise.all([
-            this.fetchPending(),
-            this.fetchPendingReset(),
-        ]);
-        return { messages, pendingReset };
+        return this.requireHandle().query(signals_1.pendingIntakeQuery);
     }
     // ── Reset intake (3d D14) ──
-    /** Poll the workflow's single-slot pending reset (null = none). */
+    /**
+     * Poll the workflow's single-slot pending reset (null = none).
+     *
+     * 2.0 (#788): the standalone `pendingReset` query was removed — derive the
+     * reset from the combined `pendingIntake` query. Only the cue-pump's
+     * no-`intakeSource` fallback path reaches this; the primary pump path reads
+     * `pendingReset` straight off `fetchIntake`'s result.
+     */
     async fetchPendingReset() {
-        const handle = this.requireHandle();
-        return handle.query(signals_1.pendingResetQuery);
+        return (await this.requireHandle().query(signals_1.pendingIntakeQuery)).pendingReset;
     }
     /**
      * Ack a performed reset by id — the workflow clears the slot ONLY if the id

package/dist/types.d.ts

@@ -290,7 +290,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 +300,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 +344,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 +736,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. */

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: [] };
+}