dsh-computers 1.1.0 → 1.3.0

package/lib/hub.js

@@ -1,17 +1,22 @@
 /**
  * The live side of dsh-computers: one SSE stream per computer and the exec
- * dispatcher that rides it (PROTOCOL §3.2, §3.3, §5.2).
+ * dispatcher that rides it (PROTOCOL §3.2, §3.3, §11.2, §11.6).
  *
  * Invariants this file keeps:
  * - at most one stream per computer; opening a new one ends the old one and
  *   fails the old agent's in-flight executions;
  * - `online` is the live stream and nothing else; `lastSeenAt` is display data
  *   refreshed by stream open / heartbeat / result POST;
- * - every exec has a unique `req_…` id, every promise settles exactly once —
- *   a result POST, the timeout, the abort signal, the stream closing or the
- *   plugin disposing;
- * - a late result for an already settled id is not accepted (the route answers
- *   404).
+ * - every exec has a unique `req_…` id and settles exactly once — a result
+ *   POST, the silence timeout, the abort signal, a job cancel, the stream
+ *   closing or the plugin disposing;
+ * - streaming frames are deduped/reassembled by `seq` and a `heartbeat` frame
+ *   resets the execution's silence timer (it carries no output);
+ * - a foreground timeout can be *adopted* by a job instead of killing the
+ *   command (`promoteOnTimeout`), after which chunks keep flowing into the job
+ *   ring and the model controls it with job_output/job_kill;
+ * - a late result for an already settled id is not accepted (the route
+ *   answers 404).
  *
  * Node builtins only.
  */
