super-dsh 0.1.6 → 0.1.9

package/superd-hub/dist/rpc.js

@@ -1,11 +1,20 @@
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { PACK_VERSION } from './pack-version.js';
 import { listRuntimeKeys } from './targets.js';
 import { agentLinks } from './agent-roster.js';
+import { ensureSelf } from './machines.js';
 /** The shared-channel Fetch route path this RPC face owns. */
 export const AGENT_RUNTIME_RPC_PATH = '/api/agent-runtime';
 /** The live registry view: native plus every registered foreign context. */
 export const registryTargets = {
     listRuntimes: listRuntimeKeys,
 };
+/** The version this hub SERVES as `hub.version` — the super-dsh PACK version
+ * (D6): the subpackage's own 0.1.0 never moves, so peers comparing against it
+ * could never see a mismatch. The pack manifest ships exactly two hops above
+ * the compiled output in every layout (see pack-version.ts); 'unknown' when
+ * unreadable — an honest non-number, not a fake one. */
+const HUB_VERSION = PACK_VERSION;
 function json(status, body) {
     return new Response(JSON.stringify(body), {
         status,
@@ -14,16 +23,35 @@ function json(status, body) {
 }
 /**
  * The control-plane handler: world inventory only.
+ *
+ * ADDITIVE contract (mesh P1): the GET body gained `hub: {machineId, label,
+ * version}` and every `agents` row gained `id` (a6); `available` and all
+ * pre-existing agents fields are unchanged — old clients ignore the new
+ * fields, new clients read them.
  * @param request - the incoming `/api/agent-runtime` request.
  * @param source - live runtime registry view.
+ * @param deps - optional home override; defaults to `resolveDshHome()`.
  * @returns the JSON response.
  */
-export async function handleAgentRuntime(request, source) {
+export async function handleAgentRuntime(request, source, deps) {
     const available = source.listRuntimes();
     if (request.method === 'GET' || request.method === 'HEAD') {
         // The selector asks this face for the roster: keys AND the mount path each
-        // key is addressed by. Read-only — the roster carries no selection.
-        return json(200, { available, agents: agentLinks() });
+        // key is addressed by. Read-only — the roster carries no selection. The
+        // hub block (this machine's m4 + label + hub version) rides along for the
+        // multi-machine UI; the a6 row ids ride on every agents row.
+        const home = deps?.home ?? resolveDshHome();
+        const self = ensureSelf(home, 'local');
+        // Self-description discipline (2026-09-28 user ruling): a peer's discovery
+        // probe (`?mesh=1`) receives THIS machine's own rows only — a hub never
+        // re-broadcasts other remotes' agents to its peers (hub-to-hub is P2P;
+        // the requester fans out one probe per paired machine and merges itself).
+        // The plain browser GET keeps the full roster — the local UI's machine
+        // grouping consumes exactly that.
+        const links = new URL(request.url).searchParams.get('mesh') === '1'
+            ? agentLinks(home).filter((l) => l.machine === 'local')
+            : agentLinks(home);
+        return json(200, { available, agents: links, hub: { machineId: self.id, label: self.label, version: HUB_VERSION } });
     }
     // A POST that used to switch a global selector has no meaning any more:
     // the addressed world is the mount path of the request, not a shared value.
@@ -35,7 +63,9 @@ export async function handleAgentRuntime(request, source) {
 /**
  * Register the control-plane RPC face on the shared `/api` connection channel
  * (behind the standard browser-trust + auth fence). No-op when the
- * `connection` service is absent (e.g. fake-ctx unit tests).
+ * `connection` service is absent (e.g. fake-ctx unit tests). The route answers
+ * with the DEFAULT home (`resolveDshHome()` at request time); callers needing
+ * a pinned home invoke handleAgentRuntime directly with deps.
  */
 export function registerSelectorRpc(ctx, source) {
     ctx.inject(['connection'], (connCtx) => {

package/superd-hub/dist/spawn-world.js

@@ -71,7 +71,9 @@ async function publishWorldInHostResolutionTurn(packages, launcher, opts, worldP
     const declarer = join(worldProfileDir, 'package.json');
     const worldScope = join(worldProfileDir, 'node_modules', '@pgmi-builds');
     const baseNames = new Set(base.entries.map((entry) => entry.name));
-    for (const name of readdirSync(worldScope, { withFileTypes: true })) {
+    // R0 scan guard: a dsh-base world has NO farm — a missing scope is not a
+    // publish failure, just nothing to add (existsSync before readdirSync).
+    for (const name of existsSync(worldScope) ? readdirSync(worldScope, { withFileTypes: true }) : []) {
         if (!name.isDirectory() && !name.isSymbolicLink())
             continue;
         const pkgName = `@pgmi-builds/${name.name}`;

package/superd-hub/dist/switch-core.d.ts

@@ -457,8 +457,13 @@ export interface HubRosterRow {
     readonly label: string;
     /** The row's mount path. */
     readonly path: string;
-    /** Machine the runtime comes from (the roster parser guarantees it — `'local'` when an older host shape omitted it). */
-    readonly machine: string;
+    /**
+     * Machine the runtime comes from (mesh P2): `'local'` for this machine's
+     * rows, the owning machine's m4 for federated rows. Optional — the wire
+     * may omit it and the grouping now lives client-side (mesh-groups.ts,
+     * fed the machines API's label map).
+     */
+    readonly machine?: string;
 }
 /**
  * The active agent's display name for the Hub row's right-edge selector: the
@@ -470,25 +475,6 @@ export interface HubRosterRow {
  * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
  */
 export declare function activeAgentName(activeAgent: string | undefined, roster: readonly HubRosterRow[]): string | undefined;
-/** Which machine one roster row groups under: the row's own machine (parser-guaranteed). */
-export declare function machineGroup(row: HubRosterRow): string;
-/** One machine's group of roster rows, in roster order. */
-export interface MachineGroup {
-    /** The grouping key (the members' shared `machine`). */
-    readonly machine: string;
-    /** The rows of this machine, keeping the roster's own order. */
-    readonly agents: readonly HubRosterRow[];
-}
-/**
- * Group a roster by machine for the HubPanelIcon chevron menu's native
- * workspace-list look: one group per distinct `machineGroup` key, groups in
- * first-appearance order, members keeping the roster's order inside their
- * group. A single-group roster (today's local-only shape) renders exactly
- * like the old flat list minus the card border.
- *
- * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
- */
-export declare function machineGroups(rows: readonly HubRosterRow[]): readonly MachineGroup[];
 /**
  * What the machine hands the host's gate composition (T-G): the machine-side
  * ingredients of {@link LandingGateOptions}. Structurally a full
@@ -628,19 +614,70 @@ export interface SwitchController {
  * switch's pointer-restored view).
  */
 export declare function createSwitchController(host: SwitchHost, options?: SwitchOptions): SwitchController;
-/** What attemptSwitch does with a roster row: run the machine / report failure / wait for readiness. */
-export type PreFlightDecision = 'run' | 'failed' | 'wait';
-/** The roster fields the pre-flight reads (the projection carries both since C1 task 3). */
+/** What attemptSwitch does with a roster row: run the machine / report failure / wait for readiness / fail fast on a degraded federated row. */
+export type PreFlightDecision = 'run' | 'failed' | 'wait' | 'machine-down';
+/**
+ * The roster fields the pre-flight reads (the projection carries both since
+ * C1 task 3; `machine` since the mesh P2 roster dimension).
+ */
 export interface PreFlightRow {
     ready?: boolean;
     failed?: boolean;
+    /**
+     * Owning machine (m4) for FEDERATED rows — `'local'` or absent means this
+     * machine's own world (the C1 spawn-wait semantics). The client's
+     * `AgentLink` satisfies this structurally; the field decides the I1(c)
+     * fail-fast branch.
+     */
+    machine?: string;
 }
 /**
  * The pure pre-flight decision. `native` always runs; an absent row (roster
  * fetch failed, or the key is not listed) also runs — the machine's roster
- * probe is the authority on unknown targets, exactly as before C1.
+ * probe is the authority on unknown targets, exactly as before C1. A
+ * not-ready FEDERATED row (`machine` set and not `'local'`) decides
+ * `'machine-down'` — an immediate actionable failure, never a wait loop
+ * (the hub's probe already knows the machine is unreachable or its auth
+ * expired); `failed` keeps precedence everywhere (a peer-reported spawn
+ * rejection still reports as failed).
  */
 export declare function decidePreFlight(label: string, row: PreFlightRow | undefined): PreFlightDecision;
+/** Bound on the machine-down branch's enrichment fetch (mesh P3 Task 5a:
+ *  the parked P2 minor — an unbounded `fetchMachines` await — folds here; a
+ *  hung hub answer must never swallow the toast). */
+export declare const MACHINE_DOWN_ENRICH_MS = 3000;
+/** The machines-face slice the machine-down feedback reads (the client's
+ *  `fetchMachines()` satisfies this structurally). */
+export interface MachineDownMachinesFace {
+    machines: readonly {
+        id: string;
+        label: string;
+        status: string;
+    }[];
+}
+/** The branch's injected faces — the browser wiring supplies the real
+ *  fetch/reprobe/toast; tests fake all of them. */
+export interface MachineDownFaces {
+    /** Same-origin GET of the hub machine list (enrichment only). */
+    fetchMachines(): Promise<MachineDownMachinesFace>;
+    /** The I1(b) light probe: POST `{op: 'reprobe', id}` — fire-and-forget. */
+    reprobe(id: string): Promise<void>;
+    toast(message: string): void;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+/**
+ * The machine-down branch's pure half (I1(c) feedback + I1(b) light probe,
+ * mesh P3 Task 5a): enrich the toast through the machines face — BOUNDED at
+ * {@link MACHINE_DOWN_ENRICH_MS} — then, after toasting, fire ONE reprobe
+ * for the row's machine and forget it: a stale-unreachable machine gets a
+ * fresh attempt per failed click, so the NEXT click can succeed without
+ * waiting for the hub's 5-minute sweep. Never blocks the UI path (the whole
+ * body is detached), never surfaces a reprobe failure (the sweep retries).
+ */
+export declare function runMachineDownFeedback(label: string, row: PreFlightRow & {
+    label?: string;
+}, faces: MachineDownFaces): void;
 /** Default bound on one readiness wait (the page never locks behind a stuck world). */
 export declare const WAIT_BOUND_MS = 120000;
 /** Default poll interval for one readiness wait. */

package/superd-hub/dist/switch-core.js

@@ -502,34 +502,6 @@ export function activeAgentName(activeAgent, roster) {
         return undefined;
     return roster.find((row) => row.key === activeAgent)?.label ?? activeAgent;
 }
-/** Which machine one roster row groups under: the row's own machine (parser-guaranteed). */
-export function machineGroup(row) {
-    return row.machine;
-}
-/**
- * Group a roster by machine for the HubPanelIcon chevron menu's native
- * workspace-list look: one group per distinct `machineGroup` key, groups in
- * first-appearance order, members keeping the roster's order inside their
- * group. A single-group roster (today's local-only shape) renders exactly
- * like the old flat list minus the card border.
- *
- * Host-half pure logic so `test/client-switch.test.mjs` pins it from `dist/`.
- */
-export function machineGroups(rows) {
-    const groups = [];
-    const byMachine = new Map();
-    for (const row of rows) {
-        const machine = machineGroup(row);
-        let group = byMachine.get(machine);
-        if (group === undefined) {
-            group = { machine, agents: [] };
-            byMachine.set(machine, group);
-            groups.push(group);
-        }
-        group.agents.push(row);
-    }
-    return groups;
-}
 /**
  * Build the switch machine over an injected {@link SwitchHost}.
  *
@@ -735,7 +707,12 @@ export function createSwitchController(host, options = {}) {
 /**
  * The pure pre-flight decision. `native` always runs; an absent row (roster
  * fetch failed, or the key is not listed) also runs — the machine's roster
- * probe is the authority on unknown targets, exactly as before C1.
+ * probe is the authority on unknown targets, exactly as before C1. A
+ * not-ready FEDERATED row (`machine` set and not `'local'`) decides
+ * `'machine-down'` — an immediate actionable failure, never a wait loop
+ * (the hub's probe already knows the machine is unreachable or its auth
+ * expired); `failed` keeps precedence everywhere (a peer-reported spawn
+ * rejection still reports as failed).
  */
 export function decidePreFlight(label, row) {
     if (label === NATIVE_AGENT)
@@ -744,10 +721,56 @@ export function decidePreFlight(label, row) {
         return 'run';
     if (row.failed === true)
         return 'failed';
-    if (row.ready !== true)
+    if (row.ready !== true) {
+        // I1(c): a federated not-ready row is DEGRADED, not spawning — fail fast.
+        if (row.machine !== undefined && row.machine !== 'local')
+            return 'machine-down';
         return 'wait';
+    }
     return 'run';
 }
+// ---- I1(b): the machine-down feedback (preflight light probe) ----------------
+/** Bound on the machine-down branch's enrichment fetch (mesh P3 Task 5a:
+ *  the parked P2 minor — an unbounded `fetchMachines` await — folds here; a
+ *  hung hub answer must never swallow the toast). */
+export const MACHINE_DOWN_ENRICH_MS = 3_000;
+/**
+ * The machine-down branch's pure half (I1(c) feedback + I1(b) light probe,
+ * mesh P3 Task 5a): enrich the toast through the machines face — BOUNDED at
+ * {@link MACHINE_DOWN_ENRICH_MS} — then, after toasting, fire ONE reprobe
+ * for the row's machine and forget it: a stale-unreachable machine gets a
+ * fresh attempt per failed click, so the NEXT click can succeed without
+ * waiting for the hub's 5-minute sweep. Never blocks the UI path (the whole
+ * body is detached), never surfaces a reprobe failure (the sweep retries).
+ */
+export function runMachineDownFeedback(label, row, faces) {
+    void (async () => {
+        let machineName = row.machine;
+        let status;
+        const enriched = await new Promise((resolve) => {
+            const bound = faces.setTimeout(() => resolve(undefined), MACHINE_DOWN_ENRICH_MS);
+            faces.fetchMachines().then((list) => { faces.clearTimeout(bound); resolve(list); }, () => { faces.clearTimeout(bound); resolve(undefined); });
+        });
+        if (enriched !== undefined) {
+            const found = enriched.machines.find((entry) => entry.id === row.machine);
+            if (found !== undefined) {
+                machineName = found.label;
+                if (found.status === 'unreachable' || found.status === 'auth-expired')
+                    status = found.status;
+            }
+        }
+        const who = row.label ?? label;
+        const machine = machineName ?? 'its machine';
+        faces.toast(status === undefined
+            ? `Super D: ${who} is unavailable — machine ${machine} is not ready. Reprobe or re-add it in the Hub machines panel.`
+            : `Super D: ${who} is unavailable — machine ${machine} reports ${status}. Reprobe or re-add it in the Hub machines panel.`);
+        // I1(b): exactly ONE fresh attempt per failed click — keyed by the row's
+        // machine id (the machine-down decision guarantees it is set; a malformed
+        // row simply skips the light probe).
+        if (row.machine !== undefined)
+            faces.reprobe(row.machine).catch(() => { });
+    })();
+}
 /** Default bound on one readiness wait (the page never locks behind a stuck world). */
 export const WAIT_BOUND_MS = 120_000;
 /** Default poll interval for one readiness wait. */

package/superd-hub/dist/system-head.d.ts

@@ -10,16 +10,10 @@
  * (before any step) — so every bridge-written log violated one rule or the
  * other and became unresumable across restarts.
  *
- * The native loop never hits this because it opens the step before writing
- * anything: `turn/start → step/start → system/message → user/message …`,
- * and later prompt changes REPLACE the protected head (the operation
- * compaction also uses). This module gives bridge adapters that posture with
- * a one-line wrap:
- *
- *   this.session = withSystemHead(session, () => createSystemMessage(""))
- *
- * The wrap is a transparent Proxy that tracks the open turn/step (exactly as
- * the v4 reader does) and intervenes minimally:
+ * The wrap installs the co-writer as OWN PROPERTIES on the session object
+ * itself (an `append` own-property shadow over the prototype method, plus
+ * `stampSystemPrompt`) and tracks the open turn/step (exactly as the v4
+ * reader does), intervening minimally:
  *
  *   - the FIRST `user/message` append on a still-headless, still-empty
  *     surface first opens the turn's next step (when a turn is open but no
@@ -35,6 +29,18 @@
  *     queued and flushed inside the next step the adapter opens;
  *   - everything else delegates unchanged.
  *
+ * IDENTITY IS THE CONTRACT (2026-09-28, D1): the wrap must return the session
+ * object ITSELF, never a wrapper. Upstream identity-checks live sessions by
+ * object equality — `session-title`'s `rename()` refuses unless
+ * `ctx.sessions.get(session.id) === session` (session-title/src/index.ts),
+ * and adapters register the RAW prepared session with `sessions.enter()` /
+ * `announce()` (e.g. agent-pi/src/index.ts). An earlier revision returned a
+ * transparent `Proxy`; every world-context rename then failed with
+ * `session "<id>" is not live in this store` because the Agent handle's
+ * `session` (the Proxy) was never the store-registered object. Returning the
+ * same object keeps `agent.session === ctx.sessions.get(id)` true, so the
+ * whole upstream session plane (rename included) sees one identity.
+ *
  * A surface that already starts with a user message and has no head (legacy
  * logs) stays headless — valid — and is never stamped: appending a head
  * there is exactly the corruption this module exists to prevent.
@@ -54,7 +60,7 @@ export interface HeadAwareSessionFace {
 }
 /** Builds the placeholder head message (adapters pass their createSystemMessage). */
 export type HeadPlaceholder = () => unknown;
-/** One co-written session: transparent delegation + head bookkeeping. */
+/** One co-written session: the session itself, carrying head bookkeeping (object identity preserved — see the module note). */
 export type WithSystemHead<S> = S & {
     /** Append-or-replace the protected head with the runtime's system prompt. */
     stampSystemPrompt(turn: number, step: number, message: unknown): void;
@@ -64,6 +70,10 @@ export type WithSystemHead<S> = S & {
  * @param session - the adapter's real Session.
  * @param placeholder - builds the placeholder head message when the first
  *   user message arrives on an empty surface.
- * @returns the session (transparently delegated) with `stampSystemPrompt`.
+ * @returns the SAME session object with the co-writer installed as own
+ *   properties (`append` shadow + `stampSystemPrompt`). Identity is the
+ *   contract (D1): upstream liveness checks compare
+ *   `ctx.sessions.get(id) === agent.session`, so the returned object must be
+ *   the one registered with `sessions.enter()` — never a wrapper.
  */
 export declare function withSystemHead<S extends HeadAwareSessionFace>(session: S, placeholder: HeadPlaceholder): WithSystemHead<S>;

package/superd-hub/dist/system-head.js

@@ -10,16 +10,10 @@
  * (before any step) — so every bridge-written log violated one rule or the
  * other and became unresumable across restarts.
  *
- * The native loop never hits this because it opens the step before writing
- * anything: `turn/start → step/start → system/message → user/message …`,
- * and later prompt changes REPLACE the protected head (the operation
- * compaction also uses). This module gives bridge adapters that posture with
- * a one-line wrap:
- *
- *   this.session = withSystemHead(session, () => createSystemMessage(""))
- *
- * The wrap is a transparent Proxy that tracks the open turn/step (exactly as
- * the v4 reader does) and intervenes minimally:
+ * The wrap installs the co-writer as OWN PROPERTIES on the session object
+ * itself (an `append` own-property shadow over the prototype method, plus
+ * `stampSystemPrompt`) and tracks the open turn/step (exactly as the v4
+ * reader does), intervening minimally:
  *
  *   - the FIRST `user/message` append on a still-headless, still-empty
  *     surface first opens the turn's next step (when a turn is open but no
@@ -35,6 +29,18 @@
  *     queued and flushed inside the next step the adapter opens;
  *   - everything else delegates unchanged.
  *
+ * IDENTITY IS THE CONTRACT (2026-09-28, D1): the wrap must return the session
+ * object ITSELF, never a wrapper. Upstream identity-checks live sessions by
+ * object equality — `session-title`'s `rename()` refuses unless
+ * `ctx.sessions.get(session.id) === session` (session-title/src/index.ts),
+ * and adapters register the RAW prepared session with `sessions.enter()` /
+ * `announce()` (e.g. agent-pi/src/index.ts). An earlier revision returned a
+ * transparent `Proxy`; every world-context rename then failed with
+ * `session "<id>" is not live in this store` because the Agent handle's
+ * `session` (the Proxy) was never the store-registered object. Returning the
+ * same object keeps `agent.session === ctx.sessions.get(id)` true, so the
+ * whole upstream session plane (rename included) sees one identity.
+ *
  * A surface that already starts with a user message and has no head (legacy
  * logs) stays headless — valid — and is never stamped: appending a head
  * there is exactly the corruption this module exists to prevent.
@@ -59,14 +65,22 @@ function surfaceIsEmpty(events) {
  * @param session - the adapter's real Session.
  * @param placeholder - builds the placeholder head message when the first
  *   user message arrives on an empty surface.
- * @returns the session (transparently delegated) with `stampSystemPrompt`.
+ * @returns the SAME session object with the co-writer installed as own
+ *   properties (`append` shadow + `stampSystemPrompt`). Identity is the
+ *   contract (D1): upstream liveness checks compare
+ *   `ctx.sessions.get(id) === agent.session`, so the returned object must be
+ *   the one registered with `sessions.enter()` — never a wrapper.
  */
 export function withSystemHead(session, placeholder) {
+    // Idempotent: a session already carrying the co-writer is returned as-is.
+    if (Object.prototype.hasOwnProperty.call(session, 'stampSystemPrompt'))
+        return session;
     // The one narrow this module performs: the loose face above is what makes
     // the generic real Session assignable; every call below issues exactly the
     // SystemHeadAppend shape.
     const appendHead = session.append.bind(session);
     const rawAppend = session.append.bind(session);
+    const rawAppendFull = session.append.bind(session);
     // Reader-mirrored turn/step state.
     let turn = null;
     let step = null;
@@ -115,80 +129,82 @@ export function withSystemHead(session, placeholder) {
         }
         headSeq = appendHead('system/message', { turn: turn ?? turnArg, step: step ?? stepArg, message }, { surfaceOp: { op: 'replace', startSeq: headSeq, endSeq: headSeq }, sourceEventSeqs: [headSeq] }).seq;
     };
-    return new Proxy(session, {
-        get(target, property) {
-            if (property === 'stampSystemPrompt') {
-                return (turnArg, stepArg, message) => { stamp(turnArg, stepArg, message); };
+    const interceptAppend = (type, data, opts) => {
+        if (type === 'turn/start') {
+            turn = data.turn;
+            nextStep = 1;
+            wrapOpenedStep = false;
+            wrapClosedStep = undefined;
+        }
+        else if (type === 'turn/end') {
+            // A step THIS wrap opened must not survive the turn boundary.
+            if (step !== null && wrapOpenedStep) {
+                rawAppend('step/end', { turn, step });
+                wrapClosedStep = step;
+                step = null;
+                nextStep += 1;
+            }
+            turn = null;
+        }
+        else if (type === 'step/start') {
+            const dataStep = data;
+            if (step !== null && wrapOpenedStep && dataStep.turn === turn && dataStep.step === step) {
+                // The adapter opened the step the wrap already wrote: drop the
+                // duplicate (the adapter's own counters stay consistent).
+                return { type, seq: session.snapshotEvents().length, time: Date.now(), data };
+            }
+            if (step === null && dataStep.step !== undefined)
+                step = dataStep.step;
+            wrapOpenedStep = false;
+            const applied = rawAppendFull(type, data);
+            if (queuedStamp !== undefined && step !== null) {
+                const pending = queuedStamp;
+                queuedStamp = undefined;
+                stamp(pending.turn, pending.step, pending.message);
             }
-            if (property === 'append') {
-                return (type, data, opts) => {
-                    if (type === 'turn/start') {
-                        turn = data.turn;
-                        nextStep = 1;
-                        wrapOpenedStep = false;
-                        wrapClosedStep = undefined;
-                    }
-                    else if (type === 'turn/end') {
-                        // A step THIS wrap opened must not survive the turn boundary.
-                        if (step !== null && wrapOpenedStep) {
-                            rawAppend('step/end', { turn, step });
-                            wrapClosedStep = step;
-                            step = null;
-                            nextStep += 1;
-                        }
-                        turn = null;
-                    }
-                    else if (type === 'step/start') {
-                        const dataStep = data;
-                        if (step !== null && wrapOpenedStep && dataStep.turn === turn && dataStep.step === step) {
-                            // The adapter opened the step the wrap already wrote: drop the
-                            // duplicate (the adapter's own counters stay consistent).
-                            return { type, seq: session.snapshotEvents().length, time: Date.now(), data };
-                        }
-                        if (step === null && dataStep.step !== undefined)
-                            step = dataStep.step;
-                        wrapOpenedStep = false;
-                        const applied = rawAppend(type, data);
-                        if (queuedStamp !== undefined && step !== null) {
-                            const pending = queuedStamp;
-                            queuedStamp = undefined;
-                            stamp(pending.turn, pending.step, pending.message);
-                        }
-                        return applied;
-                    }
-                    else if (type === 'step/end') {
-                        const dataStep = data;
-                        if (step === null && wrapClosedStep !== undefined && dataStep.step === wrapClosedStep) {
-                            wrapClosedStep = undefined;
-                            return { type, seq: session.snapshotEvents().length, time: Date.now(), data }; // the wrap already closed it
-                        }
-                        step = null;
-                        if (dataStep.step !== undefined)
-                            nextStep = dataStep.step + 1;
-                    }
-                    else if (type === 'user/message') {
-                        ensureHead();
-                    }
-                    else if (type === 'system/message') {
-                        // A direct adapter append (notices, bootstraps): give it the step
-                        // context the reader demands — open the turn's next step when
-                        // none is open and NORMALIZE the coordinates to that context
-                        // (requireStep compares them for equality; a mismatched append
-                        // is doomed otherwise). Surface ordering beyond the head rules
-                        // stays the adapter's own responsibility.
-                        if (step === null && turn !== null)
-                            openWrapStep();
-                        if (step !== null && turn !== null) {
-                            const direct = data;
-                            if (direct.turn !== turn || direct.step !== step)
-                                data = { ...data, turn, step };
-                        }
-                    }
-                    return Reflect.apply(target.append, target, [type, data, opts]);
-                };
+            return applied;
+        }
+        else if (type === 'step/end') {
+            const dataStep = data;
+            if (step === null && wrapClosedStep !== undefined && dataStep.step === wrapClosedStep) {
+                wrapClosedStep = undefined;
+                return { type, seq: session.snapshotEvents().length, time: Date.now(), data }; // the wrap already closed it
+            }
+            step = null;
+            if (dataStep.step !== undefined)
+                nextStep = dataStep.step + 1;
+        }
+        else if (type === 'user/message') {
+            ensureHead();
+        }
+        else if (type === 'system/message') {
+            // A direct adapter append (notices, bootstraps): give it the step
+            // context the reader demands — open the turn's next step when
+            // none is open and NORMALIZE the coordinates to that context
+            // (requireStep compares them for equality; a mismatched append
+            // is doomed otherwise). Surface ordering beyond the head rules
+            // stays the adapter's own responsibility.
+            if (step === null && turn !== null)
+                openWrapStep();
+            if (step !== null && turn !== null) {
+                const direct = data;
+                if (direct.turn !== turn || direct.step !== step)
+                    data = { ...data, turn, step };
             }
-            const value = Reflect.get(target, property, target);
-            return typeof value === 'function' ? value.bind(target) : value;
-        },
+        }
+        return rawAppendFull(type, data, opts);
+    };
+    // Install the co-writer as OWN PROPERTIES on the session itself. The
+    // `append` shadow covers every holder of the object (the adapter's Agent
+    // AND upstream services that resolved the session from the store); both
+    // properties are non-enumerable so scans/serialization of the session see
+    // nothing, and writable/configurable so it stays an ordinary instance.
+    Object.defineProperty(session, 'append', {
+        value: interceptAppend, writable: true, configurable: true, enumerable: false,
+    });
+    Object.defineProperty(session, 'stampSystemPrompt', {
+        value: (turnArg, stepArg, message) => { stamp(turnArg, stepArg, message); },
+        writable: true, configurable: true, enumerable: false,
     });
+    return session;
 }