agent-tempo 1.0.1

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

@@ -0,0 +1,78 @@
+/**
+ * Shared recall formatter (#128).
+ *
+ * Single source of truth for how the MCP `recall` tool, TUI `/recall` slash
+ * command, and CLI `agent-tempo recall` present a timeline. Pure — no
+ * Temporal, no stdout, no I/O — so each surface can unit-test its rendering
+ * with canned data.
+ *
+ * Execution order (established by the #128 design):
+ *   query → filter (`since`, `from`) → sort desc by timestamp → compute
+ *   total → slice [offset, offset+limit) → conditionally truncate bodies
+ *   by `previewLength` → emit pagination header.
+ *
+ * `previewLength` is unset by default (no sane ceiling). Callers opt in to
+ * truncation; the prior hardcoded 200-char cap at the MCP tool is retired
+ * from the recall path (the shared constant stays elsewhere).
+ */
+import type { Message, SentMessage } from '../types';
+export interface TimelineEntry {
+    direction: 'received' | 'sent';
+    /** Sender player name for received entries; undefined for sent. */
+    from?: string;
+    /** Recipient player name for sent entries; undefined for received. */
+    to?: string;
+    text: string;
+    /** ISO timestamp. */
+    timestamp: string;
+    /** Only set on received entries. */
+    delivered?: boolean;
+}
+export interface RecallFormatOpts {
+    /** Max entries per page. Defaults to 20; schema enforces 1-100 upstream. */
+    limit?: number;
+    /** Skip N entries for paging. Defaults to 0. */
+    offset?: number;
+    /**
+     * Truncate each entry body to this many characters + `…`. Omitted =
+     * unlimited (full body). Schema upstream enforces `min(1)`.
+     */
+    previewLength?: number;
+    /** ISO timestamp — only entries at or after this are included. */
+    since?: string;
+    /** Sender filter — only applied to received entries. */
+    from?: string;
+}
+/**
+ * Build the flat, unfiltered, unsorted timeline from a session's raw query
+ * results. Mirrors the shape the MCP tool used inline before #128.
+ *
+ * `includeSent === false` drops the sent-messages lane entirely rather than
+ * tagging them `direction: 'sent'`, matching the existing MCP semantics.
+ */
+export declare function buildTimeline(received: Message[], sent: SentMessage[], includeSent: boolean): TimelineEntry[];
+export interface RecallRenderResult {
+    /** Final rendered lines (header + entries, joined with blank lines between entries). */
+    text: string;
+    /** Post-filter total (before offset/limit). Useful for callers needing raw counts. */
+    total: number;
+    /** Number of entries actually rendered (≤ limit). */
+    shown: number;
+    /** `true` iff pagination would continue past `offset + limit`. */
+    hasMore: boolean;
+}
+/**
+ * Filter → sort → slice → render pipeline per the #128 design. Returns a
+ * single formatted string (plus counts for callers that want to branch on
+ * pagination state without re-scanning the rendered text).
+ *
+ * Header convention (matches `gh pr list` / `gh issue list`):
+ *   `Showing X-Y of Z messages.`
+ * Append `Use offset: N for next page.` only when total > offset + limit.
+ *
+ * Edge cases:
+ *   - empty (post-filter) → `No messages found matching the filter.`
+ *   - offset ≥ total (non-empty) → `No messages at offset N. Total: Z. Use offset: 0 to start over.`
+ *   - `previewLength > text.length` → full body, no ellipsis
+ */
+export declare function formatRecall(timeline: TimelineEntry[], opts?: RecallFormatOpts): RecallRenderResult;