@@ -21,7 +26,7 @@ import { newRequestId } from './keys.js'
 /** Failure carrying a machine-readable code the tool layer maps to a message. */
 export class HubError extends Error {
   /**
-   * @param {string} code - `offline` | `timeout` | `aborted` | `disposed`.
+   * @param {string} code - `offline` | `timeout` | `aborted` | `invalid` | `disposed`.
    * @param {string} message - model-facing detail.
    */
   constructor(code, message) {
@@ -39,6 +44,12 @@ const SSE_HEADERS = {
   'x-accel-buffering': 'no',
 }
 
+/** Host features advertised in `hello` (PROTOCOL §11.1/§11.5). */
+export const HOST_FEATURES = Object.freeze(['stream', 'fs'])
+
+/** How long a killed execution may take to report its final result before the host settles it locally. */
+const KILL_SETTLE_MS = 5_000
+
 /**
  * Trim UTF-8 text to a byte budget without cutting a character in half.
  * @param {string} text - input text.
@@ -50,17 +61,25 @@ function capText(text, maxBytes) {
   const bytes = Buffer.byteLength(text, 'utf8')
   if (bytes <= maxBytes) return { text, truncated: false }
   let out = Buffer.from(text, 'utf8').subarray(0, maxBytes).toString('utf8')
-  // A multi-byte character split at the boundary decodes to U+FFFD; drop only
-  // the trailing replacement characters this slice may have produced.
   while (out.endsWith('\uFFFD')) out = out.slice(0, -1)
   return { text: `${out}\n[output truncated]`, truncated: true }
 }
 
+/** Decode one base64 frame payload; empty/absent decodes to ''. */
+function decodeFrame(data) {
+  if (typeof data !== 'string' || data === '') return ''
+  try {
+    return Buffer.from(data, 'base64').toString('utf8')
+  } catch {
+    return ''
+  }
+}
+
 /**
  * Create the hub for one plugin mount.
  * @param {object} options - hub options.
  * @param {object} options.store - registry store (presence timestamps).
- * @param {number} options.heartbeatMs - SSE ping cadence reported to the agent.
+ * @param {number} options.heartbeatMs - ping cadence and presence window base.
  * @param {number} options.maxOutputBytes - per-stream result cap.
  * @param {(message: string) => void} [options.onWarn] - warning sink.
  * @returns {object} the hub.
@@ -85,11 +104,15 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
     }
   }
 
-  /** Detach one pending execution's timer and abort listener (idempotent). */
+  /** Detach one pending execution's timers and abort listener (idempotent). */
   const detach = (entry) => {
-    if (entry.timer !== null) {
-      clearTimeout(entry.timer)
-      entry.timer = null
+    if (entry.silenceTimer !== null) {
+      clearTimeout(entry.silenceTimer)
+      entry.silenceTimer = null
+    }
+    if (entry.graceTimer !== null) {
+      clearTimeout(entry.graceTimer)
+      entry.graceTimer = null
     }
     if (entry.signal !== undefined && entry.onAbort !== null) {
       entry.signal.removeEventListener('abort', entry.onAbort)
@@ -97,13 +120,91 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
     }
   }
 
-  /** Reject one entry exactly once. */
+  /** Normalize one final result payload into the tool-facing shape. */
+  const normalizeResult = (entry, payload) => {
+    const stdout = capText(typeof payload.stdout === 'string' ? payload.stdout : entry.buffered.stdout, maxOutputBytes)
+    const stderr = capText(typeof payload.stderr === 'string' ? payload.stderr : entry.buffered.stderr, maxOutputBytes)
+    const exitCode = typeof payload.exitCode === 'number' && Number.isFinite(payload.exitCode)
+      ? Math.trunc(payload.exitCode)
+      : null
+    const duration = typeof payload.durationMs === 'number' && Number.isFinite(payload.durationMs) && payload.durationMs >= 0
+      ? Math.trunc(payload.durationMs)
+      : Date.now() - entry.startedAt
+    return {
+      requestId: entry.requestId,
+      ok: payload.ok === true,
+      exitCode,
+      signal: typeof payload.signal === 'string' ? payload.signal : null,
+      stdout: stdout.text,
+      stderr: stderr.text,
+      durationMs: duration,
+      truncated: payload.truncated === true || stdout.truncated || stderr.truncated,
+      timedOut: payload.timedOut === true,
+      error: typeof payload.error === 'string' ? payload.error : null,
+      killed: entry.killed === true,
+    }
+  }
+
+  /** Locally settle a killed execution that never reported a final result. */
+  const settleKilled = (entry) => {
+    if (entry.settled) return
+    const result = {
+      requestId: entry.requestId,
+      ok: false,
+      exitCode: null,
+      signal: 'SIGKILL',
+      stdout: entry.buffered.stdout,
+      stderr: entry.buffered.stderr,
+      durationMs: Date.now() - entry.startedAt,
+      truncated: false,
+      timedOut: false,
+      error: 'cancelled',
+      killed: true,
+    }
+    finish(entry, result)
+  }
+
+  /** Resolve/reject the entry exactly once, feeding the job ring when present. */
+  const finish = (entry, result) => {
+    if (entry.settled) return
+    entry.settled = true
+    detach(entry)
+    pending.delete(entry.requestId)
+    if (entry.job !== null) {
+      try {
+        entry.job.settle(result)
+      } catch (error) {
+        onWarn(`dsh-computers: job settle failed: ${error && error.message ? error.message : error}`)
+      }
+    }
+    if (entry.background === true) {
+      entry.resultResolve(result)
+    } else if (entry.promoted === true) {
+      // The foreground tool call already returned {jobId, promoted:true}.
+    } else {
+      entry.resolve(result)
+    }
+  }
+
+  /** Reject one entry exactly once (v1 failure paths). */
   const failEntry = (entry, error) => {
     if (entry.settled) return
     entry.settled = true
     detach(entry)
     pending.delete(entry.requestId)
-    entry.reject(error)
+    if (entry.job !== null) {
+      try {
+        entry.job.failed(error)
+      } catch {
+        // Already settled by the job registry.
+      }
+    }
+    if (entry.background === true) entry.resultResolve({
+      requestId: entry.requestId, ok: false, exitCode: null, signal: null, stdout: entry.buffered.stdout,
+      stderr: entry.buffered.stderr, durationMs: Date.now() - entry.startedAt, truncated: false,
+      timedOut: false, error: error.message, killed: error.code === 'aborted',
+    })
+    else if (entry.promoted !== true) entry.reject(error)
   }
 
   /** Reject every execution belonging to one computer (stream gone/offline). */
@@ -129,22 +230,139 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
     }
   }
 
+  /** (Re)arm the silence timeout. Streaming heartbeats/chunks push it forward. */
+  const armSilenceTimer = (entry) => {
+    if (entry.timeoutMs <= 0) return
+    if (entry.silenceTimer !== null) clearTimeout(entry.silenceTimer)
+    entry.silenceTimer = setTimeout(() => {
+      entry.silenceTimer = null
+      if (entry.settled) return
+      // §11.6.3: adopt the running execution into a background job instead of
+      // killing it, when the tool layer offered a promotion adapter.
+      const adopt = typeof entry.onTimeout === 'function' ? entry.onTimeout(entry) : null
+      if (adopt !== null && adopt !== undefined) {
+        entry.job = adopt
+        entry.promoted = true
+        entry.resolve({ promoted: true, jobId: adopt.jobId, requestId: entry.requestId, computer: entry.computer, command: entry.command })
+        return
+      }
+      hub.send(entry.computerId, 'cancel', { requestId: entry.requestId })
+      failEntry(entry, new HubError('timeout',
+        `computer '${entry.label}' did not answer within ${entry.timeoutMs}ms (the command was cancelled)`))
+    }, entry.timeoutMs)
+    if (typeof entry.silenceTimer.unref === 'function') entry.silenceTimer.unref()
+  }
+
+  /** Append decoded incremental output to the execution tail and the job ring. */
+  const appendChunk = (entry, channel, text) => {
+    if (text === '') return
+    const budget = maxOutputBytes
+    const key = channel === 'stderr' ? 'stderr' : 'stdout'
+    if (entry.bufferedBytes[key] < budget) {
+      const room = budget - entry.bufferedBytes[key]
+      const piece = capText(text, room)
+      entry.buffered[key] += piece.text
+      entry.bufferedBytes[key] += Buffer.byteLength(piece.text, 'utf8')
+    }
+    if (entry.job !== null) {
+      try {
+        entry.job.append(key, text)
+      } catch {
+        // The ring rejects writes after settlement; nothing else to do.
+      }
+    }
+  }
+
+  /** Create one pending execution and send its `exec` event. */
+  const beginExecution = ({
+    computerId, name, command, cwd = null, timeoutMs, agentTimeoutMs = null, shell = 'sh', signal,
+    background = false, stream = true, job = null, onTimeout = null,
+    resolve = () => {}, reject = () => {},
+  }) => {
+    const label = typeof name === 'string' && name !== '' ? name : computerId
+    if (disposed) throw new HubError('disposed', 'the dsh-computers host plugin is shutting down')
+    if (!streams.has(computerId)) {
+      throw new HubError('offline', `computer '${label}' is offline; run computer_list to see what is connected`)
+    }
+    if (typeof command !== 'string' || command.trim() === '') {
+      throw new HubError('invalid', 'command must be a non-empty string')
+    }
+    const streamRef = streams.get(computerId)
+    if (streamRef === undefined) {
+      throw new HubError('offline', `computer '${label}' is offline; run computer_list to see what is connected`)
+    }
+    const requestId = newRequestId()
+    let resultResolve = () => {}
+    const entry = {
+      requestId,
+      computerId,
+      label,
+      command,
+      computer: null,
+      startedAt: Date.now(),
+      signal,
+      onAbort: null,
+      silenceTimer: null,
+      graceTimer: null,
+      settled: false,
+      killed: false,
+      promoted: false,
+      background,
+      stream,
+      job,
+      onTimeout,
+      timeoutMs,
+      expectedSeq: 0,
+      chunkMap: new Map(),
+      buffered: { stdout: '', stderr: '' },
+      bufferedBytes: { stdout: 0, stderr: 0 },
+      resultPromise: null,
+      resultResolve: () => {},
+      resolve,
+      reject,
+    }
+    entry.resultPromise = new Promise((resolve) => {
+      resultResolve = resolve
+      entry.resultResolve = resolve
+    })
+    entry.resultResolve = resultResolve
+    pending.set(requestId, entry)
+    armSilenceTimer(entry)
+
+    if (signal !== undefined) {
+      const abort = () => {
+        hub.send(computerId, 'cancel', { requestId })
+        failEntry(entry, new HubError('aborted', `computer_exec was aborted while running on '${label}'`))
+      }
+      if (signal.aborted) {
+        abort()
+        return { requestId, result: entry.resultPromise, entry }
+      }
+      entry.onAbort = abort
+      signal.addEventListener('abort', abort, { once: true })
+    }
+
+    const written = writeFrame(streamRef, 'exec', {
+      requestId,
+      command,
+      cwd: cwd ?? null,
+      // The HOST owns the foreground timeout (§11.6.3 promotes instead of
+      // killing), so the agent receives its own generous ceiling.
+      timeoutMs: agentTimeoutMs ?? timeoutMs,
+      shell,
+      stream,
+    })
+    if (!written) {
+      failEntry(entry, new HubError('offline', `computer '${label}' is offline; run computer_list to see what is connected`))
+    }
+    return { requestId, result: entry.resultPromise, entry }
+  }
+
   const hub = {
     /** Whether a computer currently holds an open SSE stream. */
     isLive: (computerId) => streams.has(computerId),
 
-    /**
-     * Presence is the live SSE stream and nothing else.
-     *
-     * `lastSeenAt` is still refreshed by stream open / heartbeat / result POST
-     * and is shown in the UI, but a heartbeat without a stream must NOT read
-     * as online: the settings page polls every 5 s, so a machine that died
-     * while its heartbeat timestamp is still warm would show "在线" for up to
-     * 2x heartbeatMs. (PROTOCOL.md §2 still describes that older fallback; the
-     * live behaviour is stream-only and the protocol is being updated.)
-     * @param {object} computer - registry record.
-     * @returns {boolean} whether the computer holds an open stream.
-     */
+    /** Presence used everywhere the browser/tools need "online". */
     isOnline(computer) {
       if (computer === null || typeof computer !== 'object') return false
       return streams.has(computer.id)
@@ -155,14 +373,14 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
 
     /**
      * Accept a new SSE stream for a computer, replacing any previous one.
-     * The caller owns authentication and `lastSeenAt`; the hub owns framing.
      * @param {string} computerId - authenticated computer.
      * @param {string} name - display name for the `hello` event.
      * @param {import('node:http').IncomingMessage} req - request (for close hooks).
      * @param {import('node:http').ServerResponse} res - response to hold open.
+     * @param {{ capabilities?: string[] }} [handshake] - metadata to echo in `hello`.
      * @returns {{ replaced: boolean, stream: object }} the opened stream.
      */
-    openStream(computerId, name, req, res) {
+    openStream(computerId, name, req, res, handshake = {}) {
       if (disposed) throw new HubError('disposed', 'the dsh-computers host plugin is shutting down')
       const previous = streams.get(computerId)
       let replaced = false
@@ -174,8 +392,6 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
       }
 
       res.writeHead(200, SSE_HEADERS)
-      // Flush headers immediately: an agent must see the stream accepted
-      // before it decides the connection failed.
       if (typeof res.flushHeaders === 'function') res.flushHeaders()
       res.write('retry: 2000\n\n')
       if (typeof res.socket?.setNoDelay === 'function') {
@@ -188,10 +404,17 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
 
       const stream = { computerId, res, timer: null, openedAt: Date.now() }
       streams.set(computerId, stream)
-      writeFrame(stream, 'hello', { computerId, name, heartbeatMs })
+      const capabilities = Array.isArray(handshake.capabilities) ? handshake.capabilities : ['exec']
+      writeFrame(stream, 'hello', {
+        computerId,
+        name,
+        heartbeatMs,
+        capabilities,
+        // §11.1/§11.5: the agent only uses v2 frames when the host advertises them.
+        features: [...HOST_FEATURES],
+      })
 
       const onClose = () => {
-        // Only the CURRENT stream owns the computer's liveness.
         if (streams.get(computerId) !== stream) return
         retire(computerId, stream, { end: false })
         failComputerExecs(computerId, new HubError('offline', 'the connection to the computer was lost'))
@@ -199,15 +422,12 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
       res.on('close', onClose)
       res.on('error', onClose)
       req.on('close', () => {
-        // The agent may close the request side without the response side
-        // reporting it promptly on every platform.
         if (res.writableEnded || res.destroyed) onClose()
       })
 
       stream.timer = setInterval(() => {
         if (!writeFrame(stream, 'ping', { t: Date.now() })) onClose()
       }, heartbeatMs)
-      // Pings must not keep a shutting-down process alive.
       if (typeof stream.timer.unref === 'function') stream.timer.unref()
 
       return { replaced, stream }
@@ -215,9 +435,6 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
 
     /**
      * Push one event to a computer's live stream.
-     * @param {string} computerId - target computer.
-     * @param {string} event - SSE event name.
-     * @param {unknown} data - JSON payload.
      * @returns {boolean} false when the computer has no live stream.
      */
     send(computerId, event, data) {
@@ -226,15 +443,10 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
       return writeFrame(stream, event, data)
     },
 
-    /**
-     * End a computer's live stream and fail its in-flight executions.
-     * @param {string} computerId - target computer.
-     * @returns {boolean} whether a stream was open.
-     */
+    /** End a computer's live stream and fail its in-flight executions. */
     closeStream(computerId) {
       const stream = streams.get(computerId)
       if (stream === undefined) {
-        // Still fail executions: the HTTP side may already be gone.
         failComputerExecs(computerId, new HubError('offline', 'the computer was disconnected'))
         return false
       }
@@ -244,86 +456,103 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
     },
 
     /**
-     * Dispatch one command through the computer's live stream.
+     * Dispatch one foreground command (v1 shape) through the live stream.
      * @param {object} request - exec request.
-     * @param {string} request.computerId - target computer.
-     * @param {string} request.name - display name used in error messages.
-     * @param {string} request.command - shell command.
-     * @param {string | null} [request.cwd] - working directory or null.
-     * @param {number} request.timeoutMs - settlement deadline.
-     * @param {string} [request.shell] - shell hint for the agent.
-     * @param {AbortSignal | undefined} [request.signal] - caller cancellation.
-     * @returns {Promise<object>} normalized result when the agent answers.
+     * @returns {Promise<object>} normalized result, or `{ promoted:true, jobId }`.
      */
-    async dispatch({ computerId, name, command, cwd = null, timeoutMs, shell = 'sh', signal }) {
-      const label = typeof name === 'string' && name !== '' ? name : computerId
-      if (disposed) throw new HubError('disposed', 'the dsh-computers host plugin is shutting down')
-      if (!streams.has(computerId)) {
-        throw new HubError('offline', `computer '${label}' is offline; run computer_list to see what is connected`)
-      }
-      if (typeof command !== 'string' || command.trim() === '') {
-        throw new HubError('invalid', 'command must be a non-empty string')
-      }
-      const stream = streams.get(computerId)
-      if (stream === undefined) {
-        throw new HubError('offline', `computer '${label}' is offline; run computer_list to see what is connected`)
-      }
-      const requestId = newRequestId()
+    async dispatch({ computerId, name, command, cwd = null, timeoutMs, agentTimeoutMs = null, shell = 'sh', signal, stream = true, onTimeout = null }) {
       return await new Promise((resolve, reject) => {
-        const entry = {
-          requestId,
-          computerId,
-          command,
-          startedAt: Date.now(),
-          signal,
-          onAbort: null,
-          timer: null,
-          settled: false,
-          resolve,
-          reject,
-        }
-        pending.set(requestId, entry)
-
-        // NOT unref'd: an in-flight execution must settle even if it is the
-        // only work left in the process.
-        entry.timer = setTimeout(() => {
-          // Tell the agent to kill the process group before settling, so a
-          // timed-out command does not keep eating the user's computer.
-          hub.send(computerId, 'cancel', { requestId })
-          failEntry(entry, new HubError('timeout',
-            `computer '${label}' did not answer within ${timeoutMs}ms (the command was cancelled)`))
-        }, timeoutMs)
-
-        if (signal !== undefined) {
-          const abort = () => {
-            hub.send(computerId, 'cancel', { requestId })
-            failEntry(entry, new HubError('aborted', `computer_exec was aborted while running on '${label}'`))
-          }
-          if (signal.aborted) {
-            abort()
-            return
-          }
-          entry.onAbort = abort
-          signal.addEventListener('abort', abort, { once: true })
+        // Promise executor runs synchronously; beginExecution throws are captured.
+        try {
+          beginExecution({
+            computerId, name, command, cwd, timeoutMs, agentTimeoutMs, shell, signal,
+            background: false, stream, onTimeout, resolve, reject,
+          })
+        } catch (error) {
+          reject(error)
         }
+      })
+    },
 
-        const written = writeFrame(stream, 'exec', {
-          requestId,
-          command,
-          cwd: cwd ?? null,
-          timeoutMs,
-          shell,
+    /**
+     * Start one background execution immediately (job path, §11.2).
+     * @returns {{ requestId: string, result: Promise<object> }} the execution.
+     */
+    startExecution({ computerId, name, command, cwd = null, timeoutMs = 0, agentTimeoutMs = null, shell = 'sh', job = null }) {
+      const handle = beginExecution({
+        computerId, name, command, cwd, timeoutMs, agentTimeoutMs, shell,
+        background: true, stream: true, job, onTimeout: null,
+      })
+      return { requestId: handle.requestId, result: handle.result }
+    },
+
+    /**
+     * Request cancellation of a running execution and settle it locally when
+     * the agent does not report a final result in time.
+     */
+    cancelExecution(computerId, requestId, { settleAfterMs = KILL_SETTLE_MS } = {}) {
+      const entry = pending.get(requestId)
+      if (entry === undefined || entry.computerId !== computerId) return false
+      entry.killed = true
+      hub.send(computerId, 'cancel', { requestId })
+      if (entry.graceTimer !== null) clearTimeout(entry.graceTimer)
+      entry.graceTimer = setTimeout(() => {
+        entry.graceTimer = null
+        if (!entry.settled) settleKilled(entry)
+      }, settleAfterMs)
+      if (typeof entry.graceTimer.unref === 'function') entry.graceTimer.unref()
+      return true
+    },
+
+    /**
+     * Apply one streaming frame (§11.2/§11.6.2):
+     * `{type:'stdout'|'stderr'|'heartbeat', data(base64), seq}` or the v1.3
+     * `{stdout, stderr}` pair. Out-of-order frames are reassembled by seq;
+     * duplicates are dropped; heartbeats only reset the silence timer.
+     * @returns {boolean} false when the id is unknown/settled or owned elsewhere.
+     */
+    settleChunk(computerId, payload) {
+      const requestId = payload !== null && typeof payload === 'object' ? payload.requestId : undefined
+      if (typeof requestId !== 'string') return false
+      const entry = pending.get(requestId)
+      if (entry === undefined || entry.computerId !== computerId) return false
+      const frameType = typeof payload.type === 'string' ? payload.type : ''
+      if (frameType === 'heartbeat') {
+        armSilenceTimer(entry)
+        return true
+      }
+      const seq = Number.isSafeInteger(payload.seq) && payload.seq >= 0 ? payload.seq : null
+      if (seq === null) return false
+      if (seq < entry.expectedSeq) return true // duplicate / already assembled
+      // A streaming frame revives the execution: heartbeats reset it too, and
+      // any real output proves the agent is alive.
+      armSilenceTimer(entry)
+      if (frameType === 'stdout' || frameType === 'stderr') {
+        entry.chunkMap.set(seq, { channel: frameType, text: decodeFrame(payload.data) })
+      } else if (payload.stdout !== undefined || payload.stderr !== undefined) {
+        // v1.3 chunk shape: one seq carrying both streams.
+        entry.chunkMap.set(seq, {
+          stdout: typeof payload.stdout === 'string' ? decodeFrame(payload.stdout) : '',
+          stderr: typeof payload.stderr === 'string' ? decodeFrame(payload.stderr) : '',
         })
-        if (!written) {
-          failEntry(entry, new HubError('offline', `computer '${label}' is offline; run computer_list to see what is connected`))
+      } else {
+        return true
+      }
+      while (entry.chunkMap.has(entry.expectedSeq)) {
+        const frame = entry.chunkMap.get(entry.expectedSeq)
+        entry.chunkMap.delete(entry.expectedSeq)
+        if (frame.channel !== undefined) appendChunk(entry, frame.channel, frame.text)
+        else {
+          appendChunk(entry, 'stdout', frame.stdout)
+          appendChunk(entry, 'stderr', frame.stderr)
         }
-      })
+        entry.expectedSeq += 1
+      }
+      return true
     },
 
     /**
-     * Settle one pending execution from the agent's result POST.
-     * @param {string} computerId - authenticated computer.
-     * @param {unknown} payload - result body from the agent.
+     * Settle one pending execution from the agent's final result POST.
      * @returns {boolean} false when the id is unknown/settled or owned elsewhere.
      */
     settle(computerId, payload) {
@@ -331,30 +560,7 @@ export function createHub({ store, heartbeatMs, maxOutputBytes, onWarn = () => {
       if (typeof requestId !== 'string') return false
       const entry = pending.get(requestId)
       if (entry === undefined || entry.computerId !== computerId) return false
-      entry.settled = true
-      detach(entry)
-      pending.delete(requestId)
-
-      const stdout = capText(typeof payload.stdout === 'string' ? payload.stdout : '', maxOutputBytes)
-      const stderr = capText(typeof payload.stderr === 'string' ? payload.stderr : '', maxOutputBytes)
-      const exitCode = typeof payload.exitCode === 'number' && Number.isFinite(payload.exitCode)
-        ? Math.trunc(payload.exitCode)
-        : null
-      const duration = typeof payload.durationMs === 'number' && Number.isFinite(payload.durationMs) && payload.durationMs >= 0
-        ? Math.trunc(payload.durationMs)
-        : Date.now() - entry.startedAt
-      entry.resolve({
-        requestId,
-        ok: payload.ok === true,
-        exitCode,
-        signal: typeof payload.signal === 'string' ? payload.signal : null,
-        stdout: stdout.text,
-        stderr: stderr.text,
-        durationMs: duration,
-        truncated: payload.truncated === true || stdout.truncated || stderr.truncated,
-        timedOut: payload.timedOut === true,
-        error: typeof payload.error === 'string' ? payload.error : null,
-      })
+      finish(entry, normalizeResult(entry, payload))
       return true
     },