agent-tempo 1.0.1

package/dist/utils/worktree.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Compute the base directory for all worktrees in an ensemble.
+ * Convention: `{gitRoot}/../.ct-worktrees/{ensemble}/`
+ */
+export declare function worktreeBasePath(gitRoot: string, ensemble: string): string;
+export interface CreateWorktreeOpts {
+    gitRoot: string;
+    ensemble: string;
+    playerName: string;
+    branch?: string;
+}
+/**
+ * Tag returned by {@link switchWorktreeToBranch} and surfaced on
+ * {@link CreateWorktreeResult.switched} so the MCP tool's response text can
+ * report the actual state transition instead of silently reusing the request
+ * as ground truth (#261). Values:
+ *
+ * - `same` — the worktree was already on the requested branch. No-op.
+ * - `switched` — the requested branch existed locally; plain `git checkout`.
+ * - `created-from-main` — the requested branch did not exist locally;
+ *   created it off `origin/main` via `git checkout -b`.
+ */
+export type WorktreeSwitchResult = 'same' | 'switched' | 'created-from-main';
+export interface CreateWorktreeResult {
+    /** Absolute path to the worktree directory. */
+    path: string;
+    /** Branch name used for the worktree. */
+    branch: string;
+    /** Whether the worktree was newly created (false if it already existed). */
+    created: boolean;
+    /**
+     * When `created === false` (reuse path), which git operation the helper ran
+     * to bring the worktree onto the requested branch. `undefined` on fresh
+     * creation — the #261 information is only meaningful for reuse.
+     */
+    switched?: WorktreeSwitchResult;
+}
+/**
+ * Ensure the worktree at `wtPath` is checked out on `targetBranch`.
+ *
+ * Fix for #261: the prior reuse path returned the *requested* branch name in
+ * its result without ever consulting the worktree's actual HEAD, silently
+ * papering over mismatches when a worktree from a prior task was recycled for
+ * a new branch. This helper does the repointing that was missing — and
+ * refuses (rather than silently discarding) if the target worktree has
+ * uncommitted work on a different branch.
+ *
+ * Decision tree (mirrors the conductor's guidance on #261):
+ *   1. current branch === targetBranch        → no-op, return `'same'`. The
+ *      hot path. Deliberately does NOT run `status --porcelain`: if we're
+ *      not flipping the branch, dirty work is fine.
+ *   2. `git status --porcelain` non-empty     → throw `"uncommitted changes"`
+ *      with path + current branch. Must precede any checkout so we never
+ *      silently discard work on a branch flip.
+ *   3. target branch exists locally           → `git checkout <target>`.
+ *      Preserves the branch's recorded state; no `-B`, no force-reset.
+ *   4. target branch does not exist locally   → `git checkout -b <target> origin/main`.
+ *      Matches the semantics of the fresh-worktree `git worktree add -B`
+ *      path — new branch rooted at the current main tip.
+ *
+ * Caller is expected to have already verified `wtPath` is an existing git
+ * worktree (this helper runs the git commands with `-C <wtPath>` and does no
+ * path-existence checks of its own).
+ */
+export declare function switchWorktreeToBranch(wtPath: string, targetBranch: string): WorktreeSwitchResult;
+/**
+ * Create a git worktree for a player. If the worktree already exists
+ * at the expected path, returns it after repointing to the requested branch
+ * via {@link switchWorktreeToBranch} — the fix for #261, which previously
+ * reused the directory without ever consulting its actual HEAD.
+ *
+ * Branch defaults to `{ensemble}/{playerName}` if not specified.
+ */
+export declare function createWorktree(opts: CreateWorktreeOpts): CreateWorktreeResult;
+/**
+ * Install dependencies in a worktree directory.
+ *
+ * Detects the package manager (npm, yarn, pnpm) by lockfile presence.
+ * Failure or timeout is logged but does not throw — the recruit proceeds
+ * with whatever state the worktree is in.
+ */
+export declare function installDependencies(worktreePath: string, timeoutMs?: number): void;
+/**
+ * Remove a git worktree.
+ *
+ * Throws if the worktree directory survives the removal (#594). On Windows,
+ * `git worktree remove --force` deletes `.git/worktrees/<name>` metadata
+ * *first*, then `rmdir`s the directory — so when a native `.node` module
+ * inside the worktree is memory-mapped by a live process, the directory
+ * deletion fails while the metadata is already gone. The pre-#594 code
+ * swallowed that failure (log-only, no throw), so the caller reported
+ * success and Temporal state diverged from disk. Now the post-removal
+ * `existsSync` check turns a half-removal into a hard error the caller can
+ * surface.
+ *
+ * `gitRoot` scopes the `git worktree remove` invocation to the owning
+ * repository. Pre-#594 the command ran with no `cwd`, so it only worked when
+ * `process.cwd()` happened to be the right repo — fragile, and wrong outright
+ * when the conductor's cwd is a different checkout than the worktree's repo.
+ * Callers should pass `entry.gitRoot` from the `WorktreeEntry`; it defaults to
+ * `process.cwd()` for backward compatibility.
+ */
+export declare function removeWorktree(worktreePath: string, gitRoot?: string): void;

