agent-tempo 1.4.0 → 1.4.1

package/dashboard/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-tempo-dashboard",
   "private": true,
-  "version": "1.4.0",
+  "version": "1.4.1",
   "type": "module",
   "description": "Web dashboard for agent-tempo. Bundled into the npm package; served by the daemon at /dashboard/*.",
   "scripts": {

package/dist/pi/headless.js

@@ -32,6 +32,7 @@ const config_1 = require("../config");
 const sdk_probe_1 = require("../utils/sdk-probe");
 const extension_1 = require("./extension");
 const probe_1 = require("./probe");
+const session_seed_1 = require("./session-seed");
 const log = (...args) => {
     // eslint-disable-next-line no-console
     console.error('[agent-tempo:pi-headless]', ...args);
@@ -131,6 +132,16 @@ function buildPiResourceLoaderOptions(params) {
 async function runHeadlessPi(opts = {}) {
     const config = opts.config ?? (0, config_1.getConfig)();
     const toolAccess = opts.toolAccess ?? 'restricted';
+    // 0) Node-floor backstop (Decision B, #645). The recruit pre-flight is the
+    //    AUTHORITATIVE gate; this covers direct/manual launches that bypass recruit.
+    //    Checked before the SDK probe because Pi's ESM packages can't even import on
+    //    sub-22.19 Node — a clean floor message beats a cryptic import failure.
+    const nodeFloor = (0, probe_1.checkPiNodeFloor)();
+    if (!nodeFloor.ok) {
+        log(`FATAL: ${nodeFloor.reason} Exiting.`);
+        process.exit(3);
+        return;
+    }
     // 1) Probe — the spawn entry is the only place the Pi SDK is REQUIRED.
     if (!(0, sdk_probe_1.probeSdkInstall)(probe_1.PI_PACKAGE)) {
         log(`FATAL: ${probe_1.PI_PACKAGE} is not installed — cannot run headless Pi. Exiting.`);
@@ -151,6 +162,20 @@ async function runHeadlessPi(opts = {}) {
     const piSdk = await esmImport(probe_1.PI_PACKAGE);
     const createAgentSession = piSdk.createAgentSession;
     const DefaultResourceLoader = piSdk.DefaultResourceLoader;
+    // H1 (#645): ALWAYS run in-memory. A disk-backed SessionManager loads
+    // ~/.pi/agent/sessions/<cwd>/*.jsonl on startup; a stale/partial entry with
+    // malformed `content` throws "content is not iterable" during Pi's
+    // compaction/consumption scan (agent-session.js:2486/2493). inMemory loads
+    // nothing from disk → that crash vector is gone. `sessionManager` and
+    // `resourceLoader` are INDEPENDENT createAgentSession options (no conflict with
+    // the noExtensions/reload() path above).
+    const SessionManager = piSdk.SessionManager;
+    const sessionManager = SessionManager.inMemory(process.cwd());
+    // Single appendMessage chokepoint (session-seed.ts). For a fresh recruit the
+    // transcript is empty → no-op; H2 supplies the durable replay read here
+    // (fetch_state on ENV.PI_CONTINUE_SESSION). headless.ts NEVER calls
+    // appendMessage directly — sanitization is the only crash lever we control.
+    (0, session_seed_1.seedSessionManager)(sessionManager, undefined /* H2: durable replay transcript */);
     // Pi's DefaultResourceLoader REQUIRES agentDir (normalizePath does
     // `.startsWith()` on it) — getAgentDir() resolves ~/.pi/agent. Pass it to BOTH
     // createAgentSession and the loader. (Found in the 3a live smoke — devops.)
@@ -171,9 +196,10 @@ async function runHeadlessPi(opts = {}) {
         agentDir,
         ...(model ? { model } : {}),
         resourceLoader,
-        // NOTE (A4): restart-resume via a SessionManager seeded from
-        // opts.continueSessionId / ENV.PI_CONTINUE_SESSION lands in A4; 3a proves the
-        // loop on a fresh session.
+        // H1 (#645): in-memory session (seeded above via the session-seed chokepoint).
+        // H2 will seed it from agent-tempo durable state (ENV.PI_CONTINUE_SESSION
+        // saveable-state key) before this call — a true continuation, not a cue.
+        sessionManager,
     });
     // 5) Explicit bootstrap — fires session_start → the singleton claims/attaches.
     await session.bindExtensions({});

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

@@ -14,6 +14,12 @@ import type { InnerFrame } from '../inner-loop-publisher';
 export interface PlayerRow {
     playerId: string;
     isConductor: boolean;
+    /**
+     * Daemon host the player runs on (carried from `PlayerSummaryV1.hostname`,
+     * 3f/H3a). Undefined on older pre-hostname snapshots → treated as tailable
+     * (never block on absent data). Drives {@link tailability}.
+     */
+    hostname?: string;
     phase?: AttachmentPhase;
     part: string;
     /** Tool currently executing (3c coarse), `null`/undefined = idle. */
@@ -49,5 +55,34 @@ export declare function applyTempoEvent(model: BoardModel, ev: TempoEvent): void
 export declare function applyInnerFrame(model: BoardModel, frame: InnerFrame): void;
 /** Select a player for the fine tail (clears the prior tail). No-op if absent. */
 export declare function selectPlayer(model: BoardModel, playerId: string | null): boolean;
+/** Result of a {@link tailability} check — whether the operator can open a fine /inner tail. */
+export type Tailability = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'no-such-player';
+} | {
+    ok: false;
+    reason: 'ui-player';
+} | {
+    ok: false;
+    reason: 'cross-host';
+    playerHost: string;
+};
+/**
+ * Pure: can the local operator open `playerId`'s fine inner-loop tail? The 3f
+ * inner-loop tail is DAEMON-LOCAL — only players on this daemon's host are
+ * tailable.
+ *
+ * - missing player → `no-such-player`
+ * - the maestro/dashboard UI player (no /inner stream) → `ui-player` (H5; checked
+ *   BEFORE the host comparison so its `dashboard` sentinel isn't mis-framed as
+ *   cross-host)
+ * - a real player on another host → `cross-host` (carrying `playerHost`); actual
+ *   cross-host routing is the deferred H3(b) (#645)
+ * - a missing/older-snapshot `hostname` (undefined) → tailable; never block on
+ *   absent data
+ */
+export declare function tailability(model: BoardModel, playerId: string, localHost: string): Tailability;
 /** Sorted player ids — conductor first, then alphabetical (stable board ordering). */
 export declare function sortedPlayerIds(model: BoardModel): string[];

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

@@ -5,6 +5,7 @@ exports.initBoard = initBoard;
 exports.applyTempoEvent = applyTempoEvent;
 exports.applyInnerFrame = applyInnerFrame;
 exports.selectPlayer = selectPlayer;
+exports.tailability = tailability;
 exports.sortedPlayerIds = sortedPlayerIds;
 /** Default cap on the retained fine-tail frames for the selected player. */
 exports.DEFAULT_TAIL_LIMIT = 200;
@@ -16,6 +17,9 @@ function rowFromSummary(p) {
     return {
         playerId: p.playerId,
         isConductor: p.isConductor,
+        // H3a: carry the host through — the board previously DROPPED it. Drives
+        // cross-host tail refusal in `tailability`.
+        ...(p.hostname !== undefined ? { hostname: p.hostname } : {}),
         ...(p.phase !== undefined ? { phase: p.phase } : {}),
         part: p.part ?? '',
         ...(p.currentTool !== undefined ? { currentTool: p.currentTool } : {}),
@@ -92,6 +96,39 @@ function selectPlayer(model, playerId) {
     model.revision++;
     return true;
 }
+/**
+ * Sentinel hostname the TUI's own maestro/dashboard session stamps on its
+ * metadata (see `ensureMaestroSession` in `client/core.ts`). It's a UI player
+ * with NO /inner stream — non-tailable, but NOT a cross-host case (the sentinel
+ * is not a real daemon host). Mirrored locally to avoid a client→mission-control
+ * import; the maestro-tail test trips if it ever drifts. (H5)
+ */
+const UI_PLAYER_HOSTNAME = 'dashboard';
+/**
+ * Pure: can the local operator open `playerId`'s fine inner-loop tail? The 3f
+ * inner-loop tail is DAEMON-LOCAL — only players on this daemon's host are
+ * tailable.
+ *
+ * - missing player → `no-such-player`
+ * - the maestro/dashboard UI player (no /inner stream) → `ui-player` (H5; checked
+ *   BEFORE the host comparison so its `dashboard` sentinel isn't mis-framed as
+ *   cross-host)
+ * - a real player on another host → `cross-host` (carrying `playerHost`); actual
+ *   cross-host routing is the deferred H3(b) (#645)
+ * - a missing/older-snapshot `hostname` (undefined) → tailable; never block on
+ *   absent data
+ */
+function tailability(model, playerId, localHost) {
+    const row = model.players.get(playerId);
+    if (!row)
+        return { ok: false, reason: 'no-such-player' };
+    if (row.hostname === UI_PLAYER_HOSTNAME)
+        return { ok: false, reason: 'ui-player' };
+    if (row.hostname && row.hostname !== localHost) {
+        return { ok: false, reason: 'cross-host', playerHost: row.hostname };
+    }
+    return { ok: true };
+}
 /** Sorted player ids — conductor first, then alphabetical (stable board ordering). */
 function sortedPlayerIds(model) {
     return [...model.players.values()]

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

@@ -7,6 +7,8 @@ export interface MissionControlDeps {
     adminToken?: string;
     baseUrl?: string;
     renderThrottleMs?: number;
+    /** Local daemon host for tailability (test override; defaults to `os.hostname()`). */
+    localHost?: string;
 }
 /**
  * The operator-command + board controller. Holds the model + the action client;
@@ -16,9 +18,14 @@ export interface MissionControlDeps {
 export declare class Controller {
     readonly model: BoardModel;
     readonly actions: MissionControlActions;
+    /**
+     * This daemon's host (`os.hostname()`). The fine /inner tail is daemon-local,
+     * so only same-host players are tailable — see {@link tailability}.
+     */
+    readonly localHost: string;
     /** Set by the extension so /tail can (re)open the fine SSE; null in unit tests. */
     onTailRequest: ((playerId: string | null) => void) | null;
-    constructor(ensemble: string, actions: MissionControlActions);
+    constructor(ensemble: string, actions: MissionControlActions, localHost?: string);
     private notify;
     private report;
     /** First whitespace-delimited token + the remainder. */

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

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Controller = void 0;
 exports.createMissionControlExtension = createMissionControlExtension;
@@ -17,6 +50,7 @@ exports.createMissionControlExtension = createMissionControlExtension;
  * Node `subscribe` path), starts the render tick, and registers operator
  * commands; `session_shutdown` tears all of it down + clears the widget.
  */
+const os = __importStar(require("os"));
 const config_1 = require("../../config");
 const port_file_1 = require("../../http/port-file");
 const subscribe_1 = require("../../client/subscribe");
@@ -35,11 +69,17 @@ const DEFAULT_PORT = 8473;
 class Controller {
     model;
     actions;
+    /**
+     * This daemon's host (`os.hostname()`). The fine /inner tail is daemon-local,
+     * so only same-host players are tailable — see {@link tailability}.
+     */
+    localHost;
     /** Set by the extension so /tail can (re)open the fine SSE; null in unit tests. */
     onTailRequest = null;
-    constructor(ensemble, actions) {
+    constructor(ensemble, actions, localHost = os.hostname()) {
         this.model = (0, board_1.initBoard)(ensemble);
         this.actions = actions;
+        this.localHost = localHost;
     }
     notify(ctx, msg) {
         if (ctx.hasUI)
@@ -66,10 +106,26 @@ class Controller {
             this.notify(ctx, 'Inner-loop tail off.');
             return;
         }
-        if (!(0, board_1.selectPlayer)(this.model, target)) {
-            this.notify(ctx, `No such player: ${target}`);
+        // H3a: the /inner tail is daemon-local — refuse a cross-host tail with an
+        // actionable message rather than silently selecting a player that would only
+        // ever show "(no inner-loop activity yet)". Decided BEFORE select/open so a
+        // cross-host player is never selected and no tail SSE is opened.
+        const t = (0, board_1.tailability)(this.model, target, this.localHost);
+        if (!t.ok) {
+            let msg;
+            if (t.reason === 'cross-host') {
+                msg = `Inner tail unavailable: ${target} runs on host ${t.playerHost}, not this daemon's host (${this.localHost}). Cross-host tail is a tracked follow-up (#645 / H3b).`;
+            }
+            else if (t.reason === 'ui-player') {
+                msg = `${target} is a UI player — nothing to tail.`;
+            }
+            else {
+                msg = `No such player: ${target}`;
+            }
+            this.notify(ctx, msg);
             return;
         }
+        (0, board_1.selectPlayer)(this.model, target);
         this.onTailRequest?.(target);
         this.notify(ctx, `Tailing ${target}.`);
     }
@@ -156,10 +212,21 @@ function createMissionControlExtension(deps = {}) {
     return (pi) => {
         const ensemble = deps.ensemble ?? (0, config_1.getConfig)().ensemble;
         const adminToken = deps.adminToken ?? process.env[actions_1.ADMIN_TOKEN_ENV];
-        const baseUrl = resolveBaseUrl(deps.baseUrl);
         const throttleMs = deps.renderThrottleMs ?? DEFAULT_RENDER_THROTTLE_MS;
-        const actions = new actions_1.MissionControlActions({ ensemble, ...(adminToken ? { adminToken } : {}), baseUrl });
-        const ctrl = new Controller(ensemble, actions);
+        // H3a: mission-control is co-located with its 127.0.0.1 daemon, so this
+        // process's hostname IS the daemon's host. (HealthV1.hostname is the noted
+        // future upgrade for a baseUrl pointing at a remote daemon — not built here.)
+        const localHost = deps.localHost ?? os.hostname();
+        // H5: do NOT pre-resolve baseUrl. createSubscribe + MissionControlActions both
+        // re-read ~/.agent-tempo/daemon.port per-call when baseUrl is undefined, so a
+        // daemon restart on a new port self-heals (a once-resolved URL wedges the
+        // board). A `deps.baseUrl` override (tests / future remote daemon) still wins.
+        const actions = new actions_1.MissionControlActions({
+            ensemble,
+            ...(adminToken ? { adminToken } : {}),
+            ...(deps.baseUrl ? { baseUrl: deps.baseUrl } : {}),
+        });
+        const ctrl = new Controller(ensemble, actions, localHost);
         // Per-session lifecycle state (re-created on each session_start).
         let coarseAbort = null;
         let tailAbort = null;
@@ -172,22 +239,31 @@ function createMissionControlExtension(deps = {}) {
             if (ctrl.model.revision === lastRenderedRevision)
                 return; // throttle: skip no-op ticks
             lastRenderedRevision = ctrl.model.revision;
-            activeCtx.ui.setWidget(WIDGET_KEY, (0, render_1.renderBoard)(ctrl.model), { placement: 'aboveEditor' });
+            activeCtx.ui.setWidget(WIDGET_KEY, (0, render_1.renderBoard)(ctrl.model, ctrl.localHost), { placement: 'aboveEditor' });
         };
         const startCoarse = () => {
             if (!adminToken) {
                 log(`no admin token (${actions_1.ADMIN_TOKEN_ENV}) — board limited / disabled`);
             }
-            coarseAbort = new AbortController();
-            const subscribe = (0, subscribe_1.createSubscribe)({ baseUrl, ...(adminToken ? { token: adminToken } : {}) });
+            // H5: capture the controller locally. teardown nulls the outer `coarseAbort`,
+            // so the catch must check THIS signal — checking the nulled outer ref made an
+            // expected teardown abort log a spurious "coarse SSE ended: AbortError".
+            const ac = new AbortController();
+            coarseAbort = ac;
+            // H5: omit baseUrl → createSubscribe re-resolves the daemon port per
+            // (re)connect, so a daemon restart on a new port self-heals.
+            const subscribe = (0, subscribe_1.createSubscribe)({
+                ...(deps.baseUrl ? { baseUrl: deps.baseUrl } : {}),
+                ...(adminToken ? { token: adminToken } : {}),
+            });
             void (async () => {
                 try {
-                    for await (const ev of subscribe(ensemble, { signal: coarseAbort.signal })) {
+                    for await (const ev of subscribe(ensemble, { signal: ac.signal })) {
                         (0, board_1.applyTempoEvent)(ctrl.model, ev);
                     }
                 }
                 catch (err) {
-                    if (!coarseAbort?.signal.aborted)
+                    if (!ac.signal.aborted)
                         log('coarse SSE ended:', err instanceof Error ? err.message : err);
                 }
             })();
@@ -198,6 +274,9 @@ function createMissionControlExtension(deps = {}) {
             if (playerId === null || !adminToken)
                 return;
             tailAbort = new AbortController();
+            // H5: resolve the daemon base URL HERE (per /tail) so a port change is
+            // picked up on the next tail instead of being pinned at session start.
+            const baseUrl = resolveBaseUrl(deps.baseUrl);
             const fetchFn = globalThis.fetch;
             if (!fetchFn)
                 return;

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

@@ -3,4 +3,4 @@ import { type BoardModel } from './board';
  * Render the full board. Header + player rows (conductor first), then — when a
  * player is selected — a fine inner-loop tail (last {@link TAIL_RENDER_LINES}).
  */
-export declare function renderBoard(model: BoardModel): string[];
+export declare function renderBoard(model: BoardModel, localHost?: string): string[];

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

@@ -24,14 +24,17 @@ function pct(contextPercent) {
     const p = contextPercent <= 1 ? contextPercent * 100 : contextPercent;
     return `${Math.round(p)}%`;
 }
-function renderRow(row, selected) {
+function renderRow(row, selected, localHost) {
     const sel = selected ? '>' : ' ';
     const glyph = phaseGlyph(row.phase);
     const tool = row.currentTool ? `[${row.currentTool}]` : '';
     const ctx = pct(row.contextPercent);
     const part = row.part ? ` ${row.part}` : '';
-    // sel glyph id  part  tool  ctx
-    return [`${sel}${glyph} ${row.playerId}`, part, tool, ctx]
+    // H3a: flag cross-host players (`@host`) so the operator sees at a glance which
+    // are non-tailable (the /inner tail is daemon-local). Only when localHost is known.
+    const host = localHost && row.hostname && row.hostname !== localHost ? `@${row.hostname}` : '';
+    // sel glyph id  part  tool  ctx  @host
+    return [`${sel}${glyph} ${row.playerId}`, part, tool, ctx, host]
         .filter((s) => s !== '')
         .join('  ')
         .trimEnd();
@@ -67,7 +70,7 @@ function oneLine(s, max) {
  * Render the full board. Header + player rows (conductor first), then — when a
  * player is selected — a fine inner-loop tail (last {@link TAIL_RENDER_LINES}).
  */
-function renderBoard(model) {
+function renderBoard(model, localHost) {
     const ids = (0, board_1.sortedPlayerIds)(model);
     const lines = [];
     lines.push(`MISSION CONTROL · ${model.ensemble} · ${ids.length} player${ids.length === 1 ? '' : 's'}`);
@@ -77,7 +80,7 @@ function renderBoard(model) {
     else {
         for (const id of ids) {
             const row = model.players.get(id);
-            lines.push(renderRow(row, id === model.selected));
+            lines.push(renderRow(row, id === model.selected, localHost));
         }
     }
     if (model.selected) {

package/dist/pi/pi-types.d.ts

@@ -197,7 +197,21 @@ export interface PiToolDefinition {
     description?: string;
     /** TypeBox schema object. Typed `unknown` to avoid coupling pi-types to typebox. */
     parameters: unknown;
-    execute: (args: Record<string, unknown>) => Promise<PiToolResult> | PiToolResult;
+    /**
+     * Pi invokes `execute` POSITIONALLY at runtime:
+     *   execute(toolCallId, params, signal?, onUpdate?, ctx?)
+     * (installed Pi 0.78 `core/extensions/types.d.ts:354` + the wrapper at
+     * `core/tools/tool-definition-wrapper.js:10,31`). The VALIDATED params object
+     * is the SECOND positional — the FIRST is the `toolCallId` string.
+     *
+     * Declaring the full positional shape (not a single `args`) is LOAD-BEARING: a
+     * one-arg signature silently accepts `(args) => handler(args)`, which binds the
+     * toolCallId string to what the handler treats as the params object — the
+     * shipped arg-order bug (v1.4.0) this corrected type now makes a compile error.
+     * `signal`/`onUpdate`/`ctx` are optional + `unknown`: we don't consume them and
+     * avoid coupling to Pi's internal callback/context types.
+     */
+    execute: (toolCallId: string, params: Record<string, unknown>, signal?: unknown, onUpdate?: unknown, ctx?: unknown) => Promise<PiToolResult> | PiToolResult;
 }
 /** The `pi` object passed to `export default function(pi: ExtensionAPI) {}`. */
 export interface ExtensionAPI {

package/dist/pi/probe.d.ts

@@ -31,6 +31,25 @@ export declare function probePi(): PiProbeResult;
  * (conservative: unknown version is treated as below the floor).
  */
 export declare function meetsVersionFloor(installed: string, floor?: string): boolean;
+/**
+ * Node-floor preflight (Decision B, #645). The Pi optional deps require
+ * Node >= {@link PI_NODE_FLOOR} (22.19). Enforced ONLY at the Pi recruit/spawn
+ * boundary — `package.json#engines` stays `>=20` so non-Pi users are untouched.
+ *
+ * Pure + injectable (`nodeVersion` defaults to the live runtime) so it is the
+ * single source of truth shared by the recruit pre-flight (authoritative,
+ * pre-spawn) AND the {@link runHeadlessPi} backstop (direct/manual launches).
+ * Reuses {@link meetsVersionFloor}'s major.minor.patch comparison.
+ *
+ * @returns `{ ok: true }` when the floor is met, else `{ ok: false, reason }`
+ *   with an actionable, fail-clean message (mirrors the `probeSdkInstall` /
+ *   `resolveModel` style). The `reason` omits any `force: true` hint so each
+ *   caller can frame the bypass in its own voice.
+ */
+export declare function checkPiNodeFloor(nodeVersion?: string): {
+    ok: boolean;
+    reason?: string;
+};
 /**
  * Injectable collaborators for {@link probeCopilotPiPreflight}. All default to
  * real implementations; tests override them to exercise each branch without a

package/dist/pi/probe.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PI_NODE_FLOOR = exports.PI_VERSION_FLOOR = exports.TESTED_PI_VERSION = exports.PI_AI_PACKAGE = exports.PI_PACKAGE = void 0;
 exports.probePi = probePi;
 exports.meetsVersionFloor = meetsVersionFloor;
+exports.checkPiNodeFloor = checkPiNodeFloor;
 exports.probeCopilotPiPreflight = probeCopilotPiPreflight;
 /**
  * Pi dependency preflight — mirrors the opencode / claude-api optional-dep gate.
@@ -74,6 +75,30 @@ function meetsVersionFloor(installed, floor = exports.PI_VERSION_FLOOR) {
         return iMin > fMin;
     return iPat >= fPat;
 }
+/**
+ * Node-floor preflight (Decision B, #645). The Pi optional deps require
+ * Node >= {@link PI_NODE_FLOOR} (22.19). Enforced ONLY at the Pi recruit/spawn
+ * boundary — `package.json#engines` stays `>=20` so non-Pi users are untouched.
+ *
+ * Pure + injectable (`nodeVersion` defaults to the live runtime) so it is the
+ * single source of truth shared by the recruit pre-flight (authoritative,
+ * pre-spawn) AND the {@link runHeadlessPi} backstop (direct/manual launches).
+ * Reuses {@link meetsVersionFloor}'s major.minor.patch comparison.
+ *
+ * @returns `{ ok: true }` when the floor is met, else `{ ok: false, reason }`
+ *   with an actionable, fail-clean message (mirrors the `probeSdkInstall` /
+ *   `resolveModel` style). The `reason` omits any `force: true` hint so each
+ *   caller can frame the bypass in its own voice.
+ */
+function checkPiNodeFloor(nodeVersion = process.versions.node) {
+    if (meetsVersionFloor(nodeVersion, exports.PI_NODE_FLOOR))
+        return { ok: true };
+    return {
+        ok: false,
+        reason: `agent: "pi" requires Node >= ${exports.PI_NODE_FLOOR}, but this host runs Node ${nodeVersion}. ` +
+            `Upgrade Node (e.g. via nvm/fnm) and retry.`,
+    };
+}
 /** Default `~/.pi/agent/auth.json` presence check. */
 function defaultAuthFileExists() {
     return (0, fs_1.existsSync)((0, path_1.join)((0, os_1.homedir)(), '.pi', 'agent', 'auth.json'));

package/dist/pi/render-tools.js

@@ -45,7 +45,12 @@ function renderToPi(pi, descriptors) {
             name: d.name,
             description: d.description,
             parameters: (0, zod_to_typebox_1.zodShapeToTypeBox)(d.params, d.name),
-            execute: async (args) => toPiResult(await d.handler(args)),
+            // Pi calls execute POSITIONALLY: (toolCallId, params, signal, onUpdate, ctx).
+            // The validated params object is the SECOND positional — ignore the
+            // toolCallId string (1st) and hand `params` to the descriptor handler.
+            // (Passing the 1st positional was the v1.4.0 arg-order bug: handlers got the
+            // toolCallId string instead of params.) See PiToolDefinition.execute.
+            execute: async (_toolCallId, params) => toPiResult(await d.handler(params)),
         });
     }
 }

package/dist/pi/session-seed.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Pi session seeding — the SINGLE chokepoint for `appendMessage` on a headless
+ * Pi `SessionManager` (H1, epic #645).
+ *
+ * WHY a chokepoint (load-bearing, PoC-verified against Pi 0.78.0):
+ *   Pi's `SessionManager.appendMessage` NEVER validates `content` — every
+ *   malformed shape appends "ok". The throw (`"content is not iterable"`) fires
+ *   purely at CONSUMPTION: `getLastAssistantText()` /context-build /compaction
+ *   scans iterate `message.content` (agent-session.js:2486/2493 in Pi 0.78). So
+ *   seed-time sanitization is the ONLY lever agent-tempo controls — a
+ *   consumption-site guard would be Pi-internal.
+ *
+ *   Therefore {@link seedSessionManager} is the one and only place that calls
+ *   `appendMessage`, and it runs every entry through {@link sanitizeTranscriptEntry}
+ *   first. `headless.ts` MUST NOT call `appendMessage` directly.
+ *
+ * RESERVED CHOKEPOINT (#645 / H2 OPT-A outcome): no live caller passes a
+ * non-empty transcript today — Pi's `loadFromState` resume rides the existing
+ * `deliverRestart` → `receiveMessage('self-restart')` → cue-pump path (the
+ * restored-state cue lands on the in-memory session; verified by smoke +
+ * test/pi-cue-pump-restore.test.ts). `seedSessionManager` is retained as (1) the
+ * tested safety chokepoint and (2) the reserved seed gate for the DEFERRED
+ * verbatim-transcript epic; the sanitizer is defense-in-depth. NOT dead code.
+ *
+ * PURE module: no Pi SDK import. Unit-tested with a fake recording
+ * `SessionManager` (test/pi-session-seed.test.ts), mirroring
+ * `buildPiResourceLoaderOptions`' SDK-free regression test.
+ *
+ * Determinism boundary: client-side only (no wire/workflow impact).
+ */
+/**
+ * A loose structural view of a Pi transcript entry. Replay data is untrusted
+ * (it may be anything that survived durable storage), so the sanitizer accepts
+ * `unknown` and narrows.
+ */
+export interface TranscriptEntry {
+    /** Discriminator for the `Message | CustomMessage | BashExecutionMessage` union. */
+    role?: unknown;
+    /** The crash-bearing field — must be `string | unknown[]` to survive consumption. */
+    content?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Minimal structural view of Pi's `SessionManager` — only the method the seed
+ * path touches. Real signature: `appendMessage(msg): string` (the entry id); we
+ * type the return as `unknown` since the seed path ignores it.
+ */
+export interface SeedableSessionManager {
+    appendMessage(message: TranscriptEntry): unknown;
+}
+/**
+ * Validate a single replay entry. KEEP (return the entry unchanged) iff its
+ * `role` is an `appendMessage`-accepted shape AND its `content` is well-shaped
+ * (`string | array`); otherwise DROP (return `null`).
+ *
+ * DROP is the ruled default (architect): a malformed entry has no recoverable
+ * content and role-alternation is not a Pi hard-requirement. Coerce-to-`[]` is a
+ * documented one-line escape hatch reserved for a turn-pairing sensitivity that
+ * has not surfaced — it is intentionally NOT the default.
+ *
+ * Crash sites this guard protects (Pi 0.78): `agent-session.js:2486` (context
+ * build) and `:2493` (`getLastAssistantText` — `for (const c of msg.content)`).
+ */
+export declare function sanitizeTranscriptEntry(entry: unknown): TranscriptEntry | null;
+/**
+ * Seed a fresh in-memory `SessionManager` from a durable replay transcript — the
+ * ONLY code path that calls `sm.appendMessage`. Each entry is run through
+ * {@link sanitizeTranscriptEntry}; survivors are appended in order, malformed
+ * entries are dropped. No-op for an empty/undefined transcript (a fresh recruit
+ * — the H1 case).
+ *
+ * @returns the number of entries actually appended (for logging + tests).
+ */
+export declare function seedSessionManager(sm: SeedableSessionManager, transcript: readonly unknown[] | undefined | null): number;

package/dist/pi/session-seed.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Pi session seeding — the SINGLE chokepoint for `appendMessage` on a headless
+ * Pi `SessionManager` (H1, epic #645).
+ *
+ * WHY a chokepoint (load-bearing, PoC-verified against Pi 0.78.0):
+ *   Pi's `SessionManager.appendMessage` NEVER validates `content` — every
+ *   malformed shape appends "ok". The throw (`"content is not iterable"`) fires
+ *   purely at CONSUMPTION: `getLastAssistantText()` /context-build /compaction
+ *   scans iterate `message.content` (agent-session.js:2486/2493 in Pi 0.78). So
+ *   seed-time sanitization is the ONLY lever agent-tempo controls — a
+ *   consumption-site guard would be Pi-internal.
+ *
+ *   Therefore {@link seedSessionManager} is the one and only place that calls
+ *   `appendMessage`, and it runs every entry through {@link sanitizeTranscriptEntry}
+ *   first. `headless.ts` MUST NOT call `appendMessage` directly.
+ *
+ * RESERVED CHOKEPOINT (#645 / H2 OPT-A outcome): no live caller passes a
+ * non-empty transcript today — Pi's `loadFromState` resume rides the existing
+ * `deliverRestart` → `receiveMessage('self-restart')` → cue-pump path (the
+ * restored-state cue lands on the in-memory session; verified by smoke +
+ * test/pi-cue-pump-restore.test.ts). `seedSessionManager` is retained as (1) the
+ * tested safety chokepoint and (2) the reserved seed gate for the DEFERRED
+ * verbatim-transcript epic; the sanitizer is defense-in-depth. NOT dead code.
+ *
+ * PURE module: no Pi SDK import. Unit-tested with a fake recording
+ * `SessionManager` (test/pi-session-seed.test.ts), mirroring
+ * `buildPiResourceLoaderOptions`' SDK-free regression test.
+ *
+ * Determinism boundary: client-side only (no wire/workflow impact).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeTranscriptEntry = sanitizeTranscriptEntry;
+exports.seedSessionManager = seedSessionManager;
+/**
+ * Roles `appendMessage` accepts, derived from the installed Pi 0.78 type defs
+ * (NOT assumed):
+ *   - `@earendil-works/pi-ai` `Message` union → `user` | `assistant` | `toolResult`
+ *     (types.d.ts:192/197/211)
+ *   - `@earendil-works/pi-coding-agent` extras → `bashExecution` | `custom`
+ *     (core/messages.d.ts:16/32)
+ * An entry whose `role` is not one of these is not a message Pi can append → DROP.
+ */
+const ACCEPTED_ROLES = new Set([
+    'user',
+    'assistant',
+    'toolResult',
+    'bashExecution',
+    'custom',
+]);
+/**
+ * The load-bearing predicate (PoC-confirmed against Pi 0.78.0 — no refinement
+ * needed). `content` must be a string or an array; anything else (`null`,
+ * `undefined`, `{}`, a number) is non-iterable and throws at consumption.
+ */
+function isWellShapedContent(content) {
+    return typeof content === 'string' || Array.isArray(content);
+}
+/**
+ * Validate a single replay entry. KEEP (return the entry unchanged) iff its
+ * `role` is an `appendMessage`-accepted shape AND its `content` is well-shaped
+ * (`string | array`); otherwise DROP (return `null`).
+ *
+ * DROP is the ruled default (architect): a malformed entry has no recoverable
+ * content and role-alternation is not a Pi hard-requirement. Coerce-to-`[]` is a
+ * documented one-line escape hatch reserved for a turn-pairing sensitivity that
+ * has not surfaced — it is intentionally NOT the default.
+ *
+ * Crash sites this guard protects (Pi 0.78): `agent-session.js:2486` (context
+ * build) and `:2493` (`getLastAssistantText` — `for (const c of msg.content)`).
+ */
+function sanitizeTranscriptEntry(entry) {
+    if (entry === null || typeof entry !== 'object')
+        return null;
+    const e = entry;
+    if (typeof e.role !== 'string' || !ACCEPTED_ROLES.has(e.role))
+        return null;
+    if (!isWellShapedContent(e.content))
+        return null;
+    return e;
+}
+/**
+ * Seed a fresh in-memory `SessionManager` from a durable replay transcript — the
+ * ONLY code path that calls `sm.appendMessage`. Each entry is run through
+ * {@link sanitizeTranscriptEntry}; survivors are appended in order, malformed
+ * entries are dropped. No-op for an empty/undefined transcript (a fresh recruit
+ * — the H1 case).
+ *
+ * @returns the number of entries actually appended (for logging + tests).
+ */
+function seedSessionManager(sm, transcript) {
+    if (!transcript || transcript.length === 0)
+        return 0;
+    let appended = 0;
+    for (const raw of transcript) {
+        const entry = sanitizeTranscriptEntry(raw);
+        if (entry === null)
+            continue; // DROP — never reaches the Pi session
+        sm.appendMessage(entry);
+        appended += 1;
+    }
+    return appended;
+}

package/dist/tools/recruit.js

@@ -266,6 +266,21 @@ function buildRecruitTool(client, config, getPlayerId, handle, ownAgentType = 'c
                     return (0, descriptor_1.fail)(`agent: "copilot" requires the @github/copilot-sdk optional dependency. Install with \`npm install @github/copilot-sdk\` and retry, or use \`force: true\` to bypass this check.`);
                 }
             }
+            // Node-floor (Decision B, #645) — AUTHORITATIVE, NON-BYPASSABLE gate, so it
+            // sits ABOVE the `&& !force` block below. Unlike sdk-probe (a filesystem
+            // heuristic with possible false-negatives, where `force` stays legitimate),
+            // the Node floor has NO false-negative — `process.versions.node` is
+            // authoritative and Pi literally cannot import on sub-22.19 — so there is no
+            // legitimate override. Checked even under `force: true`, matching the
+            // unconditional runHeadlessPi backstop, so recruit fails clean BEFORE spawn
+            // in ALL local cases. Local recruit only — cross-host (`host` set) defers to
+            // the target daemon's availableAgentTypes. Gates BOTH the Copilot and
+            // Anthropic/Pi-default paths below.
+            if (agent === 'pi' && !host) {
+                const nodeFloor = (0, probe_1.checkPiNodeFloor)();
+                if (!nodeFloor.ok)
+                    return (0, descriptor_1.fail)(`agent: "pi" — ${nodeFloor.reason}`);
+            }
             // Phase 3a — headless Pi pre-flight. The Pi SDK is an optional Node-22.19+
             // dep required at the headless entry; gate at recruit (cross-host skips —
             // the target daemon's availableAgentTypes is the gate there).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tempo",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Many agents, one tempo. Durable coordination for multi-agent work via Temporal.",
   "keywords": [
     "mcp",