@jini-ai/cli 0.4.1 → 0.6.10

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @jini-ai/cli
 
+## 0.6.10
+
+### Patch Changes
+
+- Updated dependencies [22f0619]
+- Updated dependencies [82ed2d3]
+- Updated dependencies [5a3de86]
+  - @jini-ai/core@0.6.10
+
+## 0.4.2 — 2026-10-22
+
+- 2026-10-22: Complexity refactors, coverage.
+
 ## 0.4.1
 
 ### Patch Changes

package/dist/command-registry.js

@@ -28,7 +28,7 @@ export class CommandRegistry {
         if (this.commands.has(name) && opts.override !== true) {
             throw new Error(`command "${name}" is already registered; pass { override: true } to replace it intentionally`);
         }
-        this.commands.set(name, { name, handler, ...(opts.usage !== undefined ? { usage: opts.usage } : {}) });
+        this.commands.set(name, { handler, ...(opts.usage !== undefined ? { usage: opts.usage } : {}) });
         return this;
     }
     has({ name }) {
@@ -56,25 +56,7 @@ export class CommandRegistry {
      * next token as a value — so the scan skips over it instead.
      */
     async dispatch({ argv }, options = {}) {
-        const valueFlags = options.valueFlags ?? new Set();
-        let index = -1;
-        for (let i = 0; i < argv.length; i++) {
-            // Loop is bounded by argv.length, so this index is always in range —
-            // noUncheckedIndexedAccess types it as possibly-undefined regardless.
-            const token = argv[i];
-            if (!token.startsWith('-')) {
-                index = i;
-                break;
-            }
-            if (token.startsWith('--')) {
-                const eq = token.indexOf('=');
-                if (eq < 0) {
-                    const key = token.slice(2);
-                    if (valueFlags.has(key))
-                        i++; // skip this flag's value token
-                }
-            }
-        }
+        const index = findCommandIndex({ argv }, { valueFlags: options.valueFlags ?? new Set() });
         if (index === -1)
             return { kind: 'empty' };
         const name = argv[index];
@@ -86,4 +68,22 @@ export class CommandRegistry {
         return { kind: 'handled' };
     }
 }
+/**
+ * Index of the first token in `argv` that does not start with `-`, or `-1` when there is none.
+ * A `--name` token (no `=`) whose `name` is in `valueFlags` also skips the token after it, so a
+ * value-flag's own value is never taken for the command name (CR-003). Single-dash and
+ * `--name=value` tokens never skip.
+ */
+function findCommandIndex({ argv }, { valueFlags }) {
+    for (let i = 0; i < argv.length; i++) {
+        // Loop is bounded by argv.length, so this index is always in range —
+        // noUncheckedIndexedAccess types it as possibly-undefined regardless.
+        const token = argv[i];
+        if (!token.startsWith('-'))
+            return i;
+        if (token.startsWith('--') && !token.includes('=') && valueFlags.has(token.slice(2)))
+            i++; // skip this flag's value token
+    }
+    return -1;
+}
 //# sourceMappingURL=command-registry.js.map

package/dist/daemon-url.js

@@ -10,30 +10,32 @@ import { isLoopbackHostname } from '@jini-ai/platform/net';
  */
 export async function resolveDaemonUrl(_requiredArgs, options = {}) {
     const env = options.env ?? process.env;
-    const warn = options.warn ?? (() => { });
-    const report = (url) => {
-        const warning = daemonUrlPolicyWarning({ url });
-        if (warning !== null)
-            warn({ message: warning });
-        return url;
-    };
-    const flagUrl = options.flagUrl ?? null;
-    if (flagUrl !== null && flagUrl.length > 0)
-        return report(flagUrl);
-    if (options.envVarName !== undefined) {
-        const envUrl = env[options.envVarName];
-        if (envUrl !== undefined && envUrl.length > 0)
-            return report(envUrl);
-    }
-    if (options.discover !== undefined) {
-        const discovered = await options.discover({ env }, { timeoutMs: options.timeoutMs ?? 800 });
-        if (discovered !== null && discovered.length > 0)
-            return report(discovered);
+    // `??` short-circuits, so discover() is only probed when flag and env both came up empty.
+    // defaultUrl is taken as-is (even `''`): only `undefined` skips it.
+    const url = nonEmpty(options.flagUrl ?? null) ??
+        envCandidate({ env }, options) ??
+        (await discoverCandidate({ env }, options)) ??
+        options.defaultUrl;
+    if (url === undefined) {
+        throw new Error('no daemon URL resolved: pass flagUrl, set envVarName on a populated env var, ' +
+            'supply a discover() probe, or provide defaultUrl.');
     }
-    if (options.defaultUrl !== undefined)
-        return report(options.defaultUrl);
-    throw new Error('no daemon URL resolved: pass flagUrl, set envVarName on a populated env var, ' +
-        'supply a discover() probe, or provide defaultUrl.');
+    const warning = daemonUrlPolicyWarning({ url });
+    if (warning !== null)
+        options.warn?.({ message: warning });
+    return url;
+}
+/** `value` when it is a non-empty string, else `undefined` (`null` and `''` both mean "unset"). */
+function nonEmpty(value) {
+    return value !== null && value.length > 0 ? value : undefined;
+}
+/** The env step: `env[envVarName]`, skipped entirely when no `envVarName` was given. */
+function envCandidate({ env }, { envVarName }) {
+    return envVarName === undefined ? undefined : nonEmpty(env[envVarName] ?? null);
+}
+/** The discovery step: one `discover()` probe with the caller timeout (default 800ms), when a probe was given. */
+async function discoverCandidate({ env }, { discover, timeoutMs }) {
+    return discover === undefined ? undefined : nonEmpty(await discover({ env }, { timeoutMs: timeoutMs ?? 800 }));
 }
 // Matches a scheme + userinfo prefix (`scheme://user:pass@`) on a URL string that failed to
 // parse via the `URL` constructor, so userinfo can still be stripped from a malformed value

package/dist/errors.js

@@ -47,7 +47,7 @@ export function structuredErrorData({ error }) {
     if (error === undefined)
         return undefined;
     const data = {};
-    if (error.data !== undefined && typeof error.data === 'object' && error.data !== null) {
+    if (typeof error.data === 'object' && error.data !== null) {
         Object.assign(data, sanitizeUnknownDeep({ value: error.data }));
     }
     if (error.details !== undefined)
@@ -83,22 +83,37 @@ function extractErrorObject(parsed) {
  * from the same untrusted response.
  */
 export async function structuredHttpFailure({ resp }, { fallbackCode = 'daemon-not-running', ...options } = {}) {
+    const { raw, parsed } = await readErrorBody({ resp });
+    const errorObj = extractErrorObject(parsed);
+    const code = typeof errorObj?.code === 'string' ? stripControlSequences({ text: errorObj.code }) : fallbackCode;
+    const structuredMessage = typeof errorObj?.message === 'string' ? sanitizeUntrustedText({ text: errorObj.message }) : undefined;
+    const message = structuredMessage ?? `HTTP ${resp.status}`;
+    const data = envelopeData({ errorObj, rawExcerptSource: structuredMessage === undefined ? raw : '' });
+    // A caller-supplied `options.data` is spread last, so it replaces the daemon-derived data.
+    return exitWithStructuredError({ code, message }, { ...(data !== undefined ? { data } : {}), ...options });
+}
+/**
+ * Read and JSON-parse a failure body. A `text()` rejection, an empty body, and unparsable JSON
+ * all yield `parsed: {}`; `raw` keeps whatever text was read (empty when `text()` rejected).
+ */
+async function readErrorBody({ resp }) {
     let raw = '';
-    let parsed = {};
     try {
         raw = await resp.text();
-        parsed = raw.length > 0 ? JSON.parse(raw) : {};
+        return { raw, parsed: raw.length > 0 ? JSON.parse(raw) : {} };
     }
     catch {
-        parsed = {};
+        return { raw, parsed: {} };
     }
-    const errorObj = extractErrorObject(parsed);
+}
+/**
+ * The envelope `data`: {@link structuredErrorData} plus, when `rawExcerptSource` is non-empty
+ * (i.e. there was no structured message), a sanitized `rawExcerpt` of the raw body.
+ */
+function envelopeData({ errorObj, rawExcerptSource }) {
     const data = structuredErrorData({ error: errorObj });
-    const code = typeof errorObj?.code === 'string' ? stripControlSequences({ text: errorObj.code }) : fallbackCode;
-    const structuredMessage = typeof errorObj?.message === 'string' ? sanitizeUntrustedText({ text: errorObj.message }) : undefined;
-    const message = structuredMessage ?? `HTTP ${resp.status}`;
-    const rawExcerpt = structuredMessage === undefined && raw.length > 0 ? sanitizeUntrustedText({ text: raw }) : undefined;
-    const mergedData = rawExcerpt !== undefined ? { ...(data ?? {}), rawExcerpt } : data;
-    return exitWithStructuredError({ code, message }, { ...(mergedData !== undefined ? { data: mergedData } : {}), ...options });
+    if (rawExcerptSource.length === 0)
+        return data;
+    return { ...data, rawExcerpt: sanitizeUntrustedText({ text: rawExcerptSource }) };
 }
 //# sourceMappingURL=errors.js.map

package/dist/flags.js

@@ -29,39 +29,41 @@ export function parseFlags({ argv }, opts = {}) {
         const a = argv[i];
         if (!a.startsWith('--'))
             continue;
-        const eq = a.indexOf('=');
-        const key = eq >= 0 ? a.slice(2, eq) : a.slice(2);
+        const { key, inlineValue } = splitFlagToken({ token: a });
         if (knownFlags.size > 0 && !knownFlags.has(key)) {
             throw new Error(`unknown flag: --${key}. Run with --help for the list of accepted flags.`);
         }
-        if (eq >= 0) {
-            out[key] = a.slice(eq + 1);
-            continue;
-        }
-        if (booleanFlags.has(key)) {
-            out[key] = true;
-            continue;
-        }
-        if (stringFlags.has(key)) {
-            const next = argv[i + 1];
-            if (next === undefined) {
-                throw new Error(`flag --${key} requires a value`);
-            }
-            out[key] = next;
-            i++;
-            continue;
-        }
-        const next = argv[i + 1];
-        if (next !== undefined && !next.startsWith('--')) {
-            out[key] = next;
+        const { value, consumesNext } = resolveFlagValue({ key, inlineValue, next: argv[i + 1] }, { stringFlags, booleanFlags });
+        out[key] = value;
+        if (consumesNext)
             i++;
-        }
-        else {
-            out[key] = true;
-        }
     }
     return out;
 }
+/** Split a `--key` / `--key=value` token; `inlineValue` is everything after the first `=`, if any. */
+function splitFlagToken({ token }) {
+    const eq = token.indexOf('=');
+    return eq >= 0 ? { key: token.slice(2, eq), inlineValue: token.slice(eq + 1) } : { key: token.slice(2), inlineValue: undefined };
+}
+/**
+ * Decide one flag's value, in precedence order: an inline `=value`, then a declared boolean
+ * (`true`), then a declared string flag (always takes `next`, which must exist), then the
+ * undeclared heuristic (`next` when it does not itself start with `--`, else `true`).
+ */
+function resolveFlagValue({ key, inlineValue, next }, { stringFlags, booleanFlags }) {
+    if (inlineValue !== undefined)
+        return { value: inlineValue, consumesNext: false };
+    if (booleanFlags.has(key))
+        return { value: true, consumesNext: false };
+    if (stringFlags.has(key)) {
+        if (next === undefined)
+            throw new Error(`flag --${key} requires a value`);
+        return { value: next, consumesNext: true };
+    }
+    if (next !== undefined && !next.startsWith('--'))
+        return { value: next, consumesNext: true };
+    return { value: true, consumesNext: false };
+}
 /**
  * Collect every non-flag token from `argv`, skipping the value token that
  * follows a known string flag (so `od run start --project p1 foo` yields
@@ -69,12 +71,13 @@ export function parseFlags({ argv }, opts = {}) {
  */
 export function positionalArgs({ argv }, opts = {}) {
     const stringFlags = opts.string ?? new Set();
+    const stopAtDoubleDash = opts.stopAtDoubleDash === true;
     const out = [];
     for (let i = 0; i < argv.length; i++) {
         // Loop is bounded by argv.length, so this index is always in range —
         // noUncheckedIndexedAccess types it as possibly-undefined regardless.
         const a = argv[i];
-        if (opts.stopAtDoubleDash === true && a === '--') {
+        if (stopAtDoubleDash && a === '--') {
             out.push(...argv.slice(i + 1));
             break;
         }
@@ -82,9 +85,8 @@ export function positionalArgs({ argv }, opts = {}) {
             out.push(a);
             continue;
         }
-        const eq = a.indexOf('=');
-        const key = eq >= 0 ? a.slice(2, eq) : a.slice(2);
-        if (eq < 0 && stringFlags.has(key))
+        const { key, inlineValue } = splitFlagToken({ token: a });
+        if (inlineValue === undefined && stringFlags.has(key))
             i++;
     }
     return out;

package/dist/http.js

@@ -11,6 +11,37 @@
 import { DEFAULT_CLI_EXIT_CODES, exitWithStructuredError, structuredErrorData } from './errors.js';
 import { sanitizeDaemonUrlForDisplay } from './daemon-url.js';
 import { sanitizeUntrustedText } from '@jini-ai/core/text';
+function writeToStderr({ text }) {
+    process.stderr.write(text);
+}
+function exitProcess({ code }) {
+    return process.exit(code);
+}
+/** `err.message` for an `Error`, `String(err)` for anything else. */
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** `value[key]` when `value` is an object whose `key` field is a string; `null` otherwise. */
+function stringField(value, key) {
+    if (value === null || typeof value !== 'object')
+        return null;
+    const field = value[key];
+    return typeof field === 'string' ? field : null;
+}
+/** `cause.code` (with `cause.message` when present), else `cause.message`, else the error's own text. */
+function describeFetchFailure(err) {
+    const cause = err !== null && typeof err === 'object' ? err.cause : null;
+    const code = stringField(cause, 'code');
+    const causeMessage = stringField(cause, 'message') ?? '';
+    // Stringified up front, before the cause-based choice below, exactly as the original did — so a
+    // value whose String() throws still throws even when a cause code is present.
+    const ownText = errorText(err);
+    if (code !== null)
+        return { code, detail: causeMessage.length > 0 ? `${code} — ${causeMessage}` : code };
+    return { code, detail: causeMessage.length > 0 ? causeMessage : ownText };
+}
+/** Cause codes that indicate an outbound connect denied by a sandbox policy rather than a down daemon. */
+const SANDBOX_DENIAL_CODES = new Set(['EPERM', 'ENETUNREACH']);
 /**
  * Format a `fetch()` rejection (network-unreachable, sandbox-denied) into a
  * human-readable stderr line, with a hint when the underlying cause looks
@@ -21,21 +52,10 @@ import { sanitizeUntrustedText } from '@jini-ai/core/text';
  * printed verbatim.
  */
 export function surfaceFetchError({ err, daemonUrl }, options = {}) {
-    const write = options.write ?? (({ text }) => { process.stderr.write(text); });
-    const cause = err !== null && typeof err === 'object' ? err.cause : null;
-    const code = cause !== null && typeof cause === 'object' && typeof cause.code === 'string'
-        ? cause.code
-        : null;
-    const causeMessage = cause !== null && typeof cause === 'object' && typeof cause.message === 'string'
-        ? cause.message
-        : '';
-    let detail = err instanceof Error ? err.message : String(err);
-    if (code !== null)
-        detail = `${code}${causeMessage.length > 0 ? ` — ${causeMessage}` : ''}`;
-    else if (causeMessage.length > 0)
-        detail = causeMessage;
+    const write = options.write ?? writeToStderr;
+    const { code, detail } = describeFetchFailure(err);
     write({ text: `failed to reach daemon at ${sanitizeDaemonUrlForDisplay({ url: daemonUrl })}: ${sanitizeUntrustedText({ text: detail })}\n` });
-    if (code === 'EPERM' || code === 'ENETUNREACH') {
+    if (code !== null && SANDBOX_DENIAL_CODES.has(code)) {
         write({ text: 'hint: outbound connect was denied, likely by a sandbox policy. ' +
                 'If this command ran inside an agent sandbox, check its network policy — ' +
                 'the daemon itself is unaffected and can be reached from a regular shell.\n',
@@ -55,6 +75,57 @@ class ResponseTooLargeError extends Error {
         this.name = 'ResponseTooLargeError';
     }
 }
+/** Rejects up front when `resp` declares a numeric `content-length` above `maxBytes`; a missing or non-numeric header is left to the byte-counting read. */
+function assertDeclaredLengthWithin(resp, maxBytes) {
+    const contentLength = resp.headers?.get?.('content-length');
+    if (contentLength === null || contentLength === undefined)
+        return;
+    const declared = Number(contentLength);
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new ResponseTooLargeError(maxBytes);
+}
+/** Drains `body` as UTF-8 text, throwing {@link ResponseTooLargeError} as soon as the running byte count passes `maxBytes`. */
+async function readStreamText(body, maxBytes) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done === true)
+                break;
+            if (value === undefined)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes)
+                throw new ResponseTooLargeError(maxBytes);
+            text += decoder.decode(value, { stream: true });
+        }
+        return text + decoder.decode();
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/** `resp.text()`, byte-checked against `maxBytes` before it is parsed. */
+async function readTextWithin(resp, maxBytes) {
+    const text = await resp.text();
+    if (Buffer.byteLength(text, 'utf8') > maxBytes)
+        throw new ResponseTooLargeError(maxBytes);
+    return text;
+}
+/** Parses `text` as JSON; an empty or non-JSON body resolves to `{}`. */
+function parseJsonOrEmpty(text) {
+    if (text.length === 0)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Read `resp`'s body as JSON without ever buffering past `maxBytes`. Prefers streaming via
  * `resp.body`'s reader (what a real `fetch()` `Response` provides) so a huge response is
@@ -64,130 +135,114 @@ class ResponseTooLargeError extends Error {
  * valid JSON resolves to `{}`, matching this module's previous behavior.
  */
 async function readJsonWithLimit(resp, maxBytes) {
-    const contentLength = resp.headers?.get?.('content-length');
-    if (contentLength !== null && contentLength !== undefined) {
-        const declared = Number(contentLength);
-        if (Number.isFinite(declared) && declared > maxBytes)
-            throw new ResponseTooLargeError(maxBytes);
-    }
+    assertDeclaredLengthWithin(resp, maxBytes);
     const body = resp.body;
-    if (body != null && typeof body.getReader === 'function') {
-        const reader = body.getReader();
-        const decoder = new TextDecoder();
-        let text = '';
-        let total = 0;
-        try {
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done === true)
-                    break;
-                if (value !== undefined) {
-                    total += value.byteLength;
-                    if (total > maxBytes)
-                        throw new ResponseTooLargeError(maxBytes);
-                    text += decoder.decode(value, { stream: true });
-                }
-            }
-            text += decoder.decode();
-        }
-        finally {
-            reader.releaseLock();
-        }
-        try {
-            return text.length > 0 ? JSON.parse(text) : {};
-        }
-        catch {
-            return {};
-        }
+    if (body != null && typeof body.getReader === 'function')
+        return parseJsonOrEmpty(await readStreamText(body, maxBytes));
+    if (typeof resp.text === 'function')
+        return parseJsonOrEmpty(await readTextWithin(resp, maxBytes));
+    return await resp.json().catch(() => ({}));
+}
+function structuredExitOptions(options) {
+    return {
+        write: options.write ?? writeToStderr,
+        exit: options.exit ?? exitProcess,
+        ...(options.exitCodes !== undefined ? { exitCodes: options.exitCodes } : {}),
+    };
+}
+/** Arms the request deadline: aborts `controller` with a route-naming error after `timeoutMs`. */
+function startDeadline({ route, timeoutMs }, { signal }) {
+    const controller = new AbortController();
+    const handle = setTimeout(() => {
+        controller.abort(new Error(`request to ${route} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    // A short-lived CLI invocation shouldn't be kept alive purely by this timer.
+    handle.unref?.();
+    return {
+        controller,
+        signal: signal !== undefined ? AbortSignal.any([signal, controller.signal]) : controller.signal,
+        clear: () => { clearTimeout(handle); },
+    };
+}
+/** POST adds a JSON content-type (a caller header of the same name still wins) and the serialized body; GET sends only the caller headers. */
+function buildFetchInit(init, headers, signal) {
+    if (init.method === 'POST') {
+        return { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(init.body), signal };
     }
-    if (typeof resp.text === 'function') {
-        const text = await resp.text();
-        if (Buffer.byteLength(text, 'utf8') > maxBytes)
-            throw new ResponseTooLargeError(maxBytes);
-        try {
-            return text.length > 0 ? JSON.parse(text) : {};
-        }
-        catch {
-            return {};
-        }
+    return { method: 'GET', headers: { ...headers }, signal };
+}
+/** A rejected `fetch()` (or a request init that could not be built) exits as `daemon-not-running`, carrying {@link surfaceFetchError}'s lines as diagnostics. */
+function exitForFetchFailure({ err, base }, structured) {
+    const diagnostics = [];
+    surfaceFetchError({ err, daemonUrl: base }, { write: ({ text }) => { diagnostics.push(text.trimEnd()); } });
+    return exitWithStructuredError({ code: 'daemon-not-running', message: `Cannot reach daemon at ${sanitizeDaemonUrlForDisplay({ url: base })}` }, { data: { diagnostics }, ...structured });
+}
+/** A body-read failure: an oversized body aborts the in-flight request and exits `response-too-large`; anything else exits `request-failed`. */
+function exitForReadFailure({ err, base, route, controller }, structured) {
+    if (err instanceof ResponseTooLargeError) {
+        controller.abort(err);
+        return exitWithStructuredError({ code: 'response-too-large', message: `response from ${sanitizeDaemonUrlForDisplay({ url: base })}${route} exceeded the ${err.limitBytes}-byte limit; aborting.` }, structured);
     }
-    return await resp.json().catch(() => ({}));
+    return exitWithStructuredError({ code: 'request-failed', message: sanitizeUntrustedText({ text: errorText(err) }) }, structured);
 }
 /**
- * Shared transport core behind {@link postJsonToDaemon} and {@link getJsonFromDaemon}: fetch
- * `<base><route>` with a bounded timeout and response-size cap, and map a network failure or a
- * non-2xx daemon response through the structured error contract (`errors.ts`) instead of
- * returning — this function either resolves with the parsed body or never returns. Per
- * CR-004/SEC-RB-009, daemon-supplied error detail is redacted before it reaches stderr rather than
- * dumped verbatim. Both public wrappers exist only to fix `init.method`/`init.body` at their own
- * call site — nothing method-specific lives here beyond that.
+ * Fetches `<base><route>` and reads its JSON body under one deadline. The timeout signal stays
+ * live through both the initial fetch *and* the body read — a daemon that returns headers
+ * promptly but then drips its body slowly should still be bounded by the same deadline, not
+ * just the connection phase.
  */
-async function requestJsonFromDaemon(base, route, init, options = {}) {
+async function fetchJsonWithinDeadline({ base, route, init }, { options, structured }) {
     const fetchImpl = options.fetchImpl ?? fetch;
-    const write = options.write ?? (({ text }) => { process.stderr.write(text); });
-    const exit = options.exit ?? (({ code }) => process.exit(code));
-    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
-    const structuredOptions = {
-        write,
-        exit,
-        ...(options.exitCodes !== undefined ? { exitCodes: options.exitCodes } : {}),
-    };
-    const timeoutController = new AbortController();
-    const timeoutHandle = setTimeout(() => {
-        timeoutController.abort(new Error(`request to ${route} timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
-    // A short-lived CLI invocation shouldn't be kept alive purely by this timer.
-    timeoutHandle.unref?.();
-    const signal = options.signal !== undefined ? AbortSignal.any([options.signal, timeoutController.signal]) : timeoutController.signal;
-    // The timeout signal stays live through both the initial fetch *and* the body read below — a
-    // daemon that returns headers promptly but then drips its body slowly should still be bounded
-    // by the same deadline, not just the connection phase.
-    let resp;
-    let data;
+    const deadline = startDeadline({ route, timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS }, { signal: options.signal });
     try {
+        let resp;
         try {
-            resp = await fetchImpl(`${base}${route}`, {
-                method: init.method,
-                headers: init.method === 'POST' ? { 'content-type': 'application/json', ...options.headers } : { ...options.headers },
-                ...(init.method === 'POST' ? { body: JSON.stringify(init.body) } : {}),
-                signal,
-            });
+            // The init is built inside this try on purpose: a body JSON.stringify cannot serialize is
+            // reported through the same daemon-not-running path as a rejected fetch, as it always was.
+            resp = await fetchImpl(`${base}${route}`, buildFetchInit(init, options.headers, deadline.signal));
         }
         catch (err) {
-            const diagnostics = [];
-            surfaceFetchError({ err, daemonUrl: base }, { write: ({ text }) => { diagnostics.push(text.trimEnd()); } });
-            return exitWithStructuredError({ code: 'daemon-not-running', message: `Cannot reach daemon at ${sanitizeDaemonUrlForDisplay({ url: base })}` }, { data: { diagnostics }, ...structuredOptions });
+            return exitForFetchFailure({ err, base }, structured);
         }
         try {
-            data = await readJsonWithLimit(resp, maxResponseBytes);
+            return { resp, data: await readJsonWithLimit(resp, maxResponseBytes) };
         }
         catch (err) {
-            if (err instanceof ResponseTooLargeError) {
-                timeoutController.abort(err);
-                return exitWithStructuredError({ code: 'response-too-large', message: `response from ${sanitizeDaemonUrlForDisplay({ url: base })}${route} exceeded the ${err.limitBytes}-byte limit; aborting.` }, structuredOptions);
-            }
-            const detail = err instanceof Error ? err.message : String(err);
-            return exitWithStructuredError({ code: 'request-failed', message: sanitizeUntrustedText({ text: detail }) }, structuredOptions);
+            return exitForReadFailure({ err, base, route, controller: deadline.controller }, structured);
         }
     }
     finally {
-        clearTimeout(timeoutHandle);
+        deadline.clear();
     }
-    if (!resp.ok) {
-        const errorObj = data?.error;
-        const exitCodes = { ...DEFAULT_CLI_EXIT_CODES, ...options.exitCodes };
-        const code = typeof errorObj?.code === 'string' && errorObj.code in exitCodes ? errorObj.code : null;
-        if (code !== null) {
-            const rawMessage = typeof errorObj?.message === 'string' ? errorObj.message : `HTTP ${resp.status}`;
-            const message = sanitizeUntrustedText({ text: rawMessage });
-            const errorData = structuredErrorData({ error: errorObj });
-            return exitWithStructuredError({ code, message }, { ...(errorData !== undefined ? { data: errorData } : {}), ...structuredOptions });
-        }
-        const rawExcerpt = describeUnrecognizedDaemonPayload(data);
-        const fallbackCode = typeof errorObj?.code === 'string' ? sanitizeUntrustedText({ text: errorObj.code }) : 'http-error';
-        return exitWithStructuredError({ code: fallbackCode, message: `${init.method} ${route} failed: ${resp.status}${rawExcerpt}` }, structuredOptions);
+}
+/** Maps a non-2xx daemon response to a structured exit: a recognized `error.code` keeps its own exit code and sanitized message/data; anything else exits with a bounded, redacted payload excerpt. */
+function exitForDaemonError({ resp, data, method, route }, structured) {
+    const errorObj = data?.error;
+    const exitCodes = { ...DEFAULT_CLI_EXIT_CODES, ...structured.exitCodes };
+    const rawCode = errorObj?.code;
+    if (typeof rawCode === 'string' && rawCode in exitCodes) {
+        const rawMessage = typeof errorObj?.message === 'string' ? errorObj.message : `HTTP ${resp.status}`;
+        const errorData = structuredErrorData({ error: errorObj });
+        return exitWithStructuredError({ code: rawCode, message: sanitizeUntrustedText({ text: rawMessage }) }, { ...(errorData !== undefined ? { data: errorData } : {}), ...structured });
     }
+    const fallbackCode = typeof rawCode === 'string' ? sanitizeUntrustedText({ text: rawCode }) : 'http-error';
+    return exitWithStructuredError({ code: fallbackCode, message: `${method} ${route} failed: ${resp.status}${describeUnrecognizedDaemonPayload(data)}` }, structured);
+}
+/**
+ * Shared transport core behind {@link postJsonToDaemon} and {@link getJsonFromDaemon}: fetch
+ * `<base><route>` with a bounded timeout and response-size cap, and map a network failure or a
+ * non-2xx daemon response through the structured error contract (`errors.ts`) instead of
+ * returning — this function either resolves with the parsed body or never returns. Per
+ * CR-004/SEC-RB-009, daemon-supplied error detail is redacted before it reaches stderr rather than
+ * dumped verbatim. Both public wrappers exist only to fix `init.method`/`init.body` at their own
+ * call site — nothing method-specific lives here beyond that.
+ */
+async function requestJsonFromDaemon({ base, route, init }, options) {
+    const structured = structuredExitOptions(options);
+    const { resp, data } = await fetchJsonWithinDeadline({ base, route, init }, { options, structured });
+    if (!resp.ok)
+        return exitForDaemonError({ resp, data, method: init.method, route }, structured);
     return data;
 }
 /**
@@ -202,7 +257,7 @@ async function requestJsonFromDaemon(base, route, init, options = {}) {
  * it verbatim.
  */
 export async function postJsonToDaemon({ base, route, body }, options = {}) {
-    return requestJsonFromDaemon(base, route, { method: 'POST', body }, options);
+    return requestJsonFromDaemon({ base, route, init: { method: 'POST', body } }, options);
 }
 /**
  * `GET` `<base><route>` and return the parsed JSON response. Same transport contract as
@@ -211,7 +266,7 @@ export async function postJsonToDaemon({ base, route, body }, options = {}) {
  * `GET /api/runs/:runId`.
  */
 export async function getJsonFromDaemon({ base, route }, options = {}) {
-    return requestJsonFromDaemon(base, route, { method: 'GET' }, options);
+    return requestJsonFromDaemon({ base, route, init: { method: 'GET' } }, options);
 }
 /** A bounded, redacted excerpt of an unrecognized daemon error payload — never the full raw body. */
 function describeUnrecognizedDaemonPayload(data) {

package/dist/introspection.js

@@ -20,7 +20,7 @@ export function introspectProgram({ program, excludedCommands }) {
             return;
         }
         commands.push({
-            name: fullPath.join(" "), description: command.description() ?? "",
+            name: fullPath.join(" "), description: command.description(),
             arguments: command.registeredArguments.map((arg) => ({ name: arg.name(), required: arg.required, description: arg.description ?? "" })),
             options: command.options.map((opt) => ({
                 flags: opt.flags, attributeName: opt.attributeName(), description: opt.description ?? "",
@@ -31,7 +31,7 @@ export function introspectProgram({ program, excludedCommands }) {
     }
     for (const command of program.commands)
         visit(command, []);
-    return { name: program.name(), description: program.description() ?? "", commands };
+    return { name: program.name(), description: program.description(), commands };
 }
 /**
  * Project a CLI manifest into string-valued MCP input schemas; boolean switches are omitted.

package/dist/main.js

@@ -89,6 +89,9 @@ function defaultWrite({ text }) {
 function defaultWriteErr({ text }) {
     process.stderr.write(text);
 }
+function defaultExit({ code }) {
+    return process.exit(code);
+}
 /** Name of the environment variable {@link resolveDaemonUrl} checks when `--daemon-url` is absent. */
 const DAEMON_URL_ENV_VAR = 'JINI_DAEMON_URL';
 const ROOT_USAGE = renderUsage({ usage: ['jini <command> [...args]'] }, { description: 'CLI transport for a Jini daemon over HTTP. Commands: run, daemon, version.', options: [
@@ -114,34 +117,40 @@ const GLOBAL_FLAG_NAMES = ['daemon-url', 'data-dir', 'registry-path'];
  * failure.
  */
 function partitionGlobalArgv(argv) {
-    const names = new Set(GLOBAL_FLAG_NAMES);
     const globals = {};
     const rest = [];
     for (let i = 0; i < argv.length; i++) {
         // Loop is bounded by argv.length, so this index is always in range —
         // noUncheckedIndexedAccess types it as possibly-undefined regardless.
         const token = argv[i];
-        if (token.startsWith('--')) {
-            const eq = token.indexOf('=');
-            const key = eq >= 0 ? token.slice(2, eq) : token.slice(2);
-            if (names.has(key)) {
-                if (eq >= 0) {
-                    globals[key] = token.slice(eq + 1);
-                }
-                else {
-                    const value = argv[i + 1];
-                    if (value === undefined)
-                        throw new Error(`flag --${key} requires a value`);
-                    globals[key] = value;
-                    i++;
-                }
-                continue;
-            }
+        const match = matchGlobalFlag(token);
+        if (match === null) {
+            rest.push(token);
+            continue;
+        }
+        if (match.inlineValue !== undefined) {
+            globals[match.key] = match.inlineValue;
+            continue;
         }
-        rest.push(token);
+        const value = argv[i + 1];
+        if (value === undefined)
+            throw new Error(`flag --${match.key} requires a value`);
+        globals[match.key] = value;
+        i++;
     }
     return { globals, rest };
 }
+const GLOBAL_FLAG_SET = new Set(GLOBAL_FLAG_NAMES);
+/** Recognizes `--<global>` / `--<global>=<value>`; `null` for any token that is not one of this binary's own global flags. */
+function matchGlobalFlag(token) {
+    if (!token.startsWith('--'))
+        return null;
+    const eq = token.indexOf('=');
+    const key = eq >= 0 ? token.slice(2, eq) : token.slice(2);
+    if (!GLOBAL_FLAG_SET.has(key))
+        return null;
+    return { key: key, inlineValue: eq >= 0 ? token.slice(eq + 1) : undefined };
+}
 /** Builds a `resolveDaemonUrl`-backed `resolveBaseUrl` closure from this binary's own parsed global flags. */
 function buildResolveBaseUrl(globals, env, warn) {
     const { 'daemon-url': daemonUrl, 'data-dir': dataDir, 'registry-path': registryPath } = globals;
@@ -158,6 +167,35 @@ function buildResolveBaseUrl(globals, env, warn) {
         warn,
     });
 }
+function isRootHelpRequest(argv) {
+    return argv.length === 0 || argv[0] === '--help' || argv[0] === '-h';
+}
+// `--version`/`-v` as the very first token is a plain alias for `jini version` — see this
+// file's own module doc for why there is no separate "this package's own version" surface.
+function expandVersionAlias(argv) {
+    return argv[0] === '--version' || argv[0] === '-v' ? ['version', ...argv.slice(1)] : argv;
+}
+/** Strips the global flags, registers `run`/`daemon`/`version` against a fresh registry and dispatches the remaining argv. */
+async function dispatchArgv({ argv, env }, { ports, fetchImpl }) {
+    const { globals, rest } = partitionGlobalArgv(argv);
+    const resolveBaseUrl = buildResolveBaseUrl(globals, env, ({ message }) => ports.writeErr({ text: message }));
+    const registry = new CommandRegistry({});
+    const commandDeps = { ...ports, ...(fetchImpl === undefined ? {} : { fetchImpl }) };
+    registerRunCommands({ registry, resolveBaseUrl }, commandDeps);
+    registerDaemonCommands({ registry, resolveBaseUrl }, commandDeps);
+    registerVersionCommand({ registry, resolveBaseUrl }, commandDeps);
+    return registry.dispatch({ argv: rest });
+}
+/** A dispatch that matched no handler: no command at all prints root usage, an unknown one exits `invalid-flag`. */
+function reportUnmatchedDispatch(result, ports) {
+    if (result.kind === 'empty') {
+        ports.write({ text: `${ROOT_USAGE}\n` });
+        return;
+    }
+    if (result.kind === 'not-found') {
+        exitWithStructuredError({ code: 'invalid-flag', message: `unknown command: "${result.name}". Run "jini --help" for usage.` }, { write: ports.writeErr, exit: ports.exit });
+    }
+}
 /**
  * Parse `argv` (already stripped of `node`/script-path, i.e. `process.argv.slice(2)`) and
  * dispatch to the registered `run`/`daemon`/`version` commands. Never throws a raw error to its
@@ -167,15 +205,11 @@ function buildResolveBaseUrl(globals, env, warn) {
 export async function main({ argv }, deps = {}) {
     const write = deps.write ?? defaultWrite;
     const writeErr = deps.writeErr ?? defaultWriteErr;
-    const rawExit = deps.exit ?? (({ code }) => process.exit(code));
-    const env = deps.env ?? process.env;
-    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    const rawExit = deps.exit ?? defaultExit;
+    if (isRootHelpRequest(argv)) {
         write({ text: `${ROOT_USAGE}\n` });
         return;
     }
-    // `--version`/`-v` as the very first token is a plain alias for `jini version` — see this
-    // file's own module doc for why there is no separate "this package's own version" surface.
-    const effectiveArgv = argv[0] === '--version' || argv[0] === '-v' ? ['version', ...argv.slice(1)] : argv;
     // Tracks whether `exit` was ever invoked, so the catch block below can tell "a nested command
     // already exited cleanly" (re-throw untouched) apart from "a genuinely raw, unhandled throw"
     // (reformat into a structured error) — see this file's own module doc, "Error boundary."
@@ -184,24 +218,10 @@ export async function main({ argv }, deps = {}) {
         exitCalled = true;
         return rawExit({ code });
     };
+    const ports = { write, writeErr, exit };
     let result;
     try {
-        const { globals, rest } = partitionGlobalArgv(effectiveArgv);
-        const resolveBaseUrl = buildResolveBaseUrl(globals, env, ({ message }) => writeErr({ text: message }));
-        const registry = new CommandRegistry({});
-        registerRunCommands({ registry, resolveBaseUrl }, {
-            write, writeErr, exit,
-            ...(deps.fetchImpl === undefined ? {} : { fetchImpl: deps.fetchImpl }),
-        });
-        registerDaemonCommands({ registry, resolveBaseUrl }, {
-            write, writeErr, exit,
-            ...(deps.fetchImpl === undefined ? {} : { fetchImpl: deps.fetchImpl }),
-        });
-        registerVersionCommand({ registry, resolveBaseUrl }, {
-            write, writeErr, exit,
-            ...(deps.fetchImpl === undefined ? {} : { fetchImpl: deps.fetchImpl }),
-        });
-        result = await registry.dispatch({ argv: rest });
+        result = await dispatchArgv({ argv: expandVersionAlias(argv), env: deps.env ?? process.env }, { ports, fetchImpl: deps.fetchImpl });
     }
     catch (error) {
         if (exitCalled)
@@ -210,13 +230,7 @@ export async function main({ argv }, deps = {}) {
         exitWithStructuredError({ code: 'invalid-flag', message }, { write: writeErr, exit });
         return;
     }
-    if (result.kind === 'empty') {
-        write({ text: `${ROOT_USAGE}\n` });
-        return;
-    }
-    if (result.kind === 'not-found') {
-        exitWithStructuredError({ code: 'invalid-flag', message: `unknown command: "${result.name}". Run "jini --help" for usage.` }, { write: writeErr, exit });
-    }
+    reportUnmatchedDispatch(result, ports);
 }
 // Only run for real when this module is the actual process entrypoint (`node dist/main.js
 // ...`, or the `jini` bin shim pnpm/npm links to it) — not merely imported, e.g. by this

package/dist/prompt.js

@@ -54,13 +54,21 @@ export async function readPromptFromFlags({ flags }, options = {}) {
     if (typeof promptFile !== 'string' || promptFile.length === 0) {
         return null;
     }
+    return await readFlagSource({ source: promptFile, readDefaultStdin: defaultReadStdin }, options);
+}
+/**
+ * Reads a `--*-file` flag's value: `-` means stdin (the injected `readStdin`, else
+ * `readDefaultStdin`), anything else is a path (the injected `readFile`, else the bounded
+ * default file reader). The byte cap and signal only reach the default readers.
+ */
+async function readFlagSource({ source, readDefaultStdin }, options) {
     const readLimits = { maxBytes: options.maxBytes ?? DEFAULT_MAX_READ_BYTES, ...(options.signal !== undefined ? { signal: options.signal } : {}) };
-    if (promptFile === '-') {
-        const readStdin = options.readStdin ?? (() => defaultReadStdin(readLimits));
+    if (source === '-') {
+        const readStdin = options.readStdin ?? (() => readDefaultStdin(readLimits));
         return await readStdin();
     }
     const readFile = options.readFile ?? (({ path }) => defaultReadFile(path, readLimits));
-    return await readFile({ path: promptFile });
+    return await readFile({ path: source });
 }
 async function defaultReadFile(path, limits) {
     const { createReadStream } = await import('node:fs');
@@ -163,13 +171,7 @@ export async function readBodyFromFlags({ flags }, options = {}) {
     const bodyFile = flags['body-file'];
     if (typeof bodyFile !== 'string')
         return undefined;
-    const readLimits = { maxBytes: options.maxBytes ?? DEFAULT_MAX_READ_BYTES, ...(options.signal !== undefined ? { signal: options.signal } : {}) };
-    if (bodyFile === '-') {
-        const readStdin = options.readStdin ?? (() => defaultReadBodyStdin(readLimits));
-        return await readStdin();
-    }
-    const readFile = options.readFile ?? (({ path }) => defaultReadFile(path, readLimits));
-    return await readFile({ path: bodyFile });
+    return await readFlagSource({ source: bodyFile, readDefaultStdin: defaultReadBodyStdin }, options);
 }
 async function defaultReadBodyStdin(limits) {
     limits.signal?.throwIfAborted();

package/dist/run-command.js

@@ -67,16 +67,18 @@ function invalidFlag(deps, message) {
 function printJsonResult(deps, value) {
     (deps.write ?? defaultWrite)({ text: `${JSON.stringify(value)}\n` });
 }
-async function resolveBaseUrl(deps) {
-    return deps.resolveBaseUrl();
+/** Prints `usage` and reports `true` when `args` asks for help (`--help`/`-h` anywhere), so the command returns before touching the daemon. */
+function printUsageIfHelp({ args, usage }, deps) {
+    if (!args.includes('--help') && !args.includes('-h'))
+        return false;
+    (deps.write ?? defaultWrite)({ text: `${usage}\n` });
+    return true;
 }
 /** `run start --context-ref <ref> [--agent-id <id>] [--idempotency-key <key>]` */
 export async function runStartCommand({ args, resolveBaseUrl: resolveBaseUrlPort }, optionalArgs = {}) {
     const deps = { resolveBaseUrl: resolveBaseUrlPort, ...optionalArgs };
-    if (args.includes('--help') || args.includes('-h')) {
-        (deps.write ?? defaultWrite)({ text: `${RUN_START_USAGE}\n` });
+    if (printUsageIfHelp({ args, usage: RUN_START_USAGE }, deps))
         return;
-    }
     const flags = parseFlags({ argv: args }, { string: new Set(['context-ref', 'agent-id', 'idempotency-key']) });
     const contextRef = flags['context-ref'];
     if (typeof contextRef !== 'string' || contextRef.length === 0) {
@@ -87,48 +89,42 @@ export async function runStartCommand({ args, resolveBaseUrl: resolveBaseUrlPort
         body.agentId = flags['agent-id'];
     if (typeof flags['idempotency-key'] === 'string')
         body.idempotencyKey = flags['idempotency-key'];
-    const baseUrl = await resolveBaseUrl(deps);
+    const baseUrl = await deps.resolveBaseUrl();
     const result = await postJsonToDaemon({ base: baseUrl, route: '/api/runs', body }, transportOptions(deps));
     printJsonResult(deps, result);
 }
 /** `run list [--context-ref <ref>]` */
 export async function runListCommand({ args, resolveBaseUrl: resolveBaseUrlPort }, optionalArgs = {}) {
     const deps = { resolveBaseUrl: resolveBaseUrlPort, ...optionalArgs };
-    if (args.includes('--help') || args.includes('-h')) {
-        (deps.write ?? defaultWrite)({ text: `${RUN_LIST_USAGE}\n` });
+    if (printUsageIfHelp({ args, usage: RUN_LIST_USAGE }, deps))
         return;
-    }
     const flags = parseFlags({ argv: args }, { string: new Set(['context-ref']) });
     const contextRef = flags['context-ref'];
     const route = typeof contextRef === 'string' && contextRef.length > 0
         ? `/api/runs?contextRef=${encodeURIComponent(contextRef)}`
         : '/api/runs';
-    const baseUrl = await resolveBaseUrl(deps);
+    const baseUrl = await deps.resolveBaseUrl();
     const result = await getJsonFromDaemon({ base: baseUrl, route }, transportOptions(deps));
     printJsonResult(deps, result);
 }
 /** `run get <runId>` */
 export async function runGetCommand({ args, resolveBaseUrl: resolveBaseUrlPort }, optionalArgs = {}) {
     const deps = { resolveBaseUrl: resolveBaseUrlPort, ...optionalArgs };
-    if (args.includes('--help') || args.includes('-h')) {
-        (deps.write ?? defaultWrite)({ text: `${RUN_GET_USAGE}\n` });
+    if (printUsageIfHelp({ args, usage: RUN_GET_USAGE }, deps))
         return;
-    }
     const runId = positionalArgs({ argv: args })[0];
     if (typeof runId !== 'string' || runId.length === 0) {
         missingInput(deps, 'runId is required: run get <runId>');
     }
-    const baseUrl = await resolveBaseUrl(deps);
+    const baseUrl = await deps.resolveBaseUrl();
     const result = await getJsonFromDaemon({ base: baseUrl, route: `/api/runs/${encodeURIComponent(runId)}` }, transportOptions(deps));
     printJsonResult(deps, result);
 }
 /** `run cancel <runId> [--reason <text>]` */
 export async function runCancelCommand({ args, resolveBaseUrl: resolveBaseUrlPort }, optionalArgs = {}) {
     const deps = { resolveBaseUrl: resolveBaseUrlPort, ...optionalArgs };
-    if (args.includes('--help') || args.includes('-h')) {
-        (deps.write ?? defaultWrite)({ text: `${RUN_CANCEL_USAGE}\n` });
+    if (printUsageIfHelp({ args, usage: RUN_CANCEL_USAGE }, deps))
         return;
-    }
     const flags = parseFlags({ argv: args }, { string: new Set(['reason']) });
     const runId = positionalArgs({ argv: args }, { string: new Set(['reason']) })[0];
     if (typeof runId !== 'string' || runId.length === 0) {
@@ -137,7 +133,7 @@ export async function runCancelCommand({ args, resolveBaseUrl: resolveBaseUrlPor
     const body = {};
     if (typeof flags.reason === 'string')
         body.reason = flags.reason;
-    const baseUrl = await resolveBaseUrl(deps);
+    const baseUrl = await deps.resolveBaseUrl();
     const result = await postJsonToDaemon({ base: baseUrl, route: `/api/runs/${encodeURIComponent(runId)}/cancel`, body }, transportOptions(deps));
     printJsonResult(deps, result);
 }
@@ -189,23 +185,15 @@ function isTerminalEventFrame(frame) {
  * error detail.
  */
 export async function watchRunEvents({ baseUrl, runId, args }, deps = {}) {
-    const flags = parseFlags({ argv: args }, { string: new Set(['after-cursor']) });
-    const afterCursor = flags['after-cursor'];
+    const headers = resumeHeaders(args);
     const fetchImpl = deps.fetchImpl ?? fetch;
     const write = deps.write ?? defaultWrite;
-    const headers = {};
-    if (typeof afterCursor === 'string' && afterCursor.length > 0)
-        headers['last-event-id'] = afterCursor;
     const resp = await fetchImpl(`${baseUrl}/api/runs/${encodeURIComponent(runId)}/events`, { headers });
     if (!resp.ok || resp.body === null) {
         return structuredHttpFailure({ resp }, { fallbackCode: 'daemon-not-running', ...errorOptions(deps) });
     }
     try {
-        for await (const frame of readSseFrames(resp.body)) {
-            write({ text: `${stripControlSequences({ text: frame.data })}\n` });
-            if (isTerminalEventFrame(frame))
-                return;
-        }
+        await writeEventsUntilEnd({ body: resp.body, write });
     }
     catch (error) {
         // A broken/hostile stream (e.g. the unbounded-buffer guard above) must exit through the same
@@ -214,18 +202,29 @@ export async function watchRunEvents({ baseUrl, runId, args }, deps = {}) {
         return exitWithStructuredError({ code: 'daemon-not-running', message: sanitizeUntrustedText({ text: message }) }, errorOptions(deps));
     }
 }
+/** `last-event-id` from a non-empty `--after-cursor`, so a reconnect resumes after that cursor; no header otherwise. */
+function resumeHeaders(args) {
+    const afterCursor = parseFlags({ argv: args }, { string: new Set(['after-cursor']) })['after-cursor'];
+    return typeof afterCursor === 'string' && afterCursor.length > 0 ? { 'last-event-id': afterCursor } : {};
+}
+/** Writes one control-sequence-stripped NDJSON line per SSE frame, stopping after the terminal `'end'` event or when the stream closes. */
+async function writeEventsUntilEnd({ body, write }) {
+    for await (const frame of readSseFrames(body)) {
+        write({ text: `${stripControlSequences({ text: frame.data })}\n` });
+        if (isTerminalEventFrame(frame))
+            return;
+    }
+}
 /** `run watch <runId> [--after-cursor <cursor>]` */
 export async function runWatchCommand({ args, resolveBaseUrl: resolveBaseUrlPort }, optionalArgs = {}) {
     const deps = { resolveBaseUrl: resolveBaseUrlPort, ...optionalArgs };
-    if (args.includes('--help') || args.includes('-h')) {
-        (deps.write ?? defaultWrite)({ text: `${RUN_WATCH_USAGE}\n` });
+    if (printUsageIfHelp({ args, usage: RUN_WATCH_USAGE }, deps))
         return;
-    }
     const runId = positionalArgs({ argv: args }, { string: new Set(['after-cursor']) })[0];
     if (typeof runId !== 'string' || runId.length === 0) {
         missingInput(deps, 'runId is required: run watch <runId>');
     }
-    const baseUrl = await resolveBaseUrl(deps);
+    const baseUrl = await deps.resolveBaseUrl();
     await watchRunEvents({ baseUrl, runId, args }, deps);
 }
 /** Registers `run` (dispatching `start`/`list`/`cancel`/`watch` on the first remaining token) against `registry`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/cli",
-  "version": "0.4.1",
+  "version": "0.6.10",
   "description": "CLI transport shell for driving a Jini daemon over HTTP: flag parsing, daemon-URL resolution, local daemon discovery, and a pluggable command registry.",
   "license": "Apache-2.0",
   "repository": {
@@ -54,16 +54,16 @@
   },
   "devDependencies": {
     "commander": "^15.0.0",
-    "@jini-ai/core": "0.4.2",
-    "@jini-ai/sidecar": "0.4.1",
-    "@jini-ai/platform": "0.5.2"
+    "@jini-ai/core": "0.6.10",
+    "@jini-ai/sidecar": "0.6.10",
+    "@jini-ai/platform": "0.6.10"
   },
   "dependencies": {
-    "@jini-ai/core": "^0.4.2"
+    "@jini-ai/core": "^0.6.10"
   },
   "peerDependencies": {
-    "@jini-ai/platform": "^0.5.1",
-    "@jini-ai/sidecar": "^0.4.0"
+    "@jini-ai/platform": "^0.6.10",
+    "@jini-ai/sidecar": "^0.6.10"
   },
   "peerDependenciesMeta": {
     "@jini-ai/platform": {