instar 1.3.90 → 1.3.92

package/dist/core/StageAdvancer.js

@@ -0,0 +1,70 @@
+/**
+ * StageAdvancer — the SOLE writer of `multiMachine.sessionPool.stage` and the
+ * mechanical rollout gate (Multi-Machine Session Pool §Rollout). A stage activates
+ * ONLY when the prior stage's Tier-3 E2E recorded `green` for the CURRENT commit;
+ * otherwise the advance is refused and audited. If a live stage later records `red`,
+ * the advancer mechanically REVERTS to the prior (safe) stage. Per "Structure >
+ * Willpower" the gate is code, not prose: no other path may flip the stage (enforced
+ * by a Config.ts write-guard that only honors writes carrying this module's token).
+ */
+export const STAGES = ['dark', 'shadow', 'live-transfer', 'rebalance'];
+export function stageIndex(stage) {
+    return STAGES.indexOf(stage);
+}
+export class StageAdvancer {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /**
+     * Advance to `targetStage`, gated on a matching `green` E2E for the PRIOR stage at
+     * the current commit. A missing/`red`/stale-commit/tampered prior result → refused.
+     */
+    advanceTo(targetStage) {
+        const targetIdx = stageIndex(targetStage);
+        if (targetIdx < 0)
+            return { ok: false, reason: 'invalid-stage', detail: String(targetStage) };
+        const current = this.d.readStage();
+        if (stageIndex(current) >= targetIdx) {
+            return { ok: false, reason: 'already-at-or-past', detail: `current=${current}` };
+        }
+        // 'dark' (index 0) is the floor — there is no prior stage to gate on; you never
+        // "advance to dark", you revert to it. So any real advance targets index ≥ 1.
+        const priorStageIdx = targetIdx - 1;
+        const prior = this.d.resultStore.getLatestForStage(priorStageIdx);
+        const sha = this.d.currentCommitSha();
+        const gateOk = !!prior && prior.result === 'green' && prior.commitSha === sha && this.d.resultStore.verify(prior);
+        if (!gateOk) {
+            const detail = !prior ? 'no-result' : prior.result !== 'green' ? `result=${prior.result}` : prior.commitSha !== sha ? 'stale-commit' : 'bad-signature';
+            this.d.audit?.('stage-advance-refused', { targetStage, priorStage: STAGES[priorStageIdx], reason: 'e2e-gate-not-passed', detail, commitSha: sha });
+            return { ok: false, reason: 'e2e-gate-not-passed', detail };
+        }
+        this.d.writeStageConfig(targetStage);
+        this.d.audit?.('stage-advanced', { from: current, to: targetStage, commitSha: sha, evidenceRef: prior.evidenceRef });
+        return { ok: true, stage: targetStage };
+    }
+    /**
+     * Reconcile on each cycle: if the CURRENT stage's latest E2E is `red` (regression),
+     * mechanically revert to the prior stage until a fresh `green` is recorded. Returns
+     * the stage after reconciliation.
+     */
+    reconcile() {
+        const current = this.d.readStage();
+        const idx = stageIndex(current);
+        if (idx <= 0)
+            return current; // 'dark' is the floor — nothing to revert to
+        const latest = this.d.resultStore.getLatestForStage(idx);
+        // Only revert on a red for the CURRENT commit — a stale red from a prior commit
+        // is not a regression of the running build and must not trigger a revert.
+        // (2026-05-29 pre-merge review.)
+        const regressed = !!latest && latest.result === 'red' && latest.commitSha === this.d.currentCommitSha() && this.d.resultStore.verify(latest);
+        if (regressed) {
+            const reverted = STAGES[idx - 1];
+            this.d.writeStageConfig(reverted);
+            this.d.audit?.('stage-reverted', { from: current, to: reverted, reason: 'e2e-red', evidenceRef: latest.evidenceRef });
+            return reverted;
+        }
+        return current;
+    }
+}
+//# sourceMappingURL=StageAdvancer.js.map

package/dist/core/StageAdvancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StageAdvancer.js","sourceRoot":"","sources":["../../src/core/StageAdvancer.ts"],"names":[],"mappings":"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"}

