@khorsheed/dsh-room 0.1.0

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-room`.
+ * @module @khorsheed/dsh-room/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "room-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,24 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-room`.
+ * @module @khorsheed/dsh-room/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-room';
+/** Cordis companion plugin name. */
+export const name = 'room-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Placeholder (Step 0/1 spike): no runtime invariant yet. The `room/created`
+ * marker write passes through Session.append, whose validation rejects any
+ * non-JSON payload, and the client contributions ride the slot/locale
+ * lifecycles disposed with the plugin fiber. Later steps (roster transition
+ * validation, dispatch invariants) install real checks here.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

package/lib/types/journal.d.ts

@@ -0,0 +1,117 @@
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { RoomMember, RoomState, RoomTask, RoomTaskProgress } from './types.ts';
+/**
+ * The native DSH member's addressing name in new rooms. It starts as the
+ * coordinator; bare messages follow the selected coordinator thereafter.
+ * Existing journals retain their recorded names, including legacy main.
+ */
+export declare const MAIN_AGENT_MEMBER = "dsh";
+/**
+ * Every `room/*` session-event type this package introduces. Room registers
+ * them into the harness's KNOWN_SESSION_EVENT_TYPES persistence catalog at
+ * apply time (see the RoomService constructor): the catalog's read-path
+ * refusal exists so a build that does NOT understand an event type never
+ * silently mangles the log — a build with room mounted understands these, so
+ * registration is the semantically correct declaration, and a build without
+ * room keeps refusing them. The catalog's own header defers a registration
+ * surface for out-of-repo plugins "until such a consumer exists"; this
+ * in-place add is that surface's temporary form — migrate to the official
+ * one when it lands upstream.
+ */
+export declare const ROOM_EVENT_TYPES: readonly ['room/created', 'room/plan-state', 'room/coordinator', 'room/delivery-state', 'room/member-added', 'room/member-updated', 'room/member-removed', 'room/dispatch', 'room/speech', 'room/run-state', 'room/relay', 'room/relay-resolved', 'room/task-added', 'room/task-updated', 'room/task-edited', 'room/goal'];
+/** Whether an event log carries the room identity marker. */
+export declare function isRoomLog(events: readonly SessionEvent[]): boolean;
+/**
+ * Parse the leading `@name` tokens of a raw composer message.
+ * @param raw - the raw text.
+ * @returns the addressed names (deduped, order-preserving) and the body with
+ * the mention prefix stripped. Only LEADING tokens address: an `@name`
+ * inside prose is plain text (a bare message goes to the selected coordinator).
+ */
+export declare function parseMentions(raw: string): {
+    readonly targets: readonly string[];
+    readonly text: string;
+};
+/**
+ * The fallback notification channel: a member reply's TRAILING own line of
+ * the form `@name <content>` (the format the roster injection teaches).
+ * Only the last line counts — an `@name` inside prose is a mention, not a
+ * notification. Leading whitespace on that line is tolerated (models indent
+ * under their own bullet/list style). The caller checks the target against
+ * the roster.
+ * @param text - the member's reply text.
+ * @returns the parsed directive, or undefined.
+ */
+export declare function parseRelayDirective(text: string): {
+    readonly to: string;
+    readonly content: string;
+} | undefined;
+/**
+ * Fold a session's event log into the room state.
+ *
+ * Write-side invariants (invite/update/remove validate before appending) are
+ * NOT re-enforced here: a replayed log may be hand-edited or forked, so the
+ * fold is defensive — a duplicate member-added keeps the first record (first
+ * wins, a replay cannot re-seat a member), and updates/removals naming an
+ * unknown member are dropped. Unknown event types (e.g. a `room/note` from
+ * the dropped blackboard design) fall through the switch and are skipped.
+ * Removal also drops the member's run state: the roster reads clean after a
+ * remove. Relays and tasks fold by id, latest resolution winning.
+ * @param events - the session's event log.
+ * @returns the folded room state (empty for a non-room log).
+ */
+export declare function replay(events: readonly SessionEvent[]): RoomState;
+/**
+ * The goal progress pair: done tasks over the COUNTABLE total — cancelled
+ * and failed tasks leave the denominator (a cancelled task was never part
+ * of the plan; a failed one was planned but never advanced it).
+ * @param tasks - the folded task board.
+ * @returns done/total.
+ */
+export declare function taskProgress(tasks: readonly RoomTask[]): RoomTaskProgress;
+/**
+ * The member's dispatch cursor as of JUST BEFORE a given dispatch event: the
+ * latest earlier dispatch naming them. The engine reads the role-instruction
+ * carry against this cursor (pass {@link Number.MAX_SAFE_INTEGER} for a
+ * dispatch that is not itself journaled, e.g. a relay delivery).
+ * @param events - the session's event log.
+ * @param member - the dispatch target.
+ * @param beforeSeq - the current dispatch event's seq.
+ * @returns the previous dispatch seq, or undefined on the member's first dispatch.
+ */
+export declare function previousCursor(events: readonly SessionEvent[], member: string, beforeSeq: number): number | undefined;
+/**
+ * Whether the roster a member was last told about is stale: any roster-visible
+ * change with a seq past their dispatch cursor — a member-added or
+ * member-removed, or a member-updated that touches what the roster section
+ * shows (instructions = the one-line role, rename = the addressing name). A
+ * childSessionId/cwd/model-only update is NOT roster-visible (the delegation
+ * handle is journaled right after a first run; counting it would re-send the
+ * roster on every member's next dispatch for nothing — the model intent never
+ * enters any prompt either). A member with no cursor has
+ * never seen the roster, so their first dispatch always counts as stale.
+ * @param events - the session's event log.
+ * @param cursor - the member's pre-dispatch cursor ({@link previousCursor}).
+ * @returns true when the next dispatch must carry the roster section.
+ */
+export declare function rosterStaleSince(events: readonly SessionEvent[], cursor: number | undefined): boolean;
+/**
+ * The role-instructions carry for the next dispatch to a member: 'initial'
+ * when the member has never been dispatched (their instructions open the
+ * first prompt), 'update' when the latest member-added/member-updated event
+ * naming them postdates their dispatch cursor (an edit rides the next
+ * dispatch as a context update). Instructions events older than the cursor
+ * were already carried.
+ * @param events - the session's event log.
+ * @param member - the dispatch target.
+ * @param cursor - the member's pre-dispatch cursor ({@link previousCursor}).
+ * @returns the carry, or undefined when nothing needs carrying.
+ */
+export declare function pendingInstructions(events: readonly SessionEvent[], member: string, cursor: number | undefined): {
+    readonly kind: 'initial' | 'update';
+    readonly instructions: string;
+} | undefined;
+/** Resolve legacy join identity through renames; never key a new dispatch by display name. */
+export declare function memberId(events: readonly SessionEvent[], member: RoomMember): string;
+export declare function coordinatorMember(state: RoomState, events?: readonly SessionEvent[]): RoomMember | undefined;
+//# sourceMappingURL=journal.d.ts.map

