@homespunapps/cli 1.6.54 → 1.6.56

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
-        : await 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 {
@@ -196,6 +273,30 @@ function runChild(exec, stdin) {
             resolve({ code: 127, stdout, stderr: stderr + String(err) });
         });
         child.on("close", (code) => resolve({ code, stdout, stderr }));
+        // The envelope write races the child's exit, and losing that race used to
+        // kill the WORKER, not the task.
+        //
+        // A broken pipe surfaces on the STREAM, and an unhandled stream "error"
+        // event is fatal to the process. `child.on("error")` above does not cover
+        // it: that fires for a failed SPAWN, which with `shell: true` almost never
+        // happens because the shell itself starts fine. So a child that exits
+        // before reading stdin (a typo in `--exec`, where the shell prints
+        // "not found" and exits 127; or any script that simply does not read)
+        // raised an uncaught EPIPE and took down every other task the worker held.
+        //
+        // Measured 2026-08-09: it is the race, not the payload. A 500-byte write to
+        // a child running `exit 0` crashed a Node 24 process every time, and an
+        // agent-task envelope is comfortably larger than that. It reached CI as an
+        // intermittent "write EPIPE" in this file's own tests (issue #1616) while
+        // every assertion passed, which is why it read as flake rather than as the
+        // bug it is.
+        //
+        // Swallowed rather than reported, because it is a SYMPTOM and the real
+        // outcome is already on its way: the child's exit code and stderr arrive on
+        // "close" and decide ack versus nack. Reporting here as well would nack
+        // twice for one failure. This mirrors `report`'s own rule a few lines
+        // below, that one task's trouble must never cost the worker the others.
+        child.stdin.on("error", () => { });
         child.stdin.write(stdin);
         child.stdin.end();
     });
@@ -224,87 +325,73 @@ 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.
- */
-/**
- * Exported for testing. This function is the one part of `work` that had NO test and
- * shipped broken twice over (a URL built from the app id rather than its real
- * location, and a swallowed connect error), so it is worth being able to point a test
- * straight at it rather than only at the command that calls it.
- */
-export async function openWakeSocket(opts, apiKey, base, onWake) {
-    if (opts.appIds.length !== 1)
-        return null;
-    const appId = opts.appIds[0];
-    // ASK THE RELAY where the app lives. This was reconstructed as `${base}/a/${appId}/`,
-    // which is wrong in two ways at once: an app is served under its SLUG, not its id,
-    // and on a usercontent deployment it is a different origin entirely
-    // (`<slug>.homespunapps.com`) rather than a path on the API host. The socket
-    // therefore never connected, and the reconnect logic below reported it as
-    // "wake socket lost", which reads like a transient blip rather than a URL that
-    // could never work. Found by running a worker against a live relay; no test
-    // covered this function at all.
-    //
-    // A failure here is NOT fatal: polling still drains the queue, so a worker that
-    // cannot resolve its app keeps working, just without the wake hint.
-    let appUrl;
-    try {
-        const res = await fetch(`${base}/v1/apps/${appId}`, {
-            headers: { authorization: `Bearer ${apiKey}` },
-        });
-        if (!res.ok) {
-            warn(`cannot resolve app ${appId} for the wake socket (${res.status}); polling only`);
-            return null;
-        }
-        appUrl = (await res.json()).url ?? "";
-        if (!appUrl) {
-            warn(`app ${appId} reports no url; polling only`);
-            return null;
-        }
-    }
-    catch (err) {
-        warn(`cannot resolve app ${appId} for the wake socket (${err instanceof Error ? err.message : String(err)}); polling only`);
-        return null;
-    }
+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(appUrl);
-        handle = openAppStream(
-        // `since: 0`, not a huge sentinel. The intent was "do not replay history", and
-        // MAX_SAFE_INTEGER expressed that by sending a cursor the relay will not accept,
-        // so the socket was refused and the wake frame never arrived. The worker sets no
-        // `onEntry` handler at all, so a replayed batch is discarded as it is parsed:
-        // there is nothing to avoid.
-        { wsUrl, apiKey, since: 0 }, {
-            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: ({ 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
@@ -315,6 +402,11 @@ export async function openWakeSocket(opts, apiKey, base, onWake) {
     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((connectedOnce
                 ? "wake socket lost; polling continues while it reconnects"
@@ -332,6 +424,7 @@ export async 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.54",
+  "version": "1.6.56",
   "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.54",
+    "@homespunapps/core": "^1.6.56",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {