agent-tempo 1.2.0 → 1.4.0

package/dist/pi/tool-capability.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Tool capability classifier (3d / MD-C) — a PURE function mapping a tool name
+ * to its risk class. The 3d operator gate and the MD-C headless tool-access
+ * posture consume it; this module owns the MECHANISM, tempo-security owns the
+ * CONTENT (the name-sets below) and signs off on it.
+ *
+ *   - `'exec'`       — shell / arbitrary-code execution. HARD-BLOCKED when the
+ *                      headless tool-access policy is `restricted` (MD-C). The
+ *                      highest-danger class.
+ *   - `'high-blast'` — destructive or exfiltration-capable actions (file writes,
+ *                      network fetch, ensemble mutation). Allowed unsupervised,
+ *                      but routed to the OPERATOR GATE when an operator is armed.
+ *   - `'low-risk'`   — read-only / coordination. Always bypasses the gate.
+ *
+ * UNKNOWN tool names default to {@link UNKNOWN_DEFAULT} — a FAIL-SAFE choice
+ * (`'high-blast'`: never silently bypass a tool we don't recognize; gate it when
+ * an operator is armed). Whether an unknown tool should instead hard-block
+ * (`'exec'`) is a tempo-security posture call — see the cue to security.
+ *
+ * Matching is CASE-INSENSITIVE on the trimmed tool name. Pi's `tool_call`
+ * `toolName` is a bare string (built-ins like `bash`/`read`/`edit`/`write`/`grep`
+ * plus the natively-registered agent-tempo MCP tools), so we normalize before
+ * lookup.
+ *
+ * ⚠️ NAME-SET OWNERSHIP: the three Sets are tempo-security's posture content.
+ * They are a STARTER set (conductor's examples + Pi built-ins + the agent-tempo
+ * coordination/mutation tools) pending security's authoritative sign-off; amend
+ * the Set membership without touching the mechanism. The classifier behavior
+ * (and its tests) are keyed on representative names that won't move.
+ */
+/** Risk class for a tool, consumed by the 3d gate + MD-C policy. */
+export type ToolCapability = 'exec' | 'high-blast' | 'low-risk';
+/** Fail-safe class for an unrecognized tool name (never bypass the unknown). */
+export declare const UNKNOWN_DEFAULT: ToolCapability;
+/**
+ * Shell / arbitrary-code execution — hard-blocked at `restricted` (MD-C).
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ *
+ * CANONICAL exec denylist (single source of truth). The F1 refactor (3d) made
+ * `src/pi/extension.ts` import this set via `classify(name) === 'exec'` and
+ * REMOVED its former local `SHELL_TOOL_NAMES` — so the live restricted-mode gate
+ * now hard-blocks the full set including `powershell`/`pwsh`/`cmd`/`run` (the gap
+ * the old local list left open). Never re-declare a shell denylist elsewhere.
+ */
+export declare const EXEC_TOOLS: ReadonlySet<string>;
+/**
+ * Destructive / exfiltration-capable — gated when an operator is armed.
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ */
+export declare const HIGH_BLAST_TOOLS: ReadonlySet<string>;
+/**
+ * Read-only / coordination — always bypasses the gate.
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ */
+export declare const LOW_RISK_TOOLS: ReadonlySet<string>;
+/**
+ * Classify a tool name into its risk class. Pure + case-insensitive; unknown
+ * names fall through to {@link UNKNOWN_DEFAULT} (fail-safe — never bypass).
+ */
+export declare function classify(toolName: string): ToolCapability;

