@north-light/crouter 0.3.173 → 0.3.174

package/dist/core/memory-resolver.js

@@ -356,48 +356,53 @@ function formatLeafAmbiguous(leaf, matches) {
     const ids = matches.map(memoryDocId).join(', ');
     return `ambiguous memory document: ${leaf} matches multiple documents: ${ids}`;
 }
-/**
- * Resolve a memory document name to a single memory document.
- *
- * Accepted identifier forms:
- *   <name>            — bare name; resolved by scope precedence project>user>builtin
- *   <scope>/<name>    — pinned to one scope (user|project)
- * `<name>` may carry topical subdirs (`taste/foo`); a bare leaf (`foo`) falls
- * back to a last-segment match within the resolved scopes.
- *
- * Strong matches resolve before fallback matches. The first pass visits every
- * source nearest-first and checks, within each source: (1) exact substrate
- * identity (`doc.name === query` — the explicit frontmatter `name`, else its
- * normalized path-derived fallback, the SAME identity `listAllMemoryDocs`
- * reports); then (2) direct `memory/<name>.md` physical-path lookup (the
- * bare-dir → INDEX.md and bare-plugin-name → plugin root INDEX.md conveniences
- * neither identity nor a literal path expresses). Only if that pass finds
- * nothing does a second nearest-first pass try bare leaf-name fallback (final
- * path segment), ambiguous when two DIFFERENT identities in the SAME source
- * share a leaf. A farther canonical identity therefore beats a nearer leaf,
- * while scope precedence still decides between equally strong matches.
- *
- * `opts.kind`, when given, is a resolution CONSTRAINT, not a post-filter: in
- * both passes a candidate whose `effectiveDocKind` doesn't match is skipped,
- * so resolution keeps looking for a matching-kind document.
- */
-export function resolveMemoryDoc(rawName, opts = {}) {
+function loadMemorySources(scope) {
+    // Quiet: a targeted read must not spew other docs' frontmatter warnings
+    // before its own result (esp. a not_found) — corpus health is `lint`'s job.
+    return memorySourcesInPrecedence(scope).map((source) => ({
+        source,
+        docs: sourceMemoryDocs(source, true),
+    }));
+}
+export function createMemoryDocSnapshot() {
+    const defaultSources = loadMemorySources();
+    const sourcesByScope = new Map([[undefined, defaultSources]]);
+    const sourceFor = (scope) => {
+        let sources = sourcesByScope.get(scope);
+        if (sources === undefined) {
+            sources = loadMemorySources(scope);
+            sourcesByScope.set(scope, sources);
+        }
+        return sources;
+    };
+    return {
+        docs: defaultSources.flatMap(({ docs }) => docs),
+        resolve: (names) => {
+            const resolved = new Map();
+            for (const rawName of names) {
+                try {
+                    const parsed = parseSkillQualifier(rawName);
+                    resolved.set(rawName, resolveMemoryDocFromSources(rawName, {}, sourceFor(parsed.scope)));
+                }
+                catch {
+                    // A command registration reports its own body-read failure below; one
+                    // malformed/stale identity must not suppress every other slash command.
+                }
+            }
+            return resolved;
+        },
+    };
+}
+function resolveMemoryDocFromSources(rawName, opts, sources) {
     const parsed = parseSkillQualifier(rawName);
     if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
         throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
     }
-    const effectiveScope = opts.scope ?? parsed.scope;
     const name = parsed.segments.join('/');
     if (name === '')
         throw usage(`memory document name required`);
     const segments = name.split('/');
     const isLeafQuery = !name.includes('/');
-    // Quiet: a targeted read must not spew other docs' frontmatter warnings
-    // before its own result (esp. a not_found) — corpus health is `lint`'s job.
-    const sources = memorySourcesInPrecedence(effectiveScope).map((source) => ({
-        source,
-        docs: sourceMemoryDocs(source, true),
-    }));
     const kindOk = (d) => opts.kind === undefined || effectiveDocKind(d) === opts.kind;
     // Strong matches across the full scope stack come first. This preserves
     // nearest-scope shadowing for canonical/direct collisions without allowing a
@@ -437,3 +442,16 @@ export function resolveMemoryDoc(rawName, opts = {}) {
         scope: parsed.scope,
     });
 }
