@north-light/crouter 0.3.170 → 0.3.172

package/dist/clients/web/push-engine.js

@@ -1,111 +1,56 @@
-// push-engine.ts — the server-side web-push DIFF ENGINE (design D8/push
-// contract). SSE (`events.ts`) is a TRIGGER ONLY (`{kind, ts}`, never data);
-// this module is the one authority that re-reads canvas + decks on that
-// trigger, diffs against persisted last-seen state, and decides what (if
-// anything) to push. It never invents a second attention signal — decks/canvas
-// stay the truth.
+// push-engine.ts — the server-side web-push diff engine. SSE (`events.ts`) is
+// a trigger only (`{kind, ts}`, never data); this module re-reads the canvas,
+// diffs persisted last-seen state, and emits done-transition notifications.
 //
-// Two invalidation kinds drive two independent diff passes:
-//   - 'nodes'  -> re-read the canvas roster, detect a conversation ROOT
-//                 (parent === null) crossing into a done|dead|canceled status
-//                 from a non-done status, emit one 'done' push per transition.
-//   - 'inbox'  -> re-read pending asks (deck provenance), detect an ask id that
-//                 is present now but was not known-notified before, emit one
-//                 'needs-you' push per NEW ask, coalesced per conversation.
-//
-// On server start, `seed()` records the current state and sends NOTHING — a
-// restart is not an attention event.
-//
-// Last-seen state is only advanced past a suppressed (rate-capped) item when
-// that item was not actually the reason for suppression; a rate-capped
-// transition/ask is deliberately left out of the persisted state so the NEXT
-// invalidation retries it rather than silently losing it forever.
+// A `nodes` invalidation detects a conversation root (`parent === null`) crossing
+// from a nonterminal state into done, dead, or canceled. On server start,
+// `seed()` records the current state and sends nothing.
 import { isAllowedPushEndpoint } from './push-registry.js';
 const DONE_STATUSES = new Set(['done', 'dead', 'canceled']);
