@north-light/crouter 0.3.154

package/bin/runtime-selector.mjs

@@ -0,0 +1,378 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { GENERATION_ID, contained, isValidPublishedGeneration, nodeVersionsCompatible, parseSelectionTarget, runtimeHome, validateManifestShape } from './runtime-generation-manifest.mjs';
+
+const ROOT = runtimeHome();
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const FEEDBACK_REPO = 'crouton-labs/crouter';
+
+function remediation() {
+  return existsSync(join(PACKAGE_ROOT, '.git'))
+    ? 'Run `npm run build && npm run install-runtime` in the crouter source checkout, then retry.'
+    : 'Reinstall crouter, then retry.';
+}
+
+function fail(command, detail) {
+  process.stderr.write(`${command}: invalid runtime selection: ${detail}\n${remediation()}\n`);
+  process.exitCode = 1;
+  return null;
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function failure(error, code) {
+  return code === undefined ? { ok: false, error } : { ok: false, error, code };
+}
+
+function readSelection() {
+  const selected = join(ROOT, 'selected');
+  let target;
+  try {
+    target = readlinkSync(selected);
+  } catch {
+    return failure(`missing ${selected}`);
+  }
+  const id = parseSelectionTarget(target);
+  if (!id) return failure(`selected must target generations/<id>, got ${JSON.stringify(target)}`);
+
+  const generations = join(ROOT, 'generations');
+  const generation = resolve(ROOT, target);
+  if (!contained(generations, generation) || !existsSync(generation)) return failure(`selected target ${target} does not exist`);
+  try {
+    const slot = lstatSync(generation);
+    const physical = realpathSync(generation);
+    if (!slot.isDirectory() || slot.isSymbolicLink() || !contained(realpathSync(generations), physical)) {
+      return failure(`selected target ${target} is not a generation directory`);
+    }
+    return { ok: true, selection: { generation: physical, id } };
+  } catch (error) {
+    return failure(errorMessage(error));
+  }
+}
+
+/** Load + validate one generation directory's manifest/entry. Shared by the
+ *  primary `selected` resolution and the sibling fallback scan (Fix B) so
+ *  both apply the exact same compatibility + shape rules. */
+function loadRuntime(generationDir, id, entryName) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(generationDir, 'generation.json'), 'utf8'));
+  } catch (error) {
+    return failure(`cannot read generation manifest: ${errorMessage(error)}`);
+  }
+  const result = validateManifestShape(manifest, { id, entryName });
+  if (!result.ok) return failure(result.error, result.code);
+
+  try {
+    const entryPath = resolve(generationDir, result.entry);
+    if (!contained(generationDir, entryPath) || !lstatSync(entryPath).isFile()) {
+      return failure(`generation entry ${result.entry} is missing`);
+    }
+    return { ok: true, runtime: { manifest, entryPath, generationId: id } };
+  } catch (error) {
+    return failure(errorMessage(error));
+  }
+}
+
+/** All installed generation ids under `generations/`, best-effort (an
+ *  unreadable directory yields an empty list rather than throwing). */
+function listGenerationIds() {
+  const generationsRoot = join(ROOT, 'generations');
+  try {
+    return readdirSync(generationsRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && GENERATION_ID.test(entry.name))
+      .map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Fix B fallback: when `selected` is incompatible with the running Node, scan
+ * every installed generation for the newest one whose `nodeVersion` is
+ * ABI-compatible (see `nodeVersionsCompatible`) and otherwise valid. Never
+ * touches the `selected` symlink on disk — `selected` stays the *preferred*
+ * generation; this only changes which generation THIS process loads.
+ */
+function findCompatibleSibling(entryName, excludeId) {
+  const generationsRoot = join(ROOT, 'generations');
+  let best = null;
+  for (const id of listGenerationIds()) {
+    if (id === excludeId) continue;
+    const dir = join(generationsRoot, id);
+    let manifestVersion;
+    try {
+      manifestVersion = JSON.parse(readFileSync(join(dir, 'generation.json'), 'utf8')).nodeVersion;
+    } catch {
+      continue;
+    }
+    if (!nodeVersionsCompatible(manifestVersion, process.version)) continue;
+    const runtime = loadRuntime(dir, id, entryName);
+    if (!runtime.ok) continue;
+    // Fix B must only ever fall back to a genuinely completed, published
+    // generation — never one mid-install, corrupt, or same-size-corrupted
+    // in the window between sealing and the installer's full-hash check
+    // finishing (renamed into `generations/` but not yet sealed/validated;
+    // see install-runtime.mjs's `seal()` + `validatePublished()` +
+    // `markPublished()`). A candidate with the atomic published marker
+    // passes on that alone; a markerless candidate (e.g. a legacy sibling
+    // installed before this PR added the marker) is instead full-hash
+    // validated on the spot — never rejected outright just for predating the
+    // marker, since that would defeat Fix B's whole purpose on exactly the
+    // upgrade it exists for. See `isValidPublishedGeneration`'s doc comment.
+    if (!isValidPublishedGeneration(dir, runtime.runtime.manifest.files, generationsRoot, id)) continue;
+    if (best === null || Date.parse(runtime.runtime.manifest.createdAt) > Date.parse(best.runtime.manifest.createdAt)) best = runtime;
+  }
+  return best;
+}
+
+/** Resolve a runtime without changing process state or writing output. Falls
+ *  back to the newest ABI-compatible sibling generation when `selected` is
+ *  incompatible with the running Node; only fails outright when no compatible
+ *  generation exists at all. */
+export function tryResolveRuntime(entryName) {
+  const selected = readSelection();
+  if (!selected.ok) return selected;
+
+  const primary = loadRuntime(selected.selection.generation, selected.selection.id, entryName);
+  if (primary.ok || primary.code !== 'node-version-mismatch') return primary;
+
+  const sibling = findCompatibleSibling(entryName, selected.selection.id);
+  if (sibling === null) return primary;
+  return {
+    ok: true,
+    runtime: {
+      ...sibling.runtime,
+      notice: `selected runtime generation ${selected.selection.id} is incompatible with node ${process.version}; using compatible generation ${sibling.runtime.generationId} instead`,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Fix C — escape hatch: `sys feedback` / `sys doctor` must stay runnable even
+// when NO compatible runtime generation exists at all, so the mandated
+// bug-report path is never gated behind the very failure it reports. This is
+// a tiny, generation-independent bootstrap — not the full commands — built
+// entirely from Node built-ins so it never needs to load a `dist/` generation.
+// ---------------------------------------------------------------------------
+
+const ESCAPE_HATCHES = new Map([
+  ['sys feedback', 'feedback'],
+  ['sys doctor', 'doctor'],
+]);
+
+/** Which escape hatch (if any) this argv shape matches. Pure + exported for
+ *  focused testing. */
+export function escapeHatchKind(argv) {
+  return ESCAPE_HATCHES.get(argv.slice(0, 2).join(' ')) ?? null;
+}
+
+/** Whether `args` requests help (`-h`/`--help`, in any position) — checked
+ *  BEFORE any hatch-specific arg parsing or dispatch, so a help flag can
+ *  never be misread as a positional message and can never reach an external
+ *  write (`gh issue create`, a local save, or the reduced doctor report). */
+function wantsHelp(args) {
+  return args.some((arg) => arg === '-h' || arg === '--help');
+}
+
+const FEEDBACK_HELP = `Usage: crtr sys feedback [--title <title>] <message>
+
+File a bug report describing what broke — available even when no compatible
+runtime generation is installed for this Node (the runtime-generation escape
+hatch), so the mandated bug-report path is never gated behind the very
+failure it reports.
+
+  --title <title>   Optional report title (derived from <message> otherwise)
+  -h, --help        Show this help and exit
+
+Filed to https://github.com/${FEEDBACK_REPO}/issues via \`gh\` when available,
+or saved locally under ~/.crouter/feedback/ otherwise.
+`;
+
+const DOCTOR_HELP = `Usage: crtr sys doctor
+
+Report the current runtime-generation state — available even when no
+compatible runtime generation is installed for this Node (the
+runtime-generation escape hatch). This is a reduced, generation-independent
+diagnostic, not the full \`sys doctor\` command.
+
+  -h, --help        Show this help and exit
+`;
+
+/** Parse `sys feedback [--title X] <message>`-shaped args without a full flag
+ *  parser — good enough for a degraded-mode bootstrap. Every `-`-prefixed
+ *  token that isn't the recognized `--title` flag (`-h`/`--help` are
+ *  intercepted earlier by `wantsHelp`) is an error, so an unknown short or
+ *  long option (e.g. `-x`) can never be silently read as the message body —
+ *  it must be rejected before any side effect (`gh` spawn or local save). */
+function parseFeedbackArgs(args) {
+  let message;
+  let title;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--title') {
+      title = args[i + 1];
+      i += 1;
+    } else if (arg.startsWith('-')) {
+      return { error: `unrecognized option ${JSON.stringify(arg)}` };
+    } else if (message === undefined) {
+      message = arg;
+    }
+  }
+  return { message, title };
+}
+
+/** Build the report title + body for the feedback escape hatch. Pure +
+ *  exported for focused testing. */
+export function buildFeedbackReport({ message, title, reason, nodeVersion = process.version, platform = `${process.platform} ${process.arch}` }) {
+  const trimmed = message.trim();
+  const explicitTitle = title !== undefined && title.trim() !== '' ? title.trim() : undefined;
+  const base = explicitTitle ?? trimmed.split('\n')[0].trim();
+  const finalTitle = `[feedback] ${base.length > 80 ? base.slice(0, 79) + '…' : base}`;
+  const body = [
+    trimmed,
+    '',
+    '---',
+    '_Filed via `crtr sys feedback` in the runtime-generation escape hatch — no compatible runtime generation was available, so this is a reduced report generated by the bootstrap selector, not the full CLI._',
+    '',
+    '### Environment',
+    '| | |',
+    '|---|---|',
+    `| node version | \`${nodeVersion}\` |`,
+    `| platform | ${platform} |`,
+    ...(reason !== undefined ? [`| escape-hatch reason | ${reason} |`] : []),
+    '',
+  ].join('\n');
+  return { title: finalTitle, body };
+}
+
+function defaultFeedbackDir() {
+  return join(homedir(), '.crouter', 'feedback');
+}
+
+function defaultSpawnGh(title, body) {
+  return spawnSync('gh', ['issue', 'create', '--repo', FEEDBACK_REPO, '--title', title, '--body-file', '-'], { input: body, encoding: 'utf8' });
+}
+
+/** Persist a report locally when gh can't file it, so nothing is lost.
+ *  Returns the absolute path written. */
+function saveFeedbackLocally(feedbackDir, title, body) {
+  mkdirSync(feedbackDir, { recursive: true });
+  const path = join(feedbackDir, `${new Date().toISOString().replace(/[:.]/g, '-')}.md`);
+  writeFileSync(path, `# ${title}\n\n${body}`, 'utf8');
+  return path;
+}
+
+/** The `sys feedback` escape hatch: file via `gh` when possible, else save
+ *  locally — never lost, and never dependent on a loadable runtime
+ *  generation. `reason` is the original resolution failure, embedded in the
+ *  report body so it documents the very bug it is reporting. */
+export function runEscapeHatchFeedback(args, reason, { feedbackDir = defaultFeedbackDir(), spawnGh = defaultSpawnGh, out = process.stdout, err = process.stderr } = {}) {
+  if (wantsHelp(args)) {
+    out.write(FEEDBACK_HELP);
+    return;
+  }
+  const parsed = parseFeedbackArgs(args);
+  if (parsed.error !== undefined) {
+    err.write(`sys feedback: ${parsed.error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const { message, title } = parsed;
+  if (message === undefined || message.trim() === '') {
+    err.write('sys feedback: feedback message is required: describe what broke.\n');
+    process.exitCode = 1;
+    return;
+  }
+  const report = buildFeedbackReport({ message, title, reason });
+  const res = spawnGh(report.title, report.body);
+  if (res.error === undefined && res.status === 0) {
+    const url = res.stdout.trim().split('\n').filter((line) => line.startsWith('http')).pop() ?? res.stdout.trim();
+    out.write(`filed: ${url}\n`);
+    return;
+  }
+  const path = saveFeedbackLocally(feedbackDir, report.title, report.body);
+  out.write(`saved-locally: ${path}\n`);
+}
+
+/** Summaries of every installed generation — exactly what's needed to
+ *  diagnose "no compatible runtime generation", which is the one scenario
+ *  where this escape hatch fires. Pure data gathering, exported for focused
+ *  testing. */
+export function listGenerationSummaries() {
+  const generationsRoot = join(ROOT, 'generations');
+  return listGenerationIds()
+    .map((id) => {
+      try {
+        const manifest = JSON.parse(readFileSync(join(generationsRoot, id, 'generation.json'), 'utf8'));
+        return `${id} node=${manifest.nodeVersion ?? '?'} pkg=${manifest.packageVersion ?? '?'} createdAt=${manifest.createdAt ?? '?'}`;
+      } catch {
+        return `${id} (unreadable manifest)`;
+      }
+    })
+    .sort();
+}
+
+/** `sys doctor` (the escape-hatch form) takes no arguments beyond `-h`/
+ *  `--help`, which `wantsHelp` intercepts earlier — so by the time this
+ *  runs, ANY remaining argument is unrecognized and must be rejected before
+ *  the doctor report runs, not silently ignored. */
+function parseDoctorArgs(args) {
+  return args.length === 0 ? { ok: true } : { ok: false, error: `unrecognized argument ${JSON.stringify(args[0])}` };
+}
+
+/** The `sys doctor` escape hatch: a reduced, generation-independent report of
+ *  exactly the state this defect leaves behind (no compatible generation) —
+ *  the full doctor command needs a loadable generation to run its checks. */
+export function runEscapeHatchDoctor(reason, { out = process.stdout, err = process.stderr } = {}, args = []) {
+  if (wantsHelp(args)) {
+    out.write(DOCTOR_HELP);
+    return;
+  }
+  const parsed = parseDoctorArgs(args);
+  if (!parsed.ok) {
+    err.write(`sys doctor: ${parsed.error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  out.write(
+    [
+      `no runtime generation is compatible with the running node (${process.version}).`,
+      reason !== undefined ? `reason: ${reason}` : undefined,
+      `installed generations under ${join(ROOT, 'generations')}:`,
+      ...listGenerationSummaries().map((line) => `  - ${line}`),
+      '',
+      `remediation: ${remediation()}`,
+      '',
+    ]
+      .filter((line) => line !== undefined)
+      .join('\n'),
+  );
+}
+
+export function selectRuntime(command, entryName) {
+  const result = tryResolveRuntime(entryName);
+  return result.ok ? result.runtime : fail(command, result.error);
+}
+
+export async function runSelected(command, entryName) {
+  const result = tryResolveRuntime(entryName);
+  if (result.ok) {
+    if (result.runtime.notice !== undefined) process.stderr.write(`${command}: ${result.runtime.notice}\n`);
+    await import(pathToFileURL(result.runtime.entryPath).href);
+    return;
+  }
+
+  const argv = process.argv.slice(2);
+  const kind = entryName === 'cli' ? escapeHatchKind(argv) : null;
+  const hatchArgs = argv.slice(2);
+  if (kind === 'feedback') return runEscapeHatchFeedback(hatchArgs, result.error);
+  if (kind === 'doctor') return runEscapeHatchDoctor(result.error, undefined, hatchArgs);
+
+  fail(command, result.error);
+}

package/dist/api/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/__tests__/client.test.js

@@ -0,0 +1,274 @@
+// client.test.ts — regression for issue #516: a cold-start `/healthz` timeout
+// used to throw a bare `daemon_unavailable` message that discarded the actual
+// startup failure (the tail of crtrd.err). `coldStartTimeoutMessage` is the
+// pure composition `handleColdSocket` uses on timeout; this proves an injected
+// diagnostic is appended (not dropped) and that a missing/empty diagnostic
+// still falls back to the original bare message unchanged. `safeColdStartDiagnostic`
+// is the guard `handleColdSocket` applies before that composition; this proves a
+// THROWING hook is treated as absent (per the documented `CrtrClientOptions`
+// contract) instead of propagating and replacing the typed `daemon_unavailable`
+// error.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { coldStartTimeoutMessage, CrtrClient, safeColdStartDiagnostic } from '../client.js';
+import { ApiError } from '../errors.js';
+test('coldStartTimeoutMessage appends a present diagnostic to the base message', () => {
+    const msg = coldStartTimeoutMessage('crtrd.err (tail):\nError: bind EADDRINUSE');
+    assert.match(msg, /crtrd did not start/);
+    assert.match(msg, /crtrd\.err \(tail\):\nError: bind EADDRINUSE/);
+});
+test('coldStartTimeoutMessage falls back to the bare message when no diagnostic is available', () => {
+    assert.equal(coldStartTimeoutMessage(undefined), 'crtrd did not start; run `crtr sys daemon start` and check crtrd.err.');
+    assert.equal(coldStartTimeoutMessage(''), 'crtrd did not start; run `crtr sys daemon start` and check crtrd.err.');
+});
+function startDelayedHealthzServer(socketPath, delayMs) {
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    });
+    const timer = setTimeout(() => server.listen(socketPath), delayMs);
+    return { server, cancel: () => clearTimeout(timer) };
+}
+// REGRESSION: `crtr sys daemon restart` acks, then tears the old server down and
+// hands over to a successor — a request crossing that window dies with a hang-up
+// (ECONNRESET), not a refused connect. That used to surface as
+// `daemon_unavailable: socket hang up` telling the caller to run
+// `crtr sys daemon start` against a daemon that was already coming back up.
+function startHandoverServer(socketPath) {
+    let dropped = false;
+    const server = createServer((req, res) => {
+        if (!dropped) {
+            dropped = true; // model the old server dying mid-request
+            req.socket.destroy();
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, method: req.method }));
+    });
+    return {
+        server,
+        ready: new Promise((resolvePromise) => server.listen(socketPath, resolvePromise)),
+    };
+}
+test('a hang-up mid-request rides out the daemon handover and replays the idempotent call', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = new CrtrClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true, method: 'GET' });
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a hang-up mid-mutation reports daemon_restarting, not daemon_unavailable', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = new CrtrClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        await assert.rejects(() => client.request('POST', '/v1/nodes', {}), 
+        // Replaying is unsafe (the daemon may have applied it), so this one is the
+        // caller's call — but it must not be reported as a daemon that is down.
+        (err) => err instanceof ApiError && err.code === 'daemon_restarting');
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('cliClient-style cold start fails loud when the injected poll window is shorter than the (valid) startup delay', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    try {
+        const client = new CrtrClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => {
+                /* fire-and-forget: the delayed listen() above models ensureDaemon() */
+            },
+            coldStartPollWindowMs: 100, // shorter than the 300ms the daemon actually needs
+        });
+        await assert.rejects(() => client.healthz(), (err) => err instanceof ApiError && err.code === 'daemon_unavailable');
+    }
+    finally {
+        cancel(); // the client already timed out at 100ms; never let listen() fire at 300ms
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('cliClient-style cold start succeeds when the injected poll window covers the (valid) startup delay', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    try {
+        const client = new CrtrClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => {
+                /* fire-and-forget: the delayed listen() above models ensureDaemon() */
+            },
+            coldStartPollWindowMs: 2_000, // long enough to see the 300ms-delayed daemon come up
+        });
+        const health = await client.healthz();
+        assert.deepEqual(health, { ok: true });
+    }
+    finally {
+        cancel(); // already fired by the time we get here; harmless no-op
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('safeColdStartDiagnostic returns undefined for an absent hook', () => {
+    assert.equal(safeColdStartDiagnostic(undefined), undefined);
+});
+test('safeColdStartDiagnostic returns the hook result when it succeeds', () => {
+    assert.equal(safeColdStartDiagnostic(() => 'crtrd.err (tail):\nboom'), 'crtrd.err (tail):\nboom');
+});
+test('safeColdStartDiagnostic treats a THROWING hook as absent, not a propagated error', () => {
+    assert.equal(safeColdStartDiagnostic(() => {
+        throw new Error('custom hook blew up');
+    }), undefined);
+});
+/** Spin a loopback server on a temp unix socket that records every request and
+ *  replies with `respond(req)`. `respond` returning `undefined` means "handler
+ *  not reached for this call" and is never exercised by these tests. */
+async function startCapturingServer(respond) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-inbox-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const requests = [];
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            const body = raw.trim() === '' ? undefined : JSON.parse(raw);
+            const captured = { method: req.method ?? '', path: req.url ?? '', body };
+            requests.push(captured);
+            const { status, body: resBody } = respond(captured);
+            res.writeHead(status, { 'content-type': 'application/json' });
+            res.end(JSON.stringify(resBody));
+        });
+    });
+    await new Promise((resolvePromise) => server.listen(socketPath, resolvePromise));
+    const client = new CrtrClient({ socketPath, autostart: false });
+    return {
+        client,
+        requests,
+        close: () => new Promise((resolvePromise, rejectPromise) => {
+            server.close((err) => (err ? rejectPromise(err) : resolvePromise()));
+        }).finally(() => rmSync(dir, { recursive: true, force: true })),
+    };
+}
+const SAMPLE_TICKET_ID = 'a'.repeat(64);
+test('listHumanInbox sends GET /v1/human/inbox with no body and returns the parsed list', async () => {
+    const inboxList = { tickets: [{ ticket_id: SAMPLE_TICKET_ID, kind: 'deck', title: 'Approve deploy', blocked_since: '2026-01-01T00:00:00Z', source: {} }] };
+    const srv = await startCapturingServer(() => ({ status: 200, body: inboxList }));
+    try {
+        const result = await srv.client.listHumanInbox();
+        assert.deepEqual(result, inboxList);
+        assert.equal(srv.requests.length, 1);
+        assert.equal(srv.requests[0]?.method, 'GET');
+        assert.equal(srv.requests[0]?.path, '/v1/human/inbox');
+        assert.equal(srv.requests[0]?.body, undefined);
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('getHumanInboxDeck sends GET /v1/human/inbox/:ticket_id with no body and returns the parsed deck', async () => {
+    const deck = { ticket_id: SAMPLE_TICKET_ID, kind: 'deck', deck: { title: 'Approve deploy', interactions: [] } };
+    const srv = await startCapturingServer(() => ({ status: 200, body: deck }));
+    try {
+        const result = await srv.client.getHumanInboxDeck(SAMPLE_TICKET_ID);
+        assert.deepEqual(result, deck);
+        assert.equal(srv.requests[0]?.method, 'GET');
+        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}`);
+        assert.equal(srv.requests[0]?.body, undefined);
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('respondHumanInboxDeck sends POST with the exact responses body and returns the canonical result unchanged', async () => {
+    const request = { responses: [{ id: 'notify', selectedOptionId: 'ok' }] };
+    const result = { schema: 'humanloop.response/v2', kind: 'deck', responses: request.responses, summary: 'Acknowledged', completedAt: '2026-01-01T00:00:00Z' };
+    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
+    try {
+        const got = await srv.client.respondHumanInboxDeck(SAMPLE_TICKET_ID, request);
+        assert.deepEqual(got, result);
+        assert.equal(srv.requests[0]?.method, 'POST');
+        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}/respond`);
+        assert.deepEqual(srv.requests[0]?.body, request);
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('cancelHumanInboxTicket sends POST with the reason body when a request is passed', async () => {
+    const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: '2026-01-01T00:00:00Z', reason: 'no longer needed', actor: 'human' };
+    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
+    try {
+        const got = await srv.client.cancelHumanInboxTicket(SAMPLE_TICKET_ID, { reason: 'no longer needed' });
+        assert.deepEqual(got, result);
+        assert.equal(srv.requests[0]?.method, 'POST');
+        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}/cancel`);
+        assert.deepEqual(srv.requests[0]?.body, { reason: 'no longer needed' });
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('cancelHumanInboxTicket sends an empty object body when no request is passed', async () => {
+    const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: '2026-01-01T00:00:00Z' };
+    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
+    try {
+        const got = await srv.client.cancelHumanInboxTicket(SAMPLE_TICKET_ID);
+        assert.deepEqual(got, result);
+        assert.deepEqual(srv.requests[0]?.body, {});
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('a non-2xx inbox error body decodes to a typed ApiError (status/code/message)', async () => {
+    const srv = await startCapturingServer(() => ({
+        status: 409,
+        body: { error: { code: 'ticket_kind_unsupported', message: 'review tickets have no v1 response operation' } },
+    }));
+    try {
+        await assert.rejects(() => srv.client.respondHumanInboxDeck(SAMPLE_TICKET_ID, { responses: [] }), (err) => {
+            assert.ok(err instanceof ApiError);
+            assert.equal(err.status, 409);
+            assert.equal(err.code, 'ticket_kind_unsupported');
+            assert.match(err.message, /review tickets have no v1 response operation/);
+            return true;
+        });
+    }
+    finally {
+        await srv.close();
+    }
+});
+test('a malformed local ticket id throws a synchronous TypeError and never reaches the transport', async () => {
+    const srv = await startCapturingServer(() => {
+        throw new Error('handler must never be invoked for a locally-rejected ticket id');
+    });
+    try {
+        assert.throws(() => srv.client.getHumanInboxDeck('not-a-valid-hash'), TypeError);
+        assert.throws(() => srv.client.respondHumanInboxDeck('short', { responses: [] }), TypeError);
+        assert.throws(() => srv.client.cancelHumanInboxTicket('UPPERCASE'.repeat(7)), TypeError);
+        assert.equal(srv.requests.length, 0);
+    }
+    finally {
+        await srv.close();
+    }
+});