instar 1.3.596 → 1.3.597

package/dist/core/LiveTestRunner.d.ts

@@ -0,0 +1,66 @@
+/**
+ * LiveTestRunner — the orchestrator that APPLIES the live-user-channel-proof standard
+ * to the cross-machine transfer (docs/specs/live-user-channel-proof-standard.md §6 —
+ * the first feature held to the bar). It encodes the capstone flow that a user-role
+ * session runs:
+ *
+ *   1. MOVE THE SEAT FIRST — transfer the (throwaway) topic to the target machine.
+ *      If the transfer reports the seat did NOT move, the capstone premise is false and
+ *      we stop loudly (that "ok:true but moved nothing" lie is the original bug — we
+ *      refuse to paper over it).
+ *   2. Then run the LiveTestHarness over a scenario matrix that sends a real message
+ *      through each channel and asserts the reply was served FROM the target machine
+ *      (the `responderMachine` expectation — the deterministic cross-machine proof).
+ *
+ * This module is pure orchestration over the injected harness + an injected `transfer`
+ * action, so it is unit-testable with fakes. The server.ts route wires the real
+ * RealChannelDriver (real senders + placement reader) into the harness and the real
+ * `POST /pool/transfer` into `transfer`.
+ *
+ * Honesty contract: a non-moved seat THROWS (never records a misleading PASS); a moved
+ * seat that then fails to reply-from-target is a normal harness FAIL (recorded with the
+ * responder mismatch). The artifact only ever shows PASS when the seat moved AND the
+ * reply genuinely came from the target machine.
+ */
+import type { LiveTestHarness } from './LiveTestHarness.js';
+export interface TransferResult {
+    /** Did the seat genuinely move (the honest signal, NOT a bare ok:true)? */
+    seatMoved: boolean;
+    detail?: string;
+}
+export interface MultiMachineCapstoneOpts {
+    featureId?: string;
+    /** The machine the seat must move to (e.g. the Mini's machine id) — also the expected responder. */
+    targetMachine: string;
+    /** The throwaway Telegram topic id (also the placement key the responder reader uses). */
+    telegramTopicId: string;
+    /** Optional Slack channel id for the Slack half of the Telegram-AND-Slack bar. */
+    slackChannelId?: string;
+    /** The real transfer action (server.ts injects POST /pool/transfer). MUST report seatMoved honestly. */
+    transfer: (topicId: string, toMachine: string) => Promise<TransferResult>;
+    /** The user message to send (default a benign probe). */
+    message?: string;
+    timeoutMs?: number;
+    runId?: string;
+}
+export declare class LiveTestRunnerError extends Error {
+    constructor(message: string);
+}
+export declare class LiveTestRunner {
+    private readonly deps;
+    constructor(deps: {
+        harness: LiveTestHarness;
+        logger?: (m: string) => void;
+    });
+    private log;
+    /**
+     * Run the multi-machine transfer capstone. Throws LiveTestRunnerError if the seat did
+     * not move (the capstone cannot meaningfully run). Otherwise returns the harness
+     * artifact (PASS only when the reply came FROM `targetMachine`).
+     */
+    runMultiMachineTransferCapstone(opts: MultiMachineCapstoneOpts): Promise<{
+        artifact: import("./LiveTestArtifactStore.js").LiveTestArtifact;
+        entry: ReturnType<import("./LiveTestArtifactStore.js").LiveTestArtifactStore["write"]>;
+    }>;
+}
+//# sourceMappingURL=LiveTestRunner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LiveTestRunner.d.ts","sourceRoot":"","sources":["../../src/core/LiveTestRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkC,MAAM,sBAAsB,CAAC;AAG5F,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,aAAa,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,eAAe,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wGAAwG;IACxG,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1E,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAC5B;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE;QAAE,OAAO,EAAE,eAAe,CAAC;QAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE;IAE7F,OAAO,CAAC,GAAG;IAEX;;;;OAIG;IACG,+BAA+B,CAAC,IAAI,EAAE,wBAAwB;;;;CAiDrE"}

package/dist/core/LiveTestRunner.js

