@homespunapps/cli 1.6.53 → 1.6.55

package/dist/commands/apps.js

@@ -1,5 +1,6 @@
 // `homespun apps` — v2 app lifecycle management (spec-cli §3.2): list / show /
-// update / delete / wake, plus `watch` (spec-cli §3.4).
+// update / delete / wake, plus `watch` (spec-cli §3.4) and `audit` (the owner
+// security review, issue #1589 phase B).
 //
 // Naming note (deviation from spec-cli's literal top-level `homespun watch`):
 // this branch still carries the UNCHANGED v1 `homespun watch <homespun-id>` command
@@ -25,7 +26,7 @@ export async function runApps(args) {
         return;
     }
     if (verb === undefined) {
-        fail("missing verb: homespun apps <list|show|update|share-link|delete|wake|watch|domain>", "invalid_args");
+        fail("missing verb: homespun apps <list|show|audit|update|share-link|delete|wake|watch|domain>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -40,6 +41,8 @@ export async function runApps(args) {
             return runList(sub);
         case "show":
             return runShow(sub);
+        case "audit":
+            return runAudit(sub);
         case "update":
             return runUpdate(sub);
         case "share-link":
@@ -53,7 +56,7 @@ export async function runApps(args) {
         case "domain":
             return runDomain(sub);
         default:
-            fail(`unknown verb '${verb}': homespun apps <list|show|update|share-link|delete|wake|watch|domain>`, "invalid_args");
+            fail(`unknown verb '${verb}': homespun apps <list|show|audit|update|share-link|delete|wake|watch|domain>`, "invalid_args");
     }
 }
 // ---------------------------------------------------------------------------
@@ -103,6 +106,55 @@ async function runShow(args) {
     }
 }
 // ---------------------------------------------------------------------------