package/dist/core/TransferByNickname.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TransferByNickname — the pure planner behind the headline "move this to
+ * <nickname>" mid-conversation swap (Multi-Machine Session Pool §L4 "Topic
+ * Placement Updates" + §L5). It turns a recognized NicknameCommand into a gated,
+ * validated TransferPlan: resolve the nickname → machineId, enforce the rate limit,
+ * the confirmation gate (offline target / mid-reply), and the already-there no-op.
+ * Per "Structure > Willpower" a transfer is high-impact, so this is NOT free-text
+ * inference — it operates on an ALREADY-recognized command + the registry state,
+ * and an unknown/ambiguous nickname is REJECTED (listing valid nicknames), never
+ * silently mis-routed.
+ */
+import type { NicknameCommand } from './NicknameCommand.js';
+export interface TransferByNicknameState {
+    /** Resolve a nickname → machineId (case-insensitive exact match), or null if unknown. */
+    resolveNickname: (nickname: string) => string | null;
+    /** The full set of valid nicknames (returned on an unknown-nickname rejection). */
+    validNicknames: () => string[];
+    isOnline: (machineId: string) => boolean;
+    currentOwnerOf: (sessionKey: string) => string | null;
+    /** Is the session mid-reply (a turn in flight)? Confirmation is required to interrupt it. */
+    isMidReply: (sessionKey: string) => boolean;
+    /** When the topic last had a placement update (for the rate limit), or null. */
+    lastPlacementUpdateAt: (sessionKey: string) => number | null;
+    now: () => number;
+    /** Minimum ms between placement updates per topic. Default 10000. */
+    minUpdateIntervalMs?: number;
+}
+export type TransferPlanAction = 'transfer' | 'noop' | 'confirm-required' | 'reject';
+export interface TransferPlan {
+    action: TransferPlanAction;
+    sessionKey: string;
+    /** Resolved target machine (present for transfer / confirm-required / noop). */
+    targetMachine?: string;
+    /** Set the topic's preferredMachine + pinned:true (a hard pin — §L4). */
+    setPin?: boolean;
+    /** Human-facing confirmation prompt (action === 'confirm-required'). */
+    confirmationPrompt?: string;
+    /** Rejection reason (action === 'reject'). */
+    rejectReason?: 'unknown-machine-nickname' | 'rate-limited';
+    /** On unknown-nickname: the valid nicknames to surface to the user. */
+    validNicknames?: string[];
+    detail?: string;
+}
+/**
+ * Plan a transfer-by-nickname. Pure over (command, state). Both "move this to
+ * <nick>" and "run this on <nick>" set a hard pin (pinned:true) per §L4; the only
+ * intent difference is cosmetic. Confirmation is required when the target is offline,
+ * or when it differs from the current owner AND the session is mid-reply (§L4 line 456).
+ */
+export declare function planTransferByNickname(command: NicknameCommand, state: TransferByNicknameState, sessionKey: string): TransferPlan;
+//# sourceMappingURL=TransferByNickname.d.ts.map

package/dist/core/TransferByNickname.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransferByNickname.d.ts","sourceRoot":"","sources":["../../src/core/TransferByNickname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,uBAAuB;IACtC,yFAAyF;IACzF,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACrD,mFAAmF;IACnF,cAAc,EAAE,MAAM,MAAM,EAAE,CAAC;IAC/B,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,cAAc,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACtD,6FAA6F;IAC7F,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,gFAAgF;IAChF,qBAAqB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC7D,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,MAAM,GAAG,kBAAkB,GAAG,QAAQ,CAAC;AAErF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,YAAY,CAAC,EAAE,0BAA0B,GAAG,cAAc,CAAC;IAC3D,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAmCjI"}

package/dist/core/TransferByNickname.js