+/** Resolve several unqualified names over one memory-source snapshot. Failed
+ * names are omitted so callers can preserve their per-document error behavior. */
+export function resolveMemoryDocs(names) {
+    return createMemoryDocSnapshot().resolve(names);
+}
+export function resolveMemoryDoc(rawName, opts = {}) {
+    const parsed = parseSkillQualifier(rawName);
+    if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
+        throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
+    }
+    const effectiveScope = opts.scope ?? parsed.scope;
+    return resolveMemoryDocFromSources(rawName, opts, loadMemorySources(effectiveScope));
+}

package/dist/core/model-routes.d.ts

@@ -52,8 +52,23 @@ export interface InitialModelRouteSelection<Model extends {
         reason: ProviderCandidateRejection;
     }>;
 }
+export interface UnregisteredConcreteModel {
+    request: Extract<ModelRequest, {
+        kind: 'concrete' | 'exact';
+    }>;
+    candidate: RoutedCandidate;
+    reason: 'unregistered';
+}
 /** Expand config-derived route order only. Availability never affects rank. */
 export declare function expandModelCandidates(request: ModelRequest, cwd?: string, profileId?: string | null): RoutedCandidate[];
+/** Identify the one permanently invalid recipe shape: a concrete/exact request
+ * whose requested provider/model is absent from the serving registry. Auth and
+ * cooldown are deliberately outside this discriminator so callers retain their
+ * existing policy for those transient states. */
+export declare function unregisteredConcreteModel(request: ModelRequest | undefined, registry: ModelRegistryLike, options?: {
+    cwd?: string;
+    profileId?: string | null;
+}): UnregisteredConcreteModel | undefined;
 /** Probe the common availability facts consumed unchanged by resolveProviderCandidates. */
 export declare function probeRouteAvailability(candidate: RoutedCandidate, registry: ModelRegistryLike, now?: number): RouteAvailability;
 /** Select the first viable route for a new SDK session. Route declarations own

package/dist/core/model-routes.js

@@ -110,6 +110,18 @@ export function expandModelCandidates(request, cwd, profileId) {
     }
     return emitted.map((candidate, rank) => ({ ...candidate, rank }));
 }
+/** Identify the one permanently invalid recipe shape: a concrete/exact request
+ * whose requested provider/model is absent from the serving registry. Auth and
+ * cooldown are deliberately outside this discriminator so callers retain their
+ * existing policy for those transient states. */
+export function unregisteredConcreteModel(request, registry, options = {}) {
+    if (request === undefined || request.kind === 'logical')
+        return undefined;
+    const candidate = expandModelCandidates(request, options.cwd, options.profileId)[0];
+    if (candidate === undefined || registry.find(candidate.providerId, candidate.modelId) !== undefined)
+        return undefined;
+    return { request, candidate, reason: 'unregistered' };
+}
 /** Probe the common availability facts consumed unchanged by resolveProviderCandidates. */
 export function probeRouteAvailability(candidate, registry, now = Date.now()) {
     const model = registry.find(candidate.providerId, candidate.modelId);

package/dist/core/pool-credential-store.js

@@ -89,7 +89,7 @@ export class PoolCredentialStore {
             const existing = await this.read(providerId);
             if (existing !== undefined)
                 return this.auth.modify(providerId, fn);
-            throw new Error(`${getProviderLabel(providerId)} has no account to update — add one with \`crtr sys setup\` or \`/provider-sub ${providerId} add\`.`);
+            throw new Error(`${getProviderLabel(providerId)} has no account to update — add one with \`crtr sys settings\` or \`/provider-sub ${providerId} add\`.`);
         }
         const committed = await modifyElectedSubscription(providerId, (pool) => electFrom(pool), async (entry) => {
             const next = await fn(toCredential(entry));

package/dist/core/preview-registry.js

@@ -5,9 +5,8 @@
 // This file has NO imports. The attach viewer is bundled as a separate
 // esbuild process from the one that runs a leaf, so it cannot read a leaf's
 // command-owned `preview` field directly — walking the live command tree
-// to find it would pull every subtree's module graph (including `surface`
-// -> the web client -> Tailwind's native oxide binary) into the attach
-// bundle. A flat, zero-dependency static map avoids that entirely.
+// to find it would pull every subtree's module graph into the attach bundle.
+// A flat, zero-dependency static map avoids that entirely.
 //
 // Source of truth: this Set must mirror every leaf that declares
 // `help.preview.suppressOutput: true` in its own command file (currently
@@ -157,10 +156,10 @@ const LEAF_ICON_CP = {
     'search answer': 0xf075,
     'search contents': 0xf0f6,
     'surface attach to': 0xf1e6,
-    'surface web serve': 0xf0ac,
     'sys config get': 0xf019,
     'sys config set': 0xf040,
     'sys config path': 0xf07b,
+    'sys settings': 0xf013,
     'sys setup': 0xf0ad,
     'sys doctor': 0xf0f1,
     'sys sysprompt': 0xf15c,
@@ -1142,7 +1141,7 @@ function summarizeNodeWaitDeadline(text) {
         { text: id, tone: 'muted' },
     ];
 }
-/** `crtr node yield` (src/commands/node.ts:1513) has no custom `render`;
+/** `crtr node yield` (`src/commands/node/lifecycle.ts`) has no custom `render`;
  *  the generic renderer bullets `{node_id, promoted, model?, will_refresh}`
  *  — none of these names are PROSE_FIELDS. `will_refresh` is documented
  *  "Always true" (the command has no path that returns false), so
@@ -1167,7 +1166,7 @@ function summarizeNodeYield(text) {
         lines.push({ text: extras.join(' · '), tone: 'muted' });
     return lines;
 }
-/** `crtr node lifecycle close` (nodeClose.render, src/commands/node.ts:650):
+/** `crtr node lifecycle close` (`nodeClose.render` in `src/commands/node/lifecycle.ts`):
  *  `Closed ${id} and its exclusive subtree — ${count} node(s)
  *  closed${spared>0 ? ", ${spared} spared..." : ''}.` on success, or a
  *  short failure line — left as null there, the generic fallback is fine for
@@ -2235,7 +2234,7 @@ function summarizeSearchContents(text) {
  *  raw ANSI curses frames never match any marker below, so this summarizer
  *  safely returns null in that case). In the headless/agent path
  *  (src/commands/sys/setup.ts's `!process.stdout.isTTY` branch,
- *  `buildSetupStaticInstructions` in setup-core.ts:328 — the shape every
+ *  `renderSetupStaticInstructions` in setup-core.ts — the shape every
  *  bash-tool call to this leaf actually produces) it instead prints a
  *  static inventory: the headline `crtr sys setup (non-interactive)`, a
  *  `Packages:` section (`- <name> — <description> (installed|not
@@ -2589,7 +2588,7 @@ function summarizeSysLogs(text) {
     if (lines.length === 0 || lines.some((line) => line === ''))
         return null;
     for (const line of lines) {
-        const event = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2}) (DEBUG|INFO|WARN|ERROR) (daemon|broker|web) \S+ op=[0-9a-f]{32}(?: \{.*\})?$/.exec(line);
+        const event = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2}) (DEBUG|INFO|WARN|ERROR) (daemon|broker) \S+ op=[0-9a-f]{32}(?: \{.*\})?$/.exec(line);
         if (event !== null) {
             componentCounts.set(event[2], (componentCounts.get(event[2]) ?? 0) + 1);
             if (event[1] === 'ERROR')
@@ -2609,7 +2608,7 @@ function summarizeSysLogs(text) {
         }
         raw++;
     }
-    const componentDigest = summarizeOrderedCounts(componentCounts, ['daemon', 'broker', 'web']);
+    const componentDigest = summarizeOrderedCounts(componentCounts, ['daemon', 'broker']);
     const aside = [componentDigest, raw > 0 ? `${raw} raw` : ''].filter((part) => part !== '').join(' · ');
     return summarizeHealthStatus(lines.length, errors, warnings, aside === '' ? 'no component detail' : aside);
 }

package/dist/core/profiles/__tests__/root-profile.test.js

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { ensureRootProfile, listProfiles, loadProfileManifest, profileManifestPath, profileMemoryDir, profileRoot, ROOT_PROFILE_ID, } from '../manifest.js';
+import { loadProfileManifest, profileRoot, ROOT_PROFILE_ID } from '../manifest.js';
 import { selectProfileForCwd } from '../select.js';
 import { resetScopeCache } from '../../scope.js';
 let home;
@@ -45,19 +45,9 @@ after(() => {
         process.env.HOME = previousHome;
     resetScopeCache();
 });
-test('ensureRootProfile creates the stable root profile and is idempotent', () => {
-    const first = ensureRootProfile();
-    const second = ensureRootProfile();
-    assert.equal(first.profileId, ROOT_PROFILE_ID);
-    assert.equal(second.profileId, ROOT_PROFILE_ID);
-    assert.deepEqual(second, first);
-    assert.equal(first.manifest.name, 'root');
-    assert.deepEqual(first.manifest.projects, []);
-    assert.equal(existsSync(profileRoot(ROOT_PROFILE_ID)), true);
-    assert.equal(existsSync(profileManifestPath(ROOT_PROFILE_ID)), true);
-    assert.equal(existsSync(profileMemoryDir(ROOT_PROFILE_ID)), true);
-    assert.deepEqual(listProfiles().map(({ profileId }) => profileId), [ROOT_PROFILE_ID]);
-});
+// A headless node spawn in an uncovered cwd must never prompt: `isTTY` is
+// forced false above, so a regression that reached for the interactive picker
+// would hang this test the same way it would hang the spawn.
 test('selectProfileForCwd falls back to the stable root profile when nothing covers cwd', async () => {
     const profileId = await selectProfileForCwd(cwd);
     assert.equal(profileId, ROOT_PROFILE_ID);

package/dist/core/review/realize.d.ts

@@ -1,19 +1,6 @@
-import type { NodeStatus } from '../canvas/types.js';
 import { type ReviewRecord } from './types.js';
 /**
  * Finish a committed binding without ever recapturing its origin. Each step is
  * safe to repeat after a crash; review.json is the final visibility switch.
  */
 export declare function realizeReview(reviewId: string): Promise<ReviewRecord>;
-/**
- * Reopen one already-open companion when needed. The surface only attaches to
- * the returned node; it never owns a second revive path.
- */
-export declare function openExistingReview(reviewId: string): Promise<{
-    review: ReviewRecord;
-    disposition: 'terminal';
-} | {
-    review: ReviewRecord;
-    companion_status: NodeStatus;
-    disposition: 'open';
-}>;

package/dist/core/review/realize.js

@@ -5,7 +5,6 @@ import { withCanvasWrite } from '../canvas/db.js';
 import { atomicWriteJson } from '../human/convention.js';
 import { ticketDir } from '../human/root.js';
 import { submitReview } from '../human/tickets.js';
-import { isBrokerLive } from '../runtime/model-swap.js';
 import { NodeIdConflictError, spawnNode } from '../runtime/nodes.js';
 import { transition } from '../runtime/lifecycle.js';
 import { reviveNode } from '../runtime/revive.js';
@@ -122,18 +121,6 @@ function realizeBridge(review) {
     ensureBridgeSubscription(current, current.bridge_node_id);
     return current;
 }
-async function awaitAttachableCompanion(nodeId, deadlineMs) {
-    const deadline = Date.now() + deadlineMs;
-    for (;;) {
-        const companion = getNode(nodeId);
-        if (companion !== null && isBrokerLive(companion))
-            return true;
-        const remaining = deadline - Date.now();
-        if (remaining <= 0)
-            return false;
-        await new Promise((resolveWait) => setTimeout(resolveWait, Math.min(100, remaining)));
-    }
-}
 function publishTicket(review) {
     if (review.bridge_node_id === null)
         throw bridgeUnsubscribed(review, '');
@@ -188,30 +175,3 @@ export async function realizeReview(reviewId) {
     }
     return requireReview(reviewId);
 }
-/**
- * Reopen one already-open companion when needed. The surface only attaches to
- * the returned node; it never owns a second revive path.
- */
-export async function openExistingReview(reviewId) {
-    const review = requireReview(reviewId);
-    if (review.state === 'binding')
-        throw unknownReview(reviewId);
-    if (review.state !== 'open')
-        return { review, disposition: 'terminal' };
-    const companion = getNode(review.companion_node_id);
-    if (companion === null)
-        throw companionUnbound(review.review_id, 0);
-    if (!isBrokerLive(companion))
-        reviveNode(companion.node_id, { resume: true });
-    if (!await awaitAttachableCompanion(review.companion_node_id, COMPANION_BIND_DEADLINE_MS)) {
-        throw companionUnbound(review.review_id, COMPANION_BIND_DEADLINE_MS);
-    }
-    const attachable = getNode(review.companion_node_id);
-    if (attachable === null)
-        throw companionUnbound(review.review_id, 0);
-    return {
-        review: requireReview(reviewId),
-        companion_status: attachable.status,
-        disposition: 'open',
-    };
-}

package/dist/core/review/types.d.ts

@@ -9,7 +9,7 @@ export type ReviewOriginKind = 'ticket' | 'inline';
 export type CommentStatus = 'open' | 'resolved' | 'deleted';
 export type CommentAuthorKind = 'human' | 'node';
 export type CommentEventKind = 'created' | 'edited' | 'resolved' | 'reopened' | 'deleted' | 'reanchored' | 'notified' | 'notify_failed';
-export type ReviewErrorCode = 'review_origin_missing' | 'review_origin_unforkable' | 'review_origin_unstable' | 'review_branch_unavailable' | 'branch_lost' | 'review_companion_unbound' | 'review_bridge_unsubscribed' | 'review_target_unreviewable' | 'source_unreadable' | 'delivery_unroutable' | 'unknown_review' | 'review_not_open' | 'review_terminal' | 'review_required' | 'stale_document' | 'unknown_comment' | 'comment_deleted' | 'invalid_anchor' | 'anchor_out_of_range' | 'text_too_long' | 'comment_limit_reached' | 'stale_comment' | 'range_batch_incomplete' | 'range_batch_stale';
+export type ReviewErrorCode = 'review_origin_missing' | 'review_origin_unforkable' | 'review_origin_unstable' | 'review_branch_unavailable' | 'branch_lost' | 'review_companion_unbound' | 'review_bridge_unsubscribed' | 'review_target_unreviewable' | 'source_unreadable' | 'delivery_unroutable' | 'unknown_review' | 'review_terminal' | 'review_required' | 'stale_document' | 'unknown_comment' | 'comment_deleted' | 'invalid_anchor' | 'anchor_out_of_range' | 'text_too_long' | 'comment_limit_reached' | 'stale_comment' | 'range_batch_incomplete' | 'range_batch_stale';
 /** Limits */
 export declare const COMMENT_TEXT_MAX = 8000;
 export declare const COMMENT_QUOTE_MAX = 4000;

package/dist/core/runtime/__tests__/engine-route.test.js

@@ -1,6 +1,6 @@
 // Run with: node --import tsx/esm --test src/core/runtime/__tests__/engine-route.test.ts
 //
-// Regression lock for resolveEngineRoute (broker.ts): the broker is
+// Regression lock for resolveEngineRoute (broker/frame-dispatch.ts): the broker is
 // authoritative over prompt/follow_up routing against the LIVE session state.
 // m-C is the load-bearing case — a `follow_up` delivered to an IDLE session
 // used to be handed to pi's followUp(), whose queue only drains inside a
@@ -9,7 +9,7 @@
 // session). An idle follow_up must run as a prompt.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { resolveEngineRoute } from '../broker.js';
+import { resolveEngineRoute } from '../broker/frame-dispatch.js';
 const IMAGES = [{ type: 'image', data: 'aGk=', mimeType: 'image/png' }];
 test('m-C: follow_up on an IDLE session escalates to prompt (no streamingBehavior)', () => {
     const route = resolveEngineRoute({ type: 'follow_up' }, false);

package/dist/core/runtime/bearings.js

@@ -18,6 +18,7 @@ import { cadenceDisplay } from '../wake.js';
 import { renderKnowledgeBlock, renderWorkspaceOpenDocs } from '../substrate/index.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
 import { situationalContextBlock } from './situational-context.js';
+import { statusRank } from '../canvas/node-order.js';
 /** The bearings custom type is shared with every attached renderer. */
 export { CONTEXT_INTRO_CUSTOM_TYPE } from '../../shared/generated-context.js';
 function escapeAttribute(value) {
@@ -183,17 +184,6 @@ export function orchestratorContextNote(nodeId) {
 // first) and who is directly below it (its immediate children + their statuses).
 // Not the full subtree — just the load-bearing spine up and one level down.
 // ---------------------------------------------------------------------------
-/** Live-first sibling ordering, so running children surface above finished ones. */
-function statusRank(status) {
-    switch (status) {
-        case 'active': return 0;
-        case 'idle': return 1;
-        case 'done': return 2;
-        case 'canceled': return 3;
-        case 'dead': return 4;
-        default: return 5;
-    }
-}
 /** One relative's line in the map: `<id> — <kind> · <status>`, plus the node's
  *  task description when it carries one (orientation: what that relative is for). */
 function relativeLabel(meta) {

package/dist/core/runtime/broker/client-registry.d.ts

@@ -0,0 +1,33 @@
+import type { Socket } from 'node:net';
+import { FrameDecoder, type BrokerSnapshot, type BrokerToClient, type ClientRole } from '../broker-protocol.js';
+export interface BrokerClient {
+    id: string;
+    role: ClientRole;
+    socket: Socket;
+    decoder: FrameDecoder;
+    helloed: boolean;
+    pendingBytes: number;
+    queuedFrames: number;
+}
+/** Owns connected viewers, their outbound backpressure, and durable attach presence. */
+export declare class BrokerClientRegistry {
+    private readonly nodeId;
+    private readonly attachPath;
+    private readonly clients;
+    private readonly displayStatuses;
+    private readonly displayWidgets;
+    private displayTitle;
+    constructor(nodeId: string);
+    create(socket: Socket): BrokerClient;
+    writableClients(): BrokerClient[];
+    persistAttachState(): void;
+    dropClient(client: BrokerClient, reason: string): void;
+    removeClient(client: BrokerClient): void;
+    sendFrame(client: BrokerClient, frame: BrokerToClient, bypassHwm?: boolean): void;
+    broadcast(frame: BrokerToClient): void;
+    broadcastUi(frame: BrokerToClient): void;
+    displaySnapshot(): BrokerSnapshot['display'];
+    forEachHelloed(fn: (client: BrokerClient) => void): void;
+    dispose(): void;
+    clearAttachState(): void;
+}

package/dist/core/runtime/broker/client-registry.js

@@ -0,0 +1,164 @@
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { jobDir } from '../../canvas/paths.js';
+import { emitEvent } from '../../events/emit.js';
+import { encodeFrame, FrameDecoder, BROKER_READ_CAPS, } from '../broker-protocol.js';
+/** Per-viewer outbound high-water mark. Slow viewers are shed rather than allowed to backpressure the shared engine indefinitely. */
+const MAX_QUEUED_FRAMES = 1000;
+const MAX_PENDING_BYTES = 32 * 1024 * 1024;
+/** Owns connected viewers, their outbound backpressure, and durable attach presence. */
+export class BrokerClientRegistry {
+    nodeId;
+    attachPath;
+    clients = new Set();
+    displayStatuses = new Map();
+    displayWidgets = new Map();
+    displayTitle;
+    constructor(nodeId) {
+        this.nodeId = nodeId;
+        this.attachPath = `${jobDir(nodeId)}/attach.json`;
+    }
+    create(socket) {
+        const client = {
+            id: '',
+            role: 'observer',
+            socket,
+            decoder: new FrameDecoder(BROKER_READ_CAPS),
+            helloed: false,
+            pendingBytes: 0,
+            queuedFrames: 0,
+        };
+        this.clients.add(client);
+        return client;
+    }
+    writableClients() {
+        const out = [];
+        for (const client of this.clients) {
+            if (!client.helloed || client.role !== 'controller')
+                continue;
+            if (client.socket.destroyed || client.socket.readableEnded || !client.socket.writable)
+                continue;
+            out.push(client);
+        }
+        return out;
+    }
+    persistAttachState() {
+        try {
+            let viewers = 0;
+            for (const client of this.clients)
+                if (client.helloed)
+                    viewers += 1;
+            const dir = jobDir(this.nodeId);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            writeFileSync(this.attachPath, JSON.stringify({ viewers, updated: new Date().toISOString() }, null, 2), 'utf8');
+        }
+        catch {
+            /* presence is best-effort; never crash the broker */
+        }
+    }
+    dropClient(client, reason) {
+        if (!this.clients.has(client))
+            return;
+        emitEvent({
+            level: 'info',
+            event: 'broker.runtime.diagnostic',
+            fields: { message: `dropping viewer ${client.id || '(pre-hello)'} — ${reason}` },
+        });
+        this.removeClient(client);
+        try {
+            client.socket.destroy();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    removeClient(client) {
+        this.clients.delete(client);
+        this.persistAttachState();
+    }
+    sendFrame(client, frame, bypassHwm = false) {
+        let data;
+        try {
+            data = encodeFrame(frame);
+        }
+        catch {
+            return;
+        }
+        const bytes = Buffer.byteLength(data);
+        if (!bypassHwm && (client.queuedFrames + 1 > MAX_QUEUED_FRAMES || client.pendingBytes + bytes > MAX_PENDING_BYTES)) {
+            this.dropClient(client, `backpressure high-water mark exceeded (queued=${client.queuedFrames}, pending=${client.pendingBytes}B)`);
+            return;
+        }
+        client.queuedFrames += 1;
+        client.pendingBytes += bytes;
+        try {
+            client.socket.write(data, () => {
+                client.queuedFrames -= 1;
+                client.pendingBytes -= bytes;
+            });
+        }
+        catch {
+            client.queuedFrames -= 1;
+            client.pendingBytes -= bytes;
+        }
+    }
+    broadcast(frame) {
+        for (const client of this.clients)
+            if (client.helloed)
+                this.sendFrame(client, frame);
+    }
+    broadcastUi(frame) {
+        if (frame.type === 'extension_ui_request') {
+            if (frame.method === 'setStatus') {
+                this.displayStatuses.delete(frame.statusKey);
+                if (frame.statusText !== undefined)
+                    this.displayStatuses.set(frame.statusKey, frame.statusText);
+            }
+            else if (frame.method === 'setWidget') {
+                this.displayWidgets.delete(frame.widgetKey);
+                if (frame.widgetLines !== undefined) {
+                    this.displayWidgets.set(frame.widgetKey, {
+                        lines: [...frame.widgetLines],
+                        placement: frame.widgetPlacement ?? 'aboveEditor',
+                    });
+                }
+            }
+            else if (frame.method === 'setTitle') {
+                this.displayTitle = frame.title;
+            }
+        }
+        this.broadcast(frame);
+    }
+    displaySnapshot() {
+        return {
+            statuses: Object.fromEntries(this.displayStatuses),
+            widgets: Object.fromEntries([...this.displayWidgets].map(([key, widget]) => [key, { lines: [...widget.lines], placement: widget.placement }])),
+            title: this.displayTitle,
+        };
+    }
+    forEachHelloed(fn) {
+        for (const client of this.clients)
+            if (client.helloed)
+                fn(client);
+    }
+    dispose() {
+        for (const client of this.clients) {
+            try {
+                client.socket.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.clients.clear();
+    }
+    clearAttachState() {
+        try {
+            if (existsSync(this.attachPath))
+                unlinkSync(this.attachPath);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}

package/dist/core/runtime/broker/daemon-ops.d.ts

@@ -0,0 +1,19 @@
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from '../../../api/dto/broker-ops.js';
+import type { RelaunchRootResultDTO } from '../../../api/dto/lifecycle.js';
+import type { PushReportRequest } from '../../../api/dto/reports.js';
+export declare function bindBrokerSession(nodeId: string, request: BrokerSessionBoundRequest): Promise<BrokerSessionBoundResultDTO>;
+export declare function settleBroker(nodeId: string, request: BrokerSettleRequest): Promise<BrokerSettleDirective>;
+export declare function advanceBrokerInboxCursor(nodeId: string, request: BrokerInboxCursorRequest): Promise<BrokerInboxCursorDirective>;
+/** Fixed canvas projection for broker extension rendering. It deliberately
+ * exposes no generic node/database facade. */
+export declare function commitBrokerModel(nodeId: string, request: BrokerModelCommitRequest): Promise<BrokerModelCommitResultDTO>;
+export declare function brokerExtensionState(nodeId: string): Promise<BrokerExtensionStateDTO>;
+export declare function commitBrokerGeneratedName(nodeId: string, request: BrokerGeneratedNameRequest): Promise<BrokerGeneratedNameResultDTO>;
+export declare function commitBrokerPersonaAck(nodeId: string, request: BrokerPersonaAckRequest): Promise<void>;
+/** Reports still use the canonical daemon report handler; this broker adapter
+ * only preserves terminal structured output's idempotent finalization result. */
+export declare function publishBrokerReport(nodeId: string, request: PushReportRequest): Promise<void>;
+/** Root `/new` remains on the dedicated relaunch operation because it launches
+ * a replacement broker and tears down this broker. Callers must not await it
+ * from Pi's session-start dispatch. */
+export declare function relaunchBrokerRoot(nodeId: string): Promise<RelaunchRootResultDTO>;