+// audit
+// ---------------------------------------------------------------------------
+/**
+ * `homespun apps audit` — the owner security review (issue #1589 phase B).
+ *
+ * Exits 1 when any `high` finding exists, so this can gate a script or a CI
+ * step. That is a FINDINGS exit, not an error exit: the report still prints in
+ * full on the way out, and a transport or auth failure still goes through
+ * `failFromError` with its own code. A caller that only wants the data and
+ * never the gate reads the JSON and ignores the status.
+ */
+async function runAudit(args) {
+    assertKnownFlags(args, ...specFor("apps", "audit"));
+    const severity = args.flags.get("severity");
+    if (severity !== undefined && !["high", "medium", "low"].includes(severity)) {
+        fail("--severity must be high|medium|low", "invalid_args");
+    }
+    const client = makeClient(args);
+    let report;
+    try {
+        report = await client.appAdvisories(severity !== undefined ? { severity } : {});
+    }
+    catch (e) {
+        failFromError(e);
+        return;
+    }
+    if (args.bools.has("json")) {
+        printJson(report);
+    }
+    else {
+        for (const app of report.items) {
+            for (const a of app.advisories) {
+                process.stdout.write(`${a.severity.padEnd(6)} ${app.slug}  ${a.collection}  ${a.code}\n`);
+            }
+        }
+        const { high, medium, low } = report.counts;
+        process.stdout.write(`\n${report.apps_affected} of ${report.apps_scanned} apps affected: ${high} high, ${medium} medium, ${low} low\n`);
+        if (report.truncated) {
+            // Never let a partial audit read as a clean one.
+            process.stdout.write("warning: the audit stopped before every app was scanned; this report is incomplete\n");
+        }
+        if (severity !== undefined && (high > 0 || medium > 0 || low > 0)) {
+            process.stdout.write(`(counts describe the whole audit, not the --severity ${severity} filter)\n`);
+        }
+    }
+    if (report.counts.high > 0)
+        process.exitCode = 1;
+}
+// ---------------------------------------------------------------------------
 // update
 // ---------------------------------------------------------------------------
 async function runUpdate(args) {

package/dist/commands/work.js

@@ -16,6 +16,14 @@
 // correctly with no socket at all. That is why the reconnect logic below is allowed
 // to give up on the socket and keep working.
 //
+// ONE SOCKET FOR EVERY OWNED APP. Both halves of this command are owner-scoped: a
+// claim with no `--app` drains every app the identity owns, and the wake socket
+// (`/v1/agent-tasks/stream`) is subscribed to a per-owner channel, so `--app` is a
+// filter over both and never a decision about transport. Worth stating because the
+// first version was not like this: the hint rode the app's own feed socket, so `--app`
+// silently doubled as "which app's socket carries my wakes" and a worker that gained a
+// second app quietly stopped being pushed to.
+//
 // WHY THIS FILE CONTAINS RECONNECT LOGIC AT ALL, when `apps watch` does not: nothing
 // in this CLI has it. `apps watch` falls back to HTTP long-polling permanently on any
 // pre-connect WS failure, never retries, handles SIGINT but not SIGTERM, and parks on
@@ -24,11 +32,48 @@
 // degrade to a slower path and nothing would say so. So this reconnects with capped
 // backoff, says so on stderr when it does, and exits cleanly on SIGTERM.
 import { spawn } from "node:child_process";
-import { openAppStream, appWsUrlFromAppUrl } from "@homespunapps/core";
+import { openWorkerStream } from "@homespunapps/core";
 import { assertKnownFlags } from "../argv.js";
 import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
 import { resolveConfig } from "../config.js";
 import { fail, printJsonLine, warn } from "../output.js";
+function createPool(limit, run, onSlotFree) {
+    const running = new Set();
+    return {
+        async admit(task) {
+            // `Promise.race` on the live set, so this wakes on the FIRST finisher rather
+            // than the oldest. Racing the oldest would idle a free slot behind a long task.
+            while (running.size >= limit)
+                await Promise.race(running);
+            const p = (async () => {
+                try {
+                    await run(task);
+                }
+                catch (err) {
+                    // `runTask` is written not to throw, and if that ever stops being true the
+                    // failure must not escape into the pool: an unhandled rejection here would
+                    // abandon every sibling child mid-flight for the sake of one task.
+                    warn(`worker crashed on ${task.task_id}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            })();
+            const settled = p.finally(() => {
+                running.delete(settled);
+                // A freed slot is a reason to claim again NOW rather than at the end of the
+                // poll interval. Without this the pool would idle out the rest of a 15 s sleep
+                // with nothing running, which is slower than the sequential version it replaces.
+                onSlotFree();
+            });
+            running.add(settled);
+        },
+        capacity() {
+            return Math.max(0, limit - running.size);
+        },
+        async drain() {
+            while (running.size > 0)
+                await Promise.race(running);
+        },
+    };
+}
 /** Backoff bounds for the wake socket. Capped so a long outage does not spin. */
 const RECONNECT_MIN_MS = 1_000;
 const RECONNECT_MAX_MS = 60_000;
@@ -78,22 +123,46 @@ export async function runWork(args) {
     // handler this function attached and did not own up to.
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
+    // A finished child shortens the current sleep through the SAME `wake` the socket
+    // uses, because "there is capacity now" and "there is work now" both mean claim
+    // again, and one mechanism for both is one thing to keep correct.
+    const pool = createPool(opts.maxConcurrent, (task) => runTask(base, cfg.apiKey, task, opts.exec), () => wake?.());
+    // ONE BUDGET, SHARED BETWEEN PUSH AND POLL. The socket owns the credit accounting;
+    // this loop subtracts what it has promised. Capacity offered to the relay is capacity
+    // already spoken for, and a poll that claimed it as well would leave a worker told to
+    // run one task at a time holding two leases and starting one. That is the bug #1608
+    // fixed, arriving through a different door.
     const socket = opts.once
         ? null
-        : openWakeSocket(opts, cfg.apiKey, base, () => wake?.());
+        : openWakeSocket(opts, cfg.apiKey, base, () => wake?.(), () => pool.capacity(), (task) => {
+            // Not awaited: this is a socket callback, and blocking it on a free slot would
+            // stall every other frame on the connection. The relay respected the credit, so
+            // a slot exists; `admit` waits only if it somehow did not.
+            void pool.admit(task);
+        });
     try {
         for (;;) {
-            const claimed = await claim(base, cfg.apiKey, opts);
+            // Restate the offer every pass. See `reoffer`: it is the drift repair, not a
+            // belt-and-braces resend.
+            const promised = socket?.reoffer() ?? 0;
+            // Ask for what can actually be STARTED and is not already promised away. Claiming
+            // four while three children are running leases work that waits out its own lease
+            // before anything begins on it.
+            const want = Math.max(0, pool.capacity() - promised);
+            const claimed = want > 0 ? await claim(base, cfg.apiKey, opts, want) : [];
             for (const task of claimed) {
-                await runTask(base, cfg.apiKey, task, opts.exec);
                 if (stopping)
                     break;
+                // Awaited, and only for a free SLOT: `admit` returns as soon as the child is
+                // spawned, so a batch larger than the cap is fed through rather than run in
+                // lockstep.
+                await pool.admit(task);
             }
             if (opts.once || stopping)
                 break;
-            // Sleep, interruptible by the wake frame. `wake` is re-armed each pass so a
-            // frame that arrives WHILE tasks are running does not resolve a stale promise
-            // and get lost; the next sleep is what it shortens.
+            // Sleep, interruptible by the wake frame OR by a child finishing. `wake` is
+            // re-armed each pass so a frame that arrives WHILE tasks are running does not
+            // resolve a stale promise and get lost; the next sleep is what it shortens.
             await new Promise((resolve) => {
                 const timer = setTimeout(resolve, opts.pollSeconds * 1000);
                 wake = () => {
@@ -105,6 +174,11 @@ export async function runWork(args) {
         }
     }
     finally {
+        // Wait for the children BEFORE closing the socket and dropping the handlers.
+        // Under `--once` this is what makes the command mean "drain a pass", and on
+        // SIGTERM it is the difference between finishing the work in flight and stranding
+        // every lease it holds until expiry.
+        await pool.drain();
         socket?.close();
         process.off("SIGINT", stop);
         process.off("SIGTERM", stop);
@@ -116,8 +190,11 @@ export async function runWork(args) {
  * worker that needs a supervisor to do its retrying. Logged and retried on the next
  * pass instead.
  */
-async function claim(base, apiKey, opts) {
-    const body = { max: opts.maxConcurrent };
+async function claim(base, apiKey, opts, max) {
+    // `max` is the pool's free capacity, NOT `--max-concurrent`. The two are the same
+    // only on an idle worker, and asking for the flag's value while children are running
+    // is what leased work that could not be started.
+    const body = { max };
     if (opts.appIds.length > 0)
         body.app_ids = opts.appIds;
     try {
@@ -224,52 +301,93 @@ async function report(base, apiKey, taskId, verb, text) {
         warn(`${verb} failed for ${taskId} (${err instanceof Error ? err.message : String(err)}); lease will lapse`);
     }
 }
-/**
- * The wake socket, with real reconnect.
- *
- * ONE APP ONLY, and this is the honest limitation of the frame rather than of this
- * command: the hint is published on the app's own `/_hs/ws`, so a worker draining
- * five apps would need five sockets. Polling already drains every app correctly, so
- * the socket is opened only when `--app` names exactly one and is simply skipped
- * otherwise. A multi-app worker polls, which costs latency and nothing else.
- *
- * Reconnects with capped exponential backoff and says so, once, per outage. It never
- * escalates to an exit: losing the socket makes this slower, not broken, and a
- * worker that killed itself over a lost optimisation would be worse than one that
- * kept polling.
- */
-function openWakeSocket(opts, apiKey, base, onWake) {
-    if (opts.appIds.length !== 1)
-        return null;
-    const appId = opts.appIds[0];
+export function openWakeSocket(opts, apiKey, base, onWake, capacity, onAssign) {
+    // `--app` filters the wake as well as the claim. A wake for an app this worker was
+    // told to ignore would otherwise cut the sleep short to run a claim that can only
+    // come back empty, which is a wasted round trip on every OTHER app's traffic. An
+    // empty filter means every app, matching the claim.
+    const wanted = new Set(opts.appIds);
+    const wants = (appId) => wanted.size === 0 || wanted.has(appId);
     let closed = false;
+    let connectedOnce = false;
     let delay = RECONNECT_MIN_MS;
     let handle = null;
     let announcedOutage = false;
+    /** Does THIS relay push? Answered in its hello, never guessed. */
+    let pushes = false;
+    /**
+     * Restate free capacity as credit and return what is now outstanding.
+     *
+     * NOTHING IS TRACKED HERE, and two surviving mutations are what established that it
+     * should not be. Earlier versions decremented a running total on each assign and zeroed
+     * it on disconnect, and both lines could be deleted with every test still green. They
+     * were unobservable rather than untested: `capacity()` already excludes a child that a
+     * pushed task started, because `admit` occupies its slot before returning, so the
+     * recomputation below is always the same number the bookkeeping was maintaining. Code
+     * that looks load-bearing and is not is worse than no code, because the next person to
+     * chase a credit bug will trust it.
+     */
+    const offer = () => {
+        if (closed || !pushes || !handle)
+            return 0;
+        const want = Math.max(0, capacity());
+        return handle.sendReady(want) ? want : 0;
+    };
     const connect = () => {
         if (closed)
             return;
-        const wsUrl = appWsUrlFromAppUrl(`${base}/a/${appId}/`);
-        handle = openAppStream({ wsUrl, apiKey, since: Number.MAX_SAFE_INTEGER }, {
-            onHello: () => {
+        handle = openWorkerStream({ baseUrl: base, apiKey }, {
+            onHello: ({ push }) => {
                 // A successful connect resets the backoff, so a flapping link does not
                 // inherit the previous outage's delay.
+                connectedOnce = true;
                 delay = RECONNECT_MIN_MS;
+                pushes = push;
                 if (announcedOutage) {
                     warn("wake socket reconnected");
                     announcedOutage = false;
                 }
+                // OFFER IMMEDIATELY, not at the next poll pass. A worker with a long
+                // `--poll-interval` would otherwise offer nothing until the interval elapsed,
+                // so a relay ready to push had no credit to push against and the whole feature
+                // waited out a timer that push exists to avoid.
+                offer();
+            },
+            onAgentTaskAvailable: ({ appId }) => {
+                if (wants(appId))
+                    onWake();
+            },
+            onAssign: (task) => {
+                // A pushed task is already LEASED, so ignoring one costs a whole lease. It is
+                // still filtered by `--app`, but a task outside the filter is a relay bug
+                // rather than something to run quietly: the claim scope and the push scope are
+                // the same scope.
+                if (!wants(task.app_id)) {
+                    warn(`relay pushed a task for ${task.app_id}, which --app excludes; ignoring`);
+                    return;
+                }
+                onAssign?.(task);
             },
-            onAgentTaskAvailable: onWake,
-            onClose: () => scheduleReconnect(),
-            onError: () => scheduleReconnect(),
+            onClose: ({ code, reason }) => scheduleReconnect(`closed ${code}${reason ? ": " + reason : ""}`),
+            // The error is REPORTED, not swallowed. Discarding it is what made the
+            // original URL bug take three guesses to find: every failure looked
+            // identical from the outside.
+            onError: (err) => scheduleReconnect(err instanceof Error ? err.message : String(err)),
         });
     };
-    const scheduleReconnect = () => {
+    const scheduleReconnect = (why) => {
         if (closed)
             return;
+        // Credit dies with the connection. Anything the old socket was promised is gone, and
+        // the caller must be free to claim that capacity itself while this reconnects.
+        // `pushes` alone is enough: the next `offer` returns 0 while it is false, so the
+        // caller reclaims that capacity for its own polling on the very next pass.
+        pushes = false;
         if (!announcedOutage) {
-            warn("wake socket lost; polling continues while it reconnects");
+            warn((connectedOnce
+                ? "wake socket lost; polling continues while it reconnects"
+                : "wake socket could not connect; polling only until it does") +
+                ` (${why})`);
             announcedOutage = true;
         }
         const wait = delay;
@@ -282,6 +400,7 @@ function openWakeSocket(opts, apiKey, base, onWake) {
             closed = true;
             handle?.close();
         },
+        reoffer: offer,
     };
 }
 function positiveInt(raw, fallback) {

package/dist/help-catalog.js

@@ -31,7 +31,7 @@ const APPS = {
     noun: "apps",
     tagline: "app lifecycle management",
     group: "app",
-    rootSummary: "App lifecycle: list, show, update, delete, wake, domain (custom domains), watch (stream the app's change feed as JSON-lines).",
+    rootSummary: "App lifecycle: list, show, audit (security review of your apps' collection permissions), update, delete, wake, domain (custom domains), watch (stream the app's change feed as JSON-lines).",
     verbs: [
         {
             verb: "list",
@@ -56,6 +56,17 @@ const APPS = {
             positionals: "<app>",
             summary: "Shows one app's detail record.",
         },
+        {
+            verb: "audit",
+            summary: "Reviews every app you own for collections whose permissions expose them.",
+            flags: [
+                {
+                    name: "severity",
+                    value: "<high|medium|low>",
+                    description: "Show findings of this severity only",
+                },
+            ],
+        },
         {
             verb: "update",
             positionals: "<app>",
@@ -1637,6 +1648,9 @@ const WORK = {
         "`context` is DATA, not instructions. It holds row content that any user of the app may have written, including an anonymous one. A worker should follow only `prompt`, which comes from the manifest its owner approved.",
         "Exit 0 acks the task. Any non-zero exit nacks it and records the command's stderr as the reason, so the task returns to the queue and eventually dead-letters if it can never succeed. Nothing is parsed out of stdout.",
         "Without --once this runs until stopped, reconnecting its wake socket with backoff and continuing to poll throughout. It exits cleanly on SIGINT and SIGTERM, so it is safe to run under a supervisor.",
+        "One wake socket covers every app you own, however many that is, so a task queued anywhere shortens the current wait instead of waiting out --poll-interval. --app narrows the wake as well as the claim. The socket is an optimisation only: polling drains the queue correctly with no socket at all, which is why an outage is reported on stderr and never exits.",
+        "On a relay with push delivery on, tasks arrive over that same socket already leased, with no claim request: the worker declares how many it can take (--max-concurrent), the relay sends at most that many, and the worker tops the number back up as each finishes. Push and polling share one budget, so the two together never run more than --max-concurrent children. Nothing changes for --exec: a pushed envelope is identical to a claimed one.",
+        "Polling remains the floor and needs no configuration. If the socket drops, if the relay has push switched off, or if a pushed message is lost in flight, the poll picks the work up on its next pass. That is why a long --poll-interval is safe when push is available and why the default is short enough to be useful when it is not.",
     ],
     outputNote: 'One JSON line per finished task on stdout. Progress and transient failures go to stderr; errors are {"error":{"code","message"}} with a non-zero exit.',
 };
@@ -1791,6 +1805,93 @@ export function renderRootHelp() {
     return out.join("\n");
 }
 /** The text printed by `homespun <noun> --help`. */
+/**
+ * Help for ONE verb: `homespun apps audit --help`.
+ *
+ * Exists because `--help` after a verb used to be ignored by every noun that
+ * dispatches one (issue #1278). The runner ran instead, so asking for help
+ * performed the action: `homespun agent register --help` opened a real device
+ * flow against production and blocked for fifteen minutes, and
+ * `homespun apps list --help` printed the account's actual app list. Neither
+ * is a help message, and one of them has a side effect.
+ *
+ * Returns undefined when the noun or the verb is unknown, so a caller can fall
+ * back to the noun-level help rather than printing nothing. Never runs
+ * anything: that is the entire point.
+ */
+export function renderVerbHelp(nounName, verb) {
+    const WIDTH = 78;
+    const noun = nounSpec(nounName);
+    if (noun === undefined)
+        return undefined;
+    const v = noun.verbs.find((x) => x.verb === verb);
+    if (v === undefined)
+        return undefined;
+    const out = ["Usage:"];
+    const chunks = usageChunks(usageLine(noun, v));
+    const lines = [];
+    let line = "  ";
+    for (const chunk of chunks) {
+        const candidate = line.trimEnd() === "" ? line + chunk : `${line} ${chunk}`;
+        if (candidate.length > WIDTH && line.trim() !== "") {
+            lines.push(line);
+            line = "    " + chunk;
+        }
+        else {
+            line = candidate;
+        }
+    }
+    if (line.trim() !== "")
+        lines.push(line);
+    out.push(...lines);
+    if (v.summary)
+        out.push("", ...wrap(v.summary, WIDTH, ""));
+    const flags = [...(v.flags ?? []), ...(v.bools ?? [])];
+    if (flags.length > 0) {
+        out.push("", "Flags:");
+        const spelled = (f) => f.value ? `--${f.name} ${f.value}` : `--${f.name}`;
+        const col = Math.min(34, flags.reduce((w, f) => Math.max(w, spelled(f).length), 0) + 2);
+        for (const f of flags) {
+            const left = `  ${spelled(f)}`;
+            const pad = Math.max(1, col + 2 - left.length);
+            const indent = " ".repeat(col + 3);
+            const desc = wrap(f.description, WIDTH - col - 3, indent);
+            out.push(left + " ".repeat(pad) + desc[0]);
+            for (const l of desc.slice(1))
+                out.push(l);
+        }
+    }
+    out.push("", ...wrap(noun.outputNote ?? DEFAULT_OUTPUT_NOTE, WIDTH, ""));
+    return out.join("\n");
+}
+/**
+ * The whole answer to `--help` for one noun, verb or no verb.
+ *
+ * ALWAYS returns text for a known noun, which is the property that matters:
+ * the dispatcher can then return unconditionally and `--help` can never reach
+ * a runner. That was the bug in issue #1278. Verb-level `--help` used to be
+ * "the responsibility of each runner" and almost no runner took it, so asking
+ * for help performed the action: `homespun agent register --help` opened a
+ * real device flow against production, and `homespun apps list --help`
+ * printed the account's actual app list.
+ *
+ * Pure, so the behaviour is testable without spawning the CLI.
+ *
+ * Which positional names the verb differs by noun (`data` is verb-last:
+ * `homespun data <app> <collection> list`), so this matches ANY positional
+ * against the noun's own verb names rather than encoding either grammar. An
+ * unrecognised verb falls back to the noun's full help, which is the right
+ * answer for a typo and keeps the return type total.
+ */
+export function helpTextFor(nounName, positionals) {
+    const noun = nounSpec(nounName);
+    if (noun === undefined)
+        return undefined;
+    const named = positionals.find((p) => noun.verbs.some((v) => v.verb === p));
+    if (named === undefined)
+        return renderNounHelp(noun);
+    return renderVerbHelp(nounName, named) ?? renderNounHelp(noun);
+}
 export function renderNounHelp(noun) {
     const WIDTH = 78;
     const out = [

package/dist/index.js

@@ -10,7 +10,7 @@
 // $XDG_CONFIG_HOME/homespun/config.json; pick one with --profile or HOMESPUN_PROFILE.
 // Output is JSON by default. Every noun self-documents via --help.
 import { parseArgs, ArgvError, BOOLEAN_FLAGS } from "./argv.js";
-import { nounSpec, renderNounHelp, renderRootHelp } from "./help-catalog.js";
+import { helpTextFor, nounSpec, renderNounHelp, renderRootHelp, } from "./help-catalog.js";
 /**
  * Translate an ArgvError into the canonical `invalid_args` envelope and exit
  * non-zero. The parser throws ArgvError up-front; assertKnownFlags throws it
@@ -87,12 +87,26 @@ async function main() {
         }) + "\n");
         process.exit(1);
     }
-    // `homespun <noun> --help` with no verb prints the noun-level help. A verb-level
-    // --help is the responsibility of each runner (e.g. runApp dispatches to
-    // the verb runner which reads its own xxxHelp). This pre-empt only fires
-    // when --help is the FIRST positional-equivalent — i.e. no verb given.
-    if (args.bools.has("help") && args.positionals.length === 0) {
-        process.stdout.write(renderNounHelp(spec) + "\n");
+    // `--help` is answered HERE, for every noun, with and without a verb.
+    //
+    // It used to be "the responsibility of each runner", and almost no runner
+    // took it (issue #1278). The result was that asking for help PERFORMED the
+    // action: `homespun agent register --help` opened a real RFC 8628 device
+    // flow against production and blocked for fifteen minutes, and
+    // `homespun apps list --help` printed the account's actual app list. Both
+    // were long-standing, and the second is the worse shape: an unrequested
+    // authenticated read whose output lands in the user's scrollback.
+    //
+    // Centralised rather than fixed per noun, because per-noun was the design
+    // that failed. A new noun added tomorrow gets this for free and cannot
+    // forget it, which is the only version of this fix that stays fixed.
+    // The return is UNCONDITIONAL, which is the property doing the work:
+    // `helpTextFor` is total for a known noun, so there is no path from here
+    // into a runner while `--help` is set. `spec` is non-null above, so the
+    // fallback can never be taken; it is written rather than asserted away so a
+    // future change to `nounSpec` cannot turn help into a crash.
+    if (args.bools.has("help")) {
+        process.stdout.write((helpTextFor(noun, args.positionals) ?? renderNounHelp(spec)) + "\n");
         return;
     }
     switch (noun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.53",
+  "version": "1.6.55",
   "description": "Command-line client for the Homespun relay: deploy a real multi-user web app from your agent, then keep reading and writing its data.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.6.53",
+    "@homespunapps/core": "^1.6.55",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {