@openrig/cli 0.4.2 → 0.4.4

package/dist/commands/ps.js

@@ -55,6 +55,7 @@ const NUMERIC_OPERATORS = [">=", "<=", ">", "<", "="];
 // rig-level only; `rigName` is the alias and exists at both levels (per the
 // closed `rig ps trust and scale-safety` slice at openrig 0a9fb43).
 const ALLOWED_RIG_FIELDS = new Set([
+    "attentionCount",
     "rigId",
     "name",
     "rigName",
@@ -79,6 +80,7 @@ const ALLOWED_NODE_FIELDS = new Set([
     "sessionStatus",
     "startupStatus",
     "restoreOutcome",
+    "oriented",
     "lifecycleState",
     "tmuxAttachCommand",
     "resumeCommand",
@@ -195,6 +197,45 @@ function parseFields(input, allowed, level) {
     }
     return fields;
 }
+function parsePsControls(opts) {
+    let effectiveFilter = opts.filter;
+    if (opts.active) {
+        if (effectiveFilter) {
+            return {
+                error: `--active and --filter cannot be combined. ` +
+                    `--active is sugar for --filter agentActivity.state=running. ` +
+                    `Pick one form, or compose by upgrading to --filter directly.`,
+            };
+        }
+        effectiveFilter = "agentActivity.state=running";
+    }
+    let parsedFilter = null;
+    if (effectiveFilter) {
+        const result = parseFilter(effectiveFilter);
+        if ("error" in result)
+            return result;
+        parsedFilter = result;
+    }
+    const limit = opts.limit !== undefined ? Number(opts.limit) : null;
+    if (limit !== null && (!Number.isInteger(limit) || limit < 0)) {
+        return { error: `--limit must be a non-negative integer; got '${opts.limit}'` };
+    }
+    let fields = null;
+    if (opts.fields !== undefined) {
+        const fieldsLevel = opts.nodes ? "nodes" : "rig";
+        const fieldsAllowed = fieldsLevel === "nodes" ? ALLOWED_NODE_FIELDS : ALLOWED_RIG_FIELDS;
+        const fieldsResult = parseFields(opts.fields, fieldsAllowed, fieldsLevel);
+        if ("error" in fieldsResult)
+            return fieldsResult;
+        fields = fieldsResult;
+    }
+    return {
+        parsedFilter,
+        limit,
+        fields,
+        useEnvelope: parsedFilter !== null || limit !== null || fields !== null || opts.summary === true,
+    };
+}
 function applyRigFilter(entries, filter) {
     return entries.filter((e) => {
         if (filter.key === "status")
@@ -257,6 +298,65 @@ function applyNodeFilter(entries, filter) {
 // OPR.0.3.3.19 - build the /api/ps path, opting archived rigs back in when
 // --include-archived is set. Default (no flag) leaves the daemon's
 // archived-excluding default in force.
+function fanOutNodesError() {
+    return [
+        "rig ps --all-hosts/--hosts --nodes: per-node fan-out requires the FULL explicit ladder.",
+        "  rig ps --all-hosts --nodes -A             (fleet nodes per host, projected rows)",
+        "  rig ps --all-hosts --nodes -A --full      (complete per-node records — the last rung)",
+        "One rig's seats on one host: rig ps --host <id> --nodes --rig <name>.",
+    ].join("\n");
+}
+/**
+ * OPR.0.4.4.21 FR-2/FR-3 — THE centralized disclosure-ladder validator.
+ * Runs BEFORE the local/HTTP-host/SSH/fan-out dispatch split so every path
+ * obeys one grammar (qa1 plan-review: remote mode bypassed the session-rig
+ * injection and fanned wide). Principle (arch-ratified): IMPLICIT SCOPE
+ * DEFAULTS DON'T CROSS HOST BOUNDARIES — the session-rig default has no
+ * stable referent on a remote host (a same-named rig there would silently
+ * misresolve), so remote per-node views are explicit-or-error.
+ * Returns the teaching error text, or null when the invocation is valid.
+ */
+export function validatePsLadder(opts, callerRig) {
+    const isFanOut = !!(opts.allHosts || opts.hosts);
+    const isSingleRemote = !!opts.host;
+    // FR-3: -A/--all-rigs has exactly ONE meaning — the --nodes fleet widener.
+    if (opts.allRigs && !opts.nodes) {
+        return [
+            "rig ps -A: '-A/--all-rigs' now has exactly one meaning — the --nodes fleet widener.",
+            "The consolidated all-rigs view IS the default: just run 'rig ps'.",
+            "Fleet nodes: rig ps --nodes -A (add --full for complete per-node records).",
+            "Archived history: rig ps --include-archived.",
+        ].join("\n");
+    }
+    // FR-5: multi-host fan-out is rollup-only UNLESS the full explicit
+    // ladder is requested — `--nodes -A` per host (`--full` for complete
+    // records), exactly as the PRD writes it. Anything less explicit under
+    // --nodes errors; never silent rig-tier data under a --nodes flag.
+    if (opts.nodes && isFanOut && !opts.allRigs) {
+        return fanOutNodesError();
+    }
+    // FR-2: --nodes always names its scope — session default locally,
+    // explicit --rig / -A everywhere else. Never an implicit fan-out.
+    if (opts.nodes && !opts.rig && !opts.allRigs) {
+        if (isFanOut) {
+            return fanOutNodesError();
+        }
+        if (isSingleRemote) {
+            return [
+                `rig ps --host ${opts.host} --nodes: no target — the local session's rig is not a remote scope`,
+                "(implicit scope defaults don't cross host boundaries; a same-named remote rig would silently misresolve).",
+                `Name one: rig ps --host ${opts.host} --nodes --rig <name>, or that host's fleet explicitly: rig ps --host ${opts.host} --nodes -A.`,
+            ].join("\n");
+        }
+        if (!callerRig) {
+            return [
+                "rig ps --nodes: no target — outside a managed session there is no current rig to default to.",
+                "Name one: rig ps --nodes --rig <name>, or go fleet-wide explicitly: rig ps --nodes -A.",
+            ].join("\n");
+        }
+    }
+    return null;
+}
 function psApiPath(opts) {
     return opts.includeArchived ? "/api/ps?includeArchived=true" : "/api/ps";
 }
@@ -268,6 +368,12 @@ function selectFields(entries, fields) {
         return out;
     });
 }
+function selectFanOutFields(entries, fields) {
+    return entries.map((e) => {
+        const [selected] = selectFields([e], fields);
+        return { ...selected, hostId: e.hostId };
+    });
+}
 function needsAttention(node) {
     return node.lifecycleState === "attention_required"
         || node.startupStatus === "attention_required"
@@ -290,6 +396,8 @@ function compactNodeProjection(nodes) {
             // lifecycle + session/startup state.
             sessionStatus: n.sessionStatus,
             startupStatus: n.startupStatus,
+            // OPR.0.4.3.06 — challenge-verified orientation, distinct from ready.
+            oriented: n.oriented ?? "n-a",
             lifecycleState: n.lifecycleState,
             // activity (state always; short reason only when attention — keep it lean).
             agentActivity: attention
@@ -370,22 +478,39 @@ function abbrevNodeLifecycle(state) {
     return "—";
 }
 /**
- * `rig ps` — list running rigs and optionally their nodes.
+ * `rig ps` — the consolidated fleet map + explicit disclosure ladder.
  *
- * L3-followup adds CLI-side shaping flags (`--limit`, `--fields`, `--summary`,
- * `--filter`, `--full`) for context-window-safe output on large hosts. Default
- * `rig ps` (human) truncates to ~50 rigs with an explicit footer naming totals
- * and the `--full` opt-out. Default `rig ps --json` keeps the bare-array shape
- * for back-compat; the truncation/envelope shape only applies when at least
- * one of `--limit`/`--summary`/`--fields`/`--filter` is specified.
+ * OPR.0.4.4.21: the default is ALL active rigs, one compact O(rigs) row each
+ * (the current-rig-only default is retired). The token-safety invariant: no
+ * invocation returns per-node detail across all rigs unless explicitly
+ * flagged (--nodes -A), and even then rows are projected unless --full.
+ * Default `rig ps --json` keeps the bare-array shape for back-compat; the
+ * truncation/envelope shape only applies when at least one of
+ * `--limit`/`--summary`/`--fields`/`--filter` is specified.
  */
 export function psCommand(depsOverride) {
     const cmd = new Command("ps")
         .description("List rigs and their status")
         .addHelpText("after", `
-Default: current-rig scope (derived from OPENRIG_SESSION_NAME's @<rig> suffix).
-Shows ALL states (stopped, recoverable, attention, idle — non-running IS the
-actionable signal for topology/readiness). Use -A/--all-rigs for fleet breadth.
+Default (OPR.0.4.4.21): ALL active rigs, ONE compact row each — O(rigs), never
+a fleet node fan-out — plus the host rollup line ("N rigs · M seats · K need
+attention"), the archived/stopped count line, and the drill-ladder footer.
+STATED contract: default --json is a bare array of ALL non-archived rigs
+INCLUDING stopped ones (existing keys preserved; additive attentionCount);
+only the HUMAN table folds stopped rigs into the count line.
+
+The disclosure ladder (each heavier view is an explicit step):
+  rig ps                      the consolidated map (this default)
+  rig ps --rig <name>         one rig's detail
+  rig ps --nodes              per-node, CURRENT rig (session default, local only)
+  rig ps --nodes --rig <name> per-node, named rig
+  rig ps --nodes -A           fleet nodes, projected rows
+  rig ps --nodes -A --full    complete per-node records (the only full fan-out)
+
+-A/--all-rigs has exactly ONE meaning: the --nodes fleet widener. Bare -A
+errors (all-rigs IS the default; archived history stays behind
+--include-archived). The session-rig default never crosses host boundaries:
+remote --nodes requires an explicit --rig or -A.
 
 Compact defaults: 'rig ps --nodes' shows a compact summary per node
 (rig, session, lifecycle, activity state, reason when attention, queue counts,
@@ -399,11 +524,10 @@ null even with --full; fetch the full recovery guidance + currentUsage from the
 single-node detail (/api/rigs/:rigId/nodes/:logicalId) or 'rig whoami'.
 
 Examples:
-  rig ps                                          Current rig summary (compact)
-  rig ps -A                                       All rigs (fleet breadth)
-  rig ps --full                                   Current rig, full detail
-  rig ps --json                                   Current rig, compact JSON
-  rig ps -A --json                                All rigs, compact JSON
+  rig ps                                          All active rigs, one row each + rollup
+  rig ps --rig <name>                             One rig's detail
+  rig ps --full                                   All rigs, no table truncation
+  rig ps --json                                   All non-archived rigs, bare JSON array
   rig ps --json --limit 20                        Bounded JSON envelope
   rig ps --json --summary                         Aggregate-only JSON
   rig ps --json --fields rigName,status,lifecycleState
@@ -423,12 +547,16 @@ Examples:
   rig ps --nodes --running                        Same as --active
   rig ps --nodes --filter agentActivity.state=running
                                                   Same as --active (the explicit form)
-  rig ps --host vm-claude-test --nodes --json     Remote host (no current-rig default)
+  rig ps --host vm-1 --nodes --rig <name> --json  Remote host per-node (explicit target required)
+  rig ps --all-hosts                              Per-host O(rigs) rollups (AggregatedPayload JSON)
   rig ps --include-archived                       Include archived rigs (marked with *); hidden by default
 
---rig <name> overrides the current-rig default. -A/--all-rigs disables it.
---session <name> filters within the effective rig scope; use -A if the target
-session is in a different rig.
+--rig <name> scopes to one rig. -A/--all-rigs is ONLY the --nodes fleet widener.
+--session <name> filters within the effective rig scope; use --nodes -A if the
+target session is in a different rig.
+Multi-host fan-out (--all-hosts/--hosts) is rollup-only by default; the full
+explicit ladder (--all-hosts --nodes -A, --full for complete records) fans out
+per-node with hostId-stamped projected rows.
 
 --active/--running narrow to agentActivity.state=running. Cannot combine with --filter.
 
@@ -436,7 +564,8 @@ session is in a different rig.
 contextUsage.percent, contextUsage.state. Other keys are rejected.
 
 --fields accepts (rig-level): rigId, name, rigName, nodeCount, runningCount,
-activeCount, hasWorkCount, status, lifecycleState, uptime, latestSnapshot.
+activeCount, hasWorkCount, attentionCount, status, lifecycleState, uptime,
+latestSnapshot.
 --fields accepts (node-level, with --nodes): rigId, rigName, logicalId, podId,
 podNamespace, canonicalSessionName, nodeKind, runtime, sessionStatus,
 startupStatus, restoreOutcome, lifecycleState, tmuxAttachCommand,
@@ -475,15 +604,49 @@ Exit codes:
         if (opts.running)
             opts.active = true;
         const isRemote = !!(opts.host || opts.allHosts || opts.hosts);
-        if (!opts.allRigs && !opts.rig && !isRemote) {
-            const sessionName = readOpenRigEnv("OPENRIG_SESSION_NAME", "RIGGED_SESSION_NAME");
-            const callerRig = sessionName ? extractRigName(sessionName) : undefined;
-            if (callerRig)
-                opts.rig = callerRig;
+        // OPR.0.4.4.21 FR-1: the rig tier is consolidated ALL-ACTIVE-RIGS by
+        // default (the current-rig-only default is RETIRED — it hid running
+        // rigs from the operator's field of view). The session-rig default
+        // now applies ONLY to the node tier (FR-2's scoped --nodes), and
+        // ONLY locally (the ladder validator enforces explicit-or-error on
+        // every remote path).
+        const sessionName = readOpenRigEnv("OPENRIG_SESSION_NAME", "RIGGED_SESSION_NAME");
+        const callerRig = sessionName ? extractRigName(sessionName) : undefined;
+        const ladderError = validatePsLadder(opts, callerRig);
+        if (ladderError) {
+            console.error(ladderError);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.nodes && !opts.allRigs && !opts.rig && !isRemote && callerRig) {
+            opts.rig = callerRig;
         }
         const deps = getDepsF();
+        // OPR.0.4.4.21 rev1-r2 fixback: the shared shaping controls
+        // (--active/--filter/--limit/--fields/--summary) parse + validate
+        // BEFORE any dispatch — local, single-host, or fan-out — so every
+        // path honors the same composition contract and rejections stay
+        // pre-HTTP on remote paths too.
+        // Parse shared composition controls once up front so local, single-host,
+        // and fan-out paths reject malformed --filter/--limit/--fields before
+        // any HTTP call and apply the same shaping semantics.
+        const controls = parsePsControls(opts);
+        if ("error" in controls) {
+            console.error(controls.error);
+            process.exitCode = 1;
+            return;
+        }
+        const { parsedFilter, limit, fields, useEnvelope } = controls;
         if (opts.allHosts || opts.hosts) {
-            await runFanOutPs(opts, deps);
+            // AggregatedPayload is the closed fan-out contract (items + hosts).
+            // Do not add an ad-hoc summary member here; teach the per-host form.
+            if (opts.summary) {
+                console.error("rig ps --all-hosts/--hosts --summary: summary does not compose with the merged fan-out payload.\n" +
+                    "Summarize one host: rig ps --host <id> --summary; or drop --summary for the merged AggregatedPayload.");
+                process.exitCode = 1;
+                return;
+            }
+            await runFanOutPs(opts, deps, { parsedFilter, limit, fields });
             return;
         }
         if (opts.host) {
@@ -496,73 +659,31 @@ Exit codes:
             process.exitCode = 1;
             return;
         }
-        // Parse filter once up front so unknown keys/malformed filters surface
-        // as exit-1 errors before any HTTP call.
-        //
-        // PL-019 item 1: --active is sugar for --filter agentActivity.state=running.
-        // Combining --active with --filter is rejected (composition is
-        // ambiguous — pick one explicit form). Parity is verified end-to-end
-        // by the focused test: `--active` and the explicit filter must yield
-        // identical output on the same fixture.
-        let effectiveFilter = opts.filter;
-        if (opts.active) {
-            if (effectiveFilter) {
-                console.error(`--active and --filter cannot be combined. ` +
-                    `--active is sugar for --filter agentActivity.state=running. ` +
-                    `Pick one form, or compose by upgrading to --filter directly.`);
-                process.exitCode = 1;
-                return;
-            }
-            effectiveFilter = "agentActivity.state=running";
-        }
-        let parsedFilter = null;
-        if (effectiveFilter) {
-            const result = parseFilter(effectiveFilter);
-            if ("error" in result) {
-                console.error(result.error);
-                process.exitCode = 1;
-                return;
-            }
-            parsedFilter = result;
-        }
-        const limit = opts.limit !== undefined ? Number(opts.limit) : null;
-        if (limit !== null && (!Number.isInteger(limit) || limit < 0)) {
-            console.error(`--limit must be a non-negative integer; got '${opts.limit}'`);
-            process.exitCode = 1;
-            return;
-        }
-        // C9a: validate --fields against the per-level allow-list before any HTTP
-        // call, mirroring the --filter validation above. Level is determined by
-        // --nodes; both branches downstream use the same `fields` variable, so
-        // one up-front validation covers both paths.
-        let fields = null;
-        if (opts.fields !== undefined) {
-            const fieldsLevel = opts.nodes ? "nodes" : "rig";
-            const fieldsAllowed = fieldsLevel === "nodes" ? ALLOWED_NODE_FIELDS : ALLOWED_RIG_FIELDS;
-            const fieldsResult = parseFields(opts.fields, fieldsAllowed, fieldsLevel);
-            if ("error" in fieldsResult) {
-                console.error(fieldsResult.error);
-                process.exitCode = 1;
-                return;
-            }
-            fields = fieldsResult;
-        }
-        const useEnvelope = parsedFilter !== null || limit !== null || fields !== null || opts.summary === true;
         const client = deps.clientFactory(getDaemonUrl(status));
         if (opts.nodes) {
             await handleNodes(client, opts, parsedFilter, limit, fields, useEnvelope);
             return;
         }
-        const res = await client.get(psApiPath(opts));
+        // OPR.0.4.4.21 FR-1: ONE O(rigs) fetch including archived so the
+        // count line can be computed; visibility is split client-side below
+        // (JSON keeps today's default of excluding archived — parity).
+        const res = await client.get("/api/ps?includeArchived=true");
         if (res.status >= 400) {
             console.error(`Failed to fetch rig list from daemon (HTTP ${res.status}). Check daemon status with: rig status`);
             process.exitCode = 2;
             return;
         }
         const all = res.data;
+        // OPR.0.4.4.21 — archived visibility parity: the daemon call above
+        // always includes archived (for the count line); without
+        // --include-archived they are dropped from BOTH renders here, exactly
+        // as the daemon default used to do. archivedCount feeds the FR-1
+        // count line only.
+        const archivedCount = all.filter((e) => e.isArchived === true).length;
+        const visible = opts.includeArchived ? all : all.filter((e) => e.isArchived !== true);
         const rigScoped = opts.rig
-            ? all.filter((e) => (e.rigName ?? e.name) === opts.rig)
-            : all;
+            ? visible.filter((e) => (e.rigName ?? e.name) === opts.rig)
+            : visible;
         // Apply CLI-side filter (Amendment A: prefer CLI shaping).
         const filtered = parsedFilter ? applyRigFilter(rigScoped, parsedFilter) : rigScoped;
         // Summary mode short-circuits per-entry output.
@@ -605,15 +726,32 @@ Exit codes:
             if (parsedFilter) {
                 console.log(`No rigs match --filter ${parsedFilter.key}=${parsedFilter.value}`);
             }
+            else if (archivedCount > 0 && !opts.includeArchived) {
+                // Proven-empty with the history pointer, never a bare "No rigs"
+                // while archived history exists.
+                console.log(`No active rigs · ${archivedCount} archived (rig ps --include-archived)`);
+            }
             else {
                 console.log("No rigs");
             }
             return;
         }
+        // OPR.0.4.4.21 FR-1 (human table ONLY — JSON keeps ALL non-archived
+        // entries including stopped; this scope split is a STATED contract
+        // sentence in the help text): on the BARE default (no filter, no
+        // --rig, no --include-archived) stopped rigs fold into the count
+        // line — history is what the default drops, not field of view.
+        const bareDefault = !parsedFilter && !opts.rig && !opts.includeArchived;
+        const tableRows = bareDefault ? limited.filter((e) => e.status !== "stopped") : limited;
+        const stoppedCount = bareDefault ? limited.length - tableRows.length : 0;
+        // FR-1 display element 1: the host rollup line.
+        const rollupSeats = tableRows.reduce((n, e) => n + e.nodeCount, 0);
+        const rollupAttention = tableRows.reduce((n, e) => n + (e.attentionCount ?? 0), 0);
+        console.log(`${tableRows.length} rig${tableRows.length === 1 ? "" : "s"} · ${rollupSeats} seat${rollupSeats === 1 ? "" : "s"} · ${rollupAttention} need${rollupAttention === 1 ? "s" : ""} attention`);
         // Human output: apply default truncation budget unless --full.
-        const humanList = (opts.full || limit !== null) ? limited : limited.slice(0, HUMAN_RIG_BUDGET);
-        const humanTruncated = !opts.full && limit === null && filtered.length > HUMAN_RIG_BUDGET;
-        const header = padRigRow("RIG", "NODES", "RUNNING", "ACTIVE", "WORK", "STATUS", "LIFECYCLE", "UPTIME", "SNAPSHOT");
+        const humanList = (opts.full || limit !== null) ? tableRows : tableRows.slice(0, HUMAN_RIG_BUDGET);
+        const humanTruncated = !opts.full && limit === null && tableRows.length > HUMAN_RIG_BUDGET;
+        const header = padRigRow("RIG", "NODES", "RUNNING", "ACTIVE", "WORK", "ATTN", "STATUS", "LIFECYCLE", "UPTIME", "SNAPSHOT");
         console.log(header);
         let anyArchivedShown = false;
         for (const e of humanList) {
@@ -624,11 +762,27 @@ Exit codes:
                 anyArchivedShown = true;
             console.log(padRigRow(e.isArchived ? `${e.rigName ?? e.name} *` : (e.rigName ?? e.name), String(e.nodeCount), String(e.runningCount), 
             // Slice 15 — "—" when daemon predates the field; honest absence.
-            e.activeCount !== undefined ? String(e.activeCount) : "—", e.hasWorkCount !== undefined ? String(e.hasWorkCount) : "—", e.status, abbrevRigLifecycle(e.lifecycleState), e.uptime ?? "—", e.latestSnapshot ?? "—"));
+            e.activeCount !== undefined ? String(e.activeCount) : "—", e.hasWorkCount !== undefined ? String(e.hasWorkCount) : "—", 
+            // OPR.0.4.4.21 — the founder's field-of-view anchor: where is
+            // something that might concern me. "—" = daemon predates the field.
+            e.attentionCount !== undefined ? (e.attentionCount > 0 ? `▲${e.attentionCount}` : "0") : "—", e.status, abbrevRigLifecycle(e.lifecycleState), e.uptime ?? "—", e.latestSnapshot ?? "—"));
         }
         if (anyArchivedShown) {
             console.log("* = archived (hidden from the default view; shown via --include-archived). Reverse with: rig unarchive <rig>");
         }
+        // FR-1 display element 2: history as ONE count line, never rows.
+        if (stoppedCount > 0 || (!opts.includeArchived && archivedCount > 0)) {
+            const parts = [];
+            if (stoppedCount > 0)
+                parts.push(`${stoppedCount} stopped (rig ps --filter status=stopped)`);
+            if (!opts.includeArchived && archivedCount > 0)
+                parts.push(`${archivedCount} archived (rig ps --include-archived)`);
+            console.log(`not shown: ${parts.join(" · ")}`);
+        }
+        // FR-1 display element 3: the affordance footer — the drill ladder.
+        if (bareDefault) {
+            console.log("drill: rig ps --rig <name> (one rig) · rig ps --nodes --rig <name> (its seats) · --full (everything)");
+        }
         if (humanTruncated) {
             const remaining = filtered.length - HUMAN_RIG_BUDGET;
             console.log(`... and ${remaining} more rig${remaining === 1 ? "" : "s"} (truncated at ${HUMAN_RIG_BUDGET}).`);
@@ -651,14 +805,24 @@ async function handleNodes(client, opts, parsedFilter, limit, fields, useEnvelop
     const effectiveRigs = opts.rig
         ? rigRes.data.filter((r) => (r.rigName ?? r.name) === opts.rig)
         : rigRes.data;
+    // OPR.0.4.3 healthz-wedge: the daemon nodes route is CHEAP by default (no
+    // per-node tmux capture) — `rig ps --nodes` gets snapshot-based activity. Pass
+    // ?full=true only when the operator asks for --full, which opts into the
+    // per-node pane-heuristic (freshest needs_input) at the fan-out's cost.
+    const nodesQuery = opts.full ? "?full=true" : "";
     const allNodes = [];
     for (const rig of effectiveRigs) {
-        const nodesRes = await client.get(`/api/rigs/${encodeURIComponent(rig.rigId)}/nodes`, requestHeaders ? { headers: requestHeaders } : undefined);
+        const nodesRes = await client.get(`/api/rigs/${encodeURIComponent(rig.rigId)}/nodes${nodesQuery}`, requestHeaders ? { headers: requestHeaders } : undefined);
         if (nodesRes.status >= 400) {
             console.error(`Warning: failed to fetch nodes for rig "${rig.rigName ?? rig.name}" (HTTP ${nodesRes.status}). List rigs with: rig ps`);
             continue;
         }
-        allNodes.push(...nodesRes.data);
+        const parentRigName = rig.rigName ?? rig.name;
+        allNodes.push(...nodesRes.data.map((n) => ({
+            ...n,
+            rigId: n.rigId ?? rig.rigId,
+            rigName: n.rigName ?? parentRigName,
+        })));
     }
     let narrowed = allNodes;
     if (opts.rig)
@@ -724,14 +888,14 @@ async function handleNodes(client, opts, parsedFilter, limit, fields, useEnvelop
         }
     }
     else {
-        const header = padNodeRow("RIG", "POD", "MEMBER", "SESSION", "RUNTIME", "STATUS", "STARTUP", "LIFECYCLE", "TERMINAL", "WORK", "ACTIVITY", "CTX", "RESTORE", "ERROR");
+        const header = padNodeRow("RIG", "POD", "MEMBER", "SESSION", "RUNTIME", "STATUS", "STARTUP", "ORIENTED", "LIFECYCLE", "TERMINAL", "WORK", "ACTIVITY", "CTX", "RESTORE", "ERROR");
         console.log(header);
         for (const n of humanList) {
             const parts = n.logicalId.split(".");
             const pod = n.podNamespace ?? (parts.length > 1 ? parts[0] : "—");
             const member = parts.length > 1 ? parts.slice(1).join(".") : n.logicalId;
             const rig = `${n.rigName}#${n.rigId}`;
-            console.log(padNodeRow(rig, pod, member, n.canonicalSessionName ?? "—", n.runtime ?? "—", n.sessionStatus ?? "—", n.startupStatus ?? "—", abbrevNodeLifecycle(n.lifecycleState), formatTerminalActive(n.terminalActive), formatHasWork(n.hasAssignedWork, n.pendingWorkCount), formatActivity(n.agentActivity), formatContextUsage(n.contextUsage), n.restoreOutcome, n.latestError ? truncate(n.latestError, 30) : n.heldReason ? `held: ${truncate(n.heldReason, 25)}` : "—"));
+            console.log(padNodeRow(rig, pod, member, n.canonicalSessionName ?? "—", n.runtime ?? "—", n.sessionStatus ?? "—", n.startupStatus ?? "—", n.oriented ?? "—", abbrevNodeLifecycle(n.lifecycleState), formatTerminalActive(n.terminalActive), formatHasWork(n.hasAssignedWork, n.pendingWorkCount), formatActivity(n.agentActivity), formatContextUsage(n.contextUsage), n.restoreOutcome, n.latestError ? truncate(n.latestError, 30) : n.heldReason ? `held: ${truncate(n.heldReason, 25)}` : "—"));
         }
     }
     if (humanTruncated) {
@@ -761,7 +925,7 @@ function truncate(s, max) {
 function fitCell(value, width) {
     return truncate(value, width).padEnd(width);
 }
-function padRigRow(rig, nodes, running, active, work, status, lifecycle, uptime, snapshot) {
+function padRigRow(rig, nodes, running, active, work, attn, status, lifecycle, uptime, snapshot) {
     return [
         fitCell(rig, 24),
         fitCell(nodes, 7),
@@ -772,13 +936,15 @@ function padRigRow(rig, nodes, running, active, work, status, lifecycle, uptime,
         // operators see which dimension differs at a glance.
         fitCell(active, 8),
         fitCell(work, 6),
+        // OPR.0.4.4.21 — ATTN: seats needing attention (the field-of-view anchor).
+        fitCell(attn, 6),
         fitCell(status, 10),
         fitCell(lifecycle, 11),
         fitCell(uptime, 11),
         snapshot,
     ].join("");
 }
-function padNodeRow(rig, pod, member, session, runtime, status, startup, lifecycle, terminal, work, activity, ctx, restore, error) {
+function padNodeRow(rig, pod, member, session, runtime, status, startup, oriented, lifecycle, terminal, work, activity, ctx, restore, error) {
     return [
         fitCell(rig, 30),
         fitCell(pod, 10),
@@ -787,6 +953,8 @@ function padNodeRow(rig, pod, member, session, runtime, status, startup, lifecyc
         fitCell(runtime, 12),
         fitCell(status, 10),
         fitCell(startup, 10),
+        // OPR.0.4.3.06 — challenge-verified orientation, distinct from STARTUP.
+        fitCell(oriented, 9),
         fitCell(lifecycle, 11),
         // Slice 15 — distinct TERMINAL + WORK columns.
         fitCell(terminal, 9),
@@ -868,7 +1036,10 @@ async function runCrossHostPs(hostId, opts, deps) {
     // OPR.0.4.0.34: forward the breadth flag so `--host h -A` keeps all-rigs
     // breadth across the hop (the current-rig default is local-only and never
     // applied to a remote call, but an explicit -A must still reach the remote).
-    if (opts.allRigs)
+    // OPR.0.4.4.21 FR-3: -A is legal only alongside --nodes (the validator
+    // already rejected the bare form before any dispatch; this guard keeps
+    // the reconstructed remote argv obeying the same grammar).
+    if (opts.allRigs && opts.nodes)
         argv.push("--all-rigs");
     if (opts.limit !== undefined)
         argv.push("--limit", opts.limit);
@@ -922,46 +1093,15 @@ async function runHttpPs(host, opts, deps) {
         process.exitCode = 1;
         return;
     }
-    let effectiveFilter = opts.filter;
-    if (opts.active) {
-        if (effectiveFilter) {
-            console.error("--active and --filter cannot be combined.");
-            process.exitCode = 1;
-            return;
-        }
-        effectiveFilter = "agentActivity.state=running";
-    }
-    let parsedFilter = null;
-    if (effectiveFilter) {
-        const result = parseFilter(effectiveFilter);
-        if ("error" in result) {
-            console.error(result.error);
-            process.exitCode = 1;
-            return;
-        }
-        parsedFilter = result;
-    }
-    const limit = opts.limit !== undefined ? Number(opts.limit) : null;
-    if (limit !== null && (!Number.isInteger(limit) || limit < 0)) {
-        console.error(`--limit must be a non-negative integer; got '${opts.limit}'`);
+    const controls = parsePsControls(opts);
+    if ("error" in controls) {
+        console.error(controls.error);
         process.exitCode = 1;
         return;
     }
-    let fields = null;
-    if (opts.fields !== undefined) {
-        const fieldsLevel = opts.nodes ? "nodes" : "rig";
-        const fieldsAllowed = fieldsLevel === "nodes" ? ALLOWED_NODE_FIELDS : ALLOWED_RIG_FIELDS;
-        const fieldsResult = parseFields(opts.fields, fieldsAllowed, fieldsLevel);
-        if ("error" in fieldsResult) {
-            console.error(fieldsResult.error);
-            process.exitCode = 1;
-            return;
-        }
-        fields = fieldsResult;
-    }
+    const { parsedFilter, limit, fields, useEnvelope } = controls;
     const client = deps.clientFactory(host.url);
     const headers = buildRemoteHeaders(bearerResult.token);
-    const useEnvelope = parsedFilter !== null || limit !== null || fields !== null || opts.summary === true;
     try {
         if (opts.nodes) {
             await handleNodes(client, opts, parsedFilter, limit, fields, useEnvelope, headers);
@@ -1010,7 +1150,22 @@ async function runHttpPs(host, opts, deps) {
         process.exitCode = 1;
     }
 }
-async function runFanOutPs(opts, deps) {
+/** OPR.0.4.4.21 FR-5 — adapter to the intra-P4 shared contract
+ *  (fanout-contract.ts, slice 15 first-lander at 0ecd329b; the closed
+ *  status enum is THE contract, failedStep rides as additive detail). */
+function toPerHostStatus(r) {
+    const status = r.ok ? "ok"
+        : r.failedStep === "unsupported-transport" ? "unsupported-transport"
+            : r.failedStep === "permission-gate" ? "auth-failed"
+                : "unreachable";
+    const out = { hostId: r.host, status };
+    if (r.error)
+        out.error = r.error;
+    if (!r.ok && r.failedStep !== "unsupported-transport")
+        out.failedStep = r.failedStep;
+    return out;
+}
+async function runFanOutPs(opts, deps, shaping) {
     const loader = deps.hostRegistryLoader ?? loadHostRegistry;
     const registry = loader();
     if (!registry.ok) {
@@ -1030,14 +1185,20 @@ async function runFanOutPs(opts, deps) {
         }
     }
     else {
-        targetIds = allHosts.filter((h) => h.transport === "http").map((h) => h.id);
+        // OPR.0.4.4.21 fixback (qa1 F1): target EVERY declared host — non-HTTP
+        // hosts must appear in hosts[] as unsupported-transport (R15-2), never
+        // be silently absent. The per-host leg classifies transport.
+        targetIds = allHosts.map((h) => h.id);
     }
     const results = await Promise.all(targetIds.map(async (id) => {
         const host = allHosts.find((h) => h.id === id);
         if (!host)
             return { host: id, ok: false, failedStep: "remote-daemon-unreachable", error: `unknown host ${id}` };
         if (host.transport !== "http") {
-            return { host: id, ok: false, failedStep: "remote-command-failed", error: `host ${id} uses transport ${host.transport}; HTTP fan-out requires transport: http` };
+            // R15-2 (shared contract): an SSH-declared host is a STRUCTURED
+            // unsupported-transport status — never prose-only, never silently
+            // thinner output.
+            return { host: id, ok: false, failedStep: "unsupported-transport", error: `host ${id} uses transport ${host.transport}; HTTP fan-out requires transport: http` };
         }
         const httpHost = host;
         const bearerResult = resolveRemoteBearer(httpHost);
@@ -1045,16 +1206,35 @@ async function runFanOutPs(opts, deps) {
             return { host: id, ok: false, failedStep: bearerResult.failedStep, error: bearerResult.error };
         }
         const client = deps.clientFactory(httpHost.url);
+        const headers = buildRemoteHeaders(bearerResult.token);
         try {
             const psQuery = opts.includeArchived ? "?includeArchived=true" : "";
-            const res = await client.get(`/api/ps${psQuery}`, {
-                headers: buildRemoteHeaders(bearerResult.token),
-            });
+            const res = await client.get(`/api/ps${psQuery}`, { headers });
             const failedStep = classifyHttpFailedStep(res.status);
             if (failedStep !== "none") {
                 return { host: id, ok: false, failedStep, error: `HTTP ${res.status}` };
             }
-            return { host: id, ok: true, failedStep: "none", data: res.data };
+            if (!opts.nodes) {
+                return { host: id, ok: true, failedStep: "none", data: res.data };
+            }
+            // OPR.0.4.4.21 FR-5 — the full explicit ladder (--nodes -A, --full
+            // for complete records): per-host node fan-out, projected unless
+            // --full (the invariant's last rung; validated as -A-only upstream).
+            const rigs = Array.isArray(res.data) ? res.data : [];
+            const nodes = [];
+            for (const rig of rigs) {
+                const nodesRes = await client.get(`/api/rigs/${encodeURIComponent(rig.rigId)}/nodes`, { headers });
+                if (nodesRes.status >= 400) {
+                    return { host: id, ok: false, failedStep: classifyHttpFailedStep(nodesRes.status), error: `HTTP ${nodesRes.status} fetching nodes for rig ${rig.rigName ?? rig.name}` };
+                }
+                const parentRigName = rig.rigName ?? rig.name;
+                nodes.push(...nodesRes.data.map((n) => ({
+                    ...n,
+                    rigId: n.rigId ?? rig.rigId,
+                    rigName: n.rigName ?? parentRigName,
+                })));
+            }
+            return { host: id, ok: true, failedStep: "none", data: nodes };
         }
         catch (err) {
             return { host: id, ok: false, failedStep: classifyHttpError(err), error: err.message };
@@ -1062,7 +1242,49 @@ async function runFanOutPs(opts, deps) {
     }));
     const hasFailure = results.some((r) => !r.ok);
     if (opts.json) {
-        console.log(JSON.stringify({ hosts: results }));
+        // OPR.0.4.4.21 FR-5 — the intra-P4 shared payload (ONE contract with
+        // slice 15): items = each host's rows stamped with their origin hostId
+        // (flat-mergeable; origin never positional), hosts = the per-host
+        // structured status array. EVERY targeted host appears in hosts[] —
+        // ok or not (no silent thinning).
+        const rawItems = results.flatMap((r) => r.ok && Array.isArray(r.data)
+            ? r.data.map((row) => ({ ...row, hostId: r.host }))
+            : []);
+        const hostStatuses = results.map(toPerHostStatus);
+        let narrowed = rawItems;
+        if (opts.rig)
+            narrowed = narrowed.filter((e) => (e.rigName ?? e.name) === opts.rig);
+        if (opts.nodes && opts.session)
+            narrowed = narrowed.filter((n) => n.canonicalSessionName === opts.session);
+        const filtered = shaping.parsedFilter
+            ? opts.nodes
+                ? applyNodeFilter(narrowed, shaping.parsedFilter)
+                : applyRigFilter(narrowed, shaping.parsedFilter)
+            : narrowed;
+        let items;
+        if (opts.summary) {
+            items = [
+                opts.nodes
+                    ? summarizeNodes(filtered)
+                    : summarizeRigs(filtered),
+            ];
+        }
+        else {
+            const limited = shaping.limit !== null ? filtered.slice(0, shaping.limit) : filtered;
+            items = shaping.fields
+                ? selectFanOutFields(limited, shaping.fields)
+                : opts.nodes && !opts.full
+                    ? compactNodeProjection(limited).map((row, i) => ({
+                        ...row,
+                        hostId: limited[i]?.hostId,
+                    }))
+                    : limited;
+        }
+        const payload = {
+            items,
+            hosts: hostStatuses,
+        };
+        console.log(JSON.stringify(payload));
     }
     else {
         for (const r of results) {