@north-light/crouter 0.3.312 → 0.3.314

package/dist/api/dto/human-requests.d.ts

@@ -1,7 +1,7 @@
 import type { IsoTime } from './common.js';
-import type { InboxTicketIdDTO, PageResponsesDTO, TicketSourceDTO } from './inbox.js';
-/** A request id IS an opaque inbox ticket id: lowercase 64-hex. */
-export type HumanRequestIdDTO = InboxTicketIdDTO;
+import type { InboxPageDTO, PageResponsesDTO, TicketSourceDTO } from './inbox.js';
+/** Daemon-minted request identity. Inbox presentation has a separate opaque ticket id. */
+export type HumanRequestIdDTO = string;
 /** The complete authored page text, inline — never a path. */
 export interface HumanRequestPageDTO {
     dialect: 'jsx' | 'html';
@@ -22,6 +22,8 @@ export interface CreateHumanRequestRequest {
     page: HumanRequestPageDTO;
     delivery?: HumanRequestDeliveryDTO;
     source?: TicketSourceDTO;
+    /** The one node that receives the terminal result. Required for reply-bearing pages. */
+    requester_node_id?: string | null;
     creator_cwd: string;
     action?: HumanRequestActionDTO;
 }
@@ -29,6 +31,8 @@ export type HumanRequestState = 'pending' | 'answered' | 'dismissed' | 'canceled
 export type HumanRequestDeliveryState = 'none' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
 export interface CreateHumanRequestDTO {
     request_id: HumanRequestIdDTO;
+    /** Daemon-owned directory where the request's rendered page is projected. */
+    request_dir: string;
     state: 'pending';
     /** Omitted entirely when the request carries no action binding. */
     action?: {
@@ -56,6 +60,11 @@ export interface HumanRequestDeliveryDetailDTO {
 }
 export interface HumanRequestDTO {
     request_id: HumanRequestIdDTO;
+    /** Opaque inbox identity for inbox-only routes. */
+    inbox_ticket_id: string;
+    /** Daemon-owned directory where the request's rendered page is projected. */
+    request_dir: string;
+    kind: 'page' | 'review';
     state: HumanRequestState;
     title: string;
     subtitle?: string;
@@ -73,6 +82,8 @@ export interface HumanRequestDTO {
         payload: unknown;
     };
     delivery?: HumanRequestDeliveryDetailDTO;
+    /** Present exactly when this request is a page. */
+    page?: InboxPageDTO;
 }
 export interface ReplaceHumanRequestRequest {
     page: HumanRequestPageDTO;

package/dist/api/dto/human.d.ts

@@ -1,26 +1,16 @@
-import type { NodeIdDTO } from './common.js';
-/** One anchored review comment, mirroring crouter's ticket-store shape as a
- *  plain structural wire type (no store import). */
+/** One anchored review comment, mirroring crouter's canonical review result. */
 export interface FeedbackCommentDTO {
     id: string;
-    /** 1-based source line where the comment is anchored (start). */
     line: number;
-    /** 1-based source line where the anchored range ends (== line for one line). */
     endLine: number;
-    /** Exact selected substring when the human made a visual selection. */
     quote?: string;
-    /** 0-based byte column where a partial (charwise) selection starts on `line`. */
     colStart?: number;
-    /** 0-based exclusive byte column where the selection ends on `endLine`. */
     colEnd?: number;
-    /** Full source text of the anchored line(s) — context for the agent. */
     lineText: string;
     comment: string;
     createdAt: string;
 }
-/** Immutable daemon-projected approval result, mirroring crouter's canonical
- *  review result as a plain structural wire type — `src/api/**` never imports
- *  the store's own type. */
+/** Immutable daemon-projected review approval result. */
 export interface FeedbackResultDTO {
     file: string;
     submitted: true;
@@ -36,39 +26,3 @@ export interface FeedbackResultDTO {
     commentsTotal: number;
     commentsUnresolved: number;
 }
-/** `POST /v1/human/tickets/{ticket_id}/resolve` body — a page answer keyed by slot id. */
-export interface HumanResolveRequest {
-    responses: Record<string, Record<string, unknown>>;
-}
-/** `POST /v1/human/tickets/{ticket_id}/cancel` body. */
-export interface HumanCancelRequest {
-    reason?: string;
-    actor?: string;
-    /** The recipient surface closing it sends `dismissed`; a requester retracting
-     * it sends `canceled` or omits the field. */
-    disposition?: 'canceled' | 'dismissed';
-}
-/** `POST /v1/human/tickets/{ticket_id}/resolve` result. */
-export interface HumanResolveResultDTO {
-    completed: true;
-    reply_delivered: boolean;
-    kind: 'page';
-}
-/** `POST /v1/human/tickets/{ticket_id}/cancel` result. */
-export interface HumanCancelResultDTO {
-    canceled: true;
-}
-/** `POST /v1/human/bridge` body — create a terminal `kind:'human'` bridge node
- *  via `spawnNode` (NO broker engine). Distinct from `POST /v1/nodes`, whose
- *  `spawnChild` always launches a broker the bridge must never have. */
-export interface CreateHumanBridgeRequest {
-    kind: 'human';
-    parent: NodeIdDTO | null;
-    cwd: string;
-    name: string;
-}
-/** `POST /v1/human/bridge` result — the minted bridge node id + its name. */
-export interface HumanBridgeResultDTO {
-    node_id: NodeIdDTO;
-    name: string;
-}

package/dist/api/dto/human.js

@@ -1,3 +1,4 @@
-// Human-bridge and crouter ticket-store DTOs — the canvas-facing wire shapes
-// for bridge work and ticket resolution through crtrd.
+// Shared human-review result DTOs. Page and review lifecycle contracts live in
+// their request-specific modules; bridge and duplicate ticket settlement types
+// are intentionally absent.
 export {};

package/dist/api/dto/inbox.d.ts

@@ -10,6 +10,10 @@ export interface TicketSourceDTO {
     nodeId?: string;
 }
 export interface ReviewTicketSummaryDTO {
+    /** Request identity for direct request/review routes. */
+    request_id: string;
+    /** Daemon-owned projection directory. */
+    request_dir: string;
     ticket_id: InboxTicketIdDTO;
     kind: 'review';
     title: string;
@@ -33,6 +37,10 @@ export interface PageFastActionDTO {
     responses: PageResponsesDTO;
 }
 export interface PageTicketSummaryDTO {
+    /** Request identity for direct request routes. */
+    request_id: string;
+    /** Daemon-owned projection directory. */
+    request_dir: string;
     ticket_id: InboxTicketIdDTO;
     kind: 'page';
     title: string;
@@ -118,13 +126,19 @@ export interface InboxPageDTO {
     ticket_id: InboxTicketIdDTO;
     kind: 'page';
     state: 'pending' | 'resolved' | 'canceled' | 'passive';
+    /** Opaque SQL-selected immutable presentation revision. */
+    revision: string;
     page: PageManifestDTO;
     /** JSX is compiled for the host; HTML is the authored document verbatim. */
     document: string;
+    /** Authored JSX or HTML, distinct from the compiled JSX host document. */
+    source_document: string;
     document_media_type: 'text/jsx' | 'text/html';
     progress: {
         responses: PageResponsesDTO;
     } | null;
+    /** Canonical stored terminal result, or null while the ticket remains open. */
+    result: PageTicketResultDTO | CanceledTicketResultDTO | null;
     /** Ticket-attached feedback comments and the companion conversation they
      * deliver to. Comments are immutable once sent — open until the companion
      * resolves them. */

package/dist/api/dto/mail.d.ts

@@ -0,0 +1,43 @@
+export interface MailEntryDTO {
+    entry_id: string;
+    operation_id: string;
+    ts: string;
+    from: string | null;
+    from_name?: string;
+    tier: 'critical' | 'urgent' | 'normal' | 'deferred';
+    kind: 'update' | 'urgent' | 'final' | 'message' | 'completed';
+    ref?: string;
+    label: string;
+    data?: Record<string, unknown>;
+    disposition?: 'human-answer' | 'human-canceled';
+}
+export interface ClaimedMailDTO {
+    delivery_id: string;
+    attempts: number;
+    handoff: 'fresh' | 'inherited';
+    entry: MailEntryDTO;
+}
+export interface ClaimMailRequest {
+    execution_id: string;
+    channel: 'wake' | 'passive';
+}
+export interface ClaimMailResultDTO {
+    action: 'claimed' | 'hold';
+    deliveries: ClaimedMailDTO[];
+}
+export interface MailReceiptDTO {
+    delivery_id: string;
+    attempts: number;
+    disposition: 'acknowledged' | 'released';
+}
+export interface AcknowledgeMailRequest {
+    execution_id: string;
+    deliveries: MailReceiptDTO[];
+}
+export interface AcknowledgeMailResultDTO {
+    action: 'acknowledged' | 'hold';
+    results: Array<{
+        delivery_id: string;
+        outcome: 'acknowledged' | 'released' | 'stale';
+    }>;
+}

package/dist/api/dto/nodes.d.ts

@@ -1,6 +1,7 @@
 import type { Cursor, ExitIntentDTO, IsoTime, LifecycleDTO, ModeDTO, NodeIdDTO, NodeStatusDTO, TerminalReasonDTO } from './common.js';
 import type { ReportDTO } from './reports.js';
 import type { NodeOutcomeDTO, RegisterOutcomeDeliveryRequest } from './node-outcomes.js';
+import type { FaultLink, FaultKind, FaultRetry, FaultProviderError } from './recovery.js';
 /** `GET /v1/nodes/{id}/subject` — the node-config subject substrate gate
  *  predicates evaluate against. Mirrors `NodeConfigSubject`; this narrow
  *  endpoint exists so a CLI process (the `memory read` leaf) can gate-check
@@ -105,6 +106,8 @@ export interface NodeSummaryDTO {
     finalized_at: IsoTime | null;
     deadline_at: IsoTime | null;
     outcome: NodeOutcomeDTO | null;
+    fault?: NodeFaultDTO | null;
+    streaming?: boolean;
     /** Present only when requested with `include=activity`. */
     activity?: NodeActivityDTO;
 }
@@ -135,7 +138,6 @@ export interface NodePathsDTO {
     context_dir: string;
     reports_dir: string;
     meta_path: string;
-    inbox_path: string;
     transcript_path: string;
     view_socket: string;
 }
@@ -172,12 +174,15 @@ export interface NodeReviewBindingDTO {
 }
 /** The active fault projection shown by node inspection. */
 export interface NodeFaultDTO {
-    link: string;
-    kind: string;
-    retry: {
-        disposition: string;
-    };
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
     since: IsoTime;
+    operation_id: string;
+    anchorEntryId?: string;
+    providerError?: FaultProviderError;
 }
 /** The full node view — summary ∪ identity extras ∪ edges ∪ paths. Returned by
  *  `GET /v1/nodes/{id}` and by the create/lifecycle actions that yield a node. */
@@ -212,8 +217,6 @@ export interface NodeDetailDTO extends NodeSummaryDTO {
     edges: NodeEdgesDTO;
     paths: NodePathsDTO;
     worktree?: NodeWorktreeDTO | null;
-    /** The currently active runtime fault, when one is present. */
-    fault?: NodeFaultDTO | null;
     /** Present only on a `POST /promote` response — the roadmap/goal facts the
      *  promote primitive returns beyond the node meta (spec §6.2). A plain detail
      *  read omits them. */

package/dist/api/dto/recovery.d.ts

@@ -0,0 +1,96 @@
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'daemon→node' | 'crtr→pi';
+export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
+export interface FaultRetry {
+    disposition: 'auto' | 'manual' | 'fatal';
+    by?: 'sdk' | 'daemon' | 'client';
+    attempt?: number;
+    max?: number;
+    nextAt?: string;
+}
+export interface FaultProviderError {
+    provider: string;
+    model: string;
+    status?: number;
+    code?: string | number;
+    errno?: string;
+    body?: string;
+    causes?: Array<{
+        message?: string;
+        status?: number;
+        code?: string | number;
+        errno?: string;
+        body?: string;
+    }>;
+}
+export interface RecoveryFaultDTO {
+    fault_id: string;
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    since: string;
+    operation_id: string;
+    anchor_entry_id?: string;
+    provider_error?: FaultProviderError;
+}
+export interface ExecutionExitDiagnosticDTO {
+    schema: 'crtr.execution-exit-diagnostic/v1';
+    transport_poison: {
+        consecutive_passes: number;
+        routes: string[];
+    };
+}
+export interface BrokerTurnResultDTO {
+    applied: boolean;
+}
+export interface BrokerTurnRequest {
+    expected_execution_id: string;
+    event: 'started' | 'progress' | 'closed' | 'interrupted' | 'exit-diagnostic';
+    end_reason?: 'settled' | 'teardown-aborted';
+    exit_diagnostic?: ExecutionExitDiagnosticDTO;
+}
+export interface BrokerFaultInputDTO {
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    operation_id?: string;
+    since?: string;
+    anchor_entry_id?: string;
+    provider_error?: FaultProviderError;
+}
+export interface BrokerFaultResultDTO {
+    fault: RecoveryFaultDTO | null;
+}
+export interface BrokerFaultRequest {
+    expected_execution_id: string;
+    op: 'record' | 'clear';
+    link?: FaultLink;
+    preserve_episode?: boolean;
+    input?: BrokerFaultInputDTO;
+}
+export interface BrokerProviderRetryResultDTO {
+    applied: boolean;
+    episode: RecoveryStateDTO['episode'];
+}
+export interface BrokerProviderRetryRequest {
+    expected_execution_id: string;
+    op: 'record-pending' | 'admit' | 'reopen' | 'invalidate' | 'clear';
+    session_id: string;
+    fault_id?: string;
+    retry?: FaultRetry;
+    input?: BrokerFaultInputDTO;
+}
+export interface RecoveryStateDTO {
+    fault: RecoveryFaultDTO | null;
+    episode: {
+        state: 'pending' | 'admitted' | 'invalidated';
+        session_id: string | null;
+        fault: RecoveryFaultDTO;
+    } | null;
+}
+export interface NodeFaultClearResultDTO {
+    cleared: boolean;
+}

package/dist/api/dto/reviews.d.ts

@@ -26,8 +26,8 @@ export interface ReviewDTO {
     origin_kind: ReviewOriginKindDTO;
     /** Daemon-recorded originating node. */
     origin_node_id: NodeIdDTO;
-    /** Daemon-recorded ticket bridge, when this review came from a ticket. */
-    bridge_node_id: NodeIdDTO | null;
+    /** Daemon-owned directory containing the review branch and terminal result. */
+    review_dir: string;
     /** Daemon-preallocated companion node. */
     companion_node_id: NodeIdDTO;
     /** Daemon-canonicalized reviewed file path. */

package/dist/api/routes.d.ts

@@ -5,6 +5,8 @@ export declare const routes: {
     readonly healthz: () => string;
     readonly status: () => string;
     readonly daemonRestart: () => string;
+    readonly daemonMigrate: () => string;
+    readonly daemonAdmit: () => string;
     readonly nodes: () => string;
     readonly reviveAll: () => string;
     readonly node: (id: string) => string;
@@ -31,11 +33,17 @@ export declare const routes: {
     readonly nodeBrokerSettle: (id: string) => string;
     readonly nodeBrokerParkComplete: (id: string) => string;
     readonly nodeBrokerParkActivity: (id: string) => string;
-    readonly nodeBrokerInboxCursor: (id: string) => string;
+    readonly nodeMailClaim: (id: string) => string;
+    readonly nodeMailAcknowledge: (id: string) => string;
     readonly nodeBrokerModel: (id: string) => string;
     readonly nodeBrokerExtensionState: (id: string) => string;
     readonly nodeBrokerGeneratedName: (id: string) => string;
     readonly nodeBrokerPersonaAck: (id: string) => string;
+    readonly brokerTurn: (id: string) => string;
+    readonly brokerProviderRetry: (id: string) => string;
+    readonly brokerFault: (id: string) => string;
+    readonly brokerRecovery: (id: string) => string;
+    readonly nodeFault: (id: string) => string;
     readonly nodeClose: (id: string) => string;
     readonly nodeRecycle: (id: string) => string;
     readonly nodeDemote: (id: string) => string;
@@ -68,13 +76,8 @@ export declare const routes: {
     readonly canvasSnapshot: () => string;
     readonly canvasRoster: () => string;
     readonly canvasPrune: () => string;
-    readonly canvasRebuildIndex: () => string;
-    readonly humanBridge: () => string;
-    readonly humanTicketResolve: (ticketId: string) => string;
-    readonly humanTicketCancel: (ticketId: string) => string;
     readonly humanReviews: () => string;
     readonly humanReview: (reviewId: string) => string;
-    readonly humanReviewByBridge: (bridgeNodeId: string) => string;
     readonly humanReviewSubmit: (reviewId: string) => string;
     readonly humanReviewCancel: (reviewId: string) => string;
     readonly humanReviewDocument: (reviewId: string) => string;

package/dist/api/routes.js

@@ -19,6 +19,8 @@ export const routes = {
     healthz: () => '/healthz',
     status: () => `${V}/status`,
     daemonRestart: () => `${V}/daemon/restart`,
+    daemonMigrate: () => `${V}/daemon/migrate`,
+    daemonAdmit: () => `${V}/daemon/admit`,
     // Nodes — collection + item
     nodes: () => `${V}/nodes`,
     reviveAll: () => `${V}/nodes/revive-all`,
@@ -49,11 +51,17 @@ export const routes = {
     nodeBrokerSettle: (id) => `${V}/nodes/${id}/broker/settle`,
     nodeBrokerParkComplete: (id) => `${V}/nodes/${id}/broker/park-complete`,
     nodeBrokerParkActivity: (id) => `${V}/nodes/${id}/broker/park-activity`,
-    nodeBrokerInboxCursor: (id) => `${V}/nodes/${id}/broker/inbox-cursor`,
+    nodeMailClaim: (id) => `${V}/nodes/${id}/mail/claim`,
+    nodeMailAcknowledge: (id) => `${V}/nodes/${id}/mail/acknowledge`,
     nodeBrokerModel: (id) => `${V}/nodes/${id}/broker/model`,
     nodeBrokerExtensionState: (id) => `${V}/nodes/${id}/broker/extension-state`,
     nodeBrokerGeneratedName: (id) => `${V}/nodes/${id}/broker/generated-name`,
     nodeBrokerPersonaAck: (id) => `${V}/nodes/${id}/broker/persona-ack`,
+    brokerTurn: (id) => `${V}/broker/${id}/turn`,
+    brokerProviderRetry: (id) => `${V}/broker/${id}/provider-retry`,
+    brokerFault: (id) => `${V}/broker/${id}/fault`,
+    brokerRecovery: (id) => `${V}/broker/${id}/recovery`,
+    nodeFault: (id) => `${V}/nodes/${id}/fault`,
     nodeClose: (id) => `${V}/nodes/${id}/close`,
     nodeRecycle: (id) => `${V}/nodes/${id}/recycle`,
     nodeDemote: (id) => `${V}/nodes/${id}/demote`,
@@ -90,17 +98,10 @@ export const routes = {
     canvasSnapshot: () => `${V}/canvas/snapshot`,
     canvasRoster: () => `${V}/canvas/roster`,
     canvasPrune: () => `${V}/canvas/prune`,
-    canvasRebuildIndex: () => `${V}/canvas/rebuild-index`,
-    // Human bridge creation + the pinned ticket route table (design §"The `/v1`
-    // surface") — every ticket route is addressed by node id only.
-    humanBridge: () => `${V}/human/bridge`,
-    humanTicketResolve: (ticketId) => `${V}/human/tickets/${ticketId}/resolve`,
-    humanTicketCancel: (ticketId) => `${V}/human/tickets/${ticketId}/cancel`,
     // Daemon-owned document reviews and comments. All interpolated ids are
     // guarded by `CrtrClient` before they reach these pure builders.
     humanReviews: () => `${V}/human/reviews`,
     humanReview: (reviewId) => `${V}/human/reviews/${reviewId}`,
-    humanReviewByBridge: (bridgeNodeId) => `${V}/human/reviews/by-bridge/${bridgeNodeId}`,
     humanReviewSubmit: (reviewId) => `${V}/human/reviews/${reviewId}/submit`,
     humanReviewCancel: (reviewId) => `${V}/human/reviews/${reviewId}/cancel`,
     humanReviewDocument: (reviewId) => `${V}/human/reviews/${reviewId}/document`,
@@ -120,9 +121,8 @@ export const routes = {
     humanInboxResponse: (ticketId) => `${V}/human/inbox/${ticketId}/response`,
     humanInboxCancel: (ticketId) => `${V}/human/inbox/${ticketId}/cancel`,
     humanInboxFeedbackResolve: (ticketId, commentId) => `${V}/human/inbox/${ticketId}/feedback-comments/${commentId}/resolve`,
-    // Durable programmatic human requests. `request_id` is the same opaque
-    // inbox ticket id the `/v1/human/inbox` routes address, so one request is one
-    // record across both surfaces.
+    // Durable programmatic human requests. A request id is separate from the
+    // opaque inbox ticket id used by `/v1/human/inbox`.
     humanRequests: () => `${V}/human/requests`,
     humanRequest: (requestId) => `${V}/human/requests/${requestId}`,
     humanRequestReplace: (requestId) => `${V}/human/requests/${requestId}/replace`,

package/dist/build-root.d.ts

@@ -5,6 +5,10 @@ import { type CoreHookCatalog } from './core/command-hooks/catalog.js';
 export declare const SUBTREE_NAMES: readonly string[];
 export declare function coreHookCatalog(): Promise<CoreHookCatalog>;
 export declare function coreCommandPaths(): Promise<ReadonlySet<string>>;
+/** Whether argv targets the daemon-control subtree after the dispatcher's global-token normalization. This only selects a smaller canonical tree; `runCli` still parses, renders help, and reports errors. */
+export declare function isDaemonControlInvocation(argv: readonly string[]): boolean;
+/** Assemble the canonical daemon-control definitions without loading settings or plugin discovery. This path exists so `crtr sys daemon restart` can start the new generation that converts pre-SQL user state. */
+export declare function resolveDaemonControlRoot(): Promise<RootDef>;
 /** Build a root that contains only the subtree `first` dispatches into.
  *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
  *  `-h`/`--help`, `--version`, and any unknown leading token all need the

package/dist/build-root.js

@@ -1,4 +1,4 @@
-import { defineRoot } from './core/command.js';
+import { defineRoot, GLOBAL_TOKENS } from './core/command.js';
 import { createCoreHookCatalog } from './core/command-hooks/catalog.js';
 import { composeCoreHooks } from './core/command-hooks/compose.js';
 import { mark } from './core/timing.js';
@@ -104,6 +104,16 @@ export async function coreCommandPaths() {
         visit(subtree, subtree.name);
     return paths;
 }
+/** Whether argv targets the daemon-control subtree after the dispatcher's global-token normalization. This only selects a smaller canonical tree; `runCli` still parses, renders help, and reports errors. */
+export function isDaemonControlInvocation(argv) {
+    const tokens = argv.slice(2).filter((token) => !GLOBAL_TOKENS.has(token));
+    return tokens[0] === 'sys' && tokens[1] === 'daemon';
+}
+/** Assemble the canonical daemon-control definitions without loading settings or plugin discovery. This path exists so `crtr sys daemon restart` can start the new generation that converts pre-SQL user state. */
+export async function resolveDaemonControlRoot() {
+    const { registerDaemonControlSys } = await import('./commands/sys/daemon.js');
+    return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [registerDaemonControlSys()] });
+}
 /** Build a root that contains only the subtree `first` dispatches into.
  *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
  *  `-h`/`--help`, `--version`, and any unknown leading token all need the