@@ -0,0 +1,50 @@
+/**
+ * TransferByNickname — the pure planner behind the headline "move this to
+ * <nickname>" mid-conversation swap (Multi-Machine Session Pool §L4 "Topic
+ * Placement Updates" + §L5). It turns a recognized NicknameCommand into a gated,
+ * validated TransferPlan: resolve the nickname → machineId, enforce the rate limit,
+ * the confirmation gate (offline target / mid-reply), and the already-there no-op.
+ * Per "Structure > Willpower" a transfer is high-impact, so this is NOT free-text
+ * inference — it operates on an ALREADY-recognized command + the registry state,
+ * and an unknown/ambiguous nickname is REJECTED (listing valid nicknames), never
+ * silently mis-routed.
+ */
+const DEFAULT_MIN_UPDATE_INTERVAL_MS = 10000;
+/**
+ * Plan a transfer-by-nickname. Pure over (command, state). Both "move this to
+ * <nick>" and "run this on <nick>" set a hard pin (pinned:true) per §L4; the only
+ * intent difference is cosmetic. Confirmation is required when the target is offline,
+ * or when it differs from the current owner AND the session is mid-reply (§L4 line 456).
+ */
+export function planTransferByNickname(command, state, sessionKey) {
+    const target = state.resolveNickname(command.nickname);
+    if (!target) {
+        return { action: 'reject', sessionKey, rejectReason: 'unknown-machine-nickname', validNicknames: state.validNicknames(), detail: command.nickname };
+    }
+    // Rate limit — at most one placement update per topic per interval (defeats rapid-fire transfers).
+    const minInterval = state.minUpdateIntervalMs ?? DEFAULT_MIN_UPDATE_INTERVAL_MS;
+    const last = state.lastPlacementUpdateAt(sessionKey);
+    if (last != null && state.now() - last < minInterval) {
+        return { action: 'reject', sessionKey, targetMachine: target, rejectReason: 'rate-limited' };
+    }
+    const owner = state.currentOwnerOf(sessionKey);
+    // Already on the target → no transfer needed (still applies the pin if requested).
+    if (owner === target) {
+        return { action: 'noop', sessionKey, targetMachine: target, setPin: true, detail: 'already-on-target' };
+    }
+    // Confirmation gate (§L4): offline target, OR a different owner while mid-reply.
+    if (!state.isOnline(target)) {
+        return {
+            action: 'confirm-required', sessionKey, targetMachine: target, setPin: true,
+            confirmationPrompt: `${command.nickname} is offline right now. Move this conversation there anyway? It'll pick up like a fresh-session catch-up once it's back.`,
+        };
+    }
+    if (owner != null && owner !== target && state.isMidReply(sessionKey)) {
+        return {
+            action: 'confirm-required', sessionKey, targetMachine: target, setPin: true,
+            confirmationPrompt: `Move this to ${command.nickname}? I'm mid-reply — it'll be like a fresh-session catch-up on the other machine.`,
+        };
+    }
+    return { action: 'transfer', sessionKey, targetMachine: target, setPin: true };
+}
+//# sourceMappingURL=TransferByNickname.js.map

package/dist/core/TransferByNickname.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransferByNickname.js","sourceRoot":"","sources":["../../src/core/TransferByNickname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsCH,MAAM,8BAA8B,GAAG,KAAK,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAwB,EAAE,KAA8B,EAAE,UAAkB;IACjH,MAAM,MAAM,GAAG,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,0BAA0B,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;IACtJ,CAAC;IAED,mGAAmG;IACnG,MAAM,WAAW,GAAG,KAAK,CAAC,mBAAmB,IAAI,8BAA8B,CAAC;IAChF,MAAM,IAAI,GAAG,KAAK,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC;IACrD,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,WAAW,EAAE,CAAC;QACrD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/F,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAE/C,mFAAmF;IACnF,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC1G,CAAC;IAED,iFAAiF;IACjF,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI;YAC3E,kBAAkB,EAAE,GAAG,OAAO,CAAC,QAAQ,yHAAyH;SACjK,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACtE,OAAO;YACL,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI;YAC3E,kBAAkB,EAAE,gBAAgB,OAAO,CAAC,QAAQ,gFAAgF;SACrI,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACjF,CAAC"}