package/dist/utils/recall-format.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTimeline = buildTimeline;
+exports.formatRecall = formatRecall;
+/**
+ * Build the flat, unfiltered, unsorted timeline from a session's raw query
+ * results. Mirrors the shape the MCP tool used inline before #128.
+ *
+ * `includeSent === false` drops the sent-messages lane entirely rather than
+ * tagging them `direction: 'sent'`, matching the existing MCP semantics.
+ */
+function buildTimeline(received, sent, includeSent) {
+    const timeline = received.map((m) => ({
+        direction: 'received',
+        from: m.from,
+        text: m.text,
+        timestamp: m.timestamp,
+        delivered: m.delivered,
+    }));
+    if (includeSent) {
+        for (const s of sent) {
+            timeline.push({
+                direction: 'sent',
+                to: s.to,
+                text: s.text,
+                timestamp: s.timestamp,
+            });
+        }
+    }
+    return timeline;
+}
+/**
+ * Filter → sort → slice → render pipeline per the #128 design. Returns a
+ * single formatted string (plus counts for callers that want to branch on
+ * pagination state without re-scanning the rendered text).
+ *
+ * Header convention (matches `gh pr list` / `gh issue list`):
+ *   `Showing X-Y of Z messages.`
+ * Append `Use offset: N for next page.` only when total > offset + limit.
+ *
+ * Edge cases:
+ *   - empty (post-filter) → `No messages found matching the filter.`
+ *   - offset ≥ total (non-empty) → `No messages at offset N. Total: Z. Use offset: 0 to start over.`
+ *   - `previewLength > text.length` → full body, no ellipsis
+ */
+function formatRecall(timeline, opts = {}) {
+    const limit = opts.limit ?? 20;
+    const offset = opts.offset ?? 0;
+    // ── 1. Filter ──
+    let filtered = timeline;
+    if (opts.since !== undefined) {
+        const sinceTs = Date.parse(opts.since);
+        if (!Number.isNaN(sinceTs)) {
+            filtered = filtered.filter((e) => Date.parse(e.timestamp) >= sinceTs);
+        }
+    }
+    if (opts.from) {
+        filtered = filtered.filter((e) => (e.direction === 'received' ? e.from === opts.from : true));
+    }
+    // ── 2. Sort desc by timestamp ──
+    filtered = [...filtered].sort((a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp));
+    // ── 3. Compute total (post-filter) ──
+    const total = filtered.length;
+    // ── Early-return paths ──
+    if (total === 0) {
+        return {
+            text: 'No messages found matching the filter.',
+            total: 0,
+            shown: 0,
+            hasMore: false,
+        };
+    }
+    if (offset >= total) {
+        return {
+            text: `No messages at offset ${offset}. Total: ${total}. Use offset: 0 to start over.`,
+            total,
+            shown: 0,
+            hasMore: false,
+        };
+    }
+    // ── 4. Slice [offset, offset+limit) ──
+    const page = filtered.slice(offset, offset + limit);
+    // ── 5. Render ──
+    const renderedEntries = page.map((e) => renderEntry(e, opts.previewLength));
+    const startIdx = offset + 1;
+    const endIdx = offset + page.length;
+    const hasMore = total > offset + limit;
+    const headerLines = [`Showing ${startIdx}-${endIdx} of ${total} messages.`];
+    if (hasMore)
+        headerLines.push(`Use offset: ${offset + limit} for next page.`);
+    return {
+        text: [headerLines.join(' '), '', ...renderedEntries].join('\n'),
+        total,
+        shown: page.length,
+        hasMore,
+    };
+}
+function renderEntry(e, previewLength) {
+    const dir = e.direction === 'sent' ? `→ ${e.to}` : `← ${e.from}`;
+    const status = e.direction === 'received' && e.delivered === false ? ' (undelivered)' : '';
+    const body = previewLength !== undefined && e.text.length > previewLength
+        ? `${e.text.slice(0, previewLength)}…`
+        : e.text;
+    return `[${e.timestamp}] ${dir}${status}\n  ${body}`;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Shared formatter for the #151 `restore --all-hosts` cluster-view listing.
+ *
+ * Pure: no Temporal, no I/O, no ANSI colors. Mirrors the
+ * `format-hosts.ts` convention so unit tests can pin the rendering
+ * without spinning up a Temporal client. Consumed by:
+ *   - `src/cli/commands.ts` (`restore` verb's `--all-hosts` branch)
+ *
+ * Liveness annotation semantics (joined against `listHosts()`):
+ *
+ *   [live]    — host's daemon is polling now
+ *               (`HOST_FRESHNESS_THRESHOLD_MS`, 60s default). Recovery is
+ *               imminent on its next reconcile tick — no manual action
+ *               needed in most cases.
+ *   [stale]   — host has been registered but no poller seen in the last
+ *               minute. Probably down; manual `/migrate` from the TUI if
+ *               recovery can't wait.
+ *   [missing] — host has no registered profile at all (never came back
+ *               since boot, or maestro restarted and the profile expired).
+ *               Almost certainly safe to deliberately steal.
+ *
+ * Action edge — for cross-host orphans (NOT for `(local)` ones), the
+ * formatter prints the TUI `/migrate` command the operator would run to
+ * deliberately steal the session to the local host. The architect's
+ * §16.5-Option-B `--yes-steal=<host>` deliberate-action gate isn't on
+ * the TUI slash-command yet (separate follow-up); we print the available
+ * surface that actually parses today.
+ */
+import type { HostInfo } from '../types';
+import type { RestoreOrphanDetail } from '../reconcile/orphans';
+export interface FormatCrossHostOrphansOpts {
+    /** Operator's local hostname — sorted first, gets the `(local)` tag. */
+    localHost: string;
+    /**
+     * When set, the operator passed `--ensemble <name>` (narrowing the
+     * cluster-view listing). Otherwise the formatter says "every ensemble".
+     */
+    ensemble?: string;
+}
+/**
+ * Render the `--all-hosts` listing.
+ *
+ * Pre-condition: `details` are produced by
+ * `restoreOrphansOnce(..., { mode: 'all-hosts-readonly' })`. Entries not
+ * shaped as `{ kind: 'skipped', reason: 'crossHost' }` are silently
+ * filtered out — defensive: the formatter is a final renderer, not a
+ * data-shape gatekeeper.
+ */
+export declare function formatCrossHostOrphans(details: RestoreOrphanDetail[], hosts: HostInfo[], opts: FormatCrossHostOrphansOpts): string;

package/dist/utils/restore-format.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCrossHostOrphans = formatCrossHostOrphans;
+/**
+ * Render the `--all-hosts` listing.
+ *
+ * Pre-condition: `details` are produced by
+ * `restoreOrphansOnce(..., { mode: 'all-hosts-readonly' })`. Entries not
+ * shaped as `{ kind: 'skipped', reason: 'crossHost' }` are silently
+ * filtered out — defensive: the formatter is a final renderer, not a
+ * data-shape gatekeeper.
+ */
+function formatCrossHostOrphans(details, hosts, opts) {
+    const { localHost, ensemble } = opts;
+    const scope = ensemble
+        ? `ensemble "${ensemble}" across all hosts`
+        : 'every ensemble across all hosts';
+    // Group orphans by preferredHost (the `detail` field on each crossHost
+    // skip — set by `restoreOrphansOnce` to `preferredHost ??
+    // lastAdapter.hostname ?? '(unknown)'`).
+    const groups = new Map();
+    for (const d of details) {
+        if (d.outcome.kind !== 'skipped' || d.outcome.reason !== 'crossHost')
+            continue;
+        const key = d.outcome.detail ?? '(unknown)';
+        const bucket = groups.get(key) ?? [];
+        bucket.push(d);
+        groups.set(key, bucket);
+    }
+    const totalOrphans = Array.from(groups.values()).reduce((n, g) => n + g.length, 0);
+    if (totalOrphans === 0) {
+        return `No orphans found (${scope}).`;
+    }
+    // Stable order: local-host first (its own dormant orphans are the most
+    // actionable for the operator), then alphabetical, `(unknown)` last.
+    const groupOrder = Array.from(groups.keys()).sort((a, b) => {
+        if (a === localHost)
+            return -1;
+        if (b === localHost)
+            return 1;
+        if (a === '(unknown)')
+            return 1;
+        if (b === '(unknown)')
+            return -1;
+        return a.localeCompare(b);
+    });
+    // Build the host lookup once for the liveness join.
+    const hostByName = new Map();
+    for (const h of hosts)
+        hostByName.set(h.hostname, h);
+    const liveness = (preferredHost) => {
+        if (preferredHost === '(unknown)')
+            return 'missing';
+        const h = hostByName.get(preferredHost);
+        if (!h)
+            return 'missing';
+        return h.freshness === 'live' ? 'live' : 'stale';
+    };
+    const lines = [];
+    lines.push(`${totalOrphans} cross-host orphan${totalOrphans === 1 ? '' : 's'} found (${scope}).`);
+    lines.push('');
+    lines.push('These sessions are reattached automatically when their preferred host returns.');
+    lines.push("Below are the manual-takeover commands if a host won't come back.");
+    lines.push('');
+    for (const host of groupOrder) {
+        const orphans = groups.get(host);
+        const label = liveness(host);
+        const isLocal = host === localHost;
+        const hostHeading = isLocal
+            ? `**${host}** [${label}] (local)`
+            : `**${host}** [${label}]`;
+        lines.push(hostHeading);
+        for (const d of orphans) {
+            lines.push(`  - ${d.playerId}   (ensemble: ${d.ensemble})`);
+            if (!isLocal && host !== '(unknown)') {
+                // Action edge — TUI slash-command form. Architect confirmed (#151
+                // dispatch thread) that `--yes-steal=<host>` deliberate-action is
+                // a separate follow-up since the CLI `migrate` verb was removed
+                // in #288 and the TUI `/migrate` doesn't accept the flag yet.
+                lines.push(`      In TUI: /migrate ${d.playerId} ${localHost} --force`);
+            }
+            else if (isLocal) {
+                lines.push(`      Use \`agent-tempo restore ${d.ensemble}\` (single-ensemble) to reattach.`);
+            }
+        }
+        lines.push('');
+    }
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines.join('\n');
+}

package/dist/utils/safe-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Assert that a resolved file path falls within one of the allowed root directories.
+ * Throws if the path escapes all allowed roots (path traversal attempt).
+ */
+export declare function assertSafePath(filePath: string, allowedRoots: string[]): void;
+/**
+ * Validate and resolve a lineup file path, ensuring it stays within allowed directories.
+ * Allowed roots: ~/.agent-tempo/ensembles/, cwd, and optionally a project dir.
+ */
+export declare function safeLineupPath(filePath: string, cwd: string, projectDir?: string): string;

package/dist/utils/safe-path.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafePath = assertSafePath;
+exports.safeLineupPath = safeLineupPath;
+const path_1 = require("path");
+/**
+ * Assert that a resolved file path falls within one of the allowed root directories.
+ * Throws if the path escapes all allowed roots (path traversal attempt).
+ */
+function assertSafePath(filePath, allowedRoots) {
+    const resolved = (0, path_1.normalize)((0, path_1.resolve)(filePath));
+    const isAllowed = allowedRoots.some((root) => {
+        const normalizedRoot = (0, path_1.normalize)((0, path_1.resolve)(root));
+        // Ensure the path starts with root + separator (or is exactly the root)
+        return resolved === normalizedRoot || resolved.startsWith(normalizedRoot + getSep(normalizedRoot));
+    });
+    if (!isAllowed) {
+        throw new Error(`Path traversal blocked: "${filePath}" resolves to "${resolved}" which is outside allowed roots: ${allowedRoots.join(', ')}`);
+    }
+}
+/**
+ * Validate and resolve a lineup file path, ensuring it stays within allowed directories.
+ * Allowed roots: ~/.agent-tempo/ensembles/, cwd, and optionally a project dir.
+ */
+function safeLineupPath(filePath, cwd, projectDir) {
+    const { join } = require('path');
+    const { homedir } = require('os');
+    const allowedRoots = [
+        join(homedir(), '.agent-tempo', 'ensembles'),
+        cwd,
+    ];
+    if (projectDir && projectDir !== cwd) {
+        allowedRoots.push(projectDir);
+    }
+    const resolved = (0, path_1.normalize)((0, path_1.resolve)(filePath));
+    assertSafePath(resolved, allowedRoots);
+    return resolved;
+}
+/** Get the path separator used in a given path string. */
+function getSep(p) {
+    // Use backslash if path contains backslashes (Windows), forward slash otherwise
+    return p.includes('\\') ? '\\' : '/';
+}

package/dist/utils/sdk-probe.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @param pkgName Bare specifier (e.g. `'@opencode-ai/sdk'`).
+ * @param fromDir Where to start the walk. Defaults to the caller's
+ *   `__dirname`-equivalent — pass an explicit value if you need to anchor
+ *   the search elsewhere.
+ * @returns `true` if `<dir>/node_modules/<pkgName>/package.json` exists
+ *   anywhere on the walk up the filesystem.
+ */
+export declare function probeSdkInstall(pkgName: string, fromDir?: string): boolean;

package/dist/utils/sdk-probe.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeSdkInstall = probeSdkInstall;
+/**
+ * Filesystem-walk probe for an installed npm package.
+ *
+ * Walks `node_modules` directories upward from `__dirname` looking for a
+ * package's `package.json`. Returns whether the package is installed.
+ *
+ * **Why not `require.resolve(pkgName)` or `require.resolve(pkgName + '/package.json')`?**
+ * Some packages publish with strict ESM `exports` maps that have no
+ * `"require"` key and no `"./package.json"` sub-path entry — e.g.
+ * `@opencode-ai/sdk`. CJS-side resolution then trips
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED` even when the package is correctly
+ * installed. The filesystem walk bypasses Node's exports-map gate
+ * cleanly. The Copilot SDK works with `require('<pkg>/package.json')`
+ * (`src/daemon-adapter-versions.ts:175`) because it doesn't have that
+ * restriction; this helper is for packages that do.
+ *
+ * Used by:
+ *   - `src/adapters/opencode/adapter.ts` — module-load optional-dep gate
+ *   - `src/tools/recruit.ts` — recruit pre-flight check
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * @param pkgName Bare specifier (e.g. `'@opencode-ai/sdk'`).
+ * @param fromDir Where to start the walk. Defaults to the caller's
+ *   `__dirname`-equivalent — pass an explicit value if you need to anchor
+ *   the search elsewhere.
+ * @returns `true` if `<dir>/node_modules/<pkgName>/package.json` exists
+ *   anywhere on the walk up the filesystem.
+ */
+function probeSdkInstall(pkgName, fromDir = __dirname) {
+    let dir = fromDir;
+    while (true) {
+        const candidate = (0, path_1.join)(dir, 'node_modules', pkgName, 'package.json');
+        if ((0, fs_1.existsSync)(candidate))
+            return true;
+        const parent = (0, path_1.dirname)(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}

package/dist/utils/search-attributes.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Reusable helpers for extracting Temporal search attributes from
+ * `WorkflowExecutionInfo` (from `client.workflow.list()` iteration) and
+ * `WorkflowExecutionDescription` (from `handle.describe()`).
+ *
+ * Extracted per issue #203 to eliminate the inline
+ * `arr = wf.searchAttributes?.<Attr>; first = Array.isArray(arr) ? arr[0] : undefined`
+ * pattern previously duplicated across 9 call sites.
+ *
+ * Kept free of `@temporalio/client` imports — the `SearchAttributeCarrier`
+ * type is structural. That keeps this util reusable from tests and future
+ * call sites without dragging the Temporal client dependency in.
+ */
+import { AttachmentPhase } from '../types';
+/**
+ * Structural shape of objects carrying Temporal search attributes.
+ *
+ * Matches both `WorkflowExecutionInfo` and `WorkflowExecutionDescription`
+ * without depending on Temporal SDK types. The underlying JSON shape is a
+ * `Record<string, ReadonlyArray<unknown> | undefined>` — the SDK preserves
+ * the list shape even for single-value attributes like ensemble name or
+ * phase, and exposes it with `readonly` arrays (so this type uses
+ * `ReadonlyArray` to stay assignable from the Temporal SDK's
+ * `SearchAttributes` type).
+ */
+export interface SearchAttributeCarrier {
+    searchAttributes?: Record<string, ReadonlyArray<unknown> | undefined>;
+}
+/**
+ * Read the first element of a search-attribute array as a string.
+ *
+ * Returns `undefined` when any of these holds:
+ * - The carrier has no `searchAttributes` object.
+ * - The named attribute is absent.
+ * - The attribute value is not an array.
+ * - The array is empty.
+ *
+ * Non-string values are coerced via `String(v)` — matches the legacy
+ * inline pattern (`String(vals[0])`) at the migrated call sites.
+ */
+export declare function getSearchAttrString(carrier: SearchAttributeCarrier, name: string): string | undefined;
+/**
+ * Read the first element of a search-attribute array as a boolean.
+ *
+ * Returns `undefined` when the attribute is missing or non-boolean-shaped.
+ * Tolerates string representations (`"true"` / `"false"`) that some
+ * Temporal client versions have been known to surface instead of native
+ * booleans — same forgiveness policy as the legacy inline pattern.
+ */
+export declare function getSearchAttrBool(carrier: SearchAttributeCarrier, name: string): boolean | undefined;
+/**
+ * Read the attachment phase from `AgentTempoAttachmentState`.
+ *
+ * Post-#175 this is the canonical lifecycle state (replaced the v0.25
+ * `AgentTempoStatus` heuristic). Returns `undefined` when the attribute is
+ * missing — typically during the brief post-start window before the
+ * workflow has written its first phase transition, or for workflows that
+ * predate the attachment-lifecycle rework.
+ */
+export declare function getAttachmentPhase(carrier: SearchAttributeCarrier): AttachmentPhase | undefined;
+/**
+ * Read the ensemble name from `AgentTempoEnsemble`.
+ *
+ * Returns `undefined` when the attribute is absent — callers typically
+ * treat that as "skip this session" since every session workflow should
+ * set the attribute on start.
+ */
+export declare function getEnsembleName(carrier: SearchAttributeCarrier): string | undefined;
+/**
+ * Read the conductor flag from `AgentTempoIsConductor`.
+ *
+ * Returns `undefined` when absent (e.g. transiently un-indexed after a
+ * conductor spawn). Callers wanting the pre-#178 workflow-id-suffix
+ * fallback (`endsWith('-conductor')`) should apply it on `undefined`.
+ */
+export declare function getIsConductor(carrier: SearchAttributeCarrier): boolean | undefined;

package/dist/utils/search-attributes.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSearchAttrString = getSearchAttrString;
+exports.getSearchAttrBool = getSearchAttrBool;
+exports.getAttachmentPhase = getAttachmentPhase;
+exports.getEnsembleName = getEnsembleName;
+exports.getIsConductor = getIsConductor;
+/**
+ * Read the first element of a search-attribute array as a string.
+ *
+ * Returns `undefined` when any of these holds:
+ * - The carrier has no `searchAttributes` object.
+ * - The named attribute is absent.
+ * - The attribute value is not an array.
+ * - The array is empty.
+ *
+ * Non-string values are coerced via `String(v)` — matches the legacy
+ * inline pattern (`String(vals[0])`) at the migrated call sites.
+ */
+function getSearchAttrString(carrier, name) {
+    const arr = carrier.searchAttributes?.[name];
+    if (!Array.isArray(arr) || arr.length === 0)
+        return undefined;
+    const v = arr[0];
+    return typeof v === 'string' ? v : String(v);
+}
+/**
+ * Read the first element of a search-attribute array as a boolean.
+ *
+ * Returns `undefined` when the attribute is missing or non-boolean-shaped.
+ * Tolerates string representations (`"true"` / `"false"`) that some
+ * Temporal client versions have been known to surface instead of native
+ * booleans — same forgiveness policy as the legacy inline pattern.
+ */
+function getSearchAttrBool(carrier, name) {
+    const arr = carrier.searchAttributes?.[name];
+    if (!Array.isArray(arr) || arr.length === 0)
+        return undefined;
+    const v = arr[0];
+    if (typeof v === 'boolean')
+        return v;
+    if (typeof v === 'string') {
+        if (v === 'true')
+            return true;
+        if (v === 'false')
+            return false;
+    }
+    return undefined;
+}
+// ── Typed wrappers for agent-tempo's custom search attributes ──
+//
+// Keeping one wrapper per attribute gives callers a readable, typed API
+// without re-stating the attribute name at every site. Adding a fourth
+// attribute (e.g. `AgentTempoHost`) later follows the same pattern.
+/**
+ * Read the attachment phase from `AgentTempoAttachmentState`.
+ *
+ * Post-#175 this is the canonical lifecycle state (replaced the v0.25
+ * `AgentTempoStatus` heuristic). Returns `undefined` when the attribute is
+ * missing — typically during the brief post-start window before the
+ * workflow has written its first phase transition, or for workflows that
+ * predate the attachment-lifecycle rework.
+ */
+function getAttachmentPhase(carrier) {
+    return getSearchAttrString(carrier, 'AgentTempoAttachmentState');
+}
+/**
+ * Read the ensemble name from `AgentTempoEnsemble`.
+ *
+ * Returns `undefined` when the attribute is absent — callers typically
+ * treat that as "skip this session" since every session workflow should
+ * set the attribute on start.
+ */
+function getEnsembleName(carrier) {
+    return getSearchAttrString(carrier, 'AgentTempoEnsemble');
+}
+/**
+ * Read the conductor flag from `AgentTempoIsConductor`.
+ *
+ * Returns `undefined` when absent (e.g. transiently un-indexed after a
+ * conductor spawn). Callers wanting the pre-#178 workflow-id-suffix
+ * fallback (`endsWith('-conductor')`) should apply it on `undefined`.
+ */
+function getIsConductor(carrier) {
+    return getSearchAttrBool(carrier, 'AgentTempoIsConductor');
+}