package/lib/types/journal.js

@@ -0,0 +1,434 @@
+/**
+ * Room journal replay: folds the room session's `room/*` custom events into
+ * the derived {@link RoomState} — roster, notification relays, the task
+ * board, and run states. Pure: the Remote surface reads through it, the
+ * dispatch engine reads instruction cursors through it, and the unit tests
+ * exercise it without a cordis composition. Reload-replay recovers the exact
+ * same state, which is what makes the journal the room's single source of
+ * truth. There is NO blackboard fold: member prompts never consume the
+ * room's running log (see the design note) — speech/dispatch events are
+ * journaled for UI projection and replay only.
+ * @module @khorsheed/dsh-room/journal
+ */
+import { replayDeliveries } from './deliveries.js';
+/**
+ * The native DSH member's addressing name in new rooms. It starts as the
+ * coordinator; bare messages follow the selected coordinator thereafter.
+ * Existing journals retain their recorded names, including legacy main.
+ */
+export const MAIN_AGENT_MEMBER = 'dsh';
+/**
+ * Every `room/*` session-event type this package introduces. Room registers
+ * them into the harness's KNOWN_SESSION_EVENT_TYPES persistence catalog at
+ * apply time (see the RoomService constructor): the catalog's read-path
+ * refusal exists so a build that does NOT understand an event type never
+ * silently mangles the log — a build with room mounted understands these, so
+ * registration is the semantically correct declaration, and a build without
+ * room keeps refusing them. The catalog's own header defers a registration
+ * surface for out-of-repo plugins "until such a consumer exists"; this
+ * in-place add is that surface's temporary form — migrate to the official
+ * one when it lands upstream.
+ */
+export const ROOM_EVENT_TYPES = [
+    'room/created',
+    'room/plan-state',
+    'room/coordinator',
+    'room/delivery-state',
+    'room/member-added',
+    'room/member-updated',
+    'room/member-removed',
+    'room/dispatch',
+    'room/speech',
+    'room/run-state',
+    'room/relay',
+    'room/relay-resolved',
+    'room/task-added',
+    'room/task-updated',
+    'room/task-edited',
+    'room/goal',
+];
+/** Whether an event log carries the room identity marker. */
+export function isRoomLog(events) {
+    return events.some(event => event.type === 'room/created');
+}
+/**
+ * Parse the leading `@name` tokens of a raw composer message.
+ * @param raw - the raw text.
+ * @returns the addressed names (deduped, order-preserving) and the body with
+ * the mention prefix stripped. Only LEADING tokens address: an `@name`
+ * inside prose is plain text (a bare message goes to the selected coordinator).
+ */
+export function parseMentions(raw) {
+    const targets = [];
+    let rest = raw.trim();
+    for (;;) {
+        const match = /^@(\S+)(?:\s+|$)/.exec(rest);
+        if (match === null)
+            break;
+        const name = match[1];
+        if (!targets.includes(name))
+            targets.push(name);
+        rest = rest.slice(match[0].length).trim();
+    }
+    return { targets, text: rest };
+}
+/**
+ * The fallback notification channel: a member reply's TRAILING own line of
+ * the form `@name <content>` (the format the roster injection teaches).
+ * Only the last line counts — an `@name` inside prose is a mention, not a
+ * notification. Leading whitespace on that line is tolerated (models indent
+ * under their own bullet/list style). The caller checks the target against
+ * the roster.
+ * @param text - the member's reply text.
+ * @returns the parsed directive, or undefined.
+ */
+export function parseRelayDirective(text) {
+    const trimmed = text.trimEnd();
+    if (trimmed === '')
+        return undefined;
+    const last = trimmed.slice(trimmed.lastIndexOf('\n') + 1).trimStart();
+    const match = /^@(\S+)\s+(\S[\s\S]*)$/.exec(last);
+    if (match === null)
+        return undefined;
+    return { to: match[1], content: match[2].trim() };
+}
+/**
+ * Fold a session's event log into the room state.
+ *
+ * Write-side invariants (invite/update/remove validate before appending) are
+ * NOT re-enforced here: a replayed log may be hand-edited or forked, so the
+ * fold is defensive — a duplicate member-added keeps the first record (first
+ * wins, a replay cannot re-seat a member), and updates/removals naming an
+ * unknown member are dropped. Unknown event types (e.g. a `room/note` from
+ * the dropped blackboard design) fall through the switch and are skipped.
+ * Removal also drops the member's run state: the roster reads clean after a
+ * remove. Relays and tasks fold by id, latest resolution winning.
+ * @param events - the session's event log.
+ * @returns the folded room state (empty for a non-room log).
+ */
+export function replay(events) {
+    const members = [];
+    const byName = new Map();
+    const relays = [];
+    const relayById = new Map();
+    const tasks = [];
+    const taskById = new Map();
+    const runs = new Map();
+    let goal;
+    let coordinator;
+    for (const event of events) {
+        switch (event.type) {
+            case 'room/coordinator': {
+                if (event.data.revision > (coordinator?.revision ?? 0))
+                    coordinator = event.data;
+                break;
+            }
+            case 'room/member-added': {
+                if (byName.has(event.data.name))
+                    break;
+                const added = {
+                    id: event.data.id ?? `legacy:${event.seq}`,
+                    name: event.data.name,
+                    kind: event.data.kind,
+                    invitedBy: event.data.invitedBy,
+                    ...event.data.provider === undefined ? {} : { provider: event.data.provider },
+                    ...event.data.instructions === undefined ? {} : { instructions: event.data.instructions },
+                    ...event.data.cwd === undefined ? {} : { cwd: event.data.cwd },
+                    ...event.data.model === undefined ? {} : { model: event.data.model },
+                    ...event.data.childSessionId === undefined ? {} : { childSessionId: event.data.childSessionId },
+                };
+                byName.set(added.name, added);
+                members.push(added);
+                break;
+            }
+            case 'room/member-updated': {
+                const member = byName.get(event.data.name);
+                if (member === undefined)
+                    break;
+                // null CLEARS a field (rebuild without the key —
+                // exactOptionalPropertyTypes forbids writing undefined into it).
+                const withoutInstructions = event.data.instructions === null
+                    ? (({ instructions: _cleared, ...rest }) => rest)(member)
+                    : { ...member, ...event.data.instructions === undefined ? {} : { instructions: event.data.instructions } };
+                const withoutCwd = event.data.cwd === null
+                    ? (({ cwd: _cleared, ...rest }) => rest)(withoutInstructions)
+                    : { ...withoutInstructions, ...event.data.cwd === undefined ? {} : { cwd: event.data.cwd } };
+                const withoutModel = event.data.model === null
+                    ? (({ model: _cleared, ...rest }) => rest)(withoutCwd)
+                    : { ...withoutCwd, ...event.data.model === undefined ? {} : { model: event.data.model } };
+                const patched = {
+                    ...withoutModel,
+                    ...event.data.childSessionId === undefined ? {} : { childSessionId: event.data.childSessionId },
+                };
+                // A rename migrates every name-keyed projection: the roster key, the
+                // tasks' member (and blockedBy), the relays' from/to, and the runs
+                // key. The child session id rides the member record and stays. A
+                // colliding rename (the new name is taken — a hand-edited log; the
+                // write path validates) drops the rename, keeps the rest.
+                const rename = event.data.rename;
+                if (rename === undefined || rename === member.name || byName.has(rename)) {
+                    byName.set(member.name, patched);
+                    members[members.indexOf(member)] = patched;
+                    break;
+                }
+                const renamed = { ...patched, name: rename };
+                byName.delete(member.name);
+                byName.set(rename, renamed);
+                members[members.indexOf(member)] = renamed;
+                for (let index = 0; index < tasks.length; index++) {
+                    const task = tasks[index];
+                    if (task.member !== member.name && task.blockedBy !== member.name)
+                        continue;
+                    const migrated = {
+                        ...task,
+                        ...task.member === member.name ? { member: rename } : {},
+                        ...task.blockedBy === member.name ? { blockedBy: rename } : {},
+                    };
+                    taskById.set(migrated.id, migrated);
+                    tasks[index] = migrated;
+                }
+                for (let index = 0; index < relays.length; index++) {
+                    const relay = relays[index];
+                    if (relay.from !== member.name && relay.to !== member.name)
+                        continue;
+                    const migrated = {
+                        ...relay,
+                        from: relay.from === member.name ? rename : relay.from,
+                        to: relay.to === member.name ? rename : relay.to,
+                    };
+                    relayById.set(migrated.id, migrated);
+                    relays[index] = migrated;
+                }
+                const run = runs.get(member.name);
+                if (run !== undefined) {
+                    runs.delete(member.name);
+                    runs.set(rename, { ...run, member: rename });
+                }
+                break;
+            }
+            case 'room/member-removed': {
+                const member = byName.get(event.data.name);
+                if (member === undefined)
+                    break;
+                byName.delete(event.data.name);
+                members.splice(members.indexOf(member), 1);
+                runs.delete(event.data.name);
+                break;
+            }
+            case 'room/relay': {
+                if (relayById.has(event.data.id))
+                    break;
+                const relay = {
+                    id: event.data.id,
+                    from: event.data.from,
+                    to: event.data.to,
+                    content: event.data.content,
+                    state: 'pending',
+                    ...event.data.provenance === undefined ? {} : { provenance: event.data.provenance },
+                };
+                relayById.set(relay.id, relay);
+                relays.push(relay);
+                break;
+            }
+            case 'room/relay-resolved': {
+                const relay = relayById.get(event.data.id);
+                if (relay === undefined)
+                    break;
+                const resolved = { ...relay, state: event.data.state };
+                relayById.set(resolved.id, resolved);
+                relays[relays.indexOf(relay)] = resolved;
+                break;
+            }
+            case 'room/task-added': {
+                if (taskById.has(event.data.id))
+                    break;
+                const task = {
+                    id: event.data.id,
+                    member: event.data.member,
+                    title: event.data.title,
+                    ...event.data.deliveryId === undefined ? {} : { deliveryId: event.data.deliveryId },
+                    status: event.data.status,
+                    ...event.data.blockedBy === undefined ? {} : { blockedBy: event.data.blockedBy },
+                    updatedAt: event.time,
+                };
+                taskById.set(task.id, task);
+                tasks.push(task);
+                break;
+            }
+            case 'room/task-updated': {
+                const task = taskById.get(event.data.id);
+                if (task === undefined)
+                    break;
+                const updated = { ...task, status: event.data.status, updatedAt: event.time };
+                taskById.set(updated.id, updated);
+                tasks[tasks.indexOf(task)] = updated;
+                break;
+            }
+            case 'room/task-edited': {
+                const task = taskById.get(event.data.id);
+                if (task === undefined)
+                    break;
+                // An explicit null blockedBy CLEARS the wait: rebuild without the key
+                // (exactOptionalPropertyTypes forbids writing undefined into it).
+                const base = event.data.blockedBy === null
+                    ? (({ blockedBy: _cleared, ...rest }) => rest)(task)
+                    : { ...task, ...event.data.blockedBy === undefined ? {} : { blockedBy: event.data.blockedBy } };
+                const edited = {
+                    ...base,
+                    ...event.data.title === undefined ? {} : { title: event.data.title },
+                    updatedAt: event.time,
+                };
+                taskById.set(edited.id, edited);
+                tasks[tasks.indexOf(task)] = edited;
+                break;
+            }
+            case 'room/goal': {
+                // Latest goal event wins; a blank text clears the goal.
+                const text = event.data.text.trim();
+                goal = text === '' ? undefined : text;
+                break;
+            }
+            case 'room/run-state': {
+                const current = runs.get(event.data.member);
+                // An older turn may finish journaling after core admits its successor.
+                // Its delivery outcome remains durable, but it cannot replace that successor.
+                if (event.data.state !== 'running' && event.data.runId !== undefined && current?.runId !== undefined && current.runId !== event.data.runId)
+                    break;
+                runs.set(event.data.member, {
+                    member: event.data.member,
+                    state: event.data.state,
+                    startedAt: event.data.startedAt,
+                    ...event.data.runId === undefined ? {} : { runId: event.data.runId },
+                    ...event.data.elapsedMs === undefined ? {} : { elapsedMs: event.data.elapsedMs },
+                    ...event.data.error === undefined ? {} : { error: event.data.error },
+                });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    const planEvent = events.filter(event => event.type === 'room/plan-state').at(-1);
+    const plan = planEvent?.type === 'room/plan-state' ? (({ requests: _requests, ...view }) => view)(planEvent.data) : undefined;
+    const deliveries = replayDeliveries(events);
+    return { members, relays, tasks, ...plan === undefined ? {} : { plan }, ...deliveries.length === 0 ? {} : { deliveries }, runs: [...runs.values()], ...coordinator === undefined ? {} : { coordinator }, ...goal === undefined ? {} : { goal } };
+}
+/**
+ * The goal progress pair: done tasks over the COUNTABLE total — cancelled
+ * and failed tasks leave the denominator (a cancelled task was never part
+ * of the plan; a failed one was planned but never advanced it).
+ * @param tasks - the folded task board.
+ * @returns done/total.
+ */
+export function taskProgress(tasks) {
+    const countable = tasks.filter(task => task.status !== 'cancelled' && task.status !== 'failed');
+    return { done: countable.filter(task => task.status === 'done').length, total: countable.length };
+}
+/**
+ * The member's dispatch cursor as of JUST BEFORE a given dispatch event: the
+ * latest earlier dispatch naming them. The engine reads the role-instruction
+ * carry against this cursor (pass {@link Number.MAX_SAFE_INTEGER} for a
+ * dispatch that is not itself journaled, e.g. a relay delivery).
+ * @param events - the session's event log.
+ * @param member - the dispatch target.
+ * @param beforeSeq - the current dispatch event's seq.
+ * @returns the previous dispatch seq, or undefined on the member's first dispatch.
+ */
+export function previousCursor(events, member, beforeSeq) {
+    let cursor;
+    for (const event of events) {
+        if (event.type !== 'room/dispatch' || event.seq >= beforeSeq)
+            continue;
+        if (event.data.targets.includes(member))
+            cursor = event.seq;
+    }
+    return cursor;
+}
+/**
+ * Whether the roster a member was last told about is stale: any roster-visible
+ * change with a seq past their dispatch cursor — a member-added or
+ * member-removed, or a member-updated that touches what the roster section
+ * shows (instructions = the one-line role, rename = the addressing name). A
+ * childSessionId/cwd/model-only update is NOT roster-visible (the delegation
+ * handle is journaled right after a first run; counting it would re-send the
+ * roster on every member's next dispatch for nothing — the model intent never
+ * enters any prompt either). A member with no cursor has
+ * never seen the roster, so their first dispatch always counts as stale.
+ * @param events - the session's event log.
+ * @param cursor - the member's pre-dispatch cursor ({@link previousCursor}).
+ * @returns true when the next dispatch must carry the roster section.
+ */
+export function rosterStaleSince(events, cursor) {
+    if (cursor === undefined)
+        return true;
+    for (const event of events) {
+        if (event.seq <= cursor)
+            continue;
+        if (event.type === 'room/member-added' || event.type === 'room/member-removed')
+            return true;
+        if (event.type === 'room/member-updated'
+            && (event.data.instructions !== undefined || event.data.rename !== undefined))
+            return true;
+    }
+    return false;
+}
+/**
+ * The role-instructions carry for the next dispatch to a member: 'initial'
+ * when the member has never been dispatched (their instructions open the
+ * first prompt), 'update' when the latest member-added/member-updated event
+ * naming them postdates their dispatch cursor (an edit rides the next
+ * dispatch as a context update). Instructions events older than the cursor
+ * were already carried.
+ * @param events - the session's event log.
+ * @param member - the dispatch target.
+ * @param cursor - the member's pre-dispatch cursor ({@link previousCursor}).
+ * @returns the carry, or undefined when nothing needs carrying.
+ */
+export function pendingInstructions(events, member, cursor) {
+    let lastSeq;
+    let lastInstructions;
+    for (const event of events) {
+        if (event.type === 'room/member-added' && event.data.name === member
+            && event.data.instructions !== undefined) {
+            lastSeq = event.seq;
+            lastInstructions = event.data.instructions;
+        }
+        else if (event.type === 'room/member-updated' && event.data.name === member) {
+            // A null instructions CLEARS the preset: nothing rides the next dispatch.
+            if (event.data.instructions === null) {
+                lastSeq = undefined;
+                lastInstructions = undefined;
+            }
+            else if (event.data.instructions !== undefined) {
+                lastSeq = event.seq;
+                lastInstructions = event.data.instructions;
+            }
+        }
+    }
+    if (lastSeq === undefined || lastInstructions === undefined)
+        return undefined;
+    if (cursor === undefined)
+        return { kind: 'initial', instructions: lastInstructions };
+    if (lastSeq > cursor)
+        return { kind: 'update', instructions: lastInstructions };
+    return undefined;
+}
+/** Resolve legacy join identity through renames; never key a new dispatch by display name. */
+export function memberId(events, member) {
+    if (member.id !== undefined)
+        return member.id;
+    let name = member.name;
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (event.type === 'room/member-updated' && event.data.rename === name)
+            name = event.data.name;
+        if (event.type === 'room/member-added' && event.data.name === name)
+            return event.data.id ?? `legacy:${event.seq}`;
+    }
+    throw new Error('Room member has no join identity');
+}
+export function coordinatorMember(state, events) {
+    if (state.coordinator === undefined)
+        return state.members.find(member => member.kind === 'main-agent');
+    return state.members.find(member => (member.id ?? (events === undefined ? undefined : memberId(events, member))) === state.coordinator.memberId);
+}

package/lib/types/plan-service.d.ts

@@ -0,0 +1,34 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { PlanActor, RoomPlan } from './plan.ts';
+import type { DispatchEngine } from './dispatch.ts';
+export declare function readPlan(room: Session): RoomPlan | undefined;
+/** One serialized writer for durable goal transitions and automatic leaf dispatch. */
+export declare class PlanService {
+    private readonly ctx;
+    private readonly engine;
+    private readonly tails;
+    private readonly recovered;
+    private readonly timers;
+    constructor(ctx: Context, engine: () => DispatchEngine);
+    private locked;
+    /** Cold inspection projects the restart pause without writing or starting agents. */
+    view(sessionId: string, view: Omit<RoomPlan, 'requests'>): Omit<RoomPlan, 'requests'>;
+    recover(room: Session): Promise<void>;
+    private recoverUnlocked;
+    private write;
+    private armDeadline;
+    command(room: Session, json: string, actor: PlanActor): Promise<RoomPlan>;
+    allows(room: Session, dispatchSeq?: number): boolean;
+    admitted(room: Session, dispatchSeq?: number): Promise<void>;
+    settled(room: Session, dispatchSeq: number | undefined, outcome: {
+        state: 'done' | 'failed' | 'cancelled';
+        text?: string;
+        error?: string;
+    }): Promise<void>;
+    /** Human goal reconciliation settles its room delivery and supersedes stale queued reports. */
+    private reconcileDelivery;
+    private pump;
+    dispose(): void;
+}
+//# sourceMappingURL=plan-service.d.ts.map