package/dist/core/TransferOrchestrator.d.ts

@@ -0,0 +1,113 @@
+/**
+ * TransferOrchestrator — drives a planned session handoff through the §L3/§L5
+ * ordered sequence: active(S) → transferring(e+1) → [drain, flush ledger, target
+ * pulls+verifies] → active(T, e+2) → S-release. Claim-before-release, fenced by
+ * (status, epoch): there is no double-run (only one machine is `active` at the top
+ * epoch) and no no-owner gap (`transferring` still names S as the draining owner).
+ *
+ * The orchestrator enforces the two §L5 timing contracts:
+ *  - Drain bound (`transferDrainTimeoutMs`): a long reply/tool-call must NOT block a
+ *    transfer; on timeout the source abandons its partial output (NOT emitted).
+ *  - Output exclusion (`transferOutputCutoffMs`): T holds its CONTINUATION until the
+ *    cutoff has elapsed since the `transferring` write, so S's drain window and T's
+ *    emission window are disjoint by construction — exactly one continuation per turn.
+ *
+ * All I/O (CAS, drain, ledger flush, mesh transfer, claim, clock) is injected so the
+ * sequence + timing logic is deterministic and unit-testable; the real wiring (real
+ * SessionMigrator drain, real git ledger flush, real mesh client) lands in Track H.
+ */
+export type LedgerEntryStatus = 'reply_committed' | 'cursor_advanced' | 'in_flight';
+export interface LedgerSnapshot {
+    sessionKey: string;
+    generatedAt: number;
+    entries: Array<{
+        messageId: string;
+        status: LedgerEntryStatus;
+        replyMarker?: string;
+        updatedAt: number;
+    }>;
+    snapshotSha256: string;
+}
+/**
+ * Verify a ledger snapshot at the transfer handoff (§L5): the SHA256 must match the
+ * SyncManifest-covered value AND every entry must be terminal (nothing `in_flight`).
+ * An `in_flight` entry means a turn was still processing at flush time — the target
+ * must NOT resume from it (it waits for a terminal re-flush, or treats it as the
+ * interrupted-drain case on failover). Pure.
+ */
+export declare function verifyLedgerSnapshot(snapshot: LedgerSnapshot, expectedSha256: string, computeSha256: (s: LedgerSnapshot) => string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'sha-mismatch' | 'in-flight-entry';
+};
+export interface TransferRequest {
+    sessionKey: string;
+    source: string;
+    target: string;
+    reason: 'pin' | 'rebalance' | 'failover';
+    /** Whether the source machine is alive (planned transfer) or gone (failover). */
+    sourceAlive: boolean;
+    /** The ownership epoch the orchestrator observed before starting. */
+    baseEpoch: number;
+}
+export interface TransferOrchestratorConfig {
+    transferDrainTimeoutMs: number;
+    transferOutputCutoffMs: number;
+}
+export declare const DEFAULT_TRANSFER_CONFIG: TransferOrchestratorConfig;
+export interface TransferOrchestratorDeps {
+    /** CAS the record source→transferring(epoch+1). */
+    casToTransferring: (sessionKey: string, target: string, expectedEpoch: number) => {
+        ok: boolean;
+        epoch: number;
+    };
+    /** Quiesce + drain the in-flight reply on the source, bounded by timeoutMs. */
+    drain: (sessionKey: string, timeoutMs: number) => Promise<{
+        drained: boolean;
+        abandonedPartial: boolean;
+    }>;
+    /** Source flushes its ledger snapshot synchronously (returns the snapshot + its ref). */
+    flushLedger: (sessionKey: string) => Promise<{
+        snapshot: LedgerSnapshot;
+        ledgerSnapshotRef: string;
+        syncManifestRef: string;
+    }>;
+    /** Send the transfer MeshRpc to the target; the target pulls + verifies the snapshot. */
+    sendTransferRpc: (target: string, refs: {
+        sessionKey: string;
+        ledgerSnapshotRef: string;
+        syncManifestRef: string;
+    }) => Promise<{
+        ok: boolean;
+        verified: boolean;
+        reason?: string;
+    }>;
+    /** Target CASes itself to active(owner=T, epoch+2). */
+    targetClaim: (sessionKey: string, expectedEpoch: number) => {
+        ok: boolean;
+        epoch: number;
+    };
+    /** Cleanup: source releases (NOT a precondition for T's claim — runs after). */
+    releaseSource: (sessionKey: string) => void;
+    /** Raise a deduped Attention item on sync corruption / unrecoverable handoff. */
+    raiseAttention?: (title: string, body: string) => void;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    log?: (line: string) => void;
+}
+export type TransferStatus = 'transferred' | 'aborted-cas-lost' | 'sync-corrupted' | 'target-claim-failed';
+export interface TransferOutcome {
+    ok: boolean;
+    status: TransferStatus;
+    drainAbandoned?: boolean;
+    finalEpoch?: number;
+    detail?: string;
+}
+export declare class TransferOrchestrator {
+    private readonly deps;
+    private readonly cfg;
+    constructor(deps: TransferOrchestratorDeps, cfg?: TransferOrchestratorConfig);
+    transfer(req: TransferRequest): Promise<TransferOutcome>;
+}
+//# sourceMappingURL=TransferOrchestrator.d.ts.map