@@ -0,0 +1,85 @@
+/**
+ * LiveTestRunner — the orchestrator that APPLIES the live-user-channel-proof standard
+ * to the cross-machine transfer (docs/specs/live-user-channel-proof-standard.md §6 —
+ * the first feature held to the bar). It encodes the capstone flow that a user-role
+ * session runs:
+ *
+ *   1. MOVE THE SEAT FIRST — transfer the (throwaway) topic to the target machine.
+ *      If the transfer reports the seat did NOT move, the capstone premise is false and
+ *      we stop loudly (that "ok:true but moved nothing" lie is the original bug — we
+ *      refuse to paper over it).
+ *   2. Then run the LiveTestHarness over a scenario matrix that sends a real message
+ *      through each channel and asserts the reply was served FROM the target machine
+ *      (the `responderMachine` expectation — the deterministic cross-machine proof).
+ *
+ * This module is pure orchestration over the injected harness + an injected `transfer`
+ * action, so it is unit-testable with fakes. The server.ts route wires the real
+ * RealChannelDriver (real senders + placement reader) into the harness and the real
+ * `POST /pool/transfer` into `transfer`.
+ *
+ * Honesty contract: a non-moved seat THROWS (never records a misleading PASS); a moved
+ * seat that then fails to reply-from-target is a normal harness FAIL (recorded with the
+ * responder mismatch). The artifact only ever shows PASS when the seat moved AND the
+ * reply genuinely came from the target machine.
+ */
+export class LiveTestRunnerError extends Error {
+    constructor(message) { super(message); this.name = 'LiveTestRunnerError'; }
+}
+export class LiveTestRunner {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    log(m) { this.deps.logger?.(`[live-test-runner] ${m}`); }
+    /**
+     * Run the multi-machine transfer capstone. Throws LiveTestRunnerError if the seat did
+     * not move (the capstone cannot meaningfully run). Otherwise returns the harness
+     * artifact (PASS only when the reply came FROM `targetMachine`).
+     */
+    async runMultiMachineTransferCapstone(opts) {
+        // 1. Move the seat FIRST — and demand the honest seatMoved signal.
+        const t = await opts.transfer(opts.telegramTopicId, opts.targetMachine);
+        if (!t.seatMoved) {
+            throw new LiveTestRunnerError(`transfer to ${opts.targetMachine} did not move the seat (${t.detail ?? 'seatMoved=false'}) — ` +
+                `capstone cannot run (refusing to record a misleading PASS over a non-move)`);
+        }
+        this.log(`seat moved to ${opts.targetMachine}; running channel scenarios`);
+        // 2. Build the matrix — each channel asserts the reply was served FROM targetMachine.
+        const message = (opts.message ?? `live-test probe ${opts.runId ?? ''}`).trim();
+        const surfaces = opts.slackChannelId ? ['telegram', 'slack'] : ['telegram'];
+        const scenarios = [
+            {
+                id: 'mm-transfer-telegram-reply-from-target',
+                description: `after transfer to ${opts.targetMachine}, the Telegram reply is served FROM it`,
+                surface: 'telegram',
+                riskCategory: 'happy-path',
+                volatility: 'safe',
+                channelId: opts.telegramTopicId,
+                input: message,
+                expect: { replyNotEmpty: true, responderMachine: opts.targetMachine },
+                ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}),
+            },
+        ];
+        if (opts.slackChannelId) {
+            scenarios.push({
+                id: 'mm-transfer-slack-reply-from-target',
+                description: `after transfer to ${opts.targetMachine}, the Slack reply is served FROM it (channel parity)`,
+                surface: 'slack',
+                riskCategory: 'channel-parity',
+                volatility: 'safe',
+                channelId: opts.slackChannelId,
+                input: message,
+                expect: { replyNotEmpty: true, responderMachine: opts.targetMachine },
+                ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}),
+            });
+        }
+        const matrix = {
+            featureId: opts.featureId ?? 'multi-machine-transfer',
+            surfaces,
+            riskCategories: opts.slackChannelId ? ['happy-path', 'channel-parity'] : ['happy-path'],
+            scenarios,
+        };
+        return this.deps.harness.run(matrix, opts.runId ? { runId: opts.runId } : {});
+    }
+}
+//# sourceMappingURL=LiveTestRunner.js.map

