@north-light/crouter 0.3.170 → 0.3.172

package/dist/daemon/api/handlers/reviews.js

@@ -0,0 +1,287 @@
+// Canonical daemon-owned review lifecycle routes. Handlers validate the full
+// wire request, delegate lifecycle work to review services, and project only
+// committed daemon state.
+import { existsSync } from 'node:fs';
+import { ApiError } from '../../../api/index.js';
+import { isSafeNodeId, reviewResultPath } from '../../../core/canvas/paths.js';
+import { responsePath, reviewPath } from '../../../core/human/convention.js';
+import { ticketDir } from '../../../core/human/root.js';
+import { createReview } from '../../../core/review/birth.js';
+import { openExistingReview } from '../../../core/review/realize.js';
+import { readAnchorBase, getReview, getReviewByBridge, listReviews } from '../../../core/review/store.js';
+import { ReviewOperationError } from '../../../core/review/types.js';
+import { cancelReview, submitReviewApproval } from '../../review/finish.js';
+import { toFeedbackResultDTO, toReviewDTO } from '../map.js';
+const REVIEW_STATES = new Set(['open', 'approved', 'canceled']);
+const CREATE_FIELDS = ['origin_kind', 'origin_node_id', 'file', 'idempotency_key', 'subtitle', 'output_path'];
+const CANCEL_FIELDS = ['reason', 'actor'];
+function invalidRequest(violations) {
+    throw new ApiError(400, 'invalid_request', 'review request is invalid', { violations });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function objectBody(body, allowed, violations) {
+    if (!isRecord(body)) {
+        violations.push({ field: 'body', problem: 'must be an object', received: body });
+        return {};
+    }
+    for (const key of Object.keys(body)) {
+        if (!allowed.includes(key))
+            violations.push({ field: key, problem: 'is not allowed', received: body[key] });
+    }
+    return body;
+}
+function requiredString(body, field, violations) {
+    const value = body[field];
+    if (typeof value !== 'string' || value === '') {
+        violations.push({ field, problem: 'must be a non-empty string', ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}
+function optionalString(body, field, violations) {
+    const value = body[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value === '') {
+        violations.push({ field, problem: 'must be a non-empty string', received: value });
+        return undefined;
+    }
+    return value;
+}
+function requireReviewId(ctx, violations) {
+    const reviewId = ctx.params['review_id'];
+    if (reviewId === undefined || !isSafeNodeId(reviewId)) {
+        violations.push({ field: 'review_id', problem: 'must be a safe review id', ...(reviewId === undefined ? {} : { received: reviewId }) });
+        return undefined;
+    }
+    return reviewId;
+}
+function requireBridgeNodeId(ctx, violations) {
+    const bridgeNodeId = ctx.params['bridge_node_id'];
+    if (bridgeNodeId === undefined || !isSafeNodeId(bridgeNodeId)) {
+        violations.push({ field: 'bridge_node_id', problem: 'must be a safe node id', ...(bridgeNodeId === undefined ? {} : { received: bridgeNodeId }) });
+        return undefined;
+    }
+    return bridgeNodeId;
+}
+function requireVisibleReview(reviewId) {
+    const review = getReview(reviewId);
+    if (review === null || review.state === 'binding') {
+        throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
+    }
+    return review;
+}
+function approvedResultPath(review) {
+    if (review.origin_kind === 'inline')
+        return reviewResultPath(review.review_id);
+    if (review.bridge_node_id === null)
+        throw new Error(`approved ticket review lacks its bridge node: ${review.review_id}`);
+    return responsePath(ticketDir(review.bridge_node_id));
+}
+function toReviewResponseDTO(review) {
+    return review.state === 'approved'
+        ? toReviewDTO(review, { result_path: approvedResultPath(review) })
+        : toReviewDTO(review);
+}
+function parseCreate(ctx) {
+    const violations = [];
+    const body = objectBody(ctx.body, CREATE_FIELDS, violations);
+    const originKind = body['origin_kind'];
+    const origin_kind = originKind === 'ticket' || originKind === 'inline'
+        ? originKind
+        : undefined;
+    if (origin_kind === undefined) {
+        violations.push({ field: 'origin_kind', problem: 'must be ticket or inline', ...(originKind === undefined ? {} : { received: originKind }) });
+    }
+    const origin_node_id = requiredString(body, 'origin_node_id', violations);
+    if (origin_node_id !== undefined && !isSafeNodeId(origin_node_id)) {
+        violations.push({ field: 'origin_node_id', problem: 'must be a safe node id', received: origin_node_id });
+    }
+    const file = requiredString(body, 'file', violations);
+    const idempotency_key = requiredString(body, 'idempotency_key', violations);
+    if (idempotency_key !== undefined && idempotency_key.length > 128) {
+        violations.push({ field: 'idempotency_key', problem: 'must be at most 128 characters', received: idempotency_key });
+    }
+    const subtitle = optionalString(body, 'subtitle', violations);
+    const output_path = optionalString(body, 'output_path', violations);
+    if (origin_kind === 'ticket' && subtitle === undefined && body['subtitle'] === undefined) {
+        violations.push({ field: 'subtitle', problem: 'is required for ticket reviews' });
+    }
+    if (origin_kind === 'inline' && body['subtitle'] !== undefined) {
+        violations.push({ field: 'subtitle', problem: 'is only allowed for ticket reviews', received: body['subtitle'] });
+    }
+    if (origin_kind === 'inline' && body['output_path'] !== undefined) {
+        violations.push({ field: 'output_path', problem: 'is only allowed for ticket reviews', received: body['output_path'] });
+    }
+    if (violations.length > 0
+        || origin_kind === undefined
+        || origin_node_id === undefined
+        || !isSafeNodeId(origin_node_id)
+        || file === undefined
+        || idempotency_key === undefined
+        || idempotency_key.length > 128)
+        invalidRequest(violations);
+    return {
+        origin_kind,
+        origin_node_id,
+        file,
+        idempotency_key,
+        ...(subtitle === undefined ? {} : { subtitle }),
+        ...(output_path === undefined ? {} : { output_path }),
+    };
+}
+function parseList(ctx) {
+    const violations = [];
+    const parsed = {};
+    const allowed = new Set(['state', 'origin_node_id', 'file']);
+    for (const [field, value] of ctx.query.entries()) {
+        if (!allowed.has(field))
+            violations.push({ field, problem: 'is not allowed', received: value });
+    }
+    for (const field of allowed) {
+        const values = ctx.query.getAll(field);
+        if (values.length > 1) {
+            violations.push({ field, problem: 'must appear at most once', received: values });
+            continue;
+        }
+        const value = values[0];
+        if (value === undefined)
+            continue;
+        if (field === 'state') {
+            if (!REVIEW_STATES.has(value)) {
+                violations.push({ field, problem: 'must be open, approved, or canceled', received: value });
+            }
+            else {
+                parsed.state = value;
+            }
+        }
+        else if (field === 'origin_node_id') {
+            if (!isSafeNodeId(value)) {
+                violations.push({ field, problem: 'must be a safe node id', received: value });
+            }
+            else {
+                parsed.origin_node_id = value;
+            }
+        }
+        else if (value === '') {
+            violations.push({ field, problem: 'must be a non-empty string', received: value });
+        }
+        else {
+            parsed.file = value;
+        }
+    }
+    if (violations.length > 0)
+        invalidRequest(violations);
+    return parsed;
+}
+function parseCancel(ctx, violations) {
+    const body = ctx.body === undefined ? {} : objectBody(ctx.body, CANCEL_FIELDS, violations);
+    const reason = optionalString(body, 'reason', violations);
+    const actor = optionalString(body, 'actor', violations);
+    return { ...(reason === undefined ? {} : { reason }), ...(actor === undefined ? {} : { actor }) };
+}
+function requireEmptyBody(ctx, violations) {
+    objectBody(ctx.body, [], violations);
+}
+async function handleCreate(ctx) {
+    const review = await createReview(parseCreate(ctx));
+    return { status: 200, body: toReviewResponseDTO(review) };
+}
+function handleList(ctx) {
+    const query = parseList(ctx);
+    const body = { reviews: listReviews(query).map(toReviewResponseDTO) };
+    return { status: 200, body };
+}
+function handleRead(ctx) {
+    const violations = [];
+    const reviewId = requireReviewId(ctx, violations);
+    if (violations.length > 0 || reviewId === undefined)
+        invalidRequest(violations);
+    return { status: 200, body: toReviewResponseDTO(requireVisibleReview(reviewId)) };
+}
+function handleByBridge(ctx) {
+    const violations = [];
+    const bridgeNodeId = requireBridgeNodeId(ctx, violations);
+    if (violations.length > 0 || bridgeNodeId === undefined)
+        invalidRequest(violations);
+    const review = getReviewByBridge(bridgeNodeId);
+    if (review !== null)
+        return { status: 200, body: toReviewResponseDTO(review) };
+    if (existsSync(reviewPath(ticketDir(bridgeNodeId)))) {
+        throw new ApiError(409, 'review_predates_system', 'this review predates canonical review records; cancel it and re-file the review', { bridge_node_id: bridgeNodeId });
+    }
+    throw new ReviewOperationError('unknown_review', 'review was not found', { received: bridgeNodeId });
+}
+async function handleOpen(ctx) {
+    const violations = [];
+    const reviewId = requireReviewId(ctx, violations);
+    requireEmptyBody(ctx, violations);
+    if (violations.length > 0 || reviewId === undefined)
+        invalidRequest(violations);
+    const opened = await openExistingReview(reviewId);
+    const body = opened.disposition === 'terminal'
+        ? { review: toReviewResponseDTO(opened.review), disposition: 'terminal' }
+        : {
+            review: toReviewResponseDTO(opened.review),
+            companion_node_id: opened.review.companion_node_id,
+            companion_status: opened.companion_status,
+            disposition: 'open',
+        };
+    return { status: 200, body };
+}
+async function handleSubmit(ctx) {
+    const violations = [];
+    const reviewId = requireReviewId(ctx, violations);
+    requireEmptyBody(ctx, violations);
+    if (violations.length > 0 || reviewId === undefined)
+        invalidRequest(violations);
+    const finished = await submitReviewApproval(reviewId);
+    const body = {
+        review: toReviewResponseDTO(finished.record),
+        result: toFeedbackResultDTO(finished.result),
+        outcome: finished.outcome,
+    };
+    return { status: 200, body };
+}
+async function handleCancel(ctx) {
+    const violations = [];
+    const reviewId = requireReviewId(ctx, violations);
+    const request = parseCancel(ctx, violations);
+    if (violations.length > 0 || reviewId === undefined)
+        invalidRequest(violations);
+    const finished = await cancelReview(reviewId, request);
+    const body = {
+        review: toReviewResponseDTO(finished.record),
+        outcome: finished.outcome,
+    };
+    return { status: 200, body };
+}
+function handleDocument(ctx) {
+    const violations = [];
+    const reviewId = requireReviewId(ctx, violations);
+    if (violations.length > 0 || reviewId === undefined)
+        invalidRequest(violations);
+    const review = requireVisibleReview(reviewId);
+    const anchor = readAnchorBase(review.review_id);
+    if (anchor === null)
+        throw new Error(`review anchor base is missing: ${review.review_id}`);
+    const body = {
+        review_id: review.review_id,
+        anchor_base_sha256: anchor.sha256,
+        anchor_base_text: new TextDecoder('utf-8', { fatal: true }).decode(anchor.bytes),
+        file: review.file,
+    };
+    return { status: 200, body };
+}
+export const reviewRoutes = [
+    { method: 'POST', pattern: '/v1/human/reviews', handler: handleCreate },
+    { method: 'GET', pattern: '/v1/human/reviews', handler: handleList },
+    { method: 'GET', pattern: '/v1/human/reviews/by-bridge/:bridge_node_id', handler: handleByBridge },
+    { method: 'GET', pattern: '/v1/human/reviews/:review_id', handler: handleRead },
+    { method: 'POST', pattern: '/v1/human/reviews/:review_id/open', handler: handleOpen },
+    { method: 'POST', pattern: '/v1/human/reviews/:review_id/submit', handler: handleSubmit },
+    { method: 'POST', pattern: '/v1/human/reviews/:review_id/cancel', handler: handleCancel },
+    { method: 'GET', pattern: '/v1/human/reviews/:review_id/document', handler: handleDocument },
+];

package/dist/daemon/api/map.d.ts

@@ -1,11 +1,11 @@
 import type { ManagedWorktree, NodeMeta, NodeRow, SubscriptionRef } from '../../core/canvas/types.js';
-import type { HumanWorkRow } from '../../core/canvas/human-work-outbox.js';
+import type { ReviewComment, ReviewCommentEvent, ReviewErrorCode, ReviewRecord, ReviewResult } from '../../core/review/types.js';
 import type { Cron, CronRunRecord } from '../../core/canvas/crons.js';
 import type { ProfileEntry } from '../../core/profiles/manifest.js';
 import type { ReviveResult } from '../../core/runtime/revive.js';
 import type { CloseNodeResult } from '../../core/runtime/close.js';
 import { type PushResult } from '../../core/feed/feed.js';
-import type { CloseResultDTO, ConsultOutboxEntryDTO, CronDTO, CronRunDTO, ErrorBody, NodeEdgesDTO, NodePathsDTO, NodeStatusDTO, NodeSummaryDTO, NodeDetailDTO, NodeWorktreeDTO, ProfileDTO, PushReportResultDTO, ReviveResultDTO, SubscriptionDTO } from '../../api/index.js';
+import type { CloseResultDTO, CronDTO, CronRunDTO, ErrorBody, NodeEdgesDTO, NodePathsDTO, NodeStatusDTO, NodeSummaryDTO, NodeDetailDTO, NodeWorktreeDTO, ProfileDTO, ReviewCommentDTO, ReviewCommentEventDTO, ReviewDTO, FeedbackResultDTO, PushReportResultDTO, ReviveResultDTO, SubscriptionDTO } from '../../api/index.js';
 /** Project the queryable row (what `listNodes` yields) into a summary DTO. */
 export declare function toNodeSummaryDTO(row: NodeRow): NodeSummaryDTO;
 /** The subscription/child edges a detail projection needs. The handler gathers
@@ -61,11 +61,26 @@ export declare function toCronRunDTO(r: CronRunRecord): CronRunDTO;
  *  entry, so it is left null here — a caller that needs it resolves it
  *  separately. */
 export declare function toProfileDTO(entry: ProfileEntry): ProfileDTO;
-/** Project a `consult_outbox` (human-work) row into a consult-outbox entry DTO
- *  (the canvas half of a human consult/visual request). `work_kind` is the same
- *  `'follow_up' | 'visual'` union as `ConsultKindDTO`; `created` carries the
- *  row's last-touch timestamp (the table has no separate creation column). */
-export declare function toConsultOutboxEntryDTO(row: HumanWorkRow): ConsultOutboxEntryDTO;
+/** Extra daemon-derived review fields whose source is outside the canonical row. */
+export interface ReviewDTOExtras {
+    /** Deterministic destination of an approved review's immutable result. */
+    result_path?: string;
+}
+/** Project the canonical review row without exposing fork/session/store coordinates. */
+export declare function toReviewDTO(row: ReviewRecord, extras?: ReviewDTOExtras): ReviewDTO;
+/** Project one daemon-owned comment, omitting absent node identities on human actions. */
+export declare function toReviewCommentDTO(comment: ReviewComment): ReviewCommentDTO;
+/** Project one immutable review-comment audit event. */
+export declare function toReviewCommentEventDTO(event: ReviewCommentEvent): ReviewCommentEventDTO;
+/** Project the immutable snake_case review result to the existing camelCase feedback wire shape. */
+export declare function toFeedbackResultDTO(result: ReviewResult): FeedbackResultDTO;
+/** The only internal review-error to public HTTP projection. Every internal
+ * review failure is listed explicitly so handlers never need to invent a status
+ * or public code. */
+export declare const REVIEW_ERROR_MAP: Readonly<Record<ReviewErrorCode, {
+    status: number;
+    code: string;
+}>>;
 /** The single error-mapping function (spec §8). Projects any thrown value into
  *  `{ status, code }`:
  *   - a CrtrError → status by its `exitCode` class, `code` its machine code;

package/dist/daemon/api/map.js

@@ -9,6 +9,7 @@
 // constructors. The DTO field sets these project into were pinned by A-1 as
 // reasonable projections; this module is what makes them concrete, so any DTO
 // field that projection proves wrong is corrected here at the source.
+import { ReviewOperationError as ReviewOperationErrorClass } from '../../core/review/types.js';
 import { contextDir, inboxPath, nodeDir, nodeMetaPath, reportsDir, transcriptPath, viewSocketPath, } from '../../core/canvas/paths.js';
 import { FinalizationError } from '../../core/feed/feed.js';
 import { NodeIdConflictError } from '../../core/runtime/nodes.js';
@@ -116,6 +117,16 @@ export function toNodeDetailDTO(meta, edges) {
     dto.model_override = meta.model_override ?? null;
     if (meta.pi_session_file !== undefined)
         dto.pi_session_file = meta.pi_session_file ?? null;
+    if (meta.review_binding !== undefined) {
+        dto.review_binding = meta.review_binding === null
+            ? null
+            : {
+                review_id: meta.review_binding.review_id,
+                origin_node_id: meta.review_binding.origin_node_id,
+                branch_file: meta.review_binding.branch_file,
+                target_file: meta.review_binding.target_file,
+            };
+    }
     if (meta.managed_worktree != null)
         dto.worktree = toNodeWorktreeDTO(meta.managed_worktree);
     return dto;
@@ -242,24 +253,142 @@ export function toProfileDTO(entry) {
         default_dir: null,
     };
 }
-/** Project a `consult_outbox` (human-work) row into a consult-outbox entry DTO
- *  (the canvas half of a human consult/visual request). `work_kind` is the same
- *  `'follow_up' | 'visual'` union as `ConsultKindDTO`; `created` carries the
- *  row's last-touch timestamp (the table has no separate creation column). */
-export function toConsultOutboxEntryDTO(row) {
+/** Project the canonical review row without exposing fork/session/store coordinates. */
+export function toReviewDTO(row, extras = {}) {
+    const dto = {
+        review_id: row.review_id,
+        origin_kind: row.origin_kind,
+        origin_node_id: row.origin_node_id,
+        bridge_node_id: row.bridge_node_id,
+        companion_node_id: row.companion_node_id,
+        file: row.file,
+        state: row.state,
+        created: row.created,
+        source_missing: row.source_missing,
+        anchor_base_sha256: row.anchor_base_sha256,
+    };
+    if (row.opened_at !== null)
+        dto.opened_at = row.opened_at;
+    if (row.approved_at !== null)
+        dto.approved_at = row.approved_at;
+    if (row.changed !== null)
+        dto.changed = row.changed;
+    if (row.comments_total !== null)
+        dto.comments_total = row.comments_total;
+    if (row.comments_unresolved !== null)
+        dto.comments_unresolved = row.comments_unresolved;
+    if (row.canceled_at !== null)
+        dto.canceled_at = row.canceled_at;
+    if (row.cancel_reason !== null)
+        dto.cancel_reason = row.cancel_reason;
+    if (row.cancel_actor !== null)
+        dto.cancel_actor = row.cancel_actor;
+    if (extras.result_path !== undefined)
+        dto.result_path = extras.result_path;
+    if (row.delivery_error !== null)
+        dto.delivery_error = row.delivery_error;
+    if (row.projection_error !== null)
+        dto.projection_error = row.projection_error;
+    return dto;
+}
+/** Project one daemon-owned comment, omitting absent node identities on human actions. */
+export function toReviewCommentDTO(comment) {
     return {
-        request_id: row.request_id,
-        node_id: row.node_id,
-        kind: row.work_kind,
-        dir: row.dir,
-        created: row.updated_at,
+        comment_id: comment.comment_id,
+        review_id: comment.review_id,
+        status: comment.status,
+        revision: comment.revision,
+        text: comment.text,
+        anchor: { ...comment.anchor },
+        anchor_state: comment.anchor_state,
+        anchor_line_text: comment.anchor_line_text,
+        anchor_doc_hash: comment.anchor_doc_hash,
+        author: {
+            kind: comment.author.kind,
+            ...(comment.author.node_id === null ? {} : { node_id: comment.author.node_id }),
+        },
+        updated_by: {
+            kind: comment.updated_by.kind,
+            ...(comment.updated_by.node_id === null ? {} : { node_id: comment.updated_by.node_id }),
+        },
+        created_at: comment.created_at,
+        updated_at: comment.updated_at,
+        ...(comment.resolved_at === null ? {} : { resolved_at: comment.resolved_at }),
+        ...(comment.deleted_at === null ? {} : { deleted_at: comment.deleted_at }),
+        created_seq: comment.created_seq,
     };
 }
+/** Project one immutable review-comment audit event. */
+export function toReviewCommentEventDTO(event) {
+    return {
+        seq: event.seq,
+        review_id: event.review_id,
+        comment_id: event.comment_id,
+        kind: event.kind,
+        state_change: event.state_change === 1,
+        revision_after: event.revision_after,
+        actor: {
+            kind: event.actor.kind,
+            ...(event.actor.node_id === null ? {} : { node_id: event.actor.node_id }),
+        },
+        at: event.at,
+        operation_id: event.operation_id,
+        ...(event.payload === undefined ? {} : { payload: event.payload }),
+    };
+}
+/** Project the immutable snake_case review result to the existing camelCase feedback wire shape. */
+export function toFeedbackResultDTO(result) {
+    const dto = {
+        file: result.file,
+        submitted: result.submitted,
+        approved: result.approved,
+        comments: result.comments.map((comment) => ({ ...comment })),
+        submittedAt: result.submittedAt,
+        savedAt: result.savedAt,
+        reviewId: result.review_id,
+        changed: result.changed,
+        baselineSha256: result.baseline_sha256,
+        approvedSha256: result.approved_sha256,
+        companionNodeId: result.companion_node_id,
+        commentsTotal: result.comments_total,
+        commentsUnresolved: result.comments_unresolved,
+    };
+    return dto;
+}
 const _exitIntentParity = true;
 void _exitIntentParity;
 // ---------------------------------------------------------------------------
 // Error → HTTP status mapping (spec §8)
 // ---------------------------------------------------------------------------
+/** The only internal review-error to public HTTP projection. Every internal
+ * review failure is listed explicitly so handlers never need to invent a status
+ * or public code. */
+export const REVIEW_ERROR_MAP = Object.freeze({
+    review_origin_missing: { status: 400, code: 'review_origin_unavailable' },
+    review_origin_unforkable: { status: 400, code: 'review_origin_unavailable' },
+    review_origin_unstable: { status: 409, code: 'review_origin_unstable' },
+    review_branch_unavailable: { status: 409, code: 'review_branch_unavailable' },
+    branch_lost: { status: 409, code: 'review_branch_unavailable' },
+    review_companion_unbound: { status: 409, code: 'review_companion_unbound' },
+    review_bridge_unsubscribed: { status: 409, code: 'review_bridge_unavailable' },
+    review_target_unreviewable: { status: 400, code: 'review_file_unreadable' },
+    source_unreadable: { status: 409, code: 'review_source_unreadable' },
+    delivery_unroutable: { status: 409, code: 'review_delivery_unroutable' },
+    unknown_review: { status: 404, code: 'unknown_review' },
+    review_not_open: { status: 409, code: 'review_not_open' },
+    review_terminal: { status: 409, code: 'review_terminal_conflict' },
+    review_required: { status: 400, code: 'review_required' },
+    stale_document: { status: 409, code: 'stale_document' },
+    unknown_comment: { status: 404, code: 'unknown_comment' },
+    comment_deleted: { status: 409, code: 'comment_deleted' },
+    invalid_anchor: { status: 400, code: 'invalid_anchor' },
+    anchor_out_of_range: { status: 400, code: 'anchor_out_of_range' },
+    text_too_long: { status: 400, code: 'text_too_long' },
+    comment_limit_reached: { status: 409, code: 'comment_limit_reached' },
+    stale_comment: { status: 409, code: 'stale_comment' },
+    range_batch_incomplete: { status: 409, code: 'range_batch_incomplete' },
+    range_batch_stale: { status: 409, code: 'range_batch_stale' },
+});
 /** The single error-mapping function (spec §8). Projects any thrown value into
  *  `{ status, code }`:
  *   - a CrtrError → status by its `exitCode` class, `code` its machine code;
@@ -298,6 +427,9 @@ export function errorToStatus(err) {
     if (err instanceof NodeIdConflictError) {
         return { status: 409, code: 'node_id_exists' };
     }
+    if (err instanceof ReviewOperationErrorClass) {
+        return REVIEW_ERROR_MAP[err.code];
+    }
     if (err instanceof CrtrError) {
         return { status: statusForExitCode(err.exitCode), code: err.code };
     }
@@ -313,6 +445,18 @@ export function errorToStatus(err) {
     }
     return { status: 500, code: 'internal' };
 }
+/** Remove the store row from a terminal-conflict detail before it reaches the wire.
+ * Only the approved `ReviewDTO` fields cross this boundary; all other review
+ * errors retain their explicitly specified internal detail object. */
+function reviewErrorDetails(err) {
+    if (err.code !== 'review_terminal')
+        return err.detail;
+    const { review, ...detail } = err.detail;
+    return {
+        ...detail,
+        review: toReviewDTO(review),
+    };
+}
 function statusForExitCode(exitCode) {
     switch (exitCode) {
         case ExitCode.NOT_FOUND:
@@ -354,7 +498,11 @@ export function toErrorBody(err) {
         return { status, body: { error: { code, message: boundedCause(err) } } };
     }
     const message = err instanceof Error ? err.message : String(err);
-    const details = err instanceof CrtrError && err.details !== undefined ? err.details : undefined;
+    const details = err instanceof ReviewOperationErrorClass
+        ? reviewErrorDetails(err)
+        : err instanceof CrtrError && err.details !== undefined
+            ? err.details
+            : undefined;
     const body = { error: { code, message } };
     if (details !== undefined)
         body.error.details = details;

package/dist/daemon/api/server.js

@@ -35,6 +35,8 @@ import { modelAuthRoutes } from './handlers/modelauth.js';
 import { nodeRoutes } from './handlers/nodes.js';
 import { profileRoutes } from './handlers/profiles.js';
 import { reportRoutes } from './handlers/reports.js';
+import { reviewCommentRoutes } from './handlers/review-comments.js';
+import { reviewRoutes } from './handlers/reviews.js';
 import { subscriptionRoutes } from './handlers/subscriptions.js';
 import { cronRoutes } from './handlers/crons.js';
 import { worktreeRoutes } from './handlers/worktree.js';
@@ -58,6 +60,8 @@ function buildRouter() {
         .registerAll(profileRoutes)
         .registerAll(modelAuthRoutes)
         .registerAll(humanRoutes)
+        .registerAll(reviewRoutes)
+        .registerAll(reviewCommentRoutes)
         .registerAll(inboxRoutes);
 }
 /** Is this request an attach upgrade — `GET /v1/nodes/{id}/attach` — and if so,

package/dist/daemon/cron-run.js

@@ -30,14 +30,14 @@
 // promises for graceful-teardown drain but never blocks on a slow run.
 import { spawn } from 'node:child_process';
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
-import { notifyDeck, submitDeck } from '@crouton-kit/humanloop';
+import { notifyDeck } from '../core/human/deck-factories.js';
+import { ticketDir } from '../core/human/root.js';
+import { submitDeck } from '../core/human/tickets.js';
 import { dueClockCrons, dueOverlapCrons, expiredIdleCrons, runningCrons, acquireCronRunLease, releaseCronRunLease, recordCronRun, listCronRuns, advanceCron, consumeCron, cancelCron, killLeasedCronRun, verifyLeasedCronRun, getCron, setCronState, setCronLastOutputHash, } from '../core/canvas/crons.js';
 import { getNode } from '../core/canvas/canvas.js';
 import { fullName } from '../core/canvas/labels.js';
-import { nodeDir } from '../core/canvas/paths.js';
 import { killProcessGroup } from '../core/canvas/pid.js';
 import { appendInbox } from '../core/feed/inbox.js';
 import { atomicWriteJson } from '../core/fs-utils.js';
@@ -50,7 +50,6 @@ import { nextSlotAfter, cadenceDisplay } from '../core/wake.js';
 import { buildOperationalEnvBase } from '../core/runtime/spawn-env.js';
 import { parseSink } from './cron-sink.js';
 import { readProfileEnvVars } from '../core/profiles/env-store.js';
-import { registerCrouterRoot } from '../commands/human/shared.js';
 /** Output head caps for the run log (spec: "capped, e.g. 4KB"). */
 export const CRON_OUTPUT_HEAD_BYTES = 4 * 1024;
 /** A byte-capped capture of one output stream's head. Bytes are buffered and
@@ -187,21 +186,19 @@ async function deliverSpawnSink(c, kind, stdout) {
     });
     return res.node.node_id;
 }
-/** Deliver stdout through humanloop as a durable notify deck (fire-and-forget
+/** Deliver stdout through crouter as a durable notify deck (fire-and-forget
  *  inbox state — jobs whose output is a person's call). Mirrors `crtr human
  *  notify` minus the CLI-env source stamp: the deck names the cron instead. */
 function deliverHumanSink(c, stdout) {
     const id = `nfy-${randomBytes(4).toString('hex')}`;
-    const idir = nodeDir(id);
-    mkdirSync(idir, { recursive: true });
     const rc = { mode: 'notify' };
-    atomicWriteJson(join(idir, 'run.json'), rc);
+    atomicWriteJson(join(ticketDir(id), 'run.json'), rc);
     let deck = notifyDeck(`⏰ cron ${c.name}`, {
         subtitle: `Scheduled cron "${c.name}" delivered output for your attention.`,
         body: stdout,
     });
     deck = { ...deck, source: { sessionName: `cron ${c.name} (${c.cron_id})` } };
-    submitDeck({ root: registerCrouterRoot(), id, deck });
+    submitDeck({ dir: ticketDir(id), deck });
 }
 /** Route stdout to the cron's armed sink. Returns the delivered string on
  *  success; throws on an undeliverable sink (the caller's failure path). */