package/dist/core/TransferOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransferOrchestrator.d.ts","sourceRoot":"","sources":["../../src/core/TransferOrchestrator.ts"],"names":[],"mappings":"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"}

package/dist/core/TransferOrchestrator.js

@@ -0,0 +1,79 @@
+/**
+ * TransferOrchestrator — drives a planned session handoff through the §L3/§L5
+ * ordered sequence: active(S) → transferring(e+1) → [drain, flush ledger, target
+ * pulls+verifies] → active(T, e+2) → S-release. Claim-before-release, fenced by
+ * (status, epoch): there is no double-run (only one machine is `active` at the top
+ * epoch) and no no-owner gap (`transferring` still names S as the draining owner).
+ *
+ * The orchestrator enforces the two §L5 timing contracts:
+ *  - Drain bound (`transferDrainTimeoutMs`): a long reply/tool-call must NOT block a
+ *    transfer; on timeout the source abandons its partial output (NOT emitted).
+ *  - Output exclusion (`transferOutputCutoffMs`): T holds its CONTINUATION until the
+ *    cutoff has elapsed since the `transferring` write, so S's drain window and T's
+ *    emission window are disjoint by construction — exactly one continuation per turn.
+ *
+ * All I/O (CAS, drain, ledger flush, mesh transfer, claim, clock) is injected so the
+ * sequence + timing logic is deterministic and unit-testable; the real wiring (real
+ * SessionMigrator drain, real git ledger flush, real mesh client) lands in Track H.
+ */
+/**
+ * Verify a ledger snapshot at the transfer handoff (§L5): the SHA256 must match the
+ * SyncManifest-covered value AND every entry must be terminal (nothing `in_flight`).
+ * An `in_flight` entry means a turn was still processing at flush time — the target
+ * must NOT resume from it (it waits for a terminal re-flush, or treats it as the
+ * interrupted-drain case on failover). Pure.
+ */
+export function verifyLedgerSnapshot(snapshot, expectedSha256, computeSha256) {
+    if (computeSha256(snapshot) !== expectedSha256 || snapshot.snapshotSha256 !== expectedSha256) {
+        return { ok: false, reason: 'sha-mismatch' };
+    }
+    if (snapshot.entries.some((e) => e.status === 'in_flight')) {
+        return { ok: false, reason: 'in-flight-entry' };
+    }
+    return { ok: true };
+}
+export const DEFAULT_TRANSFER_CONFIG = {
+    transferDrainTimeoutMs: 30000,
+    transferOutputCutoffMs: 1000,
+};
+export class TransferOrchestrator {
+    deps;
+    cfg;
+    constructor(deps, cfg = DEFAULT_TRANSFER_CONFIG) {
+        this.deps = deps;
+        this.cfg = cfg;
+    }
+    async transfer(req) {
+        // 1. CAS source→transferring(e+1). Stamp the moment for the output-exclusion window.
+        const t1 = this.deps.casToTransferring(req.sessionKey, req.target, req.baseEpoch);
+        if (!t1.ok) {
+            return { ok: false, status: 'aborted-cas-lost', detail: 'could-not-enter-transferring' };
+        }
+        const transferringAt = this.deps.now();
+        // 2. Drain the in-flight reply on the source, bounded (a long reply must not block).
+        const drainRes = await this.deps.drain(req.sessionKey, this.cfg.transferDrainTimeoutMs);
+        // 3. Source flushes its ledger snapshot synchronously.
+        const flush = await this.deps.flushLedger(req.sessionKey);
+        // 4. Send transfer to the target; the target pulls + verifies (SHA + all-terminal).
+        const sent = await this.deps.sendTransferRpc(req.target, { sessionKey: req.sessionKey, ledgerSnapshotRef: flush.ledgerSnapshotRef, syncManifestRef: flush.syncManifestRef });
+        if (!sent.ok || !sent.verified) {
+            this.deps.raiseAttention?.('Session transfer sync corrupted', `${req.sessionKey} → ${req.target}: ${sent.reason ?? 'verify-failed'}`);
+            return { ok: false, status: 'sync-corrupted', drainAbandoned: drainRes.abandonedPartial, detail: sent.reason ?? 'verify-failed' };
+        }
+        // 5. Output exclusion: T must NOT emit until transferOutputCutoffMs has elapsed
+        //    since the transferring write, so S's drain window + T's emission are disjoint.
+        const elapsed = this.deps.now() - transferringAt;
+        const remaining = this.cfg.transferOutputCutoffMs - elapsed;
+        if (remaining > 0)
+            await this.deps.sleep(remaining);
+        // 6. Target claims active(owner=T, e+2). Then the source releases (cleanup only).
+        const t2 = this.deps.targetClaim(req.sessionKey, t1.epoch);
+        if (!t2.ok) {
+            return { ok: false, status: 'target-claim-failed', drainAbandoned: drainRes.abandonedPartial, detail: 'target-cas-failed' };
+        }
+        this.deps.releaseSource(req.sessionKey);
+        this.deps.log?.(`transfer ${req.sessionKey} ${req.source}→${req.target} complete @ epoch ${t2.epoch}`);
+        return { ok: true, status: 'transferred', drainAbandoned: drainRes.abandonedPartial, finalEpoch: t2.epoch };
+    }
+}
+//# sourceMappingURL=TransferOrchestrator.js.map

