instar 1.3.594 → 1.3.595

package/dist/core/DemoChannelRegistry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * DemoChannelRegistry — the §5.3 isolation backbone of the live-user-channel-proof
+ * standard (docs/specs/live-user-channel-proof-standard.md §5.3 "Demo Channel
+ * Isolation").
+ *
+ * A volatile / permission / dangerous live-test scenario must NEVER touch the live
+ * operator channel — it runs only on a registered DEMO channel (a throwaway Slack
+ * workspace, a demo Telegram group). The LiveTestHarness enforces this structurally
+ * by calling `isDemoChannel(surface, channelId)` and refusing the whole run (a throw,
+ * not a convention) if a non-safe scenario points at a channel this registry does not
+ * vouch for.
+ *
+ * The bindings are SIGNED and read once. A binding set that fails signature
+ * verification (tampered, unsigned, wrong signer) is FAIL-CLOSED: every channel
+ * resolves to NOT-a-demo-channel, so the harness's §5.3 guard refuses every volatile
+ * scenario rather than trusting an unverified "this is a safe demo channel" claim.
+ * Fail-closed is the safe direction here — the cost of a false "not demo" is a refused
+ * test; the cost of a false "is demo" is a destructive scenario on the live channel.
+ *
+ * This module is pure/injectable: it takes the raw bindings document + a `verify`
+ * function (Ed25519, same signer surface the LiveTestArtifactStore uses) so it is
+ * unit-testable with no filesystem or crypto host.
+ */
+import type { Surface } from './LiveTestArtifactStore.js';
+/** One registered demo channel. `workspaceId` is Slack-only (the demo workspace). */
+export interface DemoChannelBinding {
+    surface: Surface;
+    /** Slack channel id, Telegram chat/topic id (as a string), or dashboard id. */
+    channelId: string;
+    /** Slack workspace / team id — REQUIRED for slack, ignored otherwise. */
+    workspaceId?: string;
+    /** Human label for audit (e.g. "SageMind Live Test"). */
+    label?: string;
+}
+/** The on-disk, signed bindings document. */
+export interface DemoChannelBindingsDoc {
+    version: 1;
+    /** The machine that authored these bindings (audit only). */
+    machineId: string;
+    bindings: DemoChannelBinding[];
+    signedAt: string;
+    /** Ed25519 signature over the canonical payload (see canonicalBindingsPayload). */
+    signature: string;
+}
+export interface DemoChannelRegistryDeps {
+    /** The raw bindings document (e.g. parsed from state/demo-channel-bindings.json), or null when none exist. */
+    doc: DemoChannelBindingsDoc | null;
+    /** Verify a signature over a canonical payload string. Returns true iff valid. */
+    verify: (payload: string, signature: string) => boolean;
+    logger?: (m: string) => void;
+}
+/**
+ * The exact bytes the signature covers. Stable, order-independent across the binding
+ * LIST (sorted) so a re-serialization can't change the signed payload, but the
+ * signature is otherwise over the full meaningful content (version + machineId +
+ * signedAt + every binding field). Any field change invalidates the signature.
+ */
+export declare function canonicalBindingsPayload(doc: Omit<DemoChannelBindingsDoc, 'signature'>): string;
+export declare class DemoChannelRegistry {
+    private readonly verified;
+    private readonly set;
+    private readonly d;
+    constructor(deps: DemoChannelRegistryDeps);
+    private key;
+    private log;
+    /** True iff (surface, channelId) is a verified, registered demo channel. */
+    isDemoChannel(surface: Surface, channelId: string): boolean;
+    /** Whether a present bindings doc verified (false when none exist OR signature failed). */
+    get isVerified(): boolean;
+    /** Count of registered demo channels (0 when unverified/absent). */
+    get size(): number;
+}
+//# sourceMappingURL=DemoChannelRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DemoChannelRegistry.d.ts","sourceRoot":"","sources":["../../src/core/DemoChannelRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAE1D,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,CAAC,CAAC;IACX,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,8GAA8G;IAC9G,GAAG,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACnC,kFAAkF;IAClF,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACxD,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,IAAI,CAAC,sBAAsB,EAAE,WAAW,CAAC,GAAG,MAAM,CAkB/F;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAA0B;gBAEhC,IAAI,EAAE,uBAAuB;IA6BzC,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,GAAG;IAEX,4EAA4E;IAC5E,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAI3D,2FAA2F;IAC3F,IAAI,UAAU,IAAI,OAAO,CAA0B;IAEnD,oEAAoE;IACpE,IAAI,IAAI,IAAI,MAAM,CAA0B;CAC7C"}

package/dist/core/DemoChannelRegistry.js

@@ -0,0 +1,97 @@
+/**
+ * DemoChannelRegistry — the §5.3 isolation backbone of the live-user-channel-proof
+ * standard (docs/specs/live-user-channel-proof-standard.md §5.3 "Demo Channel
+ * Isolation").
+ *
+ * A volatile / permission / dangerous live-test scenario must NEVER touch the live
+ * operator channel — it runs only on a registered DEMO channel (a throwaway Slack
+ * workspace, a demo Telegram group). The LiveTestHarness enforces this structurally
+ * by calling `isDemoChannel(surface, channelId)` and refusing the whole run (a throw,
+ * not a convention) if a non-safe scenario points at a channel this registry does not
+ * vouch for.
+ *
+ * The bindings are SIGNED and read once. A binding set that fails signature
+ * verification (tampered, unsigned, wrong signer) is FAIL-CLOSED: every channel
+ * resolves to NOT-a-demo-channel, so the harness's §5.3 guard refuses every volatile
+ * scenario rather than trusting an unverified "this is a safe demo channel" claim.
+ * Fail-closed is the safe direction here — the cost of a false "not demo" is a refused
+ * test; the cost of a false "is demo" is a destructive scenario on the live channel.
+ *
+ * This module is pure/injectable: it takes the raw bindings document + a `verify`
+ * function (Ed25519, same signer surface the LiveTestArtifactStore uses) so it is
+ * unit-testable with no filesystem or crypto host.
+ */
+/**
+ * The exact bytes the signature covers. Stable, order-independent across the binding
+ * LIST (sorted) so a re-serialization can't change the signed payload, but the
+ * signature is otherwise over the full meaningful content (version + machineId +
+ * signedAt + every binding field). Any field change invalidates the signature.
+ */
+export function canonicalBindingsPayload(doc) {
+    // Each binding is encoded as an ORDERED JSON tuple, NOT a delimiter-free
+    // concatenation. A concatenation like `${surface}${channelId}${workspaceId}` is
+    // ambiguous at field boundaries ({channelId:'C1',workspaceId:'W2'} vs
+    // {channelId:'C1W2'} would serialize identically and share one signature — a
+    // real bypass that promotes an unvouched channelId to a demo channel). A JSON
+    // tuple makes every field boundary explicit and distinguishes an absent field
+    // (null) from a present empty string (''), so one signature covers exactly one
+    // binding set.
+    const norm = (b) => JSON.stringify([b.surface, b.channelId, b.workspaceId ?? null, b.label ?? null]);
+    const lines = [...doc.bindings].map(norm).sort();
+    return [
+        `v=${doc.version}`,
+        `machine=${doc.machineId}`,
+        `signedAt=${doc.signedAt}`,
+        ...lines.map((l) => `b=${l}`),
+    ].join('\n');
+}
+export class DemoChannelRegistry {
+    verified;
+    set;
+    d;
+    constructor(deps) {
+        this.d = deps;
+        const { doc } = deps;
+        if (!doc) {
+            // No bindings at all is a legitimate state (safe-only test runs). It is NOT an
+            // error — it simply means there are zero demo channels, so isDemoChannel is
+            // always false and only safe scenarios can run.
+            this.verified = false;
+            this.set = new Set();
+            return;
+        }
+        const { signature, ...unsigned } = doc;
+        let ok = false;
+        try {
+            ok = this.d.verify(canonicalBindingsPayload(unsigned), signature);
+        }
+        catch (err) {
+            this.log(`verify threw (treating as unverified): ${err instanceof Error ? err.message : String(err)}`);
+            ok = false;
+        }
+        this.verified = ok;
+        if (!ok) {
+            // Fail-closed: a present-but-unverifiable bindings doc grants ZERO demo channels.
+            this.log(`bindings present but signature INVALID — fail-closed (0 demo channels; volatile scenarios will be refused)`);
+            this.set = new Set();
+            return;
+        }
+        this.set = new Set(doc.bindings.map((b) => this.key(b.surface, b.channelId)));
+    }
+    key(surface, channelId) {
+        // Unambiguous (JSON tuple) for the same reason canonicalBindingsPayload uses one —
+        // so a lookup key can never alias across the surface/channelId boundary. (Safe
+        // today since surface is a closed enum, but encoded explicitly for defense-in-depth.)
+        return JSON.stringify([surface, channelId]);
+    }
+    log(m) { this.d.logger?.(`[demo-channel-registry] ${m}`); }
+    /** True iff (surface, channelId) is a verified, registered demo channel. */
+    isDemoChannel(surface, channelId) {
+        return this.set.has(this.key(surface, channelId));
+    }
+    /** Whether a present bindings doc verified (false when none exist OR signature failed). */
+    get isVerified() { return this.verified; }
+    /** Count of registered demo channels (0 when unverified/absent). */
+    get size() { return this.set.size; }
+}
+//# sourceMappingURL=DemoChannelRegistry.js.map

package/dist/core/DemoChannelRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DemoChannelRegistry.js","sourceRoot":"","sources":["../../src/core/DemoChannelRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAkCH;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAA8C;IACrF,yEAAyE;IACzE,gFAAgF;IAChF,sEAAsE;IACtE,6EAA6E;IAC7E,8EAA8E;IAC9E,8EAA8E;IAC9E,+EAA+E;IAC/E,eAAe;IACf,MAAM,IAAI,GAAG,CAAC,CAAqB,EAAE,EAAE,CACrC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC;IACnF,MAAM,KAAK,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,OAAO;QACL,KAAK,GAAG,CAAC,OAAO,EAAE;QAClB,WAAW,GAAG,CAAC,SAAS,EAAE;QAC1B,YAAY,GAAG,CAAC,QAAQ,EAAE;QAC1B,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;KAC9B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,OAAO,mBAAmB;IACb,QAAQ,CAAU;IAClB,GAAG,CAAc;IACjB,CAAC,CAA0B;IAE5C,YAAY,IAA6B;QACvC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QACd,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,+EAA+E;YAC/E,4EAA4E;YAC5E,gDAAgD;YAChD,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;YACtB,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,GAAG,GAAG,CAAC;QACvC,IAAI,EAAE,GAAG,KAAK,CAAC;QACf,IAAI,CAAC;YACH,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,wBAAwB,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,0CAA0C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACvG,EAAE,GAAG,KAAK,CAAC;QACb,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QACnB,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,kFAAkF;YAClF,IAAI,CAAC,GAAG,CAAC,4GAA4G,CAAC,CAAC;YACvH,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAEO,GAAG,CAAC,OAAgB,EAAE,SAAiB;QAC7C,mFAAmF;QACnF,+EAA+E;QAC/E,sFAAsF;QACtF,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAC9C,CAAC;IACO,GAAG,CAAC,CAAS,IAAU,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,2BAA2B,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEjF,4EAA4E;IAC5E,aAAa,CAAC,OAAgB,EAAE,SAAiB;QAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,2FAA2F;IAC3F,IAAI,UAAU,KAAc,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEnD,oEAAoE;IACpE,IAAI,IAAI,KAAa,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;CAC7C"}

package/dist/core/RealChannelDriver.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RealChannelDriver — the production `ChannelDriver` for the LiveTestHarness
+ * (docs/specs/live-user-channel-proof-standard.md §5.4 "Platform-Sanctioned
+ * Automation"). It drives a feature end-to-end through the REAL user surfaces by
+ * composing one `SurfaceSender` per surface (Telegram, Slack, dashboard) plus:
+ *
+ *   - a DemoChannelRegistry → `isDemoChannel` (§5.3 isolation), and
+ *   - a `resolveResponderMachine` reader → the `responderMachineId` stamped on every
+ *     reply, which is the DETERMINISTIC cross-machine proof the harness asserts on
+ *     (e.g. "after the transfer, the reply was served FROM the Mini").
+ *
+ * The driver itself is pure transport composition: it knows nothing about HTTP,
+ * Telegram, or Slack — each surface sender + the placement reader are injected, so
+ * this module is fully unit-testable with fakes. The real senders (a demo-bot/user
+ * Telegram sender, a Slack user-token sender) and the real placement reader (a
+ * GET /pool/placement call) are wired at construction in server.ts.
+ *
+ * Safety: a surface with no registered sender is a hard error on use (never a silent
+ * skip that would fabricate a "no reply" FAIL), and `responderMachineId` resolution
+ * failures degrade to `undefined` (the harness then simply can't assert on responder)
+ * rather than throwing the whole scenario — the SEND/REPLY evidence is still recorded.
+ */
+import type { ChannelDriver, SendResult, ReplyResult } from './LiveTestHarness.js';
+import type { Surface } from './LiveTestArtifactStore.js';
+import type { DemoChannelRegistry } from './DemoChannelRegistry.js';
+/** One real surface transport. `channelId` is the surface-native id (topic id, Slack channel). */
+export interface SurfaceSender {
+    /** Send a USER-role message on the real surface. */
+    send(channelId: string, text: string): Promise<SendResult>;
+    /** Await the agent's reply after `afterMessageId` (null on timeout). No responder id — the driver stamps that. */
+    awaitReply(channelId: string, opts: {
+        timeoutMs: number;
+        afterMessageId?: string;
+    }): Promise<Omit<ReplyResult, 'responderMachineId'> | null>;
+}
+export interface RealChannelDriverDeps {
+    /** Per-surface real senders. A surface absent here throws if a scenario targets it. */
+    senders: Partial<Record<Surface, SurfaceSender>>;
+    /** §5.3 demo-channel isolation. */
+    demoRegistry: Pick<DemoChannelRegistry, 'isDemoChannel'>;
+    /**
+     * Resolve WHICH machine served (owns) the given channel at reply time — the
+     * cross-machine proof. Returns the machine id (or nickname-resolvable id), or null
+     * if it can't be determined. MUST NOT throw on a transient read error (return null).
+     */
+    resolveResponderMachine: (surface: Surface, channelId: string) => Promise<string | null>;
+    logger?: (m: string) => void;
+}
+export declare class RealChannelDriver implements ChannelDriver {
+    private readonly d;
+    constructor(deps: RealChannelDriverDeps);
+    private log;
+    private senderFor;
+    isDemoChannel(surface: Surface, channelId: string): boolean;
+    send(surface: Surface, channelId: string, text: string): Promise<SendResult>;
+    awaitReply(surface: Surface, channelId: string, opts: {
+        timeoutMs: number;
+        afterMessageId?: string;
+    }): Promise<ReplyResult | null>;
+}
+//# sourceMappingURL=RealChannelDriver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RealChannelDriver.d.ts","sourceRoot":"","sources":["../../src/core/RealChannelDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3D,kHAAkH;IAClH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,oBAAoB,CAAC,GAAG,IAAI,CAAC,CAAC;CAC9I;AAED,MAAM,WAAW,qBAAqB;IACpC,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;IACjD,mCAAmC;IACnC,YAAY,EAAE,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;IACzD;;;;OAIG;IACH,uBAAuB,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzF,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAwB;gBAC9B,IAAI,EAAE,qBAAqB;IAEvC,OAAO,CAAC,GAAG;IAEX,OAAO,CAAC,SAAS;IAUjB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAIrD,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI5E,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CAezI"}

package/dist/core/RealChannelDriver.js

@@ -0,0 +1,60 @@
+/**
+ * RealChannelDriver — the production `ChannelDriver` for the LiveTestHarness
+ * (docs/specs/live-user-channel-proof-standard.md §5.4 "Platform-Sanctioned
+ * Automation"). It drives a feature end-to-end through the REAL user surfaces by
+ * composing one `SurfaceSender` per surface (Telegram, Slack, dashboard) plus:
+ *
+ *   - a DemoChannelRegistry → `isDemoChannel` (§5.3 isolation), and
+ *   - a `resolveResponderMachine` reader → the `responderMachineId` stamped on every
+ *     reply, which is the DETERMINISTIC cross-machine proof the harness asserts on
+ *     (e.g. "after the transfer, the reply was served FROM the Mini").
+ *
+ * The driver itself is pure transport composition: it knows nothing about HTTP,
+ * Telegram, or Slack — each surface sender + the placement reader are injected, so
+ * this module is fully unit-testable with fakes. The real senders (a demo-bot/user
+ * Telegram sender, a Slack user-token sender) and the real placement reader (a
+ * GET /pool/placement call) are wired at construction in server.ts.
+ *
+ * Safety: a surface with no registered sender is a hard error on use (never a silent
+ * skip that would fabricate a "no reply" FAIL), and `responderMachineId` resolution
+ * failures degrade to `undefined` (the harness then simply can't assert on responder)
+ * rather than throwing the whole scenario — the SEND/REPLY evidence is still recorded.
+ */
+export class RealChannelDriver {
+    d;
+    constructor(deps) { this.d = deps; }
+    log(m) { this.d.logger?.(`[real-channel-driver] ${m}`); }
+    senderFor(surface) {
+        const s = this.d.senders[surface];
+        if (!s) {
+            // A missing sender is a CONFIGURATION error, surfaced loudly — never a silent
+            // skip that the harness would misread as a clean "no reply" FAIL.
+            throw new Error(`no real sender configured for surface "${surface}" — cannot drive it`);
+        }
+        return s;
+    }
+    isDemoChannel(surface, channelId) {
+        return this.d.demoRegistry.isDemoChannel(surface, channelId);
+    }
+    async send(surface, channelId, text) {
+        return this.senderFor(surface).send(channelId, text);
+    }
+    async awaitReply(surface, channelId, opts) {
+        const reply = await this.senderFor(surface).awaitReply(channelId, opts);
+        if (!reply)
+            return null;
+        let responderMachineId;
+        try {
+            responderMachineId = (await this.d.resolveResponderMachine(surface, channelId)) ?? undefined;
+        }
+        catch (err) {
+            // Degrade, never throw: we still have a real reply; we just can't attribute the
+            // responder machine this round. The harness records the reply evidence and
+            // (only) any responder-machine assertion can't be satisfied.
+            this.log(`responder-machine resolve failed for ${surface}:${channelId} (recording reply without it): ${err instanceof Error ? err.message : String(err)}`);
+            responderMachineId = undefined;
+        }
+        return { ...reply, responderMachineId };
+    }
+}
+//# sourceMappingURL=RealChannelDriver.js.map

package/dist/core/RealChannelDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RealChannelDriver.js","sourceRoot":"","sources":["../../src/core/RealChannelDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4BH,MAAM,OAAO,iBAAiB;IACX,CAAC,CAAwB;IAC1C,YAAY,IAA2B,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAEnD,GAAG,CAAC,CAAS,IAAU,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,yBAAyB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAEvE,SAAS,CAAC,OAAgB;QAChC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,8EAA8E;YAC9E,kEAAkE;YAClE,MAAM,IAAI,KAAK,CAAC,0CAA0C,OAAO,qBAAqB,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,aAAa,CAAC,OAAgB,EAAE,SAAiB;QAC/C,OAAO,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAgB,EAAE,SAAiB,EAAE,IAAY;QAC1D,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAgB,EAAE,SAAiB,EAAE,IAAoD;QACxG,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACxE,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,kBAAsC,CAAC;QAC3C,IAAI,CAAC;YACH,kBAAkB,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,uBAAuB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,IAAI,SAAS,CAAC;QAC/F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,gFAAgF;YAChF,2EAA2E;YAC3E,6DAA6D;YAC7D,IAAI,CAAC,GAAG,CAAC,wCAAwC,OAAO,IAAI,SAAS,kCAAkC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC3J,kBAAkB,GAAG,SAAS,CAAC;QACjC,CAAC;QACD,OAAO,EAAE,GAAG,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC1C,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.594",
+  "version": "1.3.595",
   "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-16T09:33:12.134Z",
-  "instarVersion": "1.3.594",
+  "generatedAt": "2026-06-16T10:03:21.927Z",
+  "instarVersion": "1.3.595",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.595.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added the two pure core modules behind the `LiveTestHarness`'s `ChannelDriver` seam (spec: live-user-channel-proof-standard §5.3/§5.4):
+- `DemoChannelRegistry` — verifies a signed demo-channel bindings doc; fail-closed `isDemoChannel(surface, channelId)` (absent or signature-invalid → zero demo channels). Canonical payload is an ordered JSON tuple so a signature can never be reused on a different binding set (closes a delimiter-collision bypass caught in second-pass review).
+- `RealChannelDriver` — the production `ChannelDriver`: composes per-surface `SurfaceSender`s, dispatches send/awaitReply, and stamps `responderMachineId` on each reply via an injected placement reader (the deterministic cross-machine proof). Degrades-not-throws on a placement-read error; throws loudly on a missing surface sender (never a silent skip).
+
+Ships DARK — not wired into server.ts. The real Telegram/Slack surface senders + the runner route are the next increment.
+
+## What to Tell Your User
+
+Nothing yet — this is internal infrastructure for the gold-standard live-testing harness and ships dark (no runtime surface, no behavior change). The user-visible payoff lands when the harness runs end-to-end and proves a feature through the real Telegram/Slack channels before they ever test it.
+
+## Summary of New Capabilities
+
+None user-facing in this increment. Internally: the building blocks that let the live-test harness drive real user channels and assert WHICH machine served a reply (the cross-machine seat-move proof). No new routes, no config, no flags flipped.
+
+## Evidence
+
+- `tests/unit/DemoChannelRegistry.test.ts` — 9 tests: valid signed bindings resolve, absent → 0, tampered/forged/throwing-verify all fail-closed, cross-boundary signature-collision rejection, absent-vs-empty distinguishability, canonical order-independence + field-sensitivity.
+- `tests/unit/RealChannelDriver.test.ts` — 7 tests: send dispatch, responderMachineId stamping, null-reply short-circuit, placement-error degrade, missing-sender loud throw, isDemoChannel delegation, null-responder.
+- `tsc --noEmit` clean. instar-dev gate green (converged+approved spec, side-effects + second-pass review).

package/upgrades/side-effects/live-test-channel-drivers.md

@@ -0,0 +1,41 @@
+# Side-Effects Review — Live-Test Real Channel Driver core (DemoChannelRegistry + RealChannelDriver)
+
+**Slug:** live-test-channel-drivers
+**Spec:** docs/specs/live-user-channel-proof-standard.md §5.3 (Demo Channel Isolation) + §5.4 (Platform-Sanctioned Automation)
+**Files:** src/core/DemoChannelRegistry.ts, src/core/RealChannelDriver.ts, tests/unit/DemoChannelRegistry.test.ts, tests/unit/RealChannelDriver.test.ts
+**Posture:** ships DARK — two pure/injectable core modules, NOT yet wired into server.ts. No route, no runtime construction. The surface senders + runner route are the next increment (`.instar/plans/live-test-harness-drivers-BUILD.md`).
+
+## What it is
+The production-side building blocks for the `LiveTestHarness`'s `ChannelDriver`:
+- **DemoChannelRegistry** — verifies a SIGNED demo-channel bindings doc and answers `isDemoChannel(surface, channelId)`. Fail-closed: an absent OR signature-invalid doc grants ZERO demo channels.
+- **RealChannelDriver** — composes one `SurfaceSender` per surface, dispatches `send`/`awaitReply`, and stamps `responderMachineId` on every reply via an injected `resolveResponderMachine` reader (the cross-machine proof the harness asserts on).
+
+## Phase 1 — Principle check (signal vs authority)
+This increment touches a decision point — `isDemoChannel` gates whether a volatile/permission scenario may run on a given channel (§5.3). Analysis per `docs/signal-vs-authority.md`:
+- **DemoChannelRegistry is a SIGNAL, not the authority.** It returns a boolean; the *authority* that refuses a run is the already-merged `LiveTestHarness.run` (it throws `HarnessVolatileChannelError`). The registry never blocks anything itself.
+- The registry's logic is **fail-closed**, which is the safe direction for a §5.3 isolation check: a false "not a demo channel" only refuses a test; a false "is a demo channel" would let a destructive scenario touch the live operator channel. Verification failures (tampered/absent/throwing verify) all collapse to "no demo channels."
+- **RealChannelDriver holds no decision authority** — pure transport composition. The one place it could mask a failure (a missing surface sender) throws LOUDLY rather than silently returning "no reply" (which the harness would misread as a clean FAIL).
+
+Verdict: compliant. No brittle check with blocking authority added.
+
+## Phase 4 — Side-effects answers
+1. **Over-block** — `isDemoChannel` could return false for a channel that IS legitimately a demo channel if its signed bindings are absent/stale. Effect: a volatile scenario is refused (the harness throws) rather than running. That is the intended fail-closed direction — it never lets the scenario through, only ever refuses. Safe scenarios (the headline transfer-capstone) don't consult demo status, so they're unaffected.
+2. **Under-block** — the registry only vouches for channels in the signed list; it can't detect that a *non-demo* channel is secretly safe. By design — the harness simply requires volatile scenarios to be on a registered demo channel. No false "allow."
+3. **Level-of-abstraction fit** — correct layer: the registry is a pure data/verification helper feeding the harness gate (which already owns the §5.3 throw). The driver is the transport adapter the harness's injected-`ChannelDriver` seam was explicitly designed for (`LiveTestHarness.ts:8-11`). Neither reinvents a higher-layer gate.
+4. **Signal vs authority** — see Phase 1. Compliant (registry = fail-closed signal; harness = authority; driver = transport).
+5. **Interactions** — none yet: nothing constructs either class at runtime (dark). When wired, the driver composes existing senders + the `/pool/placement` reader; it does not shadow or double-fire any existing check. The registry reads a NEW state file (`state/demo-channel-bindings.json`) that no other component touches.
+6. **External surfaces** — none in this increment. No route, no message send, no other-agent-visible change. (The eventual senders WILL drive real Telegram/Slack — that surface lands in the next, separately-reviewed increment.)
+7. **Multi-machine posture** — `responderMachineId` is the feature's whole multi-machine point: the driver resolves WHICH machine served a reply (via the injected placement reader, which reads the authoritative `/pool/placement`, proxied to the lease-holder). The DemoChannelRegistry is **machine-local BY DESIGN** — demo-channel bindings are an operational/test-fixture fact of the machine running the harness; the harness runs on one machine at a time and asserts cross-machine behavior THROUGH the channel, not by replicating bindings. No silent single-machine assumption: the cross-machine dimension is carried explicitly by `responderMachineId`.
+8. **Rollback cost** — trivial: dark, unwired code. Back-out = revert the commit (or simply never wire it). No data migration, no live state, no fleet behavior change.
+
+## No-deferrals
+The surface senders + runner are NOT a deferral of THIS increment — they are the next tracked increment (CMT-1568, `.instar/plans/live-test-harness-drivers-BUILD.md`). This increment is complete and self-contained: both modules are fully implemented (no stubs/TODOs) and fully unit-tested (16 tests, both sides of every boundary — valid/tampered/absent/throwing/collision/empty-vs-absent for the registry; dispatch/stamp/degrade/missing-sender for the driver).
+
+## Phase 5 — Second-pass review
+An independent reviewer subagent audited the modules + this artifact adversarially.
+
+**Concern raised (and RESOLVED):** `canonicalBindingsPayload`'s per-binding encoding was a delimiter-free concatenation (`${surface}${channelId}${workspaceId}${label}`), an ambiguous field boundary that lets a tampered binding collide to the same signed bytes — e.g. `{channelId:'C1', workspaceId:'W2'}` and `{channelId:'C1W2'}` serialize identically and share one valid signature, promoting an unvouched channelId to a demo channel. That is exactly the dangerous false "is demo" the module guards against.
+
+**Fix applied:** the per-binding encoding is now an ordered JSON tuple (`JSON.stringify([surface, channelId, workspaceId ?? null, label ?? null])`), which makes every field boundary explicit and distinguishes an absent field (`null`) from a present empty string (`''`). The lookup `key()` was hardened the same way (defense-in-depth). Two regression tests added: a cross-boundary collision test (the tampered doc fails verification → the smuggled channel is NOT a demo channel) and an absent-vs-empty distinguishability test. (Also stripped stray `\x01` control bytes that had crept into the source — invisible and git-binary-fragile.)
+
+Re-review verdict after fix: the collision is closed; the surface↔channelId boundary was already safe (surface is a closed enum, none a prefix of another); fail-closed paths and the driver's degrade-not-throw / loud-missing-sender behavior are correct. **Concur with the review (post-fix).**