package/dist/utils/worktree.js

@@ -0,0 +1,327 @@
+"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.worktreeBasePath = worktreeBasePath;
+exports.switchWorktreeToBranch = switchWorktreeToBranch;
+exports.createWorktree = createWorktree;
+exports.installDependencies = installDependencies;
+exports.removeWorktree = removeWorktree;
+/**
+ * Git worktree helpers for player isolation.
+ *
+ * Creates and manages git worktrees so each player can work on an
+ * isolated copy of the repository without conflicting with others.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const validation_1 = require("./validation");
+const log = (...args) => console.error('[agent-tempo:worktree]', ...args);
+/**
+ * Compute the base directory for all worktrees in an ensemble.
+ * Convention: `{gitRoot}/../.ct-worktrees/{ensemble}/`
+ */
+function worktreeBasePath(gitRoot, ensemble) {
+    return path.join(path.dirname(gitRoot), '.ct-worktrees', ensemble);
+}
+/**
+ * Ensure the worktree at `wtPath` is checked out on `targetBranch`.
+ *
+ * Fix for #261: the prior reuse path returned the *requested* branch name in
+ * its result without ever consulting the worktree's actual HEAD, silently
+ * papering over mismatches when a worktree from a prior task was recycled for
+ * a new branch. This helper does the repointing that was missing — and
+ * refuses (rather than silently discarding) if the target worktree has
+ * uncommitted work on a different branch.
+ *
+ * Decision tree (mirrors the conductor's guidance on #261):
+ *   1. current branch === targetBranch        → no-op, return `'same'`. The
+ *      hot path. Deliberately does NOT run `status --porcelain`: if we're
+ *      not flipping the branch, dirty work is fine.
+ *   2. `git status --porcelain` non-empty     → throw `"uncommitted changes"`
+ *      with path + current branch. Must precede any checkout so we never
+ *      silently discard work on a branch flip.
+ *   3. target branch exists locally           → `git checkout <target>`.
+ *      Preserves the branch's recorded state; no `-B`, no force-reset.
+ *   4. target branch does not exist locally   → `git checkout -b <target> origin/main`.
+ *      Matches the semantics of the fresh-worktree `git worktree add -B`
+ *      path — new branch rooted at the current main tip.
+ *
+ * Caller is expected to have already verified `wtPath` is an existing git
+ * worktree (this helper runs the git commands with `-C <wtPath>` and does no
+ * path-existence checks of its own).
+ */
+function switchWorktreeToBranch(wtPath, targetBranch) {
+    const current = (0, child_process_1.execFileSync)('git', ['-C', wtPath, 'branch', '--show-current'], {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (current === targetBranch) {
+        log(`Worktree at "${wtPath}" already on "${targetBranch}" — no-op`);
+        return 'same';
+    }
+    // Branch mismatch → dirty-tree guard before any checkout. `--porcelain`
+    // emits one line per change with no color/decoration; empty output means
+    // the working tree + index are clean (ignored files don't count).
+    const dirty = (0, child_process_1.execFileSync)('git', ['-C', wtPath, 'status', '--porcelain'], {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (dirty.trim().length > 0) {
+        throw new Error(`Worktree at "${wtPath}" has uncommitted changes on branch "${current}"; ` +
+            `cannot repoint to "${targetBranch}". Commit or discard changes first.`);
+    }
+    // Does the target branch already exist locally? `rev-parse --verify` exits
+    // 0 on hit, non-zero on miss.
+    let branchExistsLocally = false;
+    try {
+        (0, child_process_1.execFileSync)('git', ['-C', wtPath, 'rev-parse', '--verify', `refs/heads/${targetBranch}`], {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        branchExistsLocally = true;
+    }
+    catch {
+        // refs/heads/<target> doesn't exist — fall through to create-from-main.
+    }
+    if (branchExistsLocally) {
+        log(`Worktree at "${wtPath}" switching "${current}" → "${targetBranch}" (existing local branch)`);
+        try {
+            (0, child_process_1.execFileSync)('git', ['-C', wtPath, 'checkout', targetBranch], {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            const msg = err.stderr || err.stdout || err.message || String(err);
+            throw new Error(`Failed to switch "${wtPath}" to "${targetBranch}": ${msg.trim()}`);
+        }
+        return 'switched';
+    }
+    log(`Worktree at "${wtPath}" switching "${current}" → "${targetBranch}" (new local branch from origin/main)`);
+    try {
+        (0, child_process_1.execFileSync)('git', ['-C', wtPath, 'checkout', '-b', targetBranch, 'origin/main'], {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const msg = err.stderr || err.stdout || err.message || String(err);
+        throw new Error(`Failed to create "${targetBranch}" from origin/main in "${wtPath}": ${msg.trim()}`);
+    }
+    return 'created-from-main';
+}
+/**
+ * Create a git worktree for a player. If the worktree already exists
+ * at the expected path, returns it after repointing to the requested branch
+ * via {@link switchWorktreeToBranch} — the fix for #261, which previously
+ * reused the directory without ever consulting its actual HEAD.
+ *
+ * Branch defaults to `{ensemble}/{playerName}` if not specified.
+ */
+function createWorktree(opts) {
+    const { gitRoot, ensemble, playerName } = opts;
+    const branch = opts.branch || `${ensemble}/${playerName}`;
+    const basePath = worktreeBasePath(gitRoot, ensemble);
+    const wtPath = path.join(basePath, playerName);
+    // If worktree already exists, reuse it — but verify its HEAD matches the
+    // requested branch (repoint if not). This is the #261 fix: the previous
+    // early-return trusted `branch` from the request as ground truth, so a
+    // worktree left on a prior task's branch would be silently misreported.
+    if ((0, fs_1.existsSync)(path.join(wtPath, '.git'))) {
+        log(`Worktree already exists at "${wtPath}" — reusing, verifying branch`);
+        const switched = switchWorktreeToBranch(wtPath, branch);
+        return { path: wtPath, branch, created: false, switched };
+    }
+    // #594 defect 2: stale-orphan recovery. A half-removed worktree leaves the
+    // directory on disk with its `.git` file already deleted (`git worktree
+    // remove` deletes metadata before the rmdir, which then fails under a
+    // Windows file lock). The reuse guard above keys on `.git` presence, so it
+    // is skipped — and `git worktree add` below refuses a non-empty pre-existing
+    // directory with a confusing `fatal: '...' already exists`. Detect the
+    // orphan and clear it first, with a clear error if the lock is still held.
+    if ((0, fs_1.existsSync)(wtPath)) {
+        log(`Stale worktree directory at "${wtPath}" (no \`.git\`) — attempting cleanup`);
+        try {
+            (0, fs_1.rmSync)(wtPath, { recursive: true, force: true });
+        }
+        catch (err) {
+            // Swallow — the existsSync re-check below is the authoritative gate.
+            log(`Warning: \`rmSync\` on stale worktree "${wtPath}" failed: ${err?.message ?? err}`);
+        }
+        if ((0, fs_1.existsSync)(wtPath)) {
+            throw new Error(`Stale worktree directory at "${wtPath}" could not be removed — kill any ` +
+                `processes running inside it (e.g. a dev server) and retry. On Windows, ` +
+                `memory-mapped native \`.node\` modules hold the lock until the owning ` +
+                `process exits.`);
+        }
+        // Directory cleared — prune any dangling git metadata so `git worktree add`
+        // doesn't trip over a stale registration for the same path/branch.
+        try {
+            (0, child_process_1.execFileSync)('git', ['worktree', 'prune'], {
+                cwd: gitRoot,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            // Best-effort — prune failure is non-fatal; the add below will surface
+            // any real conflict.
+        }
+    }
+    // Ensure base directory exists
+    (0, fs_1.mkdirSync)(basePath, { recursive: true });
+    // Check if the branch already has a worktree (would cause git error)
+    try {
+        const existing = (0, child_process_1.execFileSync)('git', ['worktree', 'list', '--porcelain'], {
+            cwd: gitRoot,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Parse porcelain output: "branch refs/heads/{branch}" lines
+        const branchRef = `refs/heads/${branch}`;
+        if (existing.includes(`branch ${branchRef}`)) {
+            throw new Error(`Branch "${branch}" already has an active worktree. ` +
+                `Remove it first with \`git worktree remove\` or choose a different branch.`);
+        }
+    }
+    catch (err) {
+        // Re-throw our own error, swallow git failures (e.g., no worktrees yet)
+        if (err.message?.includes('already has an active worktree'))
+            throw err;
+    }
+    // Create the worktree. Use -B to create/reset the branch.
+    try {
+        log(`Creating worktree: git worktree add -B ${branch} ${wtPath}`);
+        (0, child_process_1.execFileSync)('git', ['worktree', 'add', '-B', branch, wtPath], {
+            cwd: gitRoot,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const msg = err.stderr || err.stdout || err.message || String(err);
+        throw new Error(`Failed to create worktree at "${wtPath}": ${msg.trim()}`);
+    }
+    return { path: wtPath, branch, created: true };
+}
+/**
+ * Install dependencies in a worktree directory.
+ *
+ * Detects the package manager (npm, yarn, pnpm) by lockfile presence.
+ * Failure or timeout is logged but does not throw — the recruit proceeds
+ * with whatever state the worktree is in.
+ */
+function installDependencies(worktreePath, timeoutMs = validation_1.WORKTREE_INSTALL_TIMEOUT) {
+    // Detect package manager by lockfile
+    let cmd;
+    let args;
+    if ((0, fs_1.existsSync)(path.join(worktreePath, 'pnpm-lock.yaml'))) {
+        cmd = 'pnpm';
+        args = ['install', '--frozen-lockfile'];
+    }
+    else if ((0, fs_1.existsSync)(path.join(worktreePath, 'yarn.lock'))) {
+        cmd = 'yarn';
+        args = ['install', '--frozen-lockfile'];
+    }
+    else if ((0, fs_1.existsSync)(path.join(worktreePath, 'package-lock.json')) || (0, fs_1.existsSync)(path.join(worktreePath, 'package.json'))) {
+        cmd = 'npm';
+        args = ['install'];
+    }
+    else {
+        log(`No package.json found in "${worktreePath}" — skipping install`);
+        return;
+    }
+    try {
+        log(`Installing dependencies in "${worktreePath}": ${cmd} ${args.join(' ')}`);
+        (0, child_process_1.execFileSync)(cmd, args, {
+            cwd: worktreePath,
+            encoding: 'utf8',
+            timeout: timeoutMs,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        log(`Dependencies installed successfully in "${worktreePath}"`);
+    }
+    catch (err) {
+        // Log warning but don't throw — recruit should still proceed
+        const msg = err.killed ? `Timed out after ${timeoutMs}ms` : (err.stderr || err.message || String(err));
+        log(`Warning: dependency install failed in "${worktreePath}": ${msg}`);
+    }
+}
+/**
+ * Remove a git worktree.
+ *
+ * Throws if the worktree directory survives the removal (#594). On Windows,
+ * `git worktree remove --force` deletes `.git/worktrees/<name>` metadata
+ * *first*, then `rmdir`s the directory — so when a native `.node` module
+ * inside the worktree is memory-mapped by a live process, the directory
+ * deletion fails while the metadata is already gone. The pre-#594 code
+ * swallowed that failure (log-only, no throw), so the caller reported
+ * success and Temporal state diverged from disk. Now the post-removal
+ * `existsSync` check turns a half-removal into a hard error the caller can
+ * surface.
+ *
+ * `gitRoot` scopes the `git worktree remove` invocation to the owning
+ * repository. Pre-#594 the command ran with no `cwd`, so it only worked when
+ * `process.cwd()` happened to be the right repo — fragile, and wrong outright
+ * when the conductor's cwd is a different checkout than the worktree's repo.
+ * Callers should pass `entry.gitRoot` from the `WorktreeEntry`; it defaults to
+ * `process.cwd()` for backward compatibility.
+ */
+function removeWorktree(worktreePath, gitRoot = process.cwd()) {
+    try {
+        (0, child_process_1.execFileSync)('git', ['worktree', 'remove', '--force', worktreePath], {
+            cwd: gitRoot,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const msg = err.stderr || err.message || String(err);
+        log(`Warning: \`git worktree remove\` failed at "${worktreePath}": ${msg.trim()}`);
+        // Don't return here — fall through to the post-removal check. git may have
+        // deleted the metadata but failed the rmdir; the existsSync gate below is
+        // the real success criterion.
+    }
+    // #594 defect 1: post-removal verification. If the directory is still on
+    // disk, the removal half-succeeded — surface it instead of returning void.
+    if ((0, fs_1.existsSync)(worktreePath)) {
+        throw new Error(`Worktree directory "${worktreePath}" still exists after \`git worktree remove\`. ` +
+            `On Windows this usually means a process is holding a file lock — e.g. a dev ` +
+            `server with a memory-mapped native \`.node\` module. Stop any processes running ` +
+            `inside the worktree and retry.`);
+    }
+    log(`Removed worktree at "${worktreePath}"`);
+}

package/dist/worker.d.ts

@@ -0,0 +1,14 @@
+import { Worker } from '@temporalio/worker';
+import { Config } from './config';
+export interface DualWorkers {
+    /** Shared queue worker: workflows + delivery activities + schedule activities */
+    sharedWorker: Worker;
+    /** Per-host queue worker: spawnProcess activity only */
+    hostWorker: Worker;
+}
+/**
+ * Create dual workers:
+ * - Shared queue: workflows + all delivery activities (deliverCue, deliverReport, terminateSession, startRecruitedSession) + schedule activities
+ * - Per-host queue: spawnProcess only (routes recruit spawns to the correct machine)
+ */
+export declare function createWorkers(config: Config): Promise<DualWorkers>;

package/dist/worker.js

@@ -0,0 +1,146 @@
+"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.createWorkers = createWorkers;
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const fs = __importStar(require("fs"));
+const worker_1 = require("@temporalio/worker");
+const client_1 = require("@temporalio/client");
+const config_1 = require("./config");
+const connection_1 = require("./connection");
+const connection_2 = require("./connection");
+const schedule_fire_1 = require("./activities/schedule-fire");
+const outbox_1 = require("./activities/outbox");
+const maestro_1 = require("./activities/maestro");
+const log = (...args) => console.error('[agent-tempo:worker]', ...args);
+const BUNDLE_PATH = path.resolve(__dirname, '..', 'workflow-bundle.js');
+/**
+ * #274 — deliberately set worker identity so host-discovery (`listHosts` in
+ * `src/utils/hosts.ts`) can parse pollers back into `hostname:pid:version`
+ * tuples without guessing at the SDK default (`<pid>@<hostname>`, which
+ * loses the version axis and is only informally guaranteed).
+ *
+ * Format: `agent-tempo:<hostname>:<pid>:<version>`. Colons are safe
+ * because the middle segments have their own validation:
+ *   - hostname passes `PLAYER_NAME_REGEX` on the signal side (≤64 chars,
+ *     no colons by construction on any platform the daemon supports)
+ *   - pid is numeric
+ *   - version is a semver-ish string (no colons)
+ *
+ * Legacy identities (`<pid>@<hostname>`) from pre-#274 daemons remain
+ * parseable at the join site — see `parseIdentity` in
+ * `src/utils/hosts.ts` for the dual-format tolerance.
+ */
+function workerIdentity() {
+    // Lazy-require so the test build (which compiles worker.ts into
+    // `dist-test/src/` where `../package.json` doesn't resolve) doesn't
+    // throw MODULE_NOT_FOUND at module-load time when daemon tests
+    // transitively import this file. `createWorkers` is only called from
+    // production code paths, so this runs against the real `dist/`
+    // layout where `../package.json` is the repo root.
+    const { version } = require('../package.json');
+    return `agent-tempo:${os.hostname()}:${process.pid}:${version}`;
+}
+async function getWorkflowBundle() {
+    // Use pre-built bundle if it exists, otherwise bundle from source
+    if (fs.existsSync(BUNDLE_PATH)) {
+        log(`Loading pre-built workflow bundle from ${BUNDLE_PATH}`);
+        return { code: fs.readFileSync(BUNDLE_PATH, 'utf-8') };
+    }
+    log('No pre-built workflow bundle found — bundling from source (run `npm run build` to avoid this)');
+    const bundle = await (0, worker_1.bundleWorkflowCode)({
+        workflowsPath: path.resolve(__dirname, 'workflows', 'index'),
+    });
+    // Cache for subsequent workers
+    fs.writeFileSync(BUNDLE_PATH, bundle.code);
+    return bundle;
+}
+/**
+ * Create dual workers:
+ * - Shared queue: workflows + all delivery activities (deliverCue, deliverReport, terminateSession, startRecruitedSession) + schedule activities
+ * - Per-host queue: spawnProcess only (routes recruit spawns to the correct machine)
+ */
+async function createWorkers(config) {
+    const connection = await (0, connection_1.createTemporalNativeConnection)(config);
+    // Create a Client connection for activities that need to interact with Temporal
+    const clientConnection = await (0, connection_2.createTemporalConnection)(config);
+    const client = new client_1.Client({ connection: clientConnection, namespace: config.temporalNamespace });
+    const scheduleActivities = (0, schedule_fire_1.createScheduleActivities)(client);
+    const outboxActivities = (0, outbox_1.createOutboxActivities)(client, config);
+    const maestroActivities = (0, maestro_1.createMaestroActivities)(client);
+    const workflowBundle = await getWorkflowBundle();
+    const SHUTDOWN_GRACE_TIME = '10s';
+    const SHUTDOWN_FORCE_TIME = '15s';
+    const sharedWorker = await worker_1.Worker.create({
+        connection,
+        namespace: config.temporalNamespace,
+        taskQueue: config.taskQueue,
+        identity: workerIdentity(), // #274 — parseable agent-tempo:<host>:<pid>:<version>
+        workflowBundle,
+        shutdownGraceTime: SHUTDOWN_GRACE_TIME,
+        shutdownForceTime: SHUTDOWN_FORCE_TIME,
+        activities: {
+            ...scheduleActivities,
+            ...maestroActivities,
+            // Shared-queue delivery activities (everything except spawnProcess)
+            deliverCue: outboxActivities.deliverCue,
+            deliverReport: outboxActivities.deliverReport,
+            terminateSession: outboxActivities.terminateSession,
+            startRecruitedSession: outboxActivities.startRecruitedSession,
+            releasePlayer: outboxActivities.releasePlayer,
+            deliverDetach: outboxActivities.deliverDetach,
+            deliverDestroy: outboxActivities.deliverDestroy,
+            deliverRestart: outboxActivities.deliverRestart,
+        },
+    });
+    // Per-host worker — spawnProcess only, no workflow bundle
+    const hostConnection = await (0, connection_1.createTemporalNativeConnection)(config);
+    const hostWorker = await worker_1.Worker.create({
+        connection: hostConnection,
+        namespace: config.temporalNamespace,
+        taskQueue: (0, config_1.hostTaskQueue)(config.taskQueue, os.hostname()),
+        identity: workerIdentity(), // #274 — same format, both pollers under one identity
+        shutdownGraceTime: SHUTDOWN_GRACE_TIME,
+        shutdownForceTime: SHUTDOWN_FORCE_TIME,
+        activities: {
+            spawnProcess: outboxActivities.spawnProcess,
+            // #159 Gap 2: host-local OS-process kill. Must live on the per-host queue so it runs
+            // on the machine where the claude.exe / bridge process actually lives.
+            hardTerminateAttachment: outboxActivities.hardTerminateAttachment,
+        },
+    });
+    return { sharedWorker, hostWorker };
+}

package/dist/workflows/attachment-math.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure attachment-math helpers for the session workflow.
+ *
+ * **Workflow-sandbox safe**: this file imports only types. No `@temporalio/*`
+ * runtime imports, no `Date.now()`, no random, no I/O — every caller passes
+ * `now` as a parameter so the same inputs always produce the same output.
+ * That makes it:
+ *   - Cheap to unit-test from Mocha without `TestWorkflowEnvironment`, and
+ *   - Safe to call from deterministic workflow code (caller is responsible
+ *     for sourcing `now` via the SDK-intercepted `new Date().getTime()`).
+ *
+ * Extracted in PR #127-fix as a follow-up to PR-G (#125) architect review:
+ * the alternative was a ~60 LOC history-fill harness that would have tested
+ * Temporal's CAN-trigger heuristic rather than our extension logic, and
+ * would have been brittle to Temporal-SDK internals. Pure-function + direct
+ * unit tests is the durable choice.
+ */
+import type { Attachment } from '../types';
+/**
+ * Produce a new {@link Attachment} whose lease window is extended so an
+ * adapter that was beating normally at the moment of `continueAsNew` has room
+ * to land its next heartbeat before the new execution's first main-loop tick
+ * reaps the lease.
+ *
+ * **Design rationale (session-lifecycle-rebuild-v2.md §2.3):** the CAN
+ * transition is not instantaneous. If we were to write the pre-CAN
+ * `expiresAt` verbatim into the new execution, a transition that takes
+ * ~100-500ms could leave the new run's first deadline race observing an
+ * already-expired lease and reaping a healthy attachment. Pushing
+ * `expiresAt` out to `now + extendMs` guarantees the adapter has room to land
+ * its next heartbeat.
+ *
+ * Why this is a total function (returns a new object unconditionally,
+ * rather than accepting `null` and returning `undefined`): null-handling is
+ * the caller's business — a workflow that has no current attachment simply
+ * skips the call. Keeping this function non-nullable keeps the unit tests
+ * focused on math rather than null-propagation.
+ *
+ * @param attachment - the pre-CAN attachment record. All non-timestamp
+ *   fields (`attachmentId`, `hostname`, `adapterId`, `adapterClass`,
+ *   `claimedAt`, `leaseMs`, `runId`) are carried forward verbatim.
+ * @param extendMs - how far past `now` to push `expiresAt`, in milliseconds.
+ *   Post-#249 callers pass `attachment.leaseMs` (= 3 × heartbeatMs — covers one
+ *   full lease window and therefore at least one full heartbeat interval for
+ *   every adapter class). Pre-#249 callers passed a hardcoded 30_000 constant
+ *   which under-covered the claude-code adapter's 60s cadence — the rename
+ *   from `heartbeatMs` disambiguates that the parameter is a raw extension
+ *   duration, not a cadence. The function does not validate — any non-negative
+ *   integer is accepted.
+ * @param now - current time in epoch milliseconds. In workflow context
+ *   callers pass `new Date().getTime()` (the Temporal SDK intercepts `new
+ *   Date()` to return replay-consistent time). In unit tests callers pass
+ *   an arbitrary fixed value.
+ * @returns a new `Attachment` object — the input is not mutated.
+ */
+export declare function extendAttachmentForCAN(attachment: Attachment, extendMs: number, now: number): Attachment;