package/dist/pi/tool-capability.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Tool capability classifier (3d / MD-C) — a PURE function mapping a tool name
+ * to its risk class. The 3d operator gate and the MD-C headless tool-access
+ * posture consume it; this module owns the MECHANISM, tempo-security owns the
+ * CONTENT (the name-sets below) and signs off on it.
+ *
+ *   - `'exec'`       — shell / arbitrary-code execution. HARD-BLOCKED when the
+ *                      headless tool-access policy is `restricted` (MD-C). The
+ *                      highest-danger class.
+ *   - `'high-blast'` — destructive or exfiltration-capable actions (file writes,
+ *                      network fetch, ensemble mutation). Allowed unsupervised,
+ *                      but routed to the OPERATOR GATE when an operator is armed.
+ *   - `'low-risk'`   — read-only / coordination. Always bypasses the gate.
+ *
+ * UNKNOWN tool names default to {@link UNKNOWN_DEFAULT} — a FAIL-SAFE choice
+ * (`'high-blast'`: never silently bypass a tool we don't recognize; gate it when
+ * an operator is armed). Whether an unknown tool should instead hard-block
+ * (`'exec'`) is a tempo-security posture call — see the cue to security.
+ *
+ * Matching is CASE-INSENSITIVE on the trimmed tool name. Pi's `tool_call`
+ * `toolName` is a bare string (built-ins like `bash`/`read`/`edit`/`write`/`grep`
+ * plus the natively-registered agent-tempo MCP tools), so we normalize before
+ * lookup.
+ *
+ * ⚠️ NAME-SET OWNERSHIP: the three Sets are tempo-security's posture content.
+ * They are a STARTER set (conductor's examples + Pi built-ins + the agent-tempo
+ * coordination/mutation tools) pending security's authoritative sign-off; amend
+ * the Set membership without touching the mechanism. The classifier behavior
+ * (and its tests) are keyed on representative names that won't move.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOW_RISK_TOOLS = exports.HIGH_BLAST_TOOLS = exports.EXEC_TOOLS = exports.UNKNOWN_DEFAULT = void 0;
+exports.classify = classify;
+/** Fail-safe class for an unrecognized tool name (never bypass the unknown). */
+exports.UNKNOWN_DEFAULT = 'high-blast';
+/**
+ * Shell / arbitrary-code execution — hard-blocked at `restricted` (MD-C).
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ *
+ * CANONICAL exec denylist (single source of truth). The F1 refactor (3d) made
+ * `src/pi/extension.ts` import this set via `classify(name) === 'exec'` and
+ * REMOVED its former local `SHELL_TOOL_NAMES` — so the live restricted-mode gate
+ * now hard-blocks the full set including `powershell`/`pwsh`/`cmd`/`run` (the gap
+ * the old local list left open). Never re-declare a shell denylist elsewhere.
+ */
+exports.EXEC_TOOLS = new Set([
+    'bash',
+    'shell',
+    'exec',
+    'sh',
+    'powershell',
+    'pwsh',
+    'cmd',
+    'run',
+    'process',
+    'command',
+    'run_command',
+]);
+/**
+ * Destructive / exfiltration-capable — gated when an operator is armed.
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ */
+exports.HIGH_BLAST_TOOLS = new Set([
+    // Pi built-in mutating tools.
+    'write',
+    'edit',
+    'multiedit',
+    // Network exfiltration surface (arbitrary HTTP incl. POST). NOTE: `websearch`
+    // is LOW_RISK (read-only results) — only the fetch/browse family gates.
+    'webfetch',
+    'web_fetch',
+    'fetch',
+    'http_request',
+    'browser',
+    // agent-tempo tools that mutate the ensemble / spawn / tear down / control peers.
+    'recruit',
+    'destroy',
+    'restart',
+    'migrate',
+    'shutdown',
+    'release', // releases a held player — state change on a peer
+    'broadcast', // fans out to ALL players (amplification)
+    'schedule', // creates a durable autonomous trigger (unschedule is LOW_RISK)
+    'pause',
+    'play',
+    'restore', // re-spawns a detached player (process spawn)
+    // State / artifact destruction (irreversible).
+    'save_state',
+    'clear_state',
+    'coat_check_evict',
+    // Lineup spawn (full ensemble from YAML; save_lineup is LOW_RISK).
+    'load_lineup',
+    // Git state + disk mutation.
+    'worktree',
+    'stage',
+    'cancel_stage', // discards staged work (irreversible)
+    // Quality gates that block/unblock ensemble workflow progress.
+    'quality_gate',
+    'evaluate_gate',
+    // Drive/file mutation.
+    'copy_file',
+]);
+/**
+ * Read-only / coordination — always bypasses the gate.
+ * CONTENT owned by tempo-security (signed off 2026-06-04).
+ */
+exports.LOW_RISK_TOOLS = new Set([
+    // Pi built-in read tools.
+    'read',
+    'grep',
+    'glob',
+    'ls',
+    // Read-only web search (no arbitrary POST — distinct from the web_fetch family).
+    'websearch',
+    'web_search',
+    // agent-tempo read-only / status / messaging coordination tools.
+    'cue',
+    'report',
+    'recall',
+    'listen',
+    'ensemble',
+    'who_am_i',
+    'set_name',
+    'set_part',
+    'set_ensemble_description', // metadata only, no blast radius
+    'hosts',
+    'attachment_info',
+    'agent_types',
+    'schedules',
+    'stages',
+    'gates',
+    // Read-only state / coat-check (coat_check_put is bounded 32KB + TTL'd + visible).
+    'fetch_state',
+    'coat_check_put',
+    'coat_check_get',
+    'coat_check_list',
+    // Removes a future trigger — blast was at schedule-time, not here.
+    'unschedule',
+    // Writes the coordinator YAML (not arbitrary file write; blast is at load_lineup).
+    'save_lineup',
+]);
+/**
+ * Classify a tool name into its risk class. Pure + case-insensitive; unknown
+ * names fall through to {@link UNKNOWN_DEFAULT} (fail-safe — never bypass).
+ */
+function classify(toolName) {
+    const name = toolName.trim().toLowerCase();
+    if (exports.EXEC_TOOLS.has(name))
+        return 'exec';
+    if (exports.HIGH_BLAST_TOOLS.has(name))
+        return 'high-blast';
+    if (exports.LOW_RISK_TOOLS.has(name))
+        return 'low-risk';
+    return exports.UNKNOWN_DEFAULT;
+}

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