package/dist/core/LiveTestRunner.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.596",
+  "version": "1.3.597",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-16T10:35:02.431Z",
-  "instarVersion": "1.3.596",
+  "generatedAt": "2026-06-16T10:44:35.492Z",
+  "instarVersion": "1.3.597",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.597.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`LiveTestRunner` (spec §6) — the orchestrator that applies the live-test standard to the cross-machine transfer, ships DARK (not wired). It transfers the throwaway topic to the target machine, demands the honest `seatMoved` signal (throws if the seat didn't move — no misleading PASS over the original "ok:true but moved nothing" bug), then runs the LiveTestHarness over a matrix asserting the reply was served FROM the target machine (the cross-machine proof). Pure orchestration over an injected harness + transfer action.
+
+## What to Tell Your User
+
+Nothing yet — internal harness infrastructure, ships dark (no runtime surface). The payoff is the capstone: proving a real Laptop↔Mini seat move with a reply served from the destination, through the real channels.
+
+## Summary of New Capabilities
+
+None user-facing. Internally: the orchestration that runs the multi-machine transfer capstone and records the signed PASS/FAIL artifact. No new routes, config, or flags (the route wrapper is the next increment).
+
+## Evidence
+
+- `tests/unit/LiveTestRunner.test.ts` — 5 tests: non-move throws (no harness run), moved+reply-from-target→PASS, moved+wrong-machine→FAIL, slack channel-parity scenario added, empty-reply→FAIL.
+- `tsc --noEmit` clean. instar-dev gate green.

package/upgrades/side-effects/live-test-runner.md

@@ -0,0 +1,28 @@
+# Side-Effects Review — LiveTestRunner (multi-machine transfer capstone orchestrator)
+
+**Slug:** live-test-runner
+**Spec:** docs/specs/live-user-channel-proof-standard.md §6 (apply the standard to multi-machine — the first feature)
+**Files:** src/core/LiveTestRunner.ts, tests/unit/LiveTestRunner.test.ts
+**Posture:** ships DARK — pure orchestration over an injected harness + transfer action. NOT wired into server.ts.
+
+## What it is
+LiveTestRunner encodes the capstone flow: (1) transfer the throwaway topic to the target machine and DEMAND the honest `seatMoved` signal (throw if it didn't move — refuse a misleading PASS over the original "ok:true but moved nothing" bug); (2) run the LiveTestHarness over a matrix that sends a real message per channel and asserts the reply was served FROM the target machine (the `responderMachine` expectation = the cross-machine proof).
+
+## Phase 1 — Principle check (signal vs authority)
+Not a decision gate over agent behavior — it's a test orchestrator. The one control-flow decision (throw on `seatMoved===false`) is a FAIL-LOUD on a test premise, not a runtime authority over messages/sessions. Compliant: it produces a PASS/FAIL artifact (a signal the completion gate already consumes), holds no blocking authority.
+
+## Phase 4 — Side-effects answers
+1. **Over-block** — n/a (no runtime block). Throwing on a non-moved seat is intended: it prevents recording a PASS when the premise failed. The alternative (running anyway) would manufacture a misleading verdict.
+2. **Under-block** — the runner trusts the injected `transfer`'s `seatMoved`. If a transfer LIES (reports seatMoved=true but didn't move), the harness still catches it downstream: the reply's `responderMachine` won't equal target → FAIL. So a lying transfer can't produce a false PASS — the responder assertion is the real backstop.
+3. **Level-of-abstraction fit** — correct: thin orchestration over the merged harness + an injected transfer. It does NOT reimplement transfer or the harness; it sequences them. The server.ts route injects the real `/pool/transfer` + RealChannelDriver.
+4. **Signal vs authority** — compliant (produces an artifact; no authority).
+5. **Interactions** — none yet (dark, unwired). When wired, it CALLS `/pool/transfer` (a real seat move on a THROWAWAY topic) then sends real messages — those surfaces are the server.ts route's review. The runner itself only sequences injected actions.
+6. **External surfaces** — none in this increment (unwired). When wired, the real transfer + sends are external — but scoped to a throwaway topic/demo channel by the caller (the §5.3 isolation in DemoChannelRegistry + the throwaway-topic choice).
+7. **Multi-machine posture** — this IS the multi-machine capstone: it proves a seat moves between machines and the reply is served from the destination. The `responderMachine` assertion (via the driver's placement reader, which reads the authoritative `/pool/placement`) is the cross-machine proof. No single-machine assumption — the whole point is cross-machine.
+8. **Rollback cost** — trivial: dark, unwired. Revert the commit.
+
+## No-deferrals
+The server.ts route (`POST /live-test/run`) that wires the real driver + transfer, and the demo-channel sender-credential provisioning, are the NEXT tracked steps (CMT-1568, `.instar/plans/live-test-harness-drivers-BUILD.md` GATE 1/2), not deferrals of this orchestrator. This module is complete + unit-tested (5 tests: non-move throws, moved+reply-from-target PASS, wrong-machine FAIL, slack-parity scenario, empty-reply FAIL).
+
+## Phase 5 — Second-pass review
+Borderline (it has a control-flow throw), but it adds no runtime authority over messages/sessions/lifecycle — it orchestrates a test and records an artifact. The genuine cross-machine safety (no false PASS) rests on the harness's responder assertion (reviewed in #1195/#1196), which this can't bypass. Not required; noted.