package/dist/core/TransferOrchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransferOrchestrator.js","sourceRoot":"","sources":["../../src/core/TransferOrchestrator.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -1347,8 +1347,23 @@ export type MachineRole = 'awake' | 'standby';
  */
 export type CoordinationMode = 'primary-standby' | 'independent';
 export interface MachineRegistryEntry {
-    /** Human-friendly machine name */
+    /** Human-friendly machine name (auto-detected hostname at pairing; static). */
     name: string;
+    /**
+     * User-facing, EDITABLE nickname — the handle a user types in "run this on
+     * <nickname>" / "move this to <nickname>" (Multi-Machine Session Pool §L2).
+     * Auto-assigned at registration via NicknameAssigner (idempotent — kept if
+     * already set), editable via PATCH /pool/machines/:id, unique within the pool.
+     * Optional for backward-compat with registries written before §L2.
+     */
+    nickname?: string;
+    /**
+     * Self-attested static hardware properties (Session Pool §L2) — captured by
+     * the machine from `os` and recorded into ITS OWN registry entry, then synced
+     * to peers via the registry. Surfaced on the Machines dashboard tab + GET /pool.
+     * Optional (absent until the machine records it).
+     */
+    hardware?: MachineHardware;
     /** Current trust status */
     status: MachineStatus;
     /** Current operational role */
@@ -1427,6 +1442,71 @@ export interface MachineRegistry {
      */
     lease?: LeaseRecord;
 }
+/**
+ * Static hardware properties of a machine, captured once at registration (cheap,
+ * stable `os` reads) and surfaced on the Machines dashboard tab + as placement
+ * signal (§L2). Self-reported → advisory for display, never authority.
+ */
+export interface MachineHardware {
+    /** os.platform() — e.g. "darwin", "linux", "win32". */
+    platform: string;
+    /** os.arch() — e.g. "arm64", "x64". */
+    arch: string;
+    /** os.cpus()[0].model — e.g. "Apple M2". */
+    cpuModel: string;
+    /** os.cpus().length. */
+    cpuCores: number;
+    /** os.totalmem() in bytes. */
+    totalMemBytes: number;
+    /** os.hostname(). */
+    hostname: string;
+    /** The instar version this machine reported. */
+    instarVersion?: string;
+}
+/**
+ * Clock-skew quarantine state (§L2). An explicit three-value FSM so every
+ * implementation + recovery path is identical. A SINGLE divergent heartbeat
+ * never removes a machine; removal requires 2 consecutive divergent beats;
+ * re-admission requires 2 consecutive in-tolerance beats.
+ */
+export type ClockSkewStatus = 'ok' | 'divergence-detected-once' | 'suspect-clock-removed';
+/**
+ * Live per-machine capacity record (§L2) — the input to placement and the
+ * Machines dashboard tab. Assembled by MachinePoolRegistry from the machine
+ * registry (nickname), MachineHeartbeat (liveness), `os` (hardware/load), and
+ * SessionManager diagnostics (sessions/memPressure). Liveness + freshness key
+ * on `routerReceivedAt` (the router's own clock), NEVER the machine's
+ * self-reported timestamp (clock-skew safety).
+ */
+export interface MachineCapacity {
+    machineId: string;
+    /** User-facing nickname (§L2), mirrored from the registry entry. */
+    nickname?: string;
+    /** Liveness, computed as (now(router) − routerReceivedAt) < failoverThreshold. */
+    online: boolean;
+    /** The machine's own last-heartbeat timestamp (ISO) — debugging only. */
+    selfReportedLastSeen?: string;
+    /** When the router last observed this machine, on the ROUTER's clock (ISO). */
+    routerReceivedAt?: string;
+    /** 1-minute OS load average from the machine (os.loadavg()[0]). */
+    loadAvg?: number;
+    /** Memory pressure bucket from SessionManager diagnostics. */
+    memPressure?: 'low' | 'moderate' | 'high' | 'critical';
+    /** Active session count on the machine. */
+    activeSessionCount?: number;
+    /** Configured max sessions. */
+    maxSessions?: number;
+    /** Capabilities (e.g. "gpu", "local-model:llama3", "fast-cpu"). */
+    capabilities?: string[];
+    /** Local models available. */
+    modelsAvailable?: string[];
+    /** Agents resident on the machine (multi-agent-per-machine, §L6). */
+    agentsResident?: string[];
+    /** Static hardware properties (§L2). */
+    hardware?: MachineHardware;
+    /** Clock-skew quarantine state (§L2 FSM). */
+    clockSkewStatus: ClockSkewStatus;
+}
 export interface MultiMachineConfig {
     /** Whether multi-machine is enabled */
     enabled: boolean;
@@ -1484,6 +1564,102 @@ export interface MultiMachineConfig {
      * SEAMLESSNESS_PROTOCOL_VERSION applies); present so migrations/tests can pin it.
      */
     protocolVersion?: number;
+    /**
+     * Multi-Machine Session Pool (spec docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md).
+     * Active-active per-session placement + transfer on top of the router lease.
+     * Ships DARK: the entire layer is inert unless `enabled` is true AND the
+     * graduated `stage` has been advanced past 'dark' (the stage is written ONLY
+     * by StageAdvancer — Track H — gated on a green E2E result). Independent of
+     * the single-awake seamlessness model above; a 1-machine agent is a no-op.
+     */
+    sessionPool?: SessionPoolConfig;
+}
+/**
+ * Multi-Machine Session Pool config block. All optional with safe dark defaults
+ * (see ConfigDefaults `SHARED_DEFAULTS.multiMachine.sessionPool`). Tunables for
+ * later layers (placement, transfer, registry, clock-skew) are added to this
+ * interface by their tracks as they land.
+ */
+export interface SessionPoolConfig {
+    /** Master switch. Default false — the entire session-pool layer is inert when false. */
+    enabled?: boolean;
+    /**
+     * Graduated rollout stage (spec §Rollout). 'dark' (code shipped, placement
+     * dry-run, always local) → 'shadow' (real placement + ownership, no transfer)
+     * → 'live-transfer' (failover + pin transfers) → 'rebalance' (load-driven).
+     * Written ONLY by StageAdvancer via a Config.ts write-guard (Track H);
+     * a direct write is rejected. Default 'dark'.
+     */
+    stage?: 'dark' | 'shadow' | 'live-transfer' | 'rebalance';
+    /**
+     * When true, the placement engine LOGS the decision it would make but always
+     * places locally (Stage-0 behavior). Default true.
+     */
+    dryRun?: boolean;
+    /**
+     * Clock-skew divergence tolerance (ms) — a machine whose self-reported vs
+     * router-observed timestamps diverge beyond this on 2 consecutive heartbeats
+     * is quarantined from placement (§L2). Default 300000 (5 min). Must be
+     * ≥ 2× maxExpectedNtpDriftMs (validated at startup).
+     */
+    clockSkewToleranceMs?: number;
+    /**
+     * Max expected NTP drift (ms) on a healthy host. `clockSkewToleranceMs` must
+     * be ≥ 2× this. Default 250.
+     */
+    maxExpectedNtpDriftMs?: number;
+    /**
+     * How long an offline machine's capacity record is retained before eviction
+     * (ms). Default 86400000 (24h) — a briefly-offline machine keeps its
+     * nickname/hardware/history for fast re-placement.
+     */
+    machineRecordEvictionMs?: number;
+    /**
+     * MeshRpc (§L0) command timestamp tolerance (ms) — a signed command whose
+     * timestamp is outside |now - ts| is rejected `stale-timestamp`. Default 30000.
+     */
+    meshRpcClockToleranceMs?: number;
+    /**
+     * §L4 deliverMessage per-attempt timeout (ms) — the router treats a forward that
+     * does not ACK within this as failed and retries. Default 5000.
+     */
+    deliverMessageTimeoutMs?: number;
+    /**
+     * §L4 max deliverMessage retries before the router falls back to owner-dead
+     * re-placement. Default 3.
+     */
+    deliverMessageMaxRetries?: number;
+    /**
+     * §L4 placement stickiness margin — the current owner is kept unless another
+     * machine is better by more than this score delta (prevents flapping). Default 0.15.
+     */
+    placementHysteresisDelta?: number;
+    /**
+     * §L3 max per-session ownership CAS retries on non-fast-forward contention before
+     * the router queues the message. Default 5.
+     */
+    ownershipCasMaxRetries?: number;
+    /**
+     * §L5 max time (ms) the source drains an in-flight reply before cancelling and
+     * proceeding with the transfer — a long reply/tool-call must not block. Default 30000.
+     */
+    transferDrainTimeoutMs?: number;
+    /**
+     * §L5 output-exclusion window (ms): the source emits no NEW output after entering
+     * `transferring` and the target holds its CONTINUATION until this elapses, so the
+     * two emission windows are disjoint (no double-send). Default 1000.
+     */
+    transferOutputCutoffMs?: number;
+    /**
+     * §L4 cool-down (ms) after a transfer before a session is eligible for re-placement
+     * (a hard user-pin bypasses it). Default 300000.
+     */
+    placementCooldownMs?: number;
+    /**
+     * §L4 minimum interval (ms) between placement updates per topic — defeats rapid-fire
+     * transfers. Default 10000.
+     */
+    topicPlacementUpdateMinIntervalMs?: number;
 }
 export type AgentAutonomyLevel = 'supervised' | 'collaborative' | 'autonomous';
 export type UserRegistrationPolicy = 'open' | 'invite-only' | 'admin-only';