@muse-code/sdk 1.4.2 → 1.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -42,6 +42,19 @@ export interface DuplexTransport {
42
42
  * public `child.close()` — gets the same step 0 (PR #22819 round 4).
43
43
  */
44
44
  export declare const submissionTail: unique symbol;
45
+ /**
46
+ * Module-private friend seam, like {@link submissionTail}: a request whose
47
+ * promise also yields the exact response frame it settled on, so a caller
48
+ * that refuses a successful result (the handshake's schema-fingerprint
49
+ * check) can put the whole refused frame on `ProtocolError.line`, the same
50
+ * value every other refusal carries (#50588 review).
51
+ */
52
+ export declare const requestWithFrame: unique symbol;
53
+ /** What {@link requestWithFrame} resolves with: the result and its wire line. */
54
+ export interface FramedResult {
55
+ readonly result: Record<string, unknown>;
56
+ readonly line: string;
57
+ }
45
58
  /**
46
59
  * Tuning knobs for a `Connection`. Every option is optional: the defaults
47
60
  * suit a spawned host, so most applications never pass this at all.
@@ -81,6 +94,12 @@ export declare class MspError extends Error {
81
94
  }
82
95
  /** A local framing/correlation violation, never a server-authored MSP error. */
83
96
  export declare class ProtocolError extends Error {
97
+ /**
98
+ * The inbound frame (wire line) the violation was detected on, when there
99
+ * is one — the whole line, e.g. the response a pending request refused;
100
+ * an oversized frame is cut to the frame limit. Absent for local state
101
+ * errors (closed connection, EOF) that no frame caused.
102
+ */
84
103
  readonly line: string | undefined;
85
104
  constructor(message: string, line?: string);
86
105
  }
@@ -104,6 +123,8 @@ export declare class Connection {
104
123
  /** See {@link submissionTail}. */
105
124
  [submissionTail](): Promise<void>;
106
125
  request(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
126
+ /** See {@link requestWithFrame}. */
127
+ [requestWithFrame](method: string, params?: Record<string, unknown>): Promise<FramedResult>;
107
128
  /**
108
129
  * Take one id from THIS connection's single `commandId` minter (INV-013).
109
130
  *
@@ -8,6 +8,7 @@
8
8
  * stdout's encoding before implementing this interface — is one
9
9
  * well-behaved transport, not the general guarantee.
10
10
  */
11
+ import { createHash } from "node:crypto";
11
12
  const DEFAULT_FRAME_LIMIT_BYTES = 10_485_760;
12
13
  /**
13
14
  * Module-private friend seam (never on the package barrel, like spawn.ts's
@@ -16,6 +17,14 @@ const DEFAULT_FRAME_LIMIT_BYTES = 10_485_760;
16
17
  * public `child.close()` — gets the same step 0 (PR #22819 round 4).
17
18
  */
18
19
  export const submissionTail = Symbol("Connection.submissionTail");
20
+ /**
21
+ * Module-private friend seam, like {@link submissionTail}: a request whose
22
+ * promise also yields the exact response frame it settled on, so a caller
23
+ * that refuses a successful result (the handshake's schema-fingerprint
24
+ * check) can put the whole refused frame on `ProtocolError.line`, the same
25
+ * value every other refusal carries (#50588 review).
26
+ */
27
+ export const requestWithFrame = Symbol("Connection.requestWithFrame");
19
28
  /** The one typed error family consumers branch on (INV-012). */
20
29
  export class MspError extends Error {
21
30
  code;
@@ -33,6 +42,12 @@ export class MspError extends Error {
33
42
  }
34
43
  /** A local framing/correlation violation, never a server-authored MSP error. */
35
44
  export class ProtocolError extends Error {
45
+ /**
46
+ * The inbound frame (wire line) the violation was detected on, when there
47
+ * is one — the whole line, e.g. the response a pending request refused;
48
+ * an oversized frame is cut to the frame limit. Absent for local state
49
+ * errors (closed connection, EOF) that no frame caused.
50
+ */
36
51
  line;
37
52
  constructor(message, line) {
38
53
  super(message);
@@ -77,6 +92,13 @@ function canonical(value) {
77
92
  }
78
93
  return JSON.stringify(value);
79
94
  }
95
+ // FR-45137-1: the dedup guards compare fingerprints, so a remembered command
96
+ // costs 64 hex chars no matter how large its payload (or ack) was. The hash
97
+ // guards a correctness check, so it is SHA-256, not a faster non-crypto hash
98
+ // whose collision would silently accept a different payload.
99
+ function fingerprint(canonicalForm) {
100
+ return createHash("sha256").update(canonicalForm, "utf8").digest("hex");
101
+ }
80
102
  /** Create the SDK-owned UUIDv7 command-id source for a connection/client. */
81
103
  export function createUuidV7Mint() {
82
104
  let lastMs = -1;
@@ -177,6 +199,13 @@ export class Connection {
177
199
  return this.#submitTail;
178
200
  }
179
201
  request(method, params) {
202
+ return this.#request(method, params).then((framed) => framed.result);
203
+ }
204
+ /** See {@link requestWithFrame}. */
205
+ [requestWithFrame](method, params) {
206
+ return this.#request(method, params);
207
+ }
208
+ #request(method, params) {
180
209
  if (this.#finished)
181
210
  return Promise.reject(new ProtocolError("connection is closed"));
182
211
  const id = this.#mintRequestId();
@@ -193,7 +222,10 @@ export class Connection {
193
222
  ...(params === undefined ? {} : { params }),
194
223
  };
195
224
  return new Promise((resolve, reject) => {
196
- this.#pending.set(requestKey(id), { resolve, reject });
225
+ this.#pending.set(requestKey(id), {
226
+ resolve: (result, line) => resolve({ result, line }),
227
+ reject,
228
+ });
197
229
  void this.#write(request).catch((error) => {
198
230
  this.#pending.delete(requestKey(id));
199
231
  reject(error);
@@ -241,7 +273,7 @@ export class Connection {
241
273
  async command(method, params, options) {
242
274
  const commandId = options?.commandId ?? this.#mintCommandId();
243
275
  const commandParams = { ...params, commandId };
244
- const signature = canonical({ method, params: commandParams });
276
+ const signature = fingerprint(canonical({ method, params: commandParams }));
245
277
  const memory = this.#commands.get(commandId);
246
278
  if (memory !== undefined && memory.signature !== signature) {
247
279
  throw new ProtocolError(`commandId ${commandId} was reused with a different payload`);
@@ -261,10 +293,11 @@ export class Connection {
261
293
  if (ack["commandId"] !== undefined && ack["commandId"] !== commandId) {
262
294
  throw new ProtocolError(`${method} ack commandId ${String(ack["commandId"])} did not echo ${commandId}`);
263
295
  }
264
- if (remembered.ack !== undefined && canonical(remembered.ack) !== canonical(ack)) {
296
+ const ackFingerprint = fingerprint(canonical(ack));
297
+ if (remembered.ack !== undefined && remembered.ack !== ackFingerprint) {
265
298
  throw new ProtocolError(`${method} replay for commandId ${commandId} did not return a value-identical ack`);
266
299
  }
267
- remembered.ack = { ...ack };
300
+ remembered.ack = ackFingerprint;
268
301
  return ack;
269
302
  }
270
303
  catch (error) {
@@ -475,7 +508,7 @@ export class Connection {
475
508
  pending.reject(new ProtocolError("response result must be an object", line));
476
509
  return;
477
510
  }
478
- pending.resolve(result);
511
+ pending.resolve(result, line);
479
512
  return;
480
513
  }
481
514
  const error = frame["error"];
@@ -1,5 +1,6 @@
1
1
  /** Node stdio binding and type-state handshake for the MSP connection. */
2
- import type { ChildProcessWithoutNullStreams } from "node:child_process";
2
+ import { spawn } from "node:child_process";
3
+ import type { ChildProcessWithoutNullStreams, SpawnOptionsWithoutStdio } from "node:child_process";
3
4
  import type { InitializeParams, InitializeResult } from "../msp.js";
4
5
  import { Connection } from "./connection.js";
5
6
  import type { ConnectionOptions, DuplexTransport, NotificationHandler, ProtocolErrorHandler, ServerRequestHandler } from "./connection.js";
@@ -73,9 +74,22 @@ export interface MuseServeChildOptions {
73
74
  * `0..2147483647`; anything else throws `RangeError` at spawn.
74
75
  */
75
76
  readonly shutdownTimeoutMs?: number;
77
+ /**
78
+ * Deterministic-test seam; production always uses `child_process.spawn`.
79
+ * A stub here observes the exact options the call site passes, so a
80
+ * `windowsHide` override at the call site fails the pin (FR-45141-1).
81
+ */
82
+ readonly spawnFn?: typeof spawn;
76
83
  }
77
84
  declare const ownedTransport: unique symbol;
78
85
  declare const adoptFlushSource: unique symbol;
86
+ /**
87
+ * Module friend seam: did `initialize` get a usable answer before the
88
+ * handshake failed? Exported from this MODULE only (never the package
89
+ * barrel) so the facade can word a host lost AFTER answering truthfully
90
+ * (#49912) without a new public member on `MspHandshake`.
91
+ */
92
+ export declare const initializeAnswered: unique symbol;
79
93
  /**
80
94
  * Shutdown deadline contract: `expired` resolves and never rejects; after
81
95
  * `clear()` it may remain pending forever.
@@ -122,6 +136,17 @@ export declare class ChildStdioTransport implements DuplexTransport {
122
136
  [adoptFlushSource](source: () => Promise<void>): void;
123
137
  close(flushed?: Promise<void>): Promise<void>;
124
138
  }
139
+ /**
140
+ * The exact options `MuseServeChild.spawn` hands to `child_process.spawn`,
141
+ * factored out so the spawn-options pin can assert on them without spawning.
142
+ * Exported from this MODULE only (never the package barrel) — the same
143
+ * module-only-test-seam precedent as `isBenignCloseRace`.
144
+ */
145
+ export declare function buildSpawnOptions(options: {
146
+ readonly cwd?: string;
147
+ readonly env?: NodeJS.ProcessEnv;
148
+ readonly detached: boolean;
149
+ }): SpawnOptionsWithoutStdio;
125
150
  /** One owned MSP host process with SS2.11 diagnostics and total exit mapping. */
126
151
  export declare class MuseServeChild {
127
152
  #private;
@@ -143,6 +168,8 @@ export declare class MspHandshake {
143
168
  onNotification(handler: NotificationHandler): void;
144
169
  onProtocolError(handler: ProtocolErrorHandler): void;
145
170
  close(): Promise<ProcessExit>;
171
+ /** See {@link initializeAnswered}. */
172
+ [initializeAnswered](): boolean;
146
173
  initialize(params: InitializeParams): Promise<SpawnedMspConnection>;
147
174
  }
148
175
  /** A fully initialized connection plus its owned process boundary. */
@@ -1,6 +1,6 @@
1
1
  /** Node stdio binding and type-state handshake for the MSP connection. */
2
2
  import { spawn } from "node:child_process";
3
- import { Connection, ProtocolError, submissionTail, } from "./connection.js";
3
+ import { Connection, ProtocolError, requestWithFrame, submissionTail, } from "./connection.js";
4
4
  import { checkServedFingerprint } from "../fingerprint.js";
5
5
  const DEFAULT_STDERR_MAX_BYTES = 8 * 1024;
6
6
  const DEFAULT_STDERR_MAX_LINES = 100;
@@ -16,6 +16,13 @@ const SIGTERM_GRACE_MS = 2_000;
16
16
  const MAX_SHUTDOWN_TIMEOUT_MS = 2_147_483_647;
17
17
  const ownedTransport = Symbol("MuseServeChild.transport");
18
18
  const adoptFlushSource = Symbol("ChildStdioTransport.adoptFlushSource");
19
+ /**
20
+ * Module friend seam: did `initialize` get a usable answer before the
21
+ * handshake failed? Exported from this MODULE only (never the package
22
+ * barrel) so the facade can word a host lost AFTER answering truthfully
23
+ * (#49912) without a new public member on `MspHandshake`.
24
+ */
25
+ export const initializeAnswered = Symbol("MspHandshake.initializeAnswered");
19
26
  function makeShutdownDeadline(budgetMs) {
20
27
  let timer;
21
28
  const expired = new Promise((resolve) => {
@@ -332,6 +339,23 @@ export class ChildStdioTransport {
332
339
  yield String(chunk);
333
340
  }
334
341
  }
342
+ /**
343
+ * The exact options `MuseServeChild.spawn` hands to `child_process.spawn`,
344
+ * factored out so the spawn-options pin can assert on them without spawning.
345
+ * Exported from this MODULE only (never the package barrel) — the same
346
+ * module-only-test-seam precedent as `isBenignCloseRace`.
347
+ */
348
+ export function buildSpawnOptions(options) {
349
+ return {
350
+ ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
351
+ ...(options.env === undefined ? {} : { env: options.env }),
352
+ detached: options.detached,
353
+ // FR-45141-1: `muse serve` is never meant to be seen. Without this, a
354
+ // Windows host with no console of its own pops a console window for the
355
+ // life of the connection; the flag is a no-op on other platforms.
356
+ windowsHide: true,
357
+ };
358
+ }
335
359
  /** One owned MSP host process with SS2.11 diagnostics and total exit mapping. */
336
360
  export class MuseServeChild {
337
361
  #tail = new StderrTail();
@@ -360,12 +384,13 @@ export class MuseServeChild {
360
384
  // PID is a POSIX primitive, and pretending otherwise would fake
361
385
  // subtree containment there.
362
386
  const ownsProcessGroup = process.platform !== "win32";
363
- const spawnOptions = {
364
- ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
365
- ...(options.env === undefined ? {} : { env: options.env }),
387
+ const spawnOptions = buildSpawnOptions({
388
+ cwd: options.cwd,
389
+ env: options.env,
366
390
  detached: ownsProcessGroup,
367
- };
368
- return new MuseServeChild(spawn(options.museBin, [...(options.args ?? [])], spawnOptions), options.onStderr, options.shutdownTimeoutMs, ownsProcessGroup);
391
+ });
392
+ const spawnChild = options.spawnFn ?? spawn;
393
+ return new MuseServeChild(spawnChild(options.museBin, [...(options.args ?? [])], spawnOptions), options.onStderr, options.shutdownTimeoutMs, ownsProcessGroup);
369
394
  }
370
395
  get stderrTail() {
371
396
  return this.#tail.lines();
@@ -385,6 +410,7 @@ export class MspHandshake {
385
410
  child;
386
411
  #transport;
387
412
  #started = false;
413
+ #answered = false;
388
414
  constructor(options) {
389
415
  this.child = MuseServeChild.spawn({
390
416
  museBin: options.command,
@@ -420,14 +446,22 @@ export class MspHandshake {
420
446
  await this.#connection.close();
421
447
  return await this.#transport.exited;
422
448
  }
449
+ /** See {@link initializeAnswered}. */
450
+ [initializeAnswered]() {
451
+ return this.#answered;
452
+ }
423
453
  async initialize(params) {
424
454
  if (this.#started)
425
455
  throw new ProtocolError("initialize may be sent only once per connection");
426
456
  this.#started = true;
427
- const raw = await this.#connection.request("initialize", params);
457
+ const { result: raw, line } = await this.#connection[requestWithFrame]("initialize", params);
458
+ this.#answered = true;
428
459
  const result = raw;
429
460
  if (typeof result.schema?.fingerprint !== "string") {
430
- throw new ProtocolError("initialize result has no schema fingerprint");
461
+ // The whole refused frame rides on the error, as on every other
462
+ // refusal: a host that answered with an unusable result was not lost,
463
+ // and the facade tells the two apart by it (#49912, #50588 review).
464
+ throw new ProtocolError("initialize result has no schema fingerprint", line);
431
465
  }
432
466
  const fingerprintWarning = checkServedFingerprint(result.schema.fingerprint);
433
467
  this.#connection.notify("initialized");
@@ -106,6 +106,15 @@ export declare class MuseClient {
106
106
  * reason this factory exists beside the bare constructor: SS2.13.1 makes the
107
107
  * absent/unrecognized distinction load-bearing, and a caller re-deriving it
108
108
  * by hand is a caller that can get it wrong.
109
+ *
110
+ * Rejects with {@link MuseHostStartError} when the host is lost before the
111
+ * handshake completes (the binary could not be spawned, or the process
112
+ * ended first — exit code or signal plus the bounded stderr tail;
113
+ * `answeredInitialize` says whether it died after a usable answer). A host
114
+ * that answers with a reply the SDK refuses keeps its own error: an
115
+ * `MspError` for an SS1.6 refusal, or a `ProtocolError` (with the whole
116
+ * refused frame on `line`) for a reply the SDK cannot use, such as one with
117
+ * no schema fingerprint.
109
118
  */
110
119
  static spawn(options: MuseClientSpawnOptions): Promise<MuseClient>;
111
120
  /**
@@ -35,10 +35,12 @@
35
35
  * chain close that gap — add a member upstream and the BUILD fails here until
36
36
  * it is forwarded (or explicitly allow-listed as unforwardable).
37
37
  */
38
- import { spawnMspConnection } from "../connection/spawn.js";
38
+ import { initializeAnswered, spawnMspConnection } from "../connection/spawn.js";
39
39
  import { MuseSessionDiscardedError } from "../errors.js";
40
40
  import { DiscardedSessions } from "./discarded.js";
41
41
  import { isAbnormalHostDeath, readSessionDurability } from "./host-death.js";
42
+ import { MspError, ProtocolError } from "../connection/connection.js";
43
+ import { hostStartFailure } from "./host-start.js";
42
44
  import { Session } from "./session.js";
43
45
  /**
44
46
  * Every `StartParams` member `startSession` forwards. `config` is temporarily
@@ -72,6 +74,15 @@ export class MuseClient {
72
74
  #discarded;
73
75
  /** Sessions this client opened, so one death notification reaches them all. */
74
76
  #sessions = new Set();
77
+ /**
78
+ * Frames naming a session this client has not registered YET, held only
79
+ * while a `session/start`/`session/resume` is in flight (#49790): the host
80
+ * flushes the resume replay BEFORE the result, and the promise awaiting that
81
+ * result resumes only after the whole chunk has been routed. `#route` holds,
82
+ * `#openSession` drains, `#open` clears when the last open settles.
83
+ */
84
+ #held = new Map();
85
+ #opening = 0;
75
86
  /** The spawned host, when `spawn` built this client. */
76
87
  #child;
77
88
  #initializeResult;
@@ -113,16 +124,29 @@ export class MuseClient {
113
124
  * session: `Session.apply` already tolerates unknown methods, but only the
114
125
  * frames that name a `sessionId` have an owner to route to. A frame naming
115
126
  * an UNKNOWN session is dropped for the same reason — routing it anywhere
116
- * would trip the foreign-frame throw on a session it does not belong to.
127
+ * would trip the foreign-frame throw on a session it does not belong to —
128
+ * UNLESS an open is in flight, when it may be that open's own session named
129
+ * by the server before the awaiting promise has run (#49790): then it is
130
+ * held for `#openSession` to fold, or for `#open` to clear.
117
131
  */
118
132
  #route(notification) {
119
133
  const named = notification.params?.sessionId;
120
134
  if (typeof named !== "string")
121
135
  return;
136
+ let delivered = false;
122
137
  for (const session of this.#sessions) {
123
- if (session.sessionId === named)
138
+ if (session.sessionId === named) {
124
139
  session.apply(notification);
140
+ delivered = true;
141
+ }
125
142
  }
143
+ if (delivered || this.#opening === 0)
144
+ return;
145
+ const held = this.#held.get(named);
146
+ if (held === undefined)
147
+ this.#held.set(named, [notification]);
148
+ else
149
+ held.push(notification);
126
150
  }
127
151
  /**
128
152
  * Spawn an owned host, run the SS1.4 handshake, and hand back a client whose
@@ -132,6 +156,15 @@ export class MuseClient {
132
156
  * reason this factory exists beside the bare constructor: SS2.13.1 makes the
133
157
  * absent/unrecognized distinction load-bearing, and a caller re-deriving it
134
158
  * by hand is a caller that can get it wrong.
159
+ *
160
+ * Rejects with {@link MuseHostStartError} when the host is lost before the
161
+ * handshake completes (the binary could not be spawned, or the process
162
+ * ended first — exit code or signal plus the bounded stderr tail;
163
+ * `answeredInitialize` says whether it died after a usable answer). A host
164
+ * that answers with a reply the SDK refuses keeps its own error: an
165
+ * `MspError` for an SS1.6 refusal, or a `ProtocolError` (with the whole
166
+ * refused frame on `line`) for a reply the SDK cannot use, such as one with
167
+ * no schema fingerprint.
135
168
  */
136
169
  static async spawn(options) {
137
170
  const handshake = spawnMspConnection({
@@ -154,7 +187,23 @@ export class MuseClient {
154
187
  catch (error) {
155
188
  // A failed handshake must not leak the process it already spawned.
156
189
  await handshake.close().catch(() => undefined);
157
- throw error;
190
+ // A host that ANSWERED `initialize` is not a lost host, however it ends
191
+ // once we close it: its answer is the actionable error. "Answered" is
192
+ // evidence that a response frame came back — an SS1.6 `MspError`, or a
193
+ // `ProtocolError` carrying the frame the SDK refused (a malformed or
194
+ // version-skewed reply) — never the error's class alone (#49912).
195
+ // Decided before the exit is read, so our own close ladder can never
196
+ // dress an answer up as a death.
197
+ const answered = error instanceof MspError || (error instanceof ProtocolError && error.line !== undefined);
198
+ if (answered)
199
+ throw error;
200
+ // No refused frame: the host was lost — before answering, or after a
201
+ // usable answer while we sent `initialized` (the error then says so).
202
+ // close() ended at its observed exit (or its spawn failure), so the
203
+ // evidence is settled: the typed error carries the spawn error or the
204
+ // SS2.11 row plus the stderr tail instead of the transport's first
205
+ // symptom (#49791, #49912).
206
+ throw await hostStartFailure(handshake.child, error, handshake[initializeAnswered]());
158
207
  }
159
208
  return new MuseClient(spawned.connection, {
160
209
  durability: readSessionDurability(spawned.initializeResult),
@@ -203,15 +252,13 @@ export class MuseClient {
203
252
  params.workspaceRoots = options.workspaceRoots;
204
253
  if (options.modelId != null)
205
254
  params.modelId = options.modelId;
206
- const raw = await this.#connection.command("session/start", params);
207
- const result = raw;
208
255
  // Keyed by the id the SERVER named, never the one the caller asked for:
209
256
  // `sessionId` is a REQUEST on start, and a session keyed by a hopeful id
210
257
  // would reject every one of its own events as foreign.
211
- return this.#openSession(result.session.sessionId, {
212
- result,
258
+ return this.#open("session/start", params, (raw) => ({
259
+ result: raw,
213
260
  verb: "session/start",
214
- });
261
+ }));
215
262
  }
216
263
  /**
217
264
  * Load an existing session and subscribe this connection to its view
@@ -231,12 +278,10 @@ export class MuseClient {
231
278
  params.excludeItems = options.excludeItems;
232
279
  if (options.history != null)
233
280
  params.history = options.history;
234
- const raw = await this.#connection.command("session/resume", params);
235
- const result = raw;
236
- return this.#openSession(result.session.sessionId, {
237
- result,
281
+ return this.#open("session/resume", params, (raw) => ({
282
+ result: raw,
238
283
  verb: "session/resume",
239
- });
284
+ }));
240
285
  }
241
286
  /**
242
287
  * Shut the host down in an orderly way (SS2.1.2); the shutdown this causes
@@ -265,6 +310,25 @@ export class MuseClient {
265
310
  }
266
311
  await this.#connection.close();
267
312
  }
313
+ /**
314
+ * The window `#route` holds unknown-session frames for: from the request to
315
+ * the Session's registration. Counted, not flagged, so two concurrent opens
316
+ * keep it open until the LAST settles; cleared on settle so a frame that
317
+ * named no session this client opened is held no longer than the open it
318
+ * rode in with (#49790).
319
+ */
320
+ async #open(verb, params, opening) {
321
+ this.#opening += 1;
322
+ try {
323
+ const opened = opening(await this.#connection.command(verb, params));
324
+ return this.#openSession(opened.result.session.sessionId, opened);
325
+ }
326
+ finally {
327
+ this.#opening -= 1;
328
+ if (this.#opening === 0)
329
+ this.#held.clear();
330
+ }
331
+ }
268
332
  #openSession(sessionId, opening) {
269
333
  const session = new Session({
270
334
  connection: this.#connection,
@@ -274,6 +338,15 @@ export class MuseClient {
274
338
  sessionId,
275
339
  });
276
340
  this.#sessions.add(session);
341
+ // The frames that named this session while its verb was in flight fold
342
+ // NOW, in arrival order — synchronously, so nothing the pump routes next
343
+ // can overtake them.
344
+ const held = this.#held.get(sessionId);
345
+ if (held !== undefined) {
346
+ this.#held.delete(sessionId);
347
+ for (const frame of held)
348
+ session.apply(frame);
349
+ }
277
350
  return session;
278
351
  }
279
352
  #assertReattachAllowed(sessionId) {
@@ -208,9 +208,13 @@ export class GapFiller {
208
208
  return;
209
209
  const result = await this.#page(connection, this.#cursor);
210
210
  let reached = false;
211
+ // The last cursor this page served, skipped events included — where a
212
+ // walk toward an extended target resumes after an end-of-view page.
213
+ let lastServed;
211
214
  for (const event of result.events) {
212
215
  this.#requireOwnSession(event, after, target);
213
216
  const cursor = event.params.viewCursor;
217
+ lastServed = cursor;
214
218
  // An EARLIER fill already served — and applied — this durable event.
215
219
  // A later walk may legally page through the same range, and re-applying
216
220
  // it here is the same double fold the discard exists to prevent (PR
@@ -243,8 +247,17 @@ export class GapFiller {
243
247
  // The server's own end of the view. `next` names a LIVE cursor and
244
248
  // `view/page` serves durable-sourced events only (tdd SS4.7.3), so a
245
249
  // hole whose tail was ephemeral ends here and never at `target`.
246
- if (result.nextCursor === null)
250
+ //
251
+ // The cursor still advances to the last event served (#50252, the Rust
252
+ // SDK's INV-002 rule from #49869): if a `view/gap` extended the target
253
+ // while this page was in flight, `#walk` comes back here toward the new
254
+ // one, and re-asking from where this walk started would re-serve — and
255
+ // fold a second time — every event this page just delivered.
256
+ if (result.nextCursor === null) {
257
+ if (lastServed !== undefined)
258
+ this.#cursor = lastServed;
247
259
  return;
260
+ }
248
261
  // PROGRESS is the only bound on this walk, and it has to be, because a
249
262
  // legitimate fill is unbounded in length: an attempt cap would silently
250
263
  // truncate one. A page that carries no event, repeats the cursor it was
@@ -0,0 +1,62 @@
1
+ /**
2
+ * The typed failure of `MuseClient.spawn` when the host is lost before the
3
+ * SS1.4 handshake completes (#49791).
4
+ *
5
+ * Without it the rejection is whatever the transport saw first — `write
6
+ * EPIPE` on the first frame, or `connection reached EOF` — while the evidence
7
+ * that explains it (Node's spawn error, or the SS2.11 exit row with its
8
+ * bounded stderr tail) sits unread on the child the facade already owns.
9
+ * Spec 14990 Scenario 4 attaches that evidence to every process-exit error;
10
+ * this module is the handshake-failure arm of that rule.
11
+ */
12
+ import type { ExitClassification, MuseServeChild } from "../connection/spawn.js";
13
+ /**
14
+ * How the host was lost. Two arms because the repair differs: `spawnFailed`
15
+ * means no process ever ran (`error` is Node's own spawn error — `code`
16
+ * `ENOENT`, `EACCES`, … — so fix the path or its permissions); `hostExited`
17
+ * means a process ran and ended before the handshake completed, and `exit` is
18
+ * its SS2.11 row — any row, the clean one included: a host that wrote its
19
+ * complaint to stderr and exited 0 before its first frame is still a lost
20
+ * host, and the row says only how it ended. `answeredInitialize` says whether
21
+ * it got as far as a usable `initialize` answer before dying (then the loss
22
+ * came while the SDK was completing the handshake, not at startup).
23
+ */
24
+ export type HostStartFailure = {
25
+ readonly kind: "spawnFailed";
26
+ readonly error: NodeJS.ErrnoException;
27
+ } | {
28
+ readonly kind: "hostExited";
29
+ readonly exit: ExitClassification;
30
+ readonly answeredInitialize: boolean;
31
+ };
32
+ /**
33
+ * `MuseClient.spawn` lost its host before the handshake completed.
34
+ *
35
+ * Typed rather than a bare `Error` because the two arms of `failure` name
36
+ * STATES an embedder branches on (retry after fixing the path, versus act on
37
+ * an SS2.11 retry posture). The transport error that first surfaced the loss
38
+ * rides as `cause`, so nothing the old rejection carried is dropped.
39
+ */
40
+ export declare class MuseHostStartError extends Error {
41
+ readonly failure: HostStartFailure;
42
+ /**
43
+ * The SDK's bounded stderr tail when the host was lost, one accessor
44
+ * regardless of arm: empty when no process ran, and the only place the
45
+ * evidence lives when the row is `cleanShutdown` (SS2.11 keeps no tail on
46
+ * the clean row; a logger wants the lines either way).
47
+ */
48
+ readonly stderrTail: readonly string[];
49
+ constructor(failure: HostStartFailure, stderrTail: readonly string[], cause: unknown);
50
+ }
51
+ /**
52
+ * Read a lost host's evidence into the typed error. "Lost" is decided by
53
+ * whether the host ANSWERED — whether a response frame came back — never by
54
+ * how it ended: the caller keeps an answer's own error (`MspError`, or a
55
+ * `ProtocolError` carrying the refused frame) and routes only frameless
56
+ * failures here, where the row says how the unanswering host ended.
57
+ *
58
+ * Call only after the handshake's `close()` has settled: the close ladder
59
+ * ends at the child's observed exit (or at its spawn failure), so
60
+ * `child.exit` is already settled here and this never waits on a live host.
61
+ */
62
+ export declare function hostStartFailure(child: MuseServeChild, cause: unknown, answeredInitialize: boolean): Promise<MuseHostStartError>;