@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.14010

package/dist/commands/orient.js

@@ -1,26 +1,103 @@
 /**
- * pb orient — prints workspace stage and all orient sections per ARCH-25.
+ * pb orient — prints all orient sections per ARCH-25.
  * BET-181 Slice 0: routes through runCliCommand for JSON-default output.
  */
-import { getConfigOrGuide } from '../lib/config.js';
-import { mcpCall } from '../lib/client.js';
-import { runCliCommand } from '../lib/runner.js';
+import { getConfig, getConfigOrGuide } from '../lib/config.js';
+import { gatewayHeaders, kernelCall } from '../lib/client.js';
+import { runCliCommand, isJsonMode } from '../lib/runner.js';
+import { stripConvexInternals } from '../lib/strip.js';
 import { formatOrient, formatOrientBrief } from '../formatters/orient.js';
-function normalizeView(raw) {
+import { getOrFetchVocabCtx } from '../lib/workspaceVocabCache.js';
+import { clearSession, discardSession, readSession } from '../lib/session.js';
+import { isEndedSessionCode } from '../lib/errors.js';
+import { collectCliStartupSignals } from '../lib/startup-signals.js';
+/**
+ * The orient read is useful even when its optional local session marker has gone stale on the
+ * server. Only the lifecycle failures that prove that marker can no longer be used are
+ * recoverable here; ownership/workspace/auth failures still surface instead of being hidden.
+ * An ended session answers with its code. A session the server never had answers only in words:
+ * the not-found line carries no code of its own, so it is matched as a sentence.
+ */
+function staleSessionMarker(error) {
+    if (!(error instanceof Error) || error.name !== 'McpError')
+        return null;
+    const code = error.code;
+    if (isEndedSessionCode(code))
+        return 'ended';
+    if (code !== 'MCP_GATEWAY_CLIENT' && code !== 'SESSION_REQUIRED')
+        return null;
+    return error.message === 'Agent session not found' ? 'not-found' : null;
+}
+/**
+ * WP-376 α.3: fire-and-forget orient byte report from the CLI surface.
+ *
+ * Inlined raw fetch (vs `kernelCall`) for three reasons:
+ *   1. No spinner — observability must not show user-visible progress
+ *      indicators after the orient render completes.
+ *   2. Truly fire-and-forget — never block returning to the shell on a
+ *      slow gateway, never propagate errors to the user.
+ *   3. Avoids the post-write session-touch heartbeat (kernelCallWithSession)
+ *      — orient byte report is itself a heartbeat-equivalent observability
+ *      write, so a follow-up agent.touchSession is redundant (parallel to
+ *      MCP's TOUCH_EXCLUDED exemption in client.ts).
+ *
+ * The gateway's `injectSessionAuth` (BR-18) resolves workspaceId / apiKeyId /
+ * clerkUserId from the bearer token, so the surface only sends payload bytes
+ * + truncation flag. Auth and identity stay server-side.
+ */
+// WP-480 S3 (FEAT-1360): the taskIsMeaningful predicate mirror is DELETED — the
+// server resolves task-meaningfulness + effective tier and serves them on the
+// orient payload (`taskMeaningful`, `resolvedTier`); this surface consumes them.
+// DEC-NEW: reports the resolved tier + task-presence alongside bytes + truncated.
+function reportOrientCliBytes(bytes, truncated, tier, taskProvided) {
+    let apiKey;
+    let siteUrl;
+    try {
+        ({ apiKey, siteUrl } = getConfig());
+    }
+    catch {
+        // No config — best-effort observability never fails the command.
+        return;
+    }
+    // Thread the active session context (Codex re-review): without it, the server's N-per-key
+    // ambiguity guard skips the rendered-byte update when a key has >1 active conversation — the whole
+    // point of this public report route is the surface-rendered metric.
+    const active = readSession();
+    void fetch(`${siteUrl}/api/aki`, {
+        method: 'POST',
+        headers: gatewayHeaders(apiKey, undefined, active?.sessionId), // TASK-893: counted under this command's x-pb-command
+        body: JSON.stringify({
+            fn: 'agent.reportOrientMetric',
+            args: {
+                bytes,
+                truncated,
+                tier,
+                taskProvided,
+                ...(active?.sessionId ? { sessionId: active.sessionId } : {}),
+                ...(active?.conversationId ? { conversationId: active.conversationId } : {}),
+            },
+        }),
+    }).catch(() => {
+        // Best-effort — silently swallow.
+    });
+}
+/**
+ * Normalize the raw API view into the formatter's `OrientView` shape (optional
+ * sections become empty arrays / null, not absent). Exported so other surfaces
+ * (e.g. `pb codex-prep`) route their API view through the SAME normalizer the
+ * canonical `pb orient` path uses, instead of re-deriving fields ad hoc.
+ */
+export function normalizeView(raw) {
     return {
         ...raw,
-        governance: raw.governance ?? {
-            principles: [],
-            standards: [],
-            businessRules: [],
-        },
+        strategyHighlights: raw.strategyHighlights ?? [],
         tensions: raw.tensions ?? [],
         architectureNotes: raw.architectureNotes ?? [],
-        proposals: raw.proposals ?? [],
         absenceSignals: raw.absenceSignals ?? [],
+        startup: raw.startup,
+        taskContext: raw.taskContext,
         plannedWork: raw.plannedWork ?? {
             uncommittedDrafts: [],
-            inProgressEntries: [],
             openTensions: [],
         },
         priorSessions: raw.priorSessions ?? [],
@@ -28,19 +105,164 @@ function normalizeView(raw) {
     };
 }
 export async function runOrient(options = {}) {
-    const config = await getConfigOrGuide(() => runOrient(options));
-    if (!config)
-        return;
+    const config = await getConfigOrGuide();
+    // WP-436 S2: resolve workspace vocabulary context (Axis 2, PAT-230, DEC-1021).
+    // Uses the API key as the cache key (1:1 with workspace at CLI layer).
+    // Fail-open: if chain.getVocabulary is unreachable, resolver falls back to canonicalKey literal.
+    const vocabCtx = await getOrFetchVocabCtx(config.apiKey, async () => {
+        const vocab = await kernelCall('chain.getVocabulary', {});
+        if (vocab?.collectionLabels || vocab?.collectionDefaults) {
+            return {
+                ...(vocab.collectionLabels ? { collectionLabels: vocab.collectionLabels } : {}),
+                ...(vocab.collectionDefaults ? { collectionDefaults: vocab.collectionDefaults } : {}),
+            };
+        }
+        return null;
+    });
+    // WP-376 α.3: capture the view + raw flag from the closure so we can
+    // measure client-side rendered bytes after runCliCommand finishes.
+    let capturedView = null;
+    let capturedTruncated = false;
+    // WP-480 S3 (FEAT-1360): the served resolution (getOrientView is the payload
+    // owner) — undefined when an old deploy doesn't serve the fields yet.
+    let capturedResolvedTier;
+    let capturedTaskMeaningful;
     await runCliCommand({
         fn: async () => {
-            const raw = await mcpCall('chain.getOrientView', {});
+            const callArgs = {};
+            if (options.task)
+                callArgs.task = options.task;
+            // WP-486 Slice 1 (FEAT-1371, TEN-2724): `startupSignals` is sent unconditionally.
+            // D1d (WP-754/TASK-204): domain resolution is deleted server-side — `startupSignals` no
+            // longer feeds it. It still feeds `context.served`'s presence telemetry
+            // (`convex/lib/contextServedInput.ts`'s `changedPaths`/`branchNamePresent`/
+            // `worktreeNamePresent`), which benefits from an honest signal whether or not a task is
+            // present — that is the sole surviving reason this stays unconditional.
+            // `invocationPath` is NOT unconditional (PR #369 review,
+            // Codex): `kernel/telemetry/contextServed.ts`'s own `computeContextServed` comment
+            // ("Defaulting an unset invocationPath to 'manual-orient' conflated unattributed calls
+            // [base/workspace orients] with REAL manual `pb orient --task` rows")
+            // is an established contract this call must respect — a bare `pb orient` (no task) stays
+            // unattributed, exactly like it was before this slice. Only a task-shaped orient — the
+            // 'manual-orient' shape this constant actually names — stamps it.
+            const startupSignals = collectCliStartupSignals();
+            if (Object.keys(startupSignals).length > 0)
+                callArgs.startupSignals = startupSignals;
+            if (options.task)
+                callArgs.invocationPath = 'manual-orient';
+            // Surface forwards tier by key omission; the kernel applies the DEC-2124 default
+            // (standard) via resolveEffectiveTier when tier is unset.
+            if (options.full)
+                callArgs.tier = 'full';
+            // TEN-2449 + WP-479 review fix (Codex): declare the render mode EXPLICITLY as a tri-state so
+            // the server selects the rendered set once (and instruments the right coverage row). Rendering
+            // is per-invocation, which is why the caller — not a source header — is the one that can say
+            // this. The server must never INFER json from "non-brief": that mislabels this interactive
+            // pretty path as agent json traffic. Precedence: json mode (`--json` / `PB_JSON=1` — piping
+            // alone does NOT switch modes, WP-744 / 1e-B — where `-b --json` prints the FULL view) →
+            // 'json'; `-b` on a TTY → 'brief'; else the interactive human view → 'pretty' (deliberately
+            // uninstrumented).
+            if (isJsonMode())
+                callArgs.renderMode = 'json';
+            else if (options.brief)
+                callArgs.renderMode = 'brief';
+            else
+                callArgs.renderMode = 'pretty';
+            // WP-479 E3 stage 2 (TEN-2654): thread the EXPLICIT local session marker, when one exists,
+            // so the gateway can stamp the M1 emit rows with a real per-conversation sessionId/
+            // conversationId instead of leaving them null. `readSession()` returns null when no
+            // marker is active (no session started, or a legacy/foreign conversation) — feature-detect,
+            // never required: a bare `pb orient` with no active session still works, just unstamped.
+            const activeSession = readSession();
+            if (activeSession?.sessionId)
+                callArgs.sessionId = activeSession.sessionId;
+            if (activeSession?.conversationId)
+                callArgs.conversationId = activeSession.conversationId;
+            // WP-488 Slice 3 (FEAT-1377) — DEVIATION, documented (same root cause as the accept-time
+            // detector call entryAccept.ts made until TASK-1040 deleted it): deriving this route's return type from
+            // kernel-client (`GatewayRouteReturnByName<'chain.getOrientView'>`, or a direct
+            // type-only import of `convex/agentKnowledge/orientView.ts`'s `getOrientView`) fails
+            // packages/cli's `rootDir: "src"` + `moduleResolution: "NodeNext"` — verified via the
+            // identical failure mode that deleted call reproduced. Left as the
+            // pre-existing hand-typed `OrientViewFromApi` generic; that interface is also
+            // consumed by codex-prep.ts / tests, so replacing its DEFINITION with
+            // the derived type (rather than just this one call site) was independently out of
+            // scope for a "no behavior change" slice regardless of the tsconfig issue.
+            const raw = await kernelCall('chain.getOrientView', Object.keys(callArgs).length > 0 ? callArgs : {});
+            // An orient read and the session lifecycle transition are separate server operations.
+            // MCP already completes both; the CLI previously only forwarded the session id for
+            // attribution, leaving the session permanently unoriented and making every server-gated
+            // follow-up reject the normal `session start → orient → write` sequence. Complete the
+            // transition only when a local session exists; sessionless orient remains a read-only path.
+            // A session is oriented when the agent asked a task-shaped question, whether or not the Chain
+            // had anything to say (TASK-534, WP-791, TEN-4261; DEC-1147). A bare `pb orient` / `pb orient -b`
+            // stays a read; thin grounding is still disclosed by the formatter's grounding-status lines.
+            const taskAsked = raw.taskMeaningful === true && !raw.degradedPreloads?.some((d) => d === 'gather' || d === 'governanceLoadRejected');
+            let sessionOriented = false;
+            if (activeSession?.sessionId && taskAsked) {
+                try {
+                    await kernelCall('agent.markOriented', { sessionId: activeSession.sessionId });
+                    sessionOriented = true;
+                }
+                catch (error) {
+                    const stale = staleSessionMarker(error);
+                    if (!stale)
+                        throw error;
+                    // The read already succeeded; return the sessionless view. An ended session leaves a closed
+                    // marker, so the next `pb session start` resumes linked to it; a session the server never had leaves none.
+                    // Re-read first: another command may have replaced the marker while this call ran.
+                    if (stale === 'ended') {
+                        if (readSession()?.sessionId === activeSession.sessionId)
+                            clearSession(activeSession.conversationId);
+                    }
+                    else
+                        discardSession(activeSession.conversationId);
+                }
+            }
             // Normalize before output in any mode — ensures JSON keys are stable
             // for agent consumers (optional sections become empty arrays, not absent).
-            return normalizeView(raw);
+            const view = { ...normalizeView(raw), sessionOriented };
+            capturedView = view;
+            // BET-β S3b parity with MCP: prefer the tier-budget signal (_budget.truncated),
+            // fall back to the legacy input-scan flag (_truncated). Summary-tier section
+            // dropping is reported via _budget.truncated only, so reading _truncated alone
+            // recorded lastOrientTruncated:false on the main path this change introduces.
+            capturedTruncated = raw._budget?.truncated ?? raw._truncated === true;
+            // WP-480 S3: capture the server's resolution off the payload.
+            capturedResolvedTier = raw.resolvedTier;
+            capturedTaskMeaningful = raw.taskMeaningful;
+            return view;
         },
         formatPretty: (view) => {
-            return options.brief ? formatOrientBrief(view) : formatOrient(view);
+            return options.brief ? formatOrientBrief(view, vocabCtx) : formatOrient(view, vocabCtx);
         },
     });
+    // WP-376 α.3: fire-and-forget byte report. Match what the user actually saw —
+    // JSON-stringified data for piped/JSON mode, formatted text for TTY.
+    if (capturedView != null) {
+        try {
+            let rendered;
+            if (isJsonMode()) {
+                rendered = JSON.stringify(stripConvexInternals(capturedView));
+            }
+            else {
+                rendered = options.brief ? formatOrientBrief(capturedView, vocabCtx) : formatOrient(capturedView, vocabCtx);
+            }
+            const bytes = Buffer.byteLength(rendered, 'utf8');
+            // WP-480 S3 (FEAT-1360): consume the SERVED resolution (the payload now
+            // carries `resolvedTier` + `taskMeaningful`; getOrientView is the payload
+            // owner). Old-deploy fallback, null-guarded like retrievalMiss: explicit
+            // --full is still client-known input (not a mirrored rule); else
+            // 'standard' / false — honestly degraded, never re-derived locally.
+            const resolvedTier = capturedResolvedTier ?? (options.full ? 'full' : 'standard');
+            reportOrientCliBytes(bytes, capturedTruncated, resolvedTier, capturedTaskMeaningful ?? false);
+            // Activation-telemetry context.served is no longer emitted here. It moved to the
+            // shared server-side seam (DEC-1207): the AKI gateway derives + emits it for EVERY
+            // connector that calls chain.getOrientView, so the CLI no longer carries its own copy.
+        }
+        catch {
+            // Best-effort observability — never fail the command on measurement.
+        }
+    }
 }
 //# sourceMappingURL=orient.js.map

package/dist/commands/orient.js.map

@@ -1 +1 @@
-{"version":3,"file":"orient.js","sourceRoot":"","sources":["../../src/commands/orient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAmB,MAAM,yBAAyB,CAAC;AA6D3F,SAAS,aAAa,CAAC,GAAsB;IAC3C,OAAO;QACL,GAAG,GAAG;QACN,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI;YAC5B,UAAU,EAAE,EAAE;YACd,SAAS,EAAE,EAAE;YACb,aAAa,EAAE,EAAE;SAClB;QACD,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE;QAC5B,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,IAAI,EAAE;QAC9C,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE;QAC9B,cAAc,EAAE,GAAG,CAAC,cAAc,IAAI,EAAE;QACxC,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI;YAC9B,iBAAiB,EAAE,EAAE;YACrB,iBAAiB,EAAE,EAAE;YACrB,YAAY,EAAE,EAAE;SACjB;QACD,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,EAAE;QACtC,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;KACzC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,UAA+B,EAAE;IAC/D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAChE,IAAI,CAAC,MAAM;QAAE,OAAO;IAEpB,MAAM,aAAa,CAAa;QAC9B,EAAE,EAAE,KAAK,IAAI,EAAE;YACb,MAAM,GAAG,GAAG,MAAM,OAAO,CAAoB,qBAAqB,EAAE,EAAE,CAAC,CAAC;YACxE,qEAAqE;YACrE,2EAA2E;YAC3E,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QACD,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE;YACrB,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QACtE,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"orient.js","sourceRoot":"","sources":["../../src/commands/orient.ts"],"names":[],"mappings":"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"}

package/dist/commands/outcome.d.ts

@@ -0,0 +1,96 @@
+import { type OutcomeObjectiveView } from '../lib/outcomeObjectiveLines.js';
+/** Mirrors the door's own `kind` union (`convex/outcomes/readings.ts`). Kept as a literal list so
+ *  a bad value is refused HERE, naming the legal set, rather than as an opaque validator error. */
+declare const READING_KINDS: readonly ["measurement", "estimate", "correction"];
+type ReadingKind = (typeof READING_KINDS)[number];
+export interface OutcomeRecordOptions {
+    asOf?: string;
+    kind?: string;
+    corrects?: string;
+    byRole?: string;
+    note?: string;
+    source?: string;
+    valueText?: string;
+    json?: boolean;
+}
+export interface OutcomeListOptions {
+    limit?: string;
+    json?: boolean;
+}
+export interface ReadingRow {
+    /** Non-underscore twin of the row's `_id` (TEN-340: the CLI's JSON envelope unconditionally
+     *  strips any `_id`-keyed field via `stripConvexInternals`) — this is the field
+     *  `pb outcome record --corrects <READING-ID>` targets. Same twin `pb conflicts` (`id`) already
+     *  carries, for the same reason. */
+    readingId: string;
+    value: number;
+    valueText?: string;
+    asOf: number;
+    recordedAt: number;
+    kind: ReadingKind;
+    actorKind: string;
+    note?: string;
+    source?: string;
+    supersededByReadingId?: string;
+}
+interface ListReadingsResult {
+    entryDocId: string;
+    pageExhausted: boolean;
+    readings: ReadingRow[];
+}
+export declare function runOutcomeRecord(entryId: string, value: string, options: OutcomeRecordOptions): Promise<void>;
+export declare function formatReadingsList(entryId: string, result: ListReadingsResult | null): string;
+export declare function runOutcomeList(entryId: string, options: OutcomeListOptions): Promise<void>;
+interface OutcomeShowResult extends OutcomeObjectiveView {
+    entryId: string;
+    name: string;
+    readyToCloseInstruction: string | null;
+    outcome: {
+        current?: {
+            value: number;
+            asOf: number;
+        };
+        currentResolution: string;
+        hasNoReadings: boolean;
+        direction: string;
+        progressPct?: number;
+        pacePct?: number;
+        nextDueAt?: number;
+        state: string;
+        overdueByMs?: number;
+        completion: string;
+        completionProvenance: string;
+        readyToClose: 'achieved' | 'missed' | null;
+        ownerRole: {
+            id: string;
+            name: string | null;
+        } | null;
+        reporterRole: {
+            id: string;
+            name: string | null;
+        } | null;
+        readingCount: number;
+        unit: string | null;
+        /** Absent from a server older than DEC-2488's state word. */
+        keyResultState?: {
+            key: string;
+            word: string;
+            line: string;
+        };
+    };
+}
+/**
+ * Pretty rendering for `pb outcome show`. Exported for the same reason `formatReadingsList` is:
+ * the honesty rules here are assertable claims, not styling.
+ *
+ * Two of them are load-bearing. **A blank is never printed as a zero** — `progressPct` is
+ * `undefined` for a never-measured key result and `—` says that, where `0%` would read as a
+ * measurement. And **the recorded completion is never called "confirmed" or "verified"** — it
+ * reports what was recorded and where that came from, because nothing in this run verifies a
+ * close, and a surface that implies otherwise is the failure the whole provenance field exists to
+ * prevent.
+ */
+export declare function formatOutcomeShow(result: OutcomeShowResult | null): string;
+export declare function runOutcomeShow(entryId: string): Promise<void>;
+export {};
+//# sourceMappingURL=outcome.d.ts.map

package/dist/commands/outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.d.ts","sourceRoot":"","sources":["../../src/commands/outcome.ts"],"names":[],"mappings":"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"}

package/dist/commands/outcome.js

@@ -0,0 +1,194 @@
+import { getConfigOrGuide } from '../lib/config.js';
+import { kernelCall, kernelCallWithSession } from '../lib/client.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
+import { runCliCommand } from '../lib/runner.js';
+import { sanitizeSingleLineField } from '../lib/strip.js';
+import { formatOutcomeObjectiveLines } from '../lib/outcomeObjectiveLines.js';
+/** Mirrors the door's own `kind` union (`convex/outcomes/readings.ts`). Kept as a literal list so
+ *  a bad value is refused HERE, naming the legal set, rather than as an opaque validator error. */
+const READING_KINDS = ['measurement', 'estimate', 'correction'];
+const validation = (message, guidance) => new CLIError(message, { code: ErrorCode.VALIDATION_FAILED, category: 'validation', guidance });
+/** argv is strings; the door wants a number. `Number('')` is 0 and `Number(' ')` is 0, so the
+ *  blank cases are rejected explicitly rather than silently recorded as a reading of zero — which
+ *  would be a wrong MEASUREMENT, the one thing this table exists to get right. */
+function requireNumber(raw, flag) {
+    const trimmed = raw.trim();
+    const parsed = Number(trimmed);
+    if (trimmed === '' || !Number.isFinite(parsed)) {
+        throw validation(`${flag} must be a number (got "${raw}").`, 
+        // Placeholder, not a concrete id: a real-looking entry id in a user-facing string is a
+        // Chain-id leak (the pre-commit guard refuses it) and reads as a live reference.
+        `Example: pb outcome record <ENTRY-ID> 62${flag === '--limit' ? '' : ' --note "from the weekly dashboard"'}`);
+    }
+    return parsed;
+}
+export async function runOutcomeRecord(entryId, value, options) {
+    // Refuse everything refusable BEFORE the network call, so a malformed invocation costs no
+    // round trip and reports in the caller's own vocabulary rather than the validator's.
+    const numericValue = requireNumber(value, 'value');
+    if (options.kind !== undefined && !READING_KINDS.includes(options.kind)) {
+        throw validation(`--kind must be one of ${READING_KINDS.join(', ')} (got "${options.kind}").`, 'Use --kind estimate for a figure that is not directly measured, or --kind correction with --corrects to replace an earlier reading.');
+    }
+    // Both directions: the door refuses each, and a CLI that guards only one still sends a
+    // request it already knows will fail.
+    if (options.corrects !== undefined && options.kind !== 'correction') {
+        throw validation('--corrects is only meaningful with --kind correction.', 'Add --kind correction, or drop --corrects to record an ordinary reading.');
+    }
+    if (options.kind === 'correction' && options.corrects === undefined) {
+        throw validation('--kind correction requires --corrects <READING-ID>.', 'A correction must name the reading it replaces — find it with `pb outcome list <ENTRY-ID>`.');
+    }
+    let asOf;
+    if (options.asOf !== undefined) {
+        const parsed = Date.parse(options.asOf);
+        if (Number.isNaN(parsed)) {
+            throw validation(`--as-of must be a parseable date (got "${options.asOf}").`, 'Example: --as-of 2026-03-01. Back-dating is legitimate — a backfill shows up as asOf earlier than recordedAt.');
+        }
+        asOf = parsed;
+    }
+    await getConfigOrGuide();
+    await runCliCommand({
+        // Session-attributed on purpose: a reading's provenance is the point, and the plain caller
+        // would drop the session the reading is attributed to.
+        // Every optional is spread conditionally — a key present-but-undefined is not the same as
+        // absent to the validator, and the door's own defaults must win when the caller is silent.
+        fn: () => kernelCallWithSession('outcomes.recordReading', {
+            entryId,
+            value: numericValue,
+            ...(asOf !== undefined ? { asOf } : {}),
+            ...(options.kind ? { kind: options.kind } : {}),
+            ...(options.corrects ? { correctsReadingId: options.corrects } : {}),
+            ...(options.byRole ? { recordedByRoleId: options.byRole } : {}),
+            ...(options.note ? { note: options.note } : {}),
+            ...(options.source ? { source: options.source } : {}),
+            ...(options.valueText ? { valueText: options.valueText } : {}),
+        }),
+        formatPretty: (value_) => {
+            const receipt = value_;
+            const lines = [
+                // Same sanitiser, same reason — this line is echoed straight to the terminal.
+                `Recorded ${numericValue}${options.valueText ? ` ("${sanitizeSingleLineField(options.valueText)}")` : ''} on ${sanitizeSingleLineField(entryId)}.`,
+                // The actor is DERIVED server-side from the credential — printed here so the caller
+                // sees what was actually attributed, never what they might have assumed.
+                `  attributed: ${receipt?.actorKind ?? 'unknown'}`,
+            ];
+            return lines.join('\n');
+        },
+    });
+}
+/**
+ * Pretty rendering for `pb outcome list`. Exported so the spec'd behaviours here are asserted
+ * directly rather than only through a live walk: superseded rows are SHOWN (the ledger is
+ * append-only and the correction chain is the audit trail) and marked with the id that replaced
+ * them, and `pageExhausted: false` is reported rather than letting a bounded page read as the
+ * whole history.
+ *
+ * **Every value that did not originate in this file is sanitised** (PR #840 security review).
+ * `note` and `valueText` are free text written by ANY connector that can call
+ * `outcomes.recordReading` — agents included — and this rendering is the operator's AUDIT VIEW.
+ * An embedded newline would inject extra, unprefixed lines that look exactly like additional
+ * readings: forged evidence in the one surface someone would use to check evidence. `\r` can
+ * overwrite the line that was already drawn, and CSI/OSC sequences can retitle or clear the
+ * operator's terminal. `sanitizeSingleLineField` (`lib/strip.js`) is the package's shared,
+ * single-line-safe sanitiser — the same one `shape`, `conflicts`, `feedback`, `direction` and
+ * `questions` use — and its own docblock exists for precisely this case, because
+ * `stripControlChars` deliberately keeps `\n`. Not hand-rolled here on purpose.
+ *
+ * `entryId` is echoed from argv rather than stored, so it is self-inflicted — sanitised anyway,
+ * since it costs nothing and a pasted command is a real way to reach it. The remaining
+ * interpolations need no sanitising and it would obscure the reasoning to add it: `kind` is a
+ * Convex union literal the validator constrains, `readingId` and
+ * `supersededByReadingId` are Convex document ids, `value` is a number, and `when` is derived
+ * from a number through `toISOString`.
+ */
+/** PR #872 review round 3 (Codex P2): mirrors `packages/mcp-server/src/tools/outcome.ts`'s
+ *  `safeDateSlice` — a reading written through the existing API route is validated only with
+ *  `v.number()`, so a finite-but-Date-invalid `asOf`/`nextDueAt` (e.g. `1e100`) can be persisted.
+ *  `new Date(x).toISOString()` throws `RangeError` for such a value, which would otherwise take
+ *  down the whole `pb outcome list`/`show` command over one malformed legacy row. Not shared code
+ *  with the MCP tool (the two packages do not cross-import, same door-parity precedent every
+ *  other CLI/MCP formatter pair in this codebase follows) — content-equal by construction. */
+function safeDateSlice(ms) {
+    const d = new Date(ms);
+    return Number.isNaN(d.getTime()) ? 'invalid-date' : d.toISOString().slice(0, 10);
+}
+export function formatReadingsList(entryId, result) {
+    const safeEntryId = sanitizeSingleLineField(entryId);
+    const rows = result?.readings ?? [];
+    if (rows.length === 0)
+        return `No readings recorded on ${safeEntryId} yet.`;
+    const lines = rows.map((row) => {
+        const when = safeDateSlice(row.asOf);
+        const superseded = row.supersededByReadingId ? `  <- superseded by ${row.supersededByReadingId}` : '';
+        const text = row.valueText ? ` ("${sanitizeSingleLineField(row.valueText)}")` : '';
+        const note = row.note ? `  - ${sanitizeSingleLineField(row.note)}` : '';
+        return `  ${when}  ${String(row.value).padStart(8)}${text}  [${row.kind}]  ${row.readingId}${note}${superseded}`;
+    });
+    const tail = result?.pageExhausted === false ? '\n  (older readings not loaded - raise --limit)' : '';
+    return `${rows.length} reading(s) on ${safeEntryId}, newest first:\n${lines.join('\n')}${tail}`;
+}
+export async function runOutcomeList(entryId, options) {
+    const limit = options.limit !== undefined ? requireNumber(options.limit, '--limit') : undefined;
+    await getConfigOrGuide();
+    await runCliCommand({
+        // A read: no session required. Demanding one would break `pb outcome list` for a caller
+        // holding a valid key who simply has not started a session.
+        fn: () => kernelCall('outcomes.listReadings', {
+            entryId,
+            ...(limit !== undefined ? { limit } : {}),
+        }),
+        formatPretty: (value_) => formatReadingsList(entryId, value_),
+    });
+}
+const pct = (v, unit = '%') => (v === undefined ? '—' : `${Math.round(v * 10) / 10}${unit}`);
+/** `role.name` is an `entries.name` resolved server-side, so it is stored content written by any
+ *  connector that can update entries — agents included — and reaches the operator's terminal
+ *  through this line. Same sink class as `note`/`valueText`, and it must be sanitised for the same
+ *  reason: an embedded newline injects an unprefixed line into the audit view. */
+const roleLabel = (role) => role === null ? 'not set' : role.name === null ? 'a role that no longer exists' : sanitizeSingleLineField(role.name);
+/**
+ * Pretty rendering for `pb outcome show`. Exported for the same reason `formatReadingsList` is:
+ * the honesty rules here are assertable claims, not styling.
+ *
+ * Two of them are load-bearing. **A blank is never printed as a zero** — `progressPct` is
+ * `undefined` for a never-measured key result and `—` says that, where `0%` would read as a
+ * measurement. And **the recorded completion is never called "confirmed" or "verified"** — it
+ * reports what was recorded and where that came from, because nothing in this run verifies a
+ * close, and a surface that implies otherwise is the failure the whole provenance field exists to
+ * prevent.
+ */
+export function formatOutcomeShow(result) {
+    if (!result)
+        return 'No outcome found.';
+    const o = result.outcome;
+    const unit = o.unit ? ` ${sanitizeSingleLineField(o.unit)}` : '';
+    const lines = [
+        // N2 (TASK-367): the metric line is retired — the entry's own name (above) already states
+        // what is measured.
+        `${sanitizeSingleLineField(result.entryId)} — ${sanitizeSingleLineField(result.name)}`,
+        // The key result's own word and line, decided by the kernel (DEC-2488, RULE-664).
+        ...(o.keyResultState ? [`  standing    ${[o.keyResultState.word, o.keyResultState.line].filter(Boolean).map(sanitizeSingleLineField).join(' · ')}`] : []),
+        // The honest blank: undefined is "never measured", which is not zero.
+        `  current     ${o.current ? `${o.current.value}${unit}` : '—'}   (${o.readingCount} reading(s))`,
+        `  progress    ${pct(o.progressPct)}   direction ${o.direction}`,
+        `  pace        ${pct(o.pacePct)}   ${o.pacePct === undefined ? '(no cycle end set)' : o.pacePct >= 0 ? '(ahead of pace)' : '(behind pace)'}`,
+        `  state       ${o.state}${o.overdueByMs ? ` (by ${Math.floor(o.overdueByMs / 86400000)}d)` : ''}`,
+        `  next due    ${o.nextDueAt ? safeDateSlice(o.nextDueAt) : 'no cadence set'}`,
+        `  owner       ${roleLabel(o.ownerRole)}`,
+        `  reporter    ${roleLabel(o.reporterRole)}`,
+        // Recorded, with its provenance. Never "confirmed", never "verified".
+        `  completion  recorded as ${o.completion} (source: ${o.completionProvenance})`,
+        ...formatOutcomeObjectiveLines(result, sanitizeSingleLineField), // TASK-817: its objective and sibling key results
+    ];
+    if (result.readyToCloseInstruction) {
+        lines.push('', `  ${result.readyToCloseInstruction}`);
+    }
+    return lines.join('\n');
+}
+export async function runOutcomeShow(entryId) {
+    await getConfigOrGuide();
+    await runCliCommand({
+        fn: () => kernelCall('outcomes.showOutcome', { entryId }),
+        formatPretty: (value_) => formatOutcomeShow(value_),
+    });
+}
+//# sourceMappingURL=outcome.js.map

package/dist/commands/outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.js","sourceRoot":"","sources":["../../src/commands/outcome.ts"],"names":[],"mappings":"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"}

package/dist/commands/outcome.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=outcome.test.d.ts.map

package/dist/commands/outcome.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.test.d.ts","sourceRoot":"","sources":["../../src/commands/outcome.test.ts"],"names":[],"mappings":""}