@@ -0,0 +1,158 @@
+/**
+ * Thin CLIENT-SIDE Temporal wrapper for the Pi extension (D4 = (a)).
+ *
+ * The durable Temporal `Worker` stays in the daemon. This holds only a
+ * `WorkflowClient` that signals/queries/updates the session workflow — it never
+ * runs workflow code, so NOTHING here (or anywhere in src/pi/) is imported into
+ * the V8 workflow sandbox. The determinism boundary is preserved.
+ *
+ * Reuses the existing wire surface verbatim:
+ *   - `claimAttachment` / `heartbeat`        — lease lifecycle (drives `attached`)
+ *   - `processingStart` / `processingEnd`    — drives `processing` / `awaiting`
+ *   - `requestDetach` + `adapterExited`      — drives `draining` → `detached`
+ *   - `submitOutbox`                         — report routing (outbox compliance)
+ *   - `pendingMessages` + `markDelivered`    — cue intake + ack
+ */
+import { Client, type WorkflowHandle } from '@temporalio/client';
+import { type Config } from '../config';
+import type { AttachmentToken, DetachReason, Message, OutboxEntryInput, PendingReset, SessionMetadata } from '../types';
+import type { WorkflowAction } from './phase-driver';
+/**
+ * MD-A liveness timings (Phase 2, maintainer-approved): 30s heartbeat / 90s
+ * lease, holding the **lease = 3×heartbeat** invariant — a single (or even
+ * second) missed beat never expires the lease, but a dead process is reaped
+ * within ~one lease window. Parity with the other SDK adapters' `heartbeatMs`.
+ * Overridable per-session via `PiWorkflowClientOptions.{leaseMs,heartbeatMs}`.
+ * Exported so a guard test can assert the invariant doesn't silently drift.
+ */
+export declare const PI_HEARTBEAT_MS = 30000;
+export declare const PI_LEASE_MS = 90000;
+/** 3c Tier-1 — coarse activity sample piggybacked onto each heartbeat. */
+export type CoarseSample = {
+    currentTool: string | null;
+    contextTokens?: number;
+    contextPercent?: number;
+};
+/**
+ * Supplies the latest coarse sample at heartbeat time. eng's inner-loop
+ * publisher exposes exactly this via `getCoarseState()`; the extension wires it
+ * in after constructing the publisher. Absent (default) → heartbeats carry no
+ * coarse fields (backward-compatible with the 3a sender).
+ */
+export type CoarseProvider = () => CoarseSample | undefined;
+export interface PiWorkflowClientOptions {
+    client: Client;
+    config: Config;
+    metadata: SessionMetadata;
+    leaseMs?: number;
+    heartbeatMs?: number;
+    /** 3c — optional coarse-activity provider (eng's `publisher.getCoarseState`). */
+    coarseProvider?: CoarseProvider;
+    /**
+     * Restart/migrate handoff token (`AGENT_TEMPO_ATTACHMENT_ID`). When present,
+     * `claim()` ADOPTS the pre-created attachment via the renewal branch instead of
+     * racing a fresh claim — the clean anti-flap path the restart tool will use
+     * (the read side of that spawn wiring is a tracked Phase 3 / restart carry-item;
+     * this is the forward-compatible plumbing). Absent on a fresh recruit / manual
+     * launch → fresh claim. Mirrors the existing adapters (`base.ts` startV2Lifecycle).
+     */
+    expectedAttachmentId?: string;
+}
+/**
+ * One instance per attached Pi session — holds the session `WorkflowHandle`,
+ * lease token, and heartbeat timer for one fixed-workflowId player. Tool
+ * handlers reach this player's handle via the D11 lazy proxy (`get handle()`).
+ */
+export declare class PiWorkflowClient {
+    private readonly client;
+    private readonly config;
+    private readonly metadata;
+    private readonly leaseMs;
+    private readonly heartbeatMs;
+    private readonly expectedAttachmentId?;
+    private coarseProvider?;
+    private wfHandle;
+    private token;
+    private heartbeatTimer;
+    constructor(opts: PiWorkflowClientOptions);
+    /**
+     * 3c — wire the coarse-activity provider after construction (the inner-loop
+     * publisher is created alongside, then handed in). Each heartbeat samples it.
+     */
+    setCoarseProvider(provider: CoarseProvider): void;
+    /** Build a client from config (connection-pooled; safe to share — see D12a). */
+    static connect(config?: Config): Promise<Client>;
+    get attachmentId(): string | null;
+    /**
+     * The live session `WorkflowHandle`, or `null` before {@link ensureSessionWorkflow}.
+     * Exposed so the D11 lazy-proxy (src/pi/lazy-proxy.ts) can resolve the player's
+     * OWN handle per tool call — tool handlers route through it (e.g. `submitOutbox`)
+     * and never `.signal()` a peer workflow directly.
+     */
+    get handle(): WorkflowHandle | null;
+    private get workflowId();
+    /**
+     * Ensure the session workflow exists and grab a handle. For a human-launched
+     * `pi`, the workflow may not exist yet; `USE_EXISTING` makes this idempotent
+     * when `agent-tempo up`/recruit already started it.
+     */
+    ensureSessionWorkflow(): Promise<WorkflowHandle>;
+    private requireHandle;
+    /**
+     * Claim (or, with a handoff token, ADOPT) the attachment: phase
+     * `booting → attached`. Fresh claim when `expectedAttachmentId` is absent;
+     * renewal/adoption branch when the restart tool handed one in. Stores the token.
+     */
+    claim(): Promise<AttachmentToken>;
+    /**
+     * Liveness heartbeat — renews the lease. This is the ENTIRE reason an abrupt
+     * Pi death is detectable: stop heart-beating and `expiresAt` lapses (see
+     * src/pi/README.md "Abrupt-death finding" / MD-A).
+     */
+    heartbeat(): Promise<void>;
+    /** Start the heartbeat loop. The timer is `unref`'d so it never holds the process open. */
+    startHeartbeat(): void;
+    stopHeartbeat(): void;
+    /** agent_start → phase `processing`. */
+    processingStart(messageId: string): Promise<void>;
+    /** agent_end → phase `awaiting`. */
+    processingEnd(messageId: string): Promise<void>;
+    /**
+     * Graceful self-initiated detach: stopHeartbeat → adapterExited (→ detached).
+     *
+     * `adapterExited` ALONE collapses any live phase (attached/processing/awaiting/
+     * draining) straight to `detached` — see the workflow handler at
+     * `session.ts` adapterExitedSignal (returns early only on detached/gone). No
+     * `requestDetach` is needed for a self-exit; that signal is the EXTERNAL ask to
+     * drain a running adapter someone else controls. This matches the proven
+     * `BaseAttachment.stopV2Lifecycle(graceful)` path. Idempotent-safe to call on
+     * `session_shutdown` and from the headless exit sequence.
+     */
+    detach(reason?: DetachReason): Promise<void>;
+    /**
+     * Stash the currently-active Pi SessionManager session id onto durable
+     * workflow metadata (`metadata.sessionId`). This is the MUTABLE resume pointer
+     * — SEPARATE from the fixed workflowId (identity). A later restart of this
+     * player reads it to resume the same conversation via Pi `continueSession`
+     * (reuses the #334 sessionId resume field). No-op when the id is absent.
+     */
+    updateSessionId(sessionId: string | undefined): Promise<void>;
+    /** Route an outbox entry through the workflow outbox (player's own handle). */
+    submitOutbox(entry: OutboxEntryInput): Promise<string>;
+    /** Pull undelivered messages (cues) queued on the workflow. */
+    fetchPending(): Promise<Message[]>;
+    /** Acknowledge delivered cue ids so the workflow stops re-serving them. */
+    ackDelivered(messageIds: string[]): Promise<void>;
+    /** Poll the workflow's single-slot pending reset (null = none). */
+    fetchPendingReset(): Promise<PendingReset | null>;
+    /**
+     * Ack a performed reset by id — the workflow clears the slot ONLY if the id
+     * still matches (race-safe: a newer reset that landed mid-wipe is preserved).
+     */
+    ackReset(resetId: string): Promise<void>;
+    /**
+     * Dispatch a {@link WorkflowAction} produced by {@link PhaseDriver}. Centralizes
+     * the action→wire-call mapping so the extension wiring stays declarative.
+     */
+    performAction(action: WorkflowAction): Promise<void>;
+}