-/** Minimum interval between pushes for the same conversation root — coalesces
- *  a burst of distinct events (several new asks, or an ask+done in close
- *  succession) into at most one send per window, never a storm. */
 const DEFAULT_RATE_WINDOW_MS = 30_000;
 export class PushDiffEngine {
     registry;
     lastSeen;
     readCanvasNodes;
-    readPendingAsks;
     sendPush;
     isTargetScope;
     now;
     rateWindowMs;
-    /** Drain-queue state: only one diff pass mutates last-seen at a time. An
-     *  invalidation arriving mid-pass sets its pending flag and is reprocessed
-     *  when the current pass finishes — no two passes race the same snapshot. */
     draining = false;
     pendingNodes = false;
-    pendingInbox = false;
-    /** Per-conversation rate-cap clock. Deliberately in-memory/process-lifetime
-     *  only (not persisted) — a restart re-seeding silently is already the
-     *  no-storm guarantee; the rate cap only smooths a live process's bursts. */
     lastPushAt = new Map();
-    /** Per-(conversationId+kind) set of subscription ids already delivered for
-     *  the CURRENT still-pending notification. A transient failure on one
-     *  subscription must never cause a later retry to re-send to subscriptions
-     *  that already got `'sent'` — this is exactly what remembers them across
-     *  passes. Cleared the moment the event fully succeeds (or has no eligible
-     *  subscriber left), since a later, distinct event reusing the same key
-     *  must start fresh. */
     deliveredForKey = new Map();
     constructor(deps) {
         this.registry = deps.registry;
         this.lastSeen = deps.lastSeen;
         this.readCanvasNodes = deps.readCanvasNodes;
-        this.readPendingAsks = deps.readPendingAsks;
         this.sendPush = deps.sendPush;
         this.isTargetScope = deps.isTargetScope;
         this.now = deps.now ?? (() => Date.now());
         this.rateWindowMs = deps.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;
     }
-    /** Seed last-seen from a fresh canvas+deck read and send nothing. Call once
-     *  on server start — a restart must never be an attention event. */
+    /** Record the current canvas state without sending notifications. */
     async seed() {
-        const [nodes, asks] = await Promise.all([this.readCanvasNodes(), this.readPendingAsks()]);
+        const nodes = await this.readCanvasNodes();
         const roots = {};
-        for (const n of nodes) {
-            if (n.parent !== null)
-                continue;
-            roots[n.node_id] = { status: n.status, attention_count: n.attention_count };
+        for (const node of nodes) {
+            if (node.parent === null)
+                roots[node.node_id] = { status: node.status, attention_count: node.attention_count };
         }
-        const askState = {};
-        for (const a of asks)
-            askState[a.id] = { present: true };
-        this.lastSeen.replace({ schemaVersion: 1, updatedAt: this.now(), roots, asks: askState });
+        this.lastSeen.replace({ schemaVersion: 1, updatedAt: this.now(), roots });
     }
-    /** 'nodes' invalidation: re-read the canvas roster, emit a 'done' push for
-     *  every conversation root that just crossed into a done|dead|canceled
-     *  status from a non-done status. */
     async onNodesInvalidation() {
         this.pendingNodes = true;
         await this.drain();
     }
-    async onInboxInvalidation() {
-        this.pendingInbox = true;
-        await this.drain();
-    }
-    /** Serialize passes: if a pass is already running, just set the pending flag
-     *  and return — the running drain loop will pick it up. Otherwise run pending
-     *  passes until none remain. */
     async drain() {
         if (this.draining)
             return;
         this.draining = true;
         try {
-            while (this.pendingNodes || this.pendingInbox) {
-                if (this.pendingNodes) {
-                    this.pendingNodes = false;
-                    await this.runNodesPass();
-                }
-                if (this.pendingInbox) {
-                    this.pendingInbox = false;
-                    await this.runInboxPass();
-                }
+            while (this.pendingNodes) {
+                this.pendingNodes = false;
+                await this.runNodesPass();
             }
         }
         finally {
@@ -114,93 +59,30 @@ export class PushDiffEngine {
     }
     async runNodesPass() {
         const nodes = await this.readCanvasNodes();
-        const prev = this.lastSeen.snapshot();
-        const nextRoots = {};
-        for (const n of nodes) {
-            if (n.parent !== null)
+        const previous = this.lastSeen.snapshot();
+        const roots = {};
+        for (const node of nodes) {
+            if (node.parent !== null)
                 continue;
-            const before = prev.roots[n.node_id];
-            const isTransition = before !== undefined && !DONE_STATUSES.has(before.status) && DONE_STATUSES.has(n.status);
-            if (!isTransition) {
-                nextRoots[n.node_id] = { status: n.status, attention_count: n.attention_count };
+            const before = previous.roots[node.node_id];
+            const transitioned = before !== undefined && !DONE_STATUSES.has(before.status) && DONE_STATUSES.has(node.status);
+            if (!transitioned) {
+                roots[node.node_id] = { status: node.status, attention_count: node.attention_count };
                 continue;
             }
-            const sent = await this.emit(n.node_id, {
-                conversationId: n.node_id,
+            const sent = await this.emit(node.node_id, {
+                conversationId: node.node_id,
                 kind: 'done',
                 title: 'Conversation finished',
-                snippet: `This conversation is now ${n.status}.`,
-            });
-            // Rate-capped: keep the PRE-transition state so the next 'nodes'
-            // invalidation still sees a non-done -> done edge and retries.
-            nextRoots[n.node_id] = sent ? { status: n.status, attention_count: n.attention_count } : before;
-        }
-        this.lastSeen.replace({ schemaVersion: prev.schemaVersion, updatedAt: this.now(), roots: nextRoots, asks: prev.asks });
-    }
-    /** 'inbox' invalidation: re-read pending asks, emit exactly one 'needs-you'
-     *  push per conversation for its NEW (not-yet-notified) asks, coalesced. An
-     *  ask no longer present (resolved/missing) is simply dropped, never
-     *  notified. */
-    async runInboxPass() {
-        const asks = await this.readPendingAsks();
-        const prev = this.lastSeen.snapshot();
-        const nextAsks = {};
-        const newByConversation = new Map();
-        for (const ask of asks) {
-            if (prev.asks[ask.id]?.present === true) {
-                // Already known + already notified at some point — keep tracked, never
-                // re-notify the same unresolved ask.
-                nextAsks[ask.id] = { present: true };
-                continue;
-            }
-            const list = newByConversation.get(ask.conversationId) ?? [];
-            list.push(ask);
-            newByConversation.set(ask.conversationId, list);
-        }
-        for (const [conversationId, list] of newByConversation) {
-            const first = list[0];
-            const extra = list.length - 1;
-            const sent = await this.emit(conversationId, {
-                conversationId,
-                kind: 'needs-you',
-                askId: first.jobId,
-                title: first.conversationTitle,
-                snippet: extra > 0 ? `${first.title} (+${extra} more)` : first.title,
+                snippet: `This conversation is now ${node.status}.`,
             });
-            if (sent) {
-                for (const ask of list)
-                    nextAsks[ask.id] = { present: true };
-            }
-            // Rate-capped: leave these ask ids OUT of nextAsks so the next 'inbox'
-            // invalidation still sees them as new and retries once the window clears.
+            roots[node.node_id] = sent ? { status: node.status, attention_count: node.attention_count } : before;
         }
-        this.lastSeen.replace({ schemaVersion: prev.schemaVersion, updatedAt: this.now(), roots: prev.roots, asks: nextAsks });
+        this.lastSeen.replace({ schemaVersion: previous.schemaVersion, updatedAt: this.now(), roots });
     }
-    /** Send one push per ELIGIBLE subscription — one whose authScope is on the
-     *  watched boundary (`isTargetScope`) AND that opted in for this payload kind.
-     *  Respects the per-conversation rate cap; prunes any subscription the push
-     *  service reports gone (404/410) or whose endpoint fails the push-service
-     *  allowlist re-check. Tracks per-subscription delivery for this notification
-     *  (`deliveredForKey`) so a retry after a transient failure on one
-     *  subscription never re-sends to a subscription that already got `'sent'`.
-     *  Returns true iff last-seen may advance: false when suppressed by the rate
-     *  cap OR when a transient send error means the item must be retried next
-     *  pass. A no-eligible pass returns true (nothing to retry). */
     async emit(conversationId, payload) {
-        // Eligible = in the watched auth scope AND opted-in for this payload kind.
-        const eligible = this.registry.snapshot().filter((r) => {
-            if (!this.isTargetScope(r.authScope))
-                return false;
-            if (payload.kind === 'done' && !r.prefs.doneNotifications)
-                return false;
-            return true;
-        });
-        // Keyed by conversation + kind: a later, distinct event reusing this key
-        // (once cleared below) must start with a fresh delivered set.
+        const eligible = this.registry.snapshot().filter((record) => this.isTargetScope(record.authScope) && record.prefs.doneNotifications);
         const key = `${conversationId}:${payload.kind}`;
-        // No eligible subscriber -> the event is fully handled (nothing to retry);
-        // advance last-seen. Checked BEFORE the rate cap so a no-eligible pass never
-        // stalls the state on a phantom retry.
         if (eligible.length === 0) {
             this.deliveredForKey.delete(key);
             return true;
@@ -208,22 +90,14 @@ export class PushDiffEngine {
         const now = this.now();
         const last = this.lastPushAt.get(conversationId) ?? 0;
         if (now - last < this.rateWindowMs)
-            return false; // rate-capped -> retry next pass
+            return false;
         this.lastPushAt.set(conversationId, now);
         const delivered = this.deliveredForKey.get(key) ?? new Set();
         let transientFailure = false;
         for (const record of eligible) {
-            // Already delivered to this subscription for this event on an earlier
-            // pass — never re-send it (this is the fix for duplicate pushes on
-            // transient-failure retry: only the subscriptions that actually failed
-            // are retried).
             if (delivered.has(record.id))
                 continue;
             if (!isAllowedPushEndpoint(record.endpoint)) {
-                // Defense in depth: re-check the push-service allowlist immediately
-                // before every outbound connect (no DNS/host TOCTOU), even though
-                // normalizeEndpoint already enforced it at subscribe time. A record
-                // that fails this can never be sent to safely — prune it.
                 this.registry.deleteById(record.id);
                 continue;
             }
@@ -241,11 +115,6 @@ export class PushDiffEngine {
             else
                 transientFailure = true;
         }
-        // A transient send failure must NOT advance last-seen — retry next pass
-        // (design: "update last-seen only after a successful diff pass"), and the
-        // subscriptions already delivered above must stay remembered so that retry
-        // only reaches the ones that failed. A pruned 'gone'/disallowed record is
-        // not a failure: nothing left to retry for it.
         if (transientFailure) {
             this.deliveredForKey.set(key, delivered);
             return false;

package/dist/clients/web/push-registry.d.ts

@@ -22,14 +22,10 @@ export interface PushLastSeenRootState {
     status: NodeLifeStatus;
     attention_count: number;
 }
-export interface PushLastSeenAskState {
-    present: boolean;
-}
 export interface PushLastSeenFile {
     schemaVersion: number;
     updatedAt: number;
     roots: Record<string, PushLastSeenRootState>;
-    asks: Record<string, PushLastSeenAskState>;
 }
 /** A locally generated VAPID keypair, persisted so the same identity signs
  *  every outbound push across restarts. The private key never leaves this

package/dist/clients/web/push-registry.js

@@ -222,16 +222,12 @@ function isValidRegistryFile(value) {
 function isValidLastSeenFile(value) {
     if (!isRecord(value) || value.schemaVersion !== SCHEMA_VERSION || !isNumber(value.updatedAt))
         return false;
-    if (!isRecord(value.roots) || !isRecord(value.asks))
+    if (!isRecord(value.roots))
         return false;
     for (const record of Object.values(value.roots)) {
         if (!isRecord(record) || !isString(record.status) || !isNumber(record.attention_count))
             return false;
     }
-    for (const record of Object.values(value.asks)) {
-        if (!isRecord(record) || typeof record.present !== 'boolean')
-            return false;
-    }
     return true;
 }
 function loadRegistryFile(path) {
@@ -245,7 +241,7 @@ function loadRegistryFile(path) {
 }
 function loadLastSeenFile(path) {
     if (!existsSync(path)) {
-        return { schemaVersion: SCHEMA_VERSION, updatedAt: 0, roots: {}, asks: {} };
+        return { schemaVersion: SCHEMA_VERSION, updatedAt: 0, roots: {} };
     }
     const parsed = readJsonFile(path);
     if (!isValidLastSeenFile(parsed)) {
@@ -362,7 +358,6 @@ export class PushLastSeenStore {
             schemaVersion: this.state.schemaVersion,
             updatedAt: this.state.updatedAt,
             roots: { ...this.state.roots },
-            asks: { ...this.state.asks },
         };
     }
     replace(next) {

package/dist/clients/web/server.js

@@ -42,7 +42,6 @@ import { apiSocketPath, isSafeNodeId } from '../../core/canvas/paths.js';
 import { emitEvent } from '../../core/events/emit.js';
 import { bindWebEventSource } from '../../core/events/source.js';
 import { canvasRosterLeaf } from '../../commands/canvas-roster.js';
-import { humanList } from '../../commands/human/queue.js';
 import { startEventHub } from './events.js';
 import { createDevServer } from './dev-server.js';
 import { PushLastSeenStore, PushRegistryStore, PushRequestError, loadOrCreateVapidKeypair, parsePushDeleteBody, parsePushSubscriptionBody, pushBodyMaxBytes, } from './push-registry.js';
@@ -399,41 +398,13 @@ export async function startWebServer(opts) {
         targetScopes.add('local');
     // §push — the server-side web-push registry + diff engine (design D8). One
     // persisted, auth-scoped subscription registry; one locally-generated VAPID
-    // identity signing every send; one diff engine that re-reads canvas+decks on
-    // the SAME SSE invalidations the browser clients get (via eventHub.subscribe,
-    // no HTTP self-loop) and pushes 'done'/'needs-you' notifications.
+    // identity signing every send; one diff engine that re-reads the canvas on
+    // node invalidations received through eventHub.subscribe (no HTTP self-loop)
+    // and pushes done-transition notifications.
     const pushRegistry = new PushRegistryStore();
     const pushLastSeen = new PushLastSeenStore();
     const vapid = loadOrCreateVapidKeypair();
     webpush.setVapidDetails(vapid.subject, vapid.publicKey, vapid.privateKey);
-    // Page through every pending human ask, keeping only entries with the deck
-    // provenance (job + conversation) the payload/dedupe logic needs.
-    const collectPendingAsks = async () => {
-        const out = [];
-        let cursor;
-        for (let page = 0; page < 50; page++) {
-            const result = (await humanList.run({
-                limit: 100,
-                ...(cursor !== undefined ? { cursor } : {}),
-            }));
-            for (const item of result.items) {
-                if (item.job_id === undefined || item.conversation_id === undefined)
-                    continue;
-                out.push({
-                    id: item.id,
-                    jobId: item.job_id,
-                    title: item.title ?? item.job_id,
-                    conversationId: item.conversation_id,
-                    conversationTitle: item.conversation_title ?? item.conversation_id,
-                    blockedSince: item.blocked_since,
-                });
-            }
-            if (result.next_cursor === null)
-                break;
-            cursor = result.next_cursor;
-        }
-        return out;
-    };
     const pushEngine = new PushDiffEngine({
         registry: pushRegistry,
         lastSeen: pushLastSeen,
@@ -445,7 +416,6 @@ export async function startWebServer(opts) {
             const snap = (await canvasRosterLeaf.run({}));
             return snap.nodes;
         },
-        readPendingAsks: collectPendingAsks,
         isTargetScope: (s) => targetScopes.has(s),
         sendPush: async (record, payload) => {
             try {
@@ -463,8 +433,6 @@ export async function startWebServer(opts) {
     const unsubscribePush = eventHub.subscribe((kind) => {
         if (kind === 'nodes')
             void pushEngine.onNodesInvalidation();
-        else if (kind === 'inbox')
-            void pushEngine.onInboxInvalidation();
     });
     // Assigned before listen() when --dev; the request handler closes over it.
     let vite;

package/dist/clients/web/web-client/shared/protocol.d.ts

@@ -191,84 +191,6 @@ export interface MessageRequest {
 export interface ReviveRequest {
     fresh?: boolean;
 }
-/**
- * The five resolution flows (design §5.2). humanloop's `InteractionKind` also
- * has `review`; the deck loader normalizes it (and any unknown/absent kind)
- * onto one of these five so a deck always renders through a known flow.
- */
-export type DeckKind = 'notify' | 'validation' | 'decision' | 'context' | 'error';
-/** One option of a decision/validation interaction (humanloop InteractionOption). */
-export interface DeckOption {
-    id: string;
-    label: string;
-    /** The option's consequence/explanation (humanloop `description`). */
-    description?: string;
-}
-/** One interaction within a deck (humanloop Interaction, normalized for the web). */
-export interface DeckInteraction {
-    id: string;
-    title: string;
-    subtitle: string;
-    /** Markdown body (bodyPath already inlined by `crtr human deck`). */
-    body?: string;
-    kind: DeckKind;
-    options: DeckOption[];
-    multiSelect: boolean;
-    allowFreetext: boolean;
-    freetextLabel?: string;
-}
-/**
- * A pending ask, ranked in the inbox list (design §5.2). Provenance carries
- * private node routing and an optional authored source label for presentation.
- */
-export interface DeckSummary {
-    /** Opaque, stable inbox-entry id (base64url of the interaction dir). */
-    id: string;
-    /** The interaction job id (basename of the interaction dir). */
-    job_id: string;
-    /** The first interaction's kind — the glyph + flow for the row. */
-    kind: DeckKind;
-    title: string;
-    subtitle: string;
-    /** ISO-8601 — when the ask started blocking (drives the wait duration + rank). */
-    blocked_since: string;
-    /** Humanloop's current claim owner, when a person/session is handling it. */
-    claim_owner?: string;
-    /** Authored display label: source sessionName, then askedBy. */
-    source_label?: string;
-    /** The conversation (spine root) this ask belongs to. */
-    conversation_id: string;
-    conversation_title: string;
-    /** The node that raised the ask. */
-    asking_node_id: string;
-    asking_node_name: string;
-    /** The asking node's cwd — sub-DAG scoping. */
-    cwd: string;
-    /** How many interactions the deck holds (a multi-question deck). */
-    interaction_count: number;
-}
-/** The full deck for a resolution flow (`crtr human deck <id> --json`). */
-export interface DeckDetail extends DeckSummary {
-    interactions: DeckInteraction[];
-}
-/** One interaction's answer (humanloop InteractionResponse). */
-export interface DeckAnswer {
-    id: string;
-    selectedOptionId?: string;
-    selectedOptionIds?: string[];
-    freetext?: string;
-    optionComments?: Record<string, string>;
-}
-/** `crtr human resolve <id> --json` body. */
-export interface ResolveDeckRequest {
-    responses: DeckAnswer[];
-}
-/** `crtr human resolve <id> --json` success. */
-export interface ResolveDeckResponse {
-    resolved: true;
-    job_id: string;
-    delivered: boolean;
-}
 /**
  * Engine state carried in `snapshot.state` — pi's OWN `get_state` payload, not a
  * mirror of it. `BrokerSnapshot['state']` is this same type, so the welcome frame
@@ -290,33 +212,3 @@ export type DialogResponseValue = {
 } | {
     cancelled: true;
 };
-/**
- * A typed content block within a view tab. Discriminated union of three
- * block kinds: inline/sourced markdown, a KPI grid, and a bar-list chart.
- */
-export type ViewBlock = {
-    kind: 'markdown';
-    source: {
-        node_id: string;
-        path: string;
-    } | {
-        inline: string;
-    };
-} | {
-    kind: 'kpis';
-    items: {
-        label: string;
-        value: string;
-        unit?: string;
-        sub?: string;
-    }[];
-} | {
-    kind: 'barlist';
-    title: string;
-    rows: {
-        label: string;
-        value: number;
-        max?: number;
-        note?: string;
-    }[];
-};

package/dist/clients/web/web-cmd.js

@@ -81,7 +81,7 @@ const webServeLeaf = defineLeaf({
                 type: 'bool',
                 required: false,
                 default: false,
-                constraint: 'Serve shell assets via a Vite dev server (middleware mode, HMR) instead of the prebuilt dist/web-client/ bundle. For contributors iterating on the shell or a builtin view. The bridge, SSE lane, and WS relay are identical in both modes.',
+                constraint: 'Serve shell assets via a Vite dev server (middleware mode, HMR) instead of the prebuilt dist/web-client/ bundle. The REST proxy, SSE lane, and WS relay are identical in both modes.',
             },
         ],
         output: [],
@@ -100,7 +100,7 @@ const webServeLeaf = defineLeaf({
         const open = input['open'] ?? false;
         const dev = input['dev'] ?? false;
         const server = await startWebServer({ port, host, token, dev });
-        const nodeUrlShape = `${server.url}/node/<id>`;
+        const nodeUrlShape = `${server.url}/nodes/<id>`;
         const browserUrl = token !== undefined ? `${server.url}?token=${encodeURIComponent(token)}` : server.url;
         process.stdout.write(`crtr surface web serving on ${server.url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
             `  open a node:  ${nodeUrlShape}\n` +

package/dist/commands/__tests__/human.test.js

@@ -10,9 +10,11 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { Readable } from 'node:stream';
-import { parseArgv } from '../../core/command.js';
+import { parseArgv, unknownPathError } from '../../core/command.js';
 import { renderLeafArgv } from '../../core/help.js';
 import { humanAsk, sourceStamp } from '../human/prompts.js';
+import { humanReviewBranch } from '../human/review.js';
+import { registerHuman } from '../human.js';
 import { coerceSingleSelectAgainst } from '../human/queue.js';
 // ---------------------------------------------------------------------------
 // Helper: write a temp JSON file and return its path.
@@ -37,32 +39,42 @@ async function withPipedStdin(body, fn) {
     }
 }
 // ---------------------------------------------------------------------------
-// human review — positional file (path) + required --subtitle + optional --output
+// human review new — positional file (path) + required --subtitle + optional --output
 // ---------------------------------------------------------------------------
-describe('human review: params', () => {
-    const params = [
-        { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Existing .md file.' },
-        { kind: 'flag', name: 'subtitle', type: 'string', required: true, constraint: 'Review request.' },
-        { kind: 'flag', name: 'output', type: 'path', required: false, constraint: 'Where to write feedback.' },
-    ];
-    test('parses file + required subtitle', async () => {
-        const result = await parseArgv(params, ['/tmp/plan.md', '--subtitle', 'Review this plan so implementation can begin safely.']);
+describe('human review command branch', () => {
+    const review = registerHuman().children.find((child) => child.name === 'review');
+    const newLeaf = humanReviewBranch.children.find((child) => child.name === 'new' && child.kind === 'leaf');
+    test('registers the canonical review branch', () => {
+        assert.equal(review, humanReviewBranch);
+        assert.deepEqual(humanReviewBranch.children.map((child) => child.name), ['new', 'comment']);
+    });
+    test('bare review names valid children rather than accepting the legacy file positional', () => {
+        const error = unknownPathError(humanReviewBranch, ['human', 'review'], '/tmp/plan.md');
+        assert.equal(error.code, 'unknown_path');
+        assert.match(error.message, /unknown subcommand: \/tmp\/plan\.md/);
+        assert.match(String(error.details?.next), /Valid children: new, comment/);
+    });
+    test('new parses file + required subtitle', async () => {
+        assert.ok(newLeaf);
+        const result = await parseArgv(newLeaf.help.params ?? [], ['/tmp/plan.md', '--subtitle', 'Review this plan so implementation can begin safely.']);
         assert.equal(result['file'], '/tmp/plan.md');
         assert.equal(result['subtitle'], 'Review this plan so implementation can begin safely.');
     });
-    test('parses file + subtitle + --output', async () => {
-        const result = await parseArgv(params, ['/tmp/plan.md', '--subtitle', 'Review this plan so implementation can begin safely.', '--output', '/tmp/fb.json']);
+    test('new parses file + subtitle + --output', async () => {
+        assert.ok(newLeaf);
+        const result = await parseArgv(newLeaf.help.params ?? [], ['/tmp/plan.md', '--subtitle', 'Review this plan so implementation can begin safely.', '--output', '/tmp/fb.json']);
         assert.equal(result['file'], '/tmp/plan.md');
         assert.equal(result['output'], '/tmp/fb.json');
     });
     // Validation is complete, never first-failure: one invocation yields ONE
     // error naming every missing required parameter, and its Next: mandates the
     // schema read rather than patching the first field.
-    test('missing file AND missing subtitle throw ONE missing_parameter naming both', async () => {
-        await assert.rejects(() => parseArgv(params, [], { leafPath: ['human', 'review'] }), (err) => {
+    test('new missing file AND subtitle throws ONE missing_parameter naming both', async () => {
+        assert.ok(newLeaf);
+        await assert.rejects(() => parseArgv(newLeaf.help.params ?? [], [], { leafPath: ['human', 'review', 'new'] }), (err) => {
             assert.match(err.message, /required parameters are missing: positional FILE, --subtitle/);
             assert.equal(err.details?.field, 'file, subtitle');
-            assert.match(err.details?.next ?? '', /Run `crtr human review -h` and read the full schema before re-issuing/);
+            assert.match(err.details?.next ?? '', /Run `crtr human review new -h` and read the full schema before re-issuing/);
             return true;
         });
     });

package/dist/commands/api-client.js

@@ -20,7 +20,7 @@ import { CrtrClient, ApiError } from '../api/index.js';
 import { apiErrorToCliError } from '../core/io.js';
 import { ensureDaemon, DAEMON_VERIFY_WINDOW_MS } from '../daemon/manage.js';
 import { readState } from '../core/config.js';
-import { resolveRemoteCanvasTarget } from '../core/view/remote-canvas-target.js';
+import { resolveRemoteCanvasTarget } from '../core/remote-canvas-target.js';
 import { RemoteCanvasSource } from '../core/canvas/remote-canvas-source.js';
 import { crtrHome } from '../core/canvas/paths.js';
 // ---------------------------------------------------------------------------
@@ -186,8 +186,8 @@ function summaryToRow(s) {
 }
 /** `NodeDetailDTO` → `NodeMeta`. Populates the durable-identity ∪ runtime fields
  *  the DTO projects; the durable LAUNCH-RECIPE facts a projection cannot carry
- *  (`launch`/`env`, `persona_ack`, `human_work_target`, `private_fork_*`,
- *  `model_override`, `passive_default`, `fork_from`, `pi_session_file`,
+ *  (`launch`/`env`, `persona_ack`, `model_override`, `passive_default`,
+ *  `fork_from`, `pi_session_file`,
  *  `cycle_pending`) are left undefined — read-only viewer/inspect consumers
  *  (Stage B-7/B-9) never read them; the daemon owns the full meta for revive. */
 function detailToMeta(d) {

package/dist/commands/canvas-browse.js

@@ -8,7 +8,7 @@
 import { defineLeaf } from '../core/command.js';
 import { runBrowse } from '../core/canvas/browse/app.js';
 import { cliClient, cliCanvasSource } from './api-client.js';
-import { resolveRemoteCanvasTarget } from '../core/view/remote-canvas-target.js';
+import { resolveRemoteCanvasTarget } from '../core/remote-canvas-target.js';
 import { RemoteEventStream } from '../core/canvas/remote-event-stream.js';
 import { readState } from '../core/config.js';
 import { getDefaultProfileId } from '../core/profiles/default-binding.js';

package/dist/commands/canvas-issue.js

@@ -1,6 +1,6 @@
 // `crtr canvas issue new` — capture a quick todo/idea/bug into a GitHub issue.
 //
-// Bound to the alt+c → i → (idea|bug) prefix chord: the menu opens a tmux
+// Bound to the alt+c → c → (idea|bug) prefix chord: the menu opens a tmux
 // display-popup that runs this leaf in the originating pane's cwd (the popup is
 // started with `-d #{pane_current_path}`). The leaf:
 //   1. reads a free-text note from the popup's TTY (type, Ctrl-D to submit),

package/dist/commands/canvas-use.js

@@ -5,7 +5,7 @@
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { updateState } from '../core/config.js';
-import { getRemoteCanvasTarget } from '../core/view/remote-canvas-target.js';
+import { getRemoteCanvasTarget } from '../core/remote-canvas-target.js';
 const SCOPE = 'user';
 export const canvasUseLeaf = defineLeaf({
     name: 'use',