@north-light/crouter 0.3.170 → 0.3.172

package/dist/commands/human/review.js

@@ -0,0 +1,298 @@
+import { randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { ticketDir } from '../../core/human/root.js';
+import { cliClient } from '../api-client.js';
+function nodeActor() {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    return nodeId === undefined || nodeId === '' ? null : nodeId;
+}
+function requireOriginNode() {
+    const nodeId = nodeActor();
+    if (nodeId !== null)
+        return nodeId;
+    throw new InputError({
+        error: 'review_origin_unavailable',
+        message: 'a review must be filed from a node with a live or resumable session',
+        field: 'CRTR_NODE_ID',
+        next: 'Run this from the node whose document context should be forked for the review.',
+    });
+}
+function requireSubtitle(value) {
+    if (typeof value === 'string' && value.trim() !== '')
+        return value.trim();
+    throw new InputError({
+        error: 'missing_parameter',
+        message: 'a non-empty subtitle is required',
+        field: 'subtitle',
+        next: 'Run `crtr human review new -h` and provide one plain-English sentence explaining the review needed and why it matters.',
+    });
+}
+function requireCommentText(value, leaf) {
+    if (typeof value === 'string' && value.trim() !== '')
+        return value;
+    throw new InputError({
+        error: 'missing_parameter',
+        message: 'non-empty comment text is required on stdin',
+        field: 'text',
+        next: `Run \`crtr human review comment ${leaf} -h\` and pipe the comment text on stdin.`,
+    });
+}
+function explicitDeliver(input, context) {
+    const supplied = context?.providedParams.has('deliver') ?? input['deliver'] !== undefined;
+    if (!supplied)
+        return undefined;
+    const deliver = input['deliver'];
+    return deliver === 'wake' || deliver === 'quiet' ? deliver : undefined;
+}
+function mutationOutput(result) {
+    const { comment } = result;
+    return {
+        comment_id: comment.comment_id,
+        status: comment.status,
+        revision: comment.revision,
+        anchor: comment.anchor,
+        author: comment.author,
+        text: comment.text,
+        changed: result.changed,
+        delivery: result.delivery ?? null,
+    };
+}
+function commentPreview(comment) {
+    return {
+        comment_id: comment.comment_id,
+        status: comment.status,
+        revision: comment.revision,
+        anchor: { line: comment.anchor.line, end_line: comment.anchor.end_line },
+        anchor_state: comment.anchor_state,
+        author: comment.author,
+        updated_by: comment.updated_by,
+        created_at: comment.created_at,
+        updated_at: comment.updated_at,
+        text_preview: comment.text.slice(0, 200),
+    };
+}
+const humanReviewNew = defineLeaf({
+    name: 'new',
+    description: 'queue a document review with a collaborating companion agent',
+    whenToUse: 'filing a live document for a person to review alongside a companion agent.',
+    help: {
+        name: 'human review new',
+        summary: 'queue a live document review and return its ticket handle immediately',
+        guide: 'The person reviews the live file in the attach viewer alongside a collaborating companion agent. Keep editing the file in place; approval is pushed back as an approval fact, and a changed document instructs the origin to re-read it.',
+        params: [
+            { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Document or source file to review. Resolved to an absolute path; the daemon validates that it is readable reviewable text.' },
+            { kind: 'flag', name: 'subtitle', type: 'string', required: true, constraint: 'One plain-English sentence stating the review needed and why it matters.' },
+            { kind: 'flag', name: 'output', type: 'path', required: false, constraint: 'Where the immutable approval result JSON is projected. Default: <dir>/feedback.json.' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Ticket bridge node id. The approval is pushed to its origin when the person submits.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding the ticket projection and default approval result.' },
+            { name: 'output', type: 'string', required: true, constraint: 'Path where the immutable approval result JSON is projected.' },
+            { name: 'review_id', type: 'string', required: true, constraint: 'Daemon-owned review id for the document, comments, and companion.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'The review remains live for the person and companion; approval is delivered to the origin inbox.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'The daemon creates the ticket bridge, durable review, and companion session fork.',
+            'The reviewed file remains live in the attach viewer; this command does not submit an approval.',
+        ],
+    },
+    run: async (input) => {
+        const file = resolve(input['file']);
+        const subtitle = requireSubtitle(input['subtitle']);
+        const outputArg = input['output'];
+        const output = typeof outputArg === 'string' ? resolve(outputArg) : undefined;
+        const review = await cliClient().createReview({
+            origin_kind: 'ticket',
+            origin_node_id: requireOriginNode(),
+            file,
+            idempotency_key: randomUUID(),
+            subtitle,
+            ...(output === undefined ? {} : { output_path: output }),
+        });
+        if (review.bridge_node_id === null)
+            throw new Error('ticket review was created without a bridge node');
+        const dir = ticketDir(review.bridge_node_id);
+        return {
+            job_id: review.bridge_node_id,
+            dir,
+            output: output ?? join(dir, 'feedback.json'),
+            review_id: review.review_id,
+            follow_up: 'The review is live for the person in the attach viewer with its companion agent. Approval is pushed to the origin inbox when submitted.',
+        };
+    },
+});
+const humanReviewCommentCreate = defineLeaf({
+    name: 'create',
+    description: 'add an anchored review comment',
+    whenToUse: 'recording a new finding or instruction against one or more document lines.',
+    help: {
+        name: 'human review comment create',
+        summary: 'add a daemon-owned comment anchored to document lines',
+        guide: 'Without --review, the daemon targets the calling companion node\'s open review. Comment text is supplied on stdin; agent comments use whole-line anchors.',
+        params: [
+            { kind: 'flag', name: 'review', type: 'string', required: false, constraint: 'Review id. Omit only to target the calling companion node\'s open review.' },
+            { kind: 'flag', name: 'line', type: 'int', required: true, constraint: 'First 1-based document line in the anchor.' },
+            { kind: 'flag', name: 'end-line', type: 'int', required: false, constraint: 'Last 1-based document line in the anchor. Default: --line.' },
+            { kind: 'flag', name: 'deliver', type: 'enum', choices: ['wake', 'quiet'], required: false, constraint: 'wake interrupts the companion now; quiet leaves a durable message for its next turn. Default: wake unless the caller is the companion.' },
+            { kind: 'stdin', name: 'text', required: true, constraint: 'Non-empty comment text.' },
+        ],
+        output: [
+            { name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id.' },
+            { name: 'status', type: 'string', required: true, constraint: 'Current comment status: open, resolved, or deleted.' },
+            { name: 'revision', type: 'integer', required: true, constraint: 'Current per-comment revision.' },
+            { name: 'anchor', type: 'object', required: true, constraint: 'Current whole-line anchor.' },
+            { name: 'author', type: 'object', required: true, constraint: 'Daemon-derived human or node attribution.' },
+            { name: 'text', type: 'string', required: true, constraint: 'Stored full comment text.' },
+            { name: 'changed', type: 'boolean', required: true, constraint: 'Whether this invocation changed the comment.' },
+            { name: 'delivery', type: 'object | null', required: true, constraint: 'Best-effort companion notification outcome, or null when no notification was needed.' },
+        ],
+        outputKind: 'object',
+        effects: ['Creates a daemon-owned comment and audit event, then best-effort notifies the companion.'],
+    },
+    run: async (input, context) => {
+        const reviewId = input['review'];
+        const line = input['line'];
+        const endLine = input['endLine'];
+        const result = await cliClient().createReviewComment(reviewId, {
+            text: requireCommentText(input['text'], 'create'),
+            anchor: { line, end_line: endLine ?? line },
+            actor_node_id: nodeActor(),
+            ...(explicitDeliver(input, context) === undefined ? {} : { deliver: explicitDeliver(input, context) }),
+        });
+        return mutationOutput(result);
+    },
+});
+const humanReviewCommentList = defineLeaf({
+    name: 'list',
+    description: 'list review comments in render order',
+    whenToUse: 'choosing a comment to inspect or checking the current anchored comment set.',
+    help: {
+        name: 'human review comment list',
+        summary: 'list render-ordered review comments with short text previews',
+        guide: 'Without --review, the daemon targets the calling companion node\'s open review. Use show for full comment text and audit history.',
+        params: [
+            { kind: 'flag', name: 'review', type: 'string', required: false, constraint: 'Review id. Omit only to target the calling companion node\'s open review.' },
+            { kind: 'flag', name: 'status', type: 'enum', choices: ['open', 'resolved', 'deleted', 'all'], required: false, default: 'open', constraint: 'Comment statuses to include. Default: open.' },
+        ],
+        output: [
+            { name: 'review_id', type: 'string', required: true, constraint: 'Resolved daemon-owned review id.' },
+            { name: 'comments', type: 'object[]', required: true, constraint: 'Comments in render order with status, anchor, attribution, and a 200-character text_preview.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Points to show for full text and per-comment history.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const reviewId = input['review'];
+        const status = input['status'];
+        const result = await cliClient().listReviewComments(reviewId, reviewId === undefined
+            ? { status, actor_node_id: nodeActor() }
+            : { status });
+        return {
+            review_id: result.review_id,
+            comments: result.comments.map(commentPreview),
+            follow_up: 'Use `crtr human review comment show <comment_id>` for full comment text and event history.',
+        };
+    },
+});
+const humanReviewCommentShow = defineLeaf({
+    name: 'show',
+    description: 'read one comment and its event history',
+    whenToUse: 'you need a comment\'s full text or complete per-comment audit history.',
+    help: {
+        name: 'human review comment show',
+        summary: 'read one full review comment and its event history',
+        params: [{ kind: 'positional', name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id from comment list.' }],
+        output: [
+            { name: 'comment', type: 'object', required: true, constraint: 'Full daemon-owned comment projection, including text and attribution.' },
+            { name: 'events', type: 'object[]', required: true, constraint: 'Complete append-only event history for this comment, in event sequence order.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const result = await cliClient().getReviewComment(input['comment_id']);
+        return { comment: result.comment, events: result.events };
+    },
+});
+function commentMutationLeaf(verb) {
+    const needsText = verb === 'edit';
+    return defineLeaf({
+        name: verb,
+        description: verb === 'edit'
+            ? 'replace a comment\'s text'
+            : `${verb} one review comment`,
+        whenToUse: verb === 'edit'
+            ? 'changing the stored text of an existing open or resolved comment.'
+            : `${verb === 'resolve' ? 'marking a comment addressed' : verb === 'reopen' ? 'returning a resolved comment to open' : 'retaining a terminal comment tombstone while removing it from active work'}.`,
+        help: {
+            name: `human review comment ${verb}`,
+            summary: verb === 'edit' ? 'replace a review comment\'s full text' : `${verb} a review comment`,
+            guide: needsText ? 'Replacement comment text is supplied on stdin.' : undefined,
+            params: [
+                { kind: 'positional', name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id from comment list.' },
+                { kind: 'flag', name: 'deliver', type: 'enum', choices: ['wake', 'quiet'], required: false, constraint: `wake interrupts the companion now; quiet leaves a durable message for its next turn. Default: ${verb === 'resolve' || verb === 'delete' ? 'quiet' : 'wake'} unless the caller is the companion.` },
+                ...(needsText ? [{ kind: 'stdin', name: 'text', required: true, constraint: 'Non-empty replacement comment text.' }] : []),
+            ],
+            output: [
+                { name: 'comment_id', type: 'string', required: true, constraint: 'Daemon-owned comment id.' },
+                { name: 'status', type: 'string', required: true, constraint: 'Current comment status: open, resolved, or deleted.' },
+                { name: 'revision', type: 'integer', required: true, constraint: 'Current per-comment revision.' },
+                { name: 'anchor', type: 'object', required: true, constraint: 'Current whole-line anchor.' },
+                { name: 'author', type: 'object', required: true, constraint: 'Daemon-derived human or node attribution.' },
+                { name: 'text', type: 'string', required: true, constraint: 'Stored full comment text.' },
+                { name: 'changed', type: 'boolean', required: true, constraint: 'Whether this invocation changed the comment.' },
+                { name: 'delivery', type: 'object | null', required: true, constraint: 'Best-effort companion notification outcome, or null when no notification was needed.' },
+            ],
+            outputKind: 'object',
+            effects: [`Mutates the daemon-owned comment and appends an audit event when its state changes; notification is best-effort.`],
+        },
+        run: async (input, context) => {
+            const commentId = input['comment_id'];
+            const actor_node_id = nodeActor();
+            const deliver = explicitDeliver(input, context);
+            const request = { actor_node_id, ...(deliver === undefined ? {} : { deliver }) };
+            const result = verb === 'edit'
+                ? await cliClient().editReviewComment(commentId, { ...request, text: requireCommentText(input['text'], 'edit') })
+                : verb === 'resolve'
+                    ? await cliClient().resolveReviewComment(commentId, request)
+                    : verb === 'reopen'
+                        ? await cliClient().reopenReviewComment(commentId, request)
+                        : await cliClient().deleteReviewComment(commentId, request);
+            return mutationOutput(result);
+        },
+    });
+}
+const humanReviewComment = defineBranch({
+    name: 'comment',
+    description: 'create, inspect, and update daemon-owned review comments',
+    whenToUse: 'working with the anchored comments on a document review.',
+    help: {
+        name: 'human review comment',
+        summary: 'operate on daemon-owned anchored review comments',
+        model: 'create and list address a review; all other verbs address one comment id. Create, edit, and reopen default to wake, while resolve and delete default to quiet.',
+    },
+    children: [
+        humanReviewCommentCreate,
+        humanReviewCommentList,
+        humanReviewCommentShow,
+        commentMutationLeaf('edit'),
+        commentMutationLeaf('resolve'),
+        commentMutationLeaf('reopen'),
+        commentMutationLeaf('delete'),
+    ],
+});
+export const humanReviewBranch = defineBranch({
+    name: 'review',
+    description: 'queue a document review or operate on its anchored comments',
+    whenToUse: 'a person and companion agent should collaborate on a live document review, or you need to work with that review\'s anchored comments.',
+    help: {
+        name: 'human review',
+        summary: 'queue live document reviews and manage their daemon-owned comments',
+        model: 'new creates the durable review, ticket, and companion. comment contains the operations on the review\'s shared anchored comments.',
+    },
+    children: [humanReviewNew, humanReviewComment],
+});

package/dist/commands/human/shared.d.ts

@@ -1,81 +1,14 @@
-import type { CompletionHandler } from '@crouton-kit/humanloop';
 export declare const BODY_PATH_CONTRACT: string;
 export declare const DECK_SCHEMA_HINT: string;
 /**
  * Crouter's private per-interaction record. Reduced to the delivery essentials:
- * the mode `_deliver` dispatches on and the bridge node id it delivers back to.
- * Humanloop owns every public request/result/output path (deck.json,
+ * the mode that identifies the ticket and the bridge node id it delivers back to.
+ * The ticket store owns every public request/result/output path (deck.json,
  * response.json, review.json); crouter never records pane ids or output paths.
  *
- * Every ask records an immutable conversation-fork disposition before ticket
- * publication. A failed capture never suppresses the primary ask: it records an
- * explicit unavailable reason instead of falling back to live-session reads.
  */
-export type ConversationFork = {
-    status: 'ready';
-    source_node_id: string;
-    source_file: string;
-    source_session_id: string;
-    leaf_id: string;
-    model_spec: string;
-    branch_point: 'branch-point.jsonl';
-    captured_at: string;
-} | {
-    status: 'unavailable';
-    reason: 'no_origin' | 'broker_unavailable' | 'invalid_coordinates' | 'invalid_model' | 'materialization_failed';
-    detail?: string;
-    captured_at: string;
-};
 export interface RunRecord {
     mode: 'ask' | 'notify' | 'review';
     job_id?: string;
-    conversation_fork?: ConversationFork;
 }
 export declare function resolveMaxPanes(): number;
-/**
- * The direct-exec completion handler humanloop runs when a crouter ticket
- * resolves, fed the completion event on stdin. The argv is absolute and
- * PATH/cwd-independent — never a `crtr` shell string — and, critically, must
- * actually EXECUTE in both crouter contexts:
- *
- * - Built (`dist/cli.js` present): `node <abs>/dist/cli.js human _deliver`.
- * - Dev/tsx (only `src/cli.ts` on disk): plain `node` cannot run the `.ts`
- *   entry — its mandatory `.js`-extension ESM imports have no `.js` sibling on
- *   disk, so Node's type-stripping fails at the first relative import. So we
- *   register tsx's ESM loader first (`node --import <abs tsx/esm> src/cli.ts …`),
- *   with the tsx entry resolved to an absolute file URL so the handler stays
- *   cwd-independent when humanloop invokes it. tsx is necessarily present here
- *   because crouter itself is running under it.
- *
- * Throws loudly when neither entry exists rather than registering an argv that
- * humanloop would retry forever.
- */
-export declare function crouterDeliverHandler(): CompletionHandler;
-/**
- * The direct-exec follow-up handler humanloop runs when the human presses `?`
- * on a pending crouter ticket (design-followup-consult-v2.md §B.5/§B.7) —
- * mirrors `crouterDeliverHandler()` exactly (same dual dist/tsx entry
- * resolution) but targets the hidden `human _consult` leaf. Its presence on
- * the root registration is the ONLY signal humanloop's UI uses to offer `?`,
- * and `human _consult`'s own trust check (M3) requires the registration's
- * `followUpHandler` to be this exact argv shape — a `human _consult` entry
- * inside some sealed runtime generation — so this must stay the same shape as
- * what `registerCrouterRoot` attaches.
- */
-export declare function crouterConsultHandler(): CompletionHandler;
-/** The focus handler invoked when the human asks the inbox popup to return to
- * the conversation that created its selected ticket. */
-export declare function crouterFocusHandler(): CompletionHandler;
-/** The frozen Visual handler. Like the other root handlers, this resolves the
- * actual installed or tsx CLI entry rather than depending on PATH. */
-export declare function crouterVisualHandler(): CompletionHandler;
-/**
- * Register the canvas node root with humanloop as owner `crouter`, attaching
- * the completion, follow-up, Visual, and focus handlers. Every ticket is a
- * direct child named for its bridge node, so node lifetime is ticket lifetime.
- * This also completes the hard cut from stale per-cwd registrations — but
- * never by stranding live tickets: unresolved tickets in an outgoing root are
- * swept into the current root first, and a root that cannot be fully swept
- * stays registered so its tickets remain reachable.
- */
-export declare function registerCrouterRoot(): string;

package/dist/commands/human/shared.js

@@ -1,13 +1,7 @@
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
-import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync } from 'node:fs';
 import { readConfig } from '../../core/config.js';
-import { nodesRoot } from '../../core/canvas/paths.js';
-import { interactionState, listInboxRoots, registerInboxRoot, unregisterInboxRoot } from '@crouton-kit/humanloop';
 export const BODY_PATH_CONTRACT = 'bodyPath is a relative path to the body file, resolved from the directory containing the deck JSON; ' +
     'it must stay inside that directory, and paths escaping with .. or symlinks are rejected; absolute paths are unsupported';
-export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title (required short inbox topic), ' +
+export const DECK_SCHEMA_HINT = 'Deck must match the deck schema: {title (required short inbox topic), ' +
     'source?:{sessionName?,askedBy?,blockedSince?}, interactions:[{id, ' +
     'title (short ≤~4-word inbox topic that identifies the decision for a cold reader), ' +
     'subtitle (required ONE plain-English sentence stating the decision, your recommendation, and its stakes), ' +
@@ -21,177 +15,3 @@ export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {tit
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;
 }
-/**
- * The direct-exec completion handler humanloop runs when a crouter ticket
- * resolves, fed the completion event on stdin. The argv is absolute and
- * PATH/cwd-independent — never a `crtr` shell string — and, critically, must
- * actually EXECUTE in both crouter contexts:
- *
- * - Built (`dist/cli.js` present): `node <abs>/dist/cli.js human _deliver`.
- * - Dev/tsx (only `src/cli.ts` on disk): plain `node` cannot run the `.ts`
- *   entry — its mandatory `.js`-extension ESM imports have no `.js` sibling on
- *   disk, so Node's type-stripping fails at the first relative import. So we
- *   register tsx's ESM loader first (`node --import <abs tsx/esm> src/cli.ts …`),
- *   with the tsx entry resolved to an absolute file URL so the handler stays
- *   cwd-independent when humanloop invokes it. tsx is necessarily present here
- *   because crouter itself is running under it.
- *
- * Throws loudly when neither entry exists rather than registering an argv that
- * humanloop would retry forever.
- */
-export function crouterDeliverHandler() {
-    const here = dirname(fileURLToPath(import.meta.url)); // dist/commands/human | src/commands/human
-    const distEntry = join(here, '..', '..', 'cli.js');
-    if (existsSync(distEntry)) {
-        return { command: process.execPath, args: [distEntry, 'human', '_deliver'] };
-    }
-    const tsEntry = join(here, '..', '..', 'cli.ts');
-    if (existsSync(tsEntry)) {
-        const tsxLoader = pathToFileURL(createRequire(import.meta.url).resolve('tsx/esm')).href;
-        return { command: process.execPath, args: ['--import', tsxLoader, tsEntry, 'human', '_deliver'] };
-    }
-    throw new Error(`crouter completion handler: no runnable CLI entry near ${here} (neither cli.js nor cli.ts exists)`);
-}
-/**
- * The direct-exec follow-up handler humanloop runs when the human presses `?`
- * on a pending crouter ticket (design-followup-consult-v2.md §B.5/§B.7) —
- * mirrors `crouterDeliverHandler()` exactly (same dual dist/tsx entry
- * resolution) but targets the hidden `human _consult` leaf. Its presence on
- * the root registration is the ONLY signal humanloop's UI uses to offer `?`,
- * and `human _consult`'s own trust check (M3) requires the registration's
- * `followUpHandler` to be this exact argv shape — a `human _consult` entry
- * inside some sealed runtime generation — so this must stay the same shape as
- * what `registerCrouterRoot` attaches.
- */
-export function crouterConsultHandler() {
-    const here = dirname(fileURLToPath(import.meta.url)); // dist/commands/human | src/commands/human
-    const distEntry = join(here, '..', '..', 'cli.js');
-    if (existsSync(distEntry)) {
-        return { command: process.execPath, args: [distEntry, 'human', '_consult'] };
-    }
-    const tsEntry = join(here, '..', '..', 'cli.ts');
-    if (existsSync(tsEntry)) {
-        const tsxLoader = pathToFileURL(createRequire(import.meta.url).resolve('tsx/esm')).href;
-        return { command: process.execPath, args: ['--import', tsxLoader, tsEntry, 'human', '_consult'] };
-    }
-    throw new Error(`crouter follow-up handler: no runnable CLI entry near ${here} (neither cli.js nor cli.ts exists)`);
-}
-/** The focus handler invoked when the human asks the inbox popup to return to
- * the conversation that created its selected ticket. */
-export function crouterFocusHandler() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const distEntry = join(here, '..', '..', 'cli.js');
-    if (existsSync(distEntry))
-        return { command: process.execPath, args: [distEntry, 'human', '_focus'] };
-    const tsEntry = join(here, '..', '..', 'cli.ts');
-    if (existsSync(tsEntry)) {
-        const tsxLoader = pathToFileURL(createRequire(import.meta.url).resolve('tsx/esm')).href;
-        return { command: process.execPath, args: ['--import', tsxLoader, tsEntry, 'human', '_focus'] };
-    }
-    throw new Error(`crouter focus handler: no runnable CLI entry near ${here} (neither cli.js nor cli.ts exists)`);
-}
-/** The frozen Visual handler. Like the other root handlers, this resolves the
- * actual installed or tsx CLI entry rather than depending on PATH. */
-export function crouterVisualHandler() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const distEntry = join(here, '..', '..', 'cli.js');
-    if (existsSync(distEntry))
-        return { command: process.execPath, args: [distEntry, 'human', '_visual'] };
-    const tsEntry = join(here, '..', '..', 'cli.ts');
-    if (existsSync(tsEntry)) {
-        const tsxLoader = pathToFileURL(createRequire(import.meta.url).resolve('tsx/esm')).href;
-        return { command: process.execPath, args: ['--import', tsxLoader, tsEntry, 'human', '_visual'] };
-    }
-    throw new Error(`crouter Visual handler: no runnable CLI entry near ${here} (neither cli.js nor cli.ts exists)`);
-}
-/**
- * Move one unresolved ticket directory from an outgoing crouter root into the
- * current root, preserving its id (the bridge node id) and every descriptor
- * file so `_deliver`/`_consult` still resolve against the same `run.json`.
- * The destination may already exist as the bridge node's canvas dir (the new
- * convention puts ticket files directly in the node dir), so an existing
- * destination is merged file-by-file; a collision on any name aborts this
- * ticket's sweep without partial loss of visibility (the caller then keeps the
- * old root registered).
- */
-function sweepTicket(oldDir, newDir) {
-    if (!existsSync(newDir)) {
-        renameSync(oldDir, newDir);
-        return true;
-    }
-    const entries = readdirSync(oldDir);
-    for (const entry of entries)
-        if (existsSync(join(newDir, entry)))
-            return false;
-    for (const entry of entries)
-        renameSync(join(oldDir, entry), join(newDir, entry));
-    try {
-        rmdirSync(oldDir);
-    }
-    catch { /* leftover empty dir is harmless */ }
-    return true;
-}
-/**
- * Sweep every unresolved ticket out of an outgoing crouter root into the
- * current one. Returns true only when nothing unresolved remains in the old
- * root — the caller must NOT unregister a root this returns false for,
- * because unresolved tickets in an unregistered root become invisible to
- * every inbox surface (`hl inbox list`, `crtr human list`) and their asking
- * agents wait forever.
- */
-function sweepUnresolvedTickets(oldRoot, newRoot) {
-    if (!existsSync(oldRoot))
-        return true;
-    let entries;
-    try {
-        entries = readdirSync(oldRoot);
-    }
-    catch {
-        return false;
-    }
-    let clean = true;
-    for (const entry of entries) {
-        const oldDir = join(oldRoot, entry);
-        try {
-            if (!statSync(oldDir).isDirectory())
-                continue;
-            const state = interactionState(oldDir);
-            if (state === 'missing' || state === 'resolved')
-                continue;
-            if (!sweepTicket(oldDir, join(newRoot, entry)))
-                clean = false;
-        }
-        catch {
-            clean = false;
-        }
-    }
-    return clean;
-}
-/**
- * Register the canvas node root with humanloop as owner `crouter`, attaching
- * the completion, follow-up, Visual, and focus handlers. Every ticket is a
- * direct child named for its bridge node, so node lifetime is ticket lifetime.
- * This also completes the hard cut from stale per-cwd registrations — but
- * never by stranding live tickets: unresolved tickets in an outgoing root are
- * swept into the current root first, and a root that cannot be fully swept
- * stays registered so its tickets remain reachable.
- */
-export function registerCrouterRoot() {
-    const root = nodesRoot();
-    mkdirSync(root, { recursive: true });
-    for (const registration of listInboxRoots()) {
-        if (registration.owner === 'crouter' && registration.root !== root) {
-            if (sweepUnresolvedTickets(registration.root, root)) {
-                unregisterInboxRoot(registration.root, 'crouter');
-            }
-        }
-    }
-    return registerInboxRoot({
-        root,
-        owner: 'crouter',
-        handler: crouterDeliverHandler(),
-        followUpHandler: crouterConsultHandler(),
-        visualHandler: crouterVisualHandler(),
-        focusHandler: crouterFocusHandler(),
-    }).root;
-}

package/dist/commands/human.js

@@ -1,44 +1,39 @@
-// `crtr human` subtree — humanloop producer + completion bridge.
+// `crtr human` creates bridge nodes and durable tickets for human decisions.
 //
-// Kickoff leaves (ask/review) create a terminal kind:'human' bridge node under
-// the asking node, register the one canvas node root with humanloop (owner
-// 'crouter', `_deliver` handler), submit the deck/review, and return at once —
-// nothing opens on screen. When the human answers from humanloop's inbox popup
-// (the inbox-toggle keybinding, or `hl inbox open`), humanloop invokes the
-// registered `_deliver` handler, which pushFinals
-// the answer as the bridge node's final report, fanning it into the asking
-// node's inbox. notify enqueues a durable deck with no node; show is passive
-// display. Humanloop owns the queue UI, claims, and atomic finalization.
+// Ask creates a bridge node and submits a ticket to the store. Review creation
+// asks crtrd to create a ticket, daemon-owned review, and companion. notify
+// enqueues a durable deck with no node; show is passive display.
 import { defineBranch } from '../core/command.js';
-import { humanAsk, humanReview, humanNotify, humanShow } from './human/prompts.js';
-import { humanList, humanDeck, humanResolve, humanCancel, humanDeliver, humanFocus, humanConsult, humanVisual } from './human/queue.js';
+import { humanAsk, humanNotify, humanShow } from './human/prompts.js';
+import { humanReviewBranch } from './human/review.js';
+import { humanList, humanDeck, humanResolve, humanCancel } from './human/queue.js';
+import { humanInbox } from './human/inbox.js';
+import { humanDoc } from './human/doc.js';
 import { inboxOpenInstruction } from '../core/keybindings/index.js';
 export function registerHuman() {
     return defineBranch({
         name: 'human',
         rootEntry: {
             concept: 'human-in-the-loop decisions, document review, and live display',
-            desc: 'ask, review, notify, show, cancel, list',
-            useWhen: 'you have a question for the user, want their feedback, or are presenting them with options or a choice — always reach for human instead of guessing or assuming, or laying a choice out as prose, when a person can decide; and whenever the user wants to review a spec, plan, or requirements document, this is the command for anchored line-by-line comments.'
+            desc: 'ask, review new/comment, notify, show, cancel, list',
+            useWhen: 'when a person must decide, review a document with you, or receive a live display.'
         },
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: `Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see \`termrender doc -h\` for the directive set before authoring one. ask and review are kickoffs: they create a kind:'human' bridge node under you and return instantly, never blocking. Nothing opens on screen — the ticket is queued in the humanloop inbox; the human opens it — ${inboxOpenInstruction()} — on their own time, and their response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call; review queues a .md for anchored comments and the inbox previews the live file, so edit in place rather than canceling and re-presenting. notify enqueues a durable acknowledgement with no node; show is passive live display.`,
+            model: `Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see \`crtr human doc check\` to validate a body before submitting it. ask creates a kind:'human' bridge node under you and returns instantly, never blocking. Nothing opens on screen — the ticket is queued in the human inbox; the human opens it — ${inboxOpenInstruction()} — on their own time, and their response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call. review is a branch: new queues a live document for the human to review in the attach viewer alongside a companion agent, while comment verbs operate on daemon-owned anchored comments; approval is pushed back as an approval fact, and a changed document instructs the origin to re-read it. notify enqueues a durable acknowledgement with no node; show is passive live display. inbox opens or toggles the queue on this screen; doc validates or renders a directive-flavored markdown body.`,
         },
         children: [
             humanAsk,
-            humanReview,
+            humanReviewBranch,
             humanNotify,
             humanShow,
             humanCancel,
             humanList,
             humanDeck,
             humanResolve,
-            humanDeliver,
-            humanFocus,
-            humanConsult,
-            humanVisual,
+            humanInbox,
+            humanDoc,
         ],
     });
 }

package/dist/commands/memory/__tests__/lint.test.d.ts

@@ -0,0 +1 @@
+export {};