package/dist/pi/workflow-client.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PiWorkflowClient = exports.PI_LEASE_MS = exports.PI_HEARTBEAT_MS = void 0;
+/**
+ * Thin CLIENT-SIDE Temporal wrapper for the Pi extension (D4 = (a)).
+ *
+ * The durable Temporal `Worker` stays in the daemon. This holds only a
+ * `WorkflowClient` that signals/queries/updates the session workflow — it never
+ * runs workflow code, so NOTHING here (or anywhere in src/pi/) is imported into
+ * the V8 workflow sandbox. The determinism boundary is preserved.
+ *
+ * Reuses the existing wire surface verbatim:
+ *   - `claimAttachment` / `heartbeat`        — lease lifecycle (drives `attached`)
+ *   - `processingStart` / `processingEnd`    — drives `processing` / `awaiting`
+ *   - `requestDetach` + `adapterExited`      — drives `draining` → `detached`
+ *   - `submitOutbox`                         — report routing (outbox compliance)
+ *   - `pendingMessages` + `markDelivered`    — cue intake + ack
+ */
+const client_1 = require("@temporalio/client");
+const connection_1 = require("../connection");
+const config_1 = require("../config");
+const signals_1 = require("../workflows/signals");
+/** Adapter identity advertised on claim. Pi interactive players are `interactive`-class. */
+const PI_ADAPTER_ID = 'pi';
+/**
+ * MD-A liveness timings (Phase 2, maintainer-approved): 30s heartbeat / 90s
+ * lease, holding the **lease = 3×heartbeat** invariant — a single (or even
+ * second) missed beat never expires the lease, but a dead process is reaped
+ * within ~one lease window. Parity with the other SDK adapters' `heartbeatMs`.
+ * Overridable per-session via `PiWorkflowClientOptions.{leaseMs,heartbeatMs}`.
+ * Exported so a guard test can assert the invariant doesn't silently drift.
+ */
+exports.PI_HEARTBEAT_MS = 30_000;
+exports.PI_LEASE_MS = 90_000;
+const log = (...args) => {
+    // eslint-disable-next-line no-console
+    console.error('[agent-tempo:pi]', ...args);
+};
+/**
+ * One instance per attached Pi session — holds the session `WorkflowHandle`,
+ * lease token, and heartbeat timer for one fixed-workflowId player. Tool
+ * handlers reach this player's handle via the D11 lazy proxy (`get handle()`).
+ */
+class PiWorkflowClient {
+    client;
+    config;
+    metadata;
+    leaseMs;
+    heartbeatMs;
+    expectedAttachmentId;
+    coarseProvider;
+    wfHandle = null;
+    token = null;
+    heartbeatTimer = null;
+    constructor(opts) {
+        this.client = opts.client;
+        this.config = opts.config;
+        this.metadata = opts.metadata;
+        this.leaseMs = opts.leaseMs ?? exports.PI_LEASE_MS;
+        this.heartbeatMs = opts.heartbeatMs ?? exports.PI_HEARTBEAT_MS;
+        this.expectedAttachmentId = opts.expectedAttachmentId;
+        this.coarseProvider = opts.coarseProvider;
+    }
+    /**
+     * 3c — wire the coarse-activity provider after construction (the inner-loop
+     * publisher is created alongside, then handed in). Each heartbeat samples it.
+     */
+    setCoarseProvider(provider) {
+        this.coarseProvider = provider;
+    }
+    /** Build a client from config (connection-pooled; safe to share — see D12a). */
+    static async connect(config = (0, config_1.getConfig)()) {
+        const connection = await (0, connection_1.createTemporalConnection)(config);
+        return new client_1.Client({ connection, namespace: config.temporalNamespace });
+    }
+    get attachmentId() {
+        return this.token?.attachmentId ?? null;
+    }
+    /**
+     * The live session `WorkflowHandle`, or `null` before {@link ensureSessionWorkflow}.
+     * Exposed so the D11 lazy-proxy (src/pi/lazy-proxy.ts) can resolve the player's
+     * OWN handle per tool call — tool handlers route through it (e.g. `submitOutbox`)
+     * and never `.signal()` a peer workflow directly.
+     */
+    get handle() {
+        return this.wfHandle;
+    }
+    get workflowId() {
+        return (0, config_1.sessionWorkflowId)(this.metadata.ensemble, this.metadata.playerId);
+    }
+    /**
+     * Ensure the session workflow exists and grab a handle. For a human-launched
+     * `pi`, the workflow may not exist yet; `USE_EXISTING` makes this idempotent
+     * when `agent-tempo up`/recruit already started it.
+     */
+    async ensureSessionWorkflow() {
+        if (this.wfHandle)
+            return this.wfHandle;
+        this.wfHandle = await this.client.workflow.start('agentSessionWorkflow', {
+            workflowId: this.workflowId,
+            taskQueue: this.config.taskQueue,
+            workflowIdConflictPolicy: 'USE_EXISTING',
+            args: [{ metadata: this.metadata, phase: 'booting' }],
+        });
+        return this.wfHandle;
+    }
+    requireHandle() {
+        if (!this.wfHandle) {
+            throw new Error('PiWorkflowClient: call ensureSessionWorkflow() before lifecycle ops');
+        }
+        return this.wfHandle;
+    }
+    /**
+     * Claim (or, with a handoff token, ADOPT) the attachment: phase
+     * `booting → attached`. Fresh claim when `expectedAttachmentId` is absent;
+     * renewal/adoption branch when the restart tool handed one in. Stores the token.
+     */
+    async claim() {
+        const handle = this.requireHandle();
+        this.token = await handle.executeUpdate(signals_1.claimAttachmentUpdate, {
+            args: [
+                {
+                    host: this.metadata.hostname,
+                    adapterId: PI_ADAPTER_ID,
+                    adapterClass: 'interactive',
+                    leaseMs: this.leaseMs,
+                    ...(this.expectedAttachmentId ? { expectedAttachmentId: this.expectedAttachmentId } : {}),
+                },
+            ],
+        });
+        log(`${this.expectedAttachmentId ? 'renewed' : 'claimed'} attachment ` +
+            `${this.token.attachmentId} (lease ${this.leaseMs}ms)`);
+        return this.token;
+    }
+    /**
+     * Liveness heartbeat — renews the lease. This is the ENTIRE reason an abrupt
+     * Pi death is detectable: stop heart-beating and `expiresAt` lapses (see
+     * src/pi/README.md "Abrupt-death finding" / MD-A).
+     */
+    async heartbeat() {
+        if (!this.token)
+            return;
+        const handle = this.requireHandle();
+        // 3c Tier-1 — piggyback the latest coarse sample (currentTool + context).
+        // Sampled per-beat; a throwing/absent provider degrades to a plain heartbeat.
+        let coarse;
+        try {
+            coarse = this.coarseProvider?.();
+        }
+        catch {
+            coarse = undefined;
+        }
+        await handle.signal(signals_1.heartbeatSignal, {
+            attachmentId: this.token.attachmentId,
+            at: new Date().toISOString(),
+            ...(coarse ? coarse : {}),
+        });
+    }
+    /** Start the heartbeat loop. The timer is `unref`'d so it never holds the process open. */
+    startHeartbeat() {
+        if (this.heartbeatTimer)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            this.heartbeat().catch((err) => log('heartbeat failed:', err));
+        }, this.heartbeatMs);
+        if (typeof this.heartbeatTimer.unref === 'function')
+            this.heartbeatTimer.unref();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    /** agent_start → phase `processing`. */
+    async processingStart(messageId) {
+        const handle = this.requireHandle();
+        await handle.executeUpdate(signals_1.processingStartUpdate, {
+            args: [{ messageId, expectedAttachmentId: this.token?.attachmentId }],
+        });
+    }
+    /** agent_end → phase `awaiting`. */
+    async processingEnd(messageId) {
+        const handle = this.requireHandle();
+        await handle.executeUpdate(signals_1.processingEndUpdate, {
+            args: [{ messageId, expectedAttachmentId: this.token?.attachmentId }],
+        });
+    }
+    /**
+     * Graceful self-initiated detach: stopHeartbeat → adapterExited (→ detached).
+     *
+     * `adapterExited` ALONE collapses any live phase (attached/processing/awaiting/
+     * draining) straight to `detached` — see the workflow handler at
+     * `session.ts` adapterExitedSignal (returns early only on detached/gone). No
+     * `requestDetach` is needed for a self-exit; that signal is the EXTERNAL ask to
+     * drain a running adapter someone else controls. This matches the proven
+     * `BaseAttachment.stopV2Lifecycle(graceful)` path. Idempotent-safe to call on
+     * `session_shutdown` and from the headless exit sequence.
+     */
+    async detach(reason = 'agent-exited') {
+        if (!this.wfHandle || !this.token)
+            return;
+        this.stopHeartbeat();
+        // Signal-DELIVERY (not a processing-ack) is sufficient by design, ruled won't-fix:
+        // the session workflow runs in the DAEMON worker, not this Pi process, so once
+        // signal() resolves the exit is durably in history and the worker transitions to
+        // `detached` regardless of this process disposing/exiting. stopHeartbeat() above is
+        // the independent backstop — a missed transition still reaps via lease expiry. No
+        // caller reads phase synchronously at detach()-return, so an executeUpdate ack would
+        // only add shutdown latency + drag determinism-sensitive workflow code into scope.
+        // If a future synchronous re-claim/migrate ever needs an OBSERVED `detached`, poll the
+        // existing attachmentInfoQuery client-side — never add an adapterExitedUpdate.
+        await this.wfHandle.signal(signals_1.adapterExitedSignal, {
+            attachmentId: this.token.attachmentId,
+            reason,
+        });
+        log(`detached (${reason})`);
+    }
+    /**
+     * Stash the currently-active Pi SessionManager session id onto durable
+     * workflow metadata (`metadata.sessionId`). This is the MUTABLE resume pointer
+     * — SEPARATE from the fixed workflowId (identity). A later restart of this
+     * player reads it to resume the same conversation via Pi `continueSession`
+     * (reuses the #334 sessionId resume field). No-op when the id is absent.
+     */
+    async updateSessionId(sessionId) {
+        if (!sessionId)
+            return;
+        const handle = this.requireHandle();
+        await handle.signal(signals_1.updateMetadataSignal, { sessionId });
+    }
+    // ── Outbox ──
+    /** Route an outbox entry through the workflow outbox (player's own handle). */
+    async submitOutbox(entry) {
+        const handle = this.requireHandle();
+        return handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+    }
+    // ── Cue intake ──
+    /** Pull undelivered messages (cues) queued on the workflow. */
+    async fetchPending() {
+        const handle = this.requireHandle();
+        return handle.query(signals_1.pendingMessagesQuery);
+    }
+    /** Acknowledge delivered cue ids so the workflow stops re-serving them. */
+    async ackDelivered(messageIds) {
+        if (messageIds.length === 0)
+            return;
+        const handle = this.requireHandle();
+        await handle.signal(signals_1.markDeliveredSignal, messageIds);
+    }
+    // ── Reset intake (3d D14) ──
+    /** Poll the workflow's single-slot pending reset (null = none). */
+    async fetchPendingReset() {
+        const handle = this.requireHandle();
+        return handle.query(signals_1.pendingResetQuery);
+    }
+    /**
+     * Ack a performed reset by id — the workflow clears the slot ONLY if the id
+     * still matches (race-safe: a newer reset that landed mid-wipe is preserved).
+     */
+    async ackReset(resetId) {
+        const handle = this.requireHandle();
+        await handle.signal(signals_1.ackResetSignal, resetId);
+    }
+    /**
+     * Dispatch a {@link WorkflowAction} produced by {@link PhaseDriver}. Centralizes
+     * the action→wire-call mapping so the extension wiring stays declarative.
+     */
+    async performAction(action) {
+        switch (action.kind) {
+            case 'claim':
+                await this.claim();
+                this.startHeartbeat();
+                return;
+            case 'processingStart':
+                await this.processingStart(action.messageId);
+                return;
+            case 'processingEnd':
+                await this.processingEnd(action.messageId);
+                return;
+            case 'detach':
+                await this.detach();
+                return;
+            case 'none':
+                return;
+        }
+    }
+}
+exports.PiWorkflowClient = PiWorkflowClient;