@north-light/api 0.3.580 → 0.3.587

package/dist/daemon/api/map.js

@@ -0,0 +1,764 @@
+// Internal type → DTO projection (spec §3.1, §8). This is the ONLY module that
+// imports BOTH `core/*` internal types and the `src/api` DTO shapes — the
+// boundary where crtrd's authoritative runtime types are projected into the
+// dependency-light wire contract. `src/api/*` stays pure (Node built-ins only);
+// all projection lives here, server-side.
+//
+// Every function here is a pure projection (no db reach) except the path
+// builders and the optional structured-result sidecar read needed by a settled
+// outcome. 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 { join } from 'node:path';
+import { readOutputResult } from '../../core/runtime/output-result.js';
+import { ReviewOperationError as ReviewOperationErrorClass } from '../../core/review/types.js';
+import { cronSinkDisplay } from '../../core/canvas/crons.js';
+import { isProfilePaused, profileDir, sanitizeProfileMetadata } from '../../core/profiles/manifest.js';
+import { nodeMetaPath, transcriptPath, viewSocketPath, } from '../../core/canvas/paths.js';
+import { appForNode, contextDir, nodeAgentDir } from '../../core/canvas/node-agent-paths.js';
+import { readControllerWait } from '../../core/canvas/waits.js';
+import { FinalizationError } from '../../core/feed/feed.js';
+import { NodeIdConflictError } from '../../core/runtime/nodes.js';
+import { ScopeDeniedError } from '../../core/scopes.js';
+import { isBeneathRefusal } from '../../core/spaces/open-beneath.js';
+import { CrtrError } from '../../core/errors.js';
+import { WorktreeError } from '../../core/worktree.js';
+import { ApiError } from '../../api/errors.js';
+import { RunError } from '../../core/runs/operations.js';
+import { ExitCode } from '../../types.js';
+export function toMigrateStateDTO(result, options) {
+    const { report } = result;
+    return {
+        stores: report.stores.map((s) => ({ root: s.root, owner: { ...s.owner }, docs: s.docs, ...(s.skipped === undefined ? {} : { skipped: s.skipped }) })),
+        counts: report.counts,
+        rewrites: report.rewrites,
+        dropped_fields: report.droppedFields,
+        skipped: report.skipped,
+        resolutions: report.resolutions.map((r) => ({ kind: r.kind, message: r.message, paths: r.paths })),
+        blockers: result.blockers.map((b) => ({ kind: b.kind, message: b.message, paths: b.paths })),
+        dryRun: result.dryRun,
+        pending: result.pending,
+        resumed: options.resumed,
+        ...(options.resumeError === undefined ? {} : { resume_error: options.resumeError }),
+    };
+}
+// Node projections
+/** Read the optional machine result without letting a missing or malformed sidecar obscure the durable outcome row. */
+async function readStructuredResult(nodeId) {
+    try {
+        return await readOutputResult(nodeId) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Project the list-row outcome, or null while this node remains unsettled. */
+export function toNodeOutcomeSummaryDTO(node) {
+    if (node.outcome_at === null || node.outcome_at === undefined || node.outcome_kind === null || node.outcome_kind === undefined || node.outcome_reason === null || node.outcome_reason === undefined) {
+        return null;
+    }
+    return { kind: node.outcome_kind, reason: node.outcome_reason, settled_at: node.outcome_at };
+}
+/** Project the full outcome, or null while this node remains unsettled. */
+export async function toNodeOutcomeDTO(node) {
+    if (node.outcome_at === null || node.outcome_at === undefined || node.outcome_kind === null || node.outcome_kind === undefined || node.outcome_reason === null || node.outcome_reason === undefined) {
+        return null;
+    }
+    let detail = null;
+    if (node.outcome_detail_json !== null && node.outcome_detail_json !== undefined) {
+        try {
+            detail = JSON.parse(node.outcome_detail_json);
+        }
+        catch {
+            detail = null;
+        }
+    }
+    // A declined structured result is a `failure` that still carries a canonical final report.
+    const finalReport = node.final_report ?? null;
+    const base = {
+        node_id: node.node_id,
+        revision: node.outcome_revision ?? 1,
+        settled_at: node.outcome_at,
+        final_report: finalReport === null ? null : `${node.node_id}/${finalReport}`,
+        structured_result: node.outcome_kind === 'result' ? await readStructuredResult(node.node_id) : null,
+        detail,
+    };
+    if (node.outcome_kind === 'result')
+        return { ...base, kind: 'result', reason: node.outcome_reason, declined: null };
+    // A declined row whose detail holds no decline block still projects: the row
+    // predates the decline block being recorded, or the outcome-column backfill
+    // rebuilt it from `terminal_reason` alone. This mapper also runs per row in
+    // the canvas-wide list projection, so throwing here would take every
+    // graph-wide read down over one unreadable node.
+    if (node.outcome_reason === 'declined')
+        return { ...base, kind: 'failure', reason: 'declined', declined: detail?.declined ?? null };
+    return { ...base, kind: 'failure', reason: node.outcome_reason, declined: null };
+}
+export async function toRunOutcomeDTO(node) {
+    const outcome = await toNodeOutcomeDTO(node);
+    if (outcome === null || outcome.reason === 'parked')
+        return null;
+    if (outcome.kind === 'result' || outcome.reason === 'finished')
+        return { ...outcome, kind: 'result', reason: 'finalized', declined: null };
+    // Contract 4 (D4-SET-18) carries the decline in `details`; `declined` stays for node-API parity.
+    if (outcome.reason === 'declined')
+        return { ...outcome, reason: 'declined', details: outcome.declined };
+    if (outcome.reason === 'deadline_exceeded')
+        return { ...outcome, reason: 'deadline_exceeded', declined: null };
+    // A model call was refused because the grantee's month spend reached its cap (D2-VOC-18).
+    if (outcome.reason === 'cap_exhausted')
+        return { ...outcome, reason: 'cap_exhausted', declined: null };
+    if (outcome.reason === 'closed' || outcome.reason === 'stranded' || outcome.reason === 'retired')
+        return { ...outcome, reason: 'canceled', declined: null };
+    return { ...outcome, reason: 'runtime_error', declined: null, details: { crouter_reason: outcome.reason } };
+}
+/** Project a durable delivery row without exposing its execution coordinates or stderr tail. */
+export function toOutcomeDeliveryDTO(row) {
+    const failure = row.lastFailure;
+    return {
+        node_id: row.nodeId,
+        state: row.state,
+        action: row.actionName,
+        attempt: row.attempt,
+        next_attempt_at: row.nextAttemptAt === 0 ? null : new Date(row.nextAttemptAt).toISOString(),
+        accepted_at: row.acceptedAt === null ? null : new Date(row.acceptedAt).toISOString(),
+        permanent_failed_at: row.permanentFailedAt === null ? null : new Date(row.permanentFailedAt).toISOString(),
+        last_failure: failure === null ? null : {
+            kind: failure.kind,
+            ...(failure.exitCode === undefined ? {} : { exit_code: failure.exitCode }),
+            ...(failure.signal === undefined ? {} : { signal: failure.signal }),
+            ...(failure.message === undefined ? {} : { message: failure.message }),
+        },
+        created_at: new Date(row.createdAt).toISOString(),
+        updated_at: new Date(row.updatedAt).toISOString(),
+    };
+}
+/** Project the queryable row (what `listNodes` yields) into a summary DTO. */
+export function toGraphNodeDTO(row) {
+    return {
+        node_id: row.node_id,
+        name: row.name,
+        description: row.description,
+        cycles: row.cycles,
+        kind: row.kind,
+        status: row.status,
+        frozen_at: row.frozen_at,
+        pi_pid: row.pi_pid,
+        telemetry_context_tokens: row.telemetry_context_tokens,
+        telemetry_last_activity: row.telemetry_last_activity,
+        fault: row.fault && row.fault.link !== 'broker↔crtrd' ? { ...row.fault, link: row.fault.link } : null,
+        streaming: row.streaming,
+    };
+}
+export async function toNodeSummaryDTO(row, paused = isProfilePaused(row.profile_id)) {
+    return {
+        node_id: row.node_id,
+        name: row.name,
+        description: row.description,
+        cycles: row.cycles,
+        kind: row.kind,
+        mode: row.mode,
+        lifecycle: row.lifecycle,
+        status: row.status,
+        cwd: row.cwd,
+        host_kind: row.host_kind,
+        profile_id: row.profile_id,
+        scopes: row.scopes,
+        isolated: row.isolated,
+        grantee: row.grantee ?? await appForNode(row.node_id),
+        profile_paused: paused,
+        parent: row.parent,
+        created: row.created,
+        intent: row.intent,
+        waiting_for: (await readControllerWait(row.node_id))?.controllerId ?? null,
+        frozen_at: row.frozen_at ?? null,
+        terminal_reason: row.terminal_reason ?? null,
+        pi_pid: row.pi_pid,
+        pi_pid_identity: row.pi_pid_identity,
+        window: row.window,
+        tmux_session: row.tmux_session,
+        pane: row.pane,
+        final_report: row.final_report ?? null,
+        finalized_at: row.finalized_at ?? null,
+        deadline_at: row.deadline_at ?? null,
+        telemetry_tokens_in: row.telemetry_tokens_in ?? null,
+        telemetry_context_tokens: row.telemetry_context_tokens ?? null,
+        telemetry_last_activity: row.telemetry_last_activity ?? null,
+        telemetry_updated_at: row.telemetry_updated_at ?? null,
+        outcome: toNodeOutcomeSummaryDTO(row),
+        fault: row.fault && row.fault.link !== 'broker↔crtrd' ? { ...row.fault, link: row.fault.link } : null,
+        streaming: row.streaming ?? false,
+    };
+}
+/** Project a node's spine + subscription edges (absorbs `managers`/`paths`). */
+export function toNodeEdgesDTO(meta, edges) {
+    return {
+        parent: meta.parent ?? null,
+        spawned_by: meta.spawned_by ?? null,
+        subscribes_to: edges.subscribesTo.map((r) => r.node_id),
+        subscribers: edges.subscribers.map((r) => r.node_id),
+        children: [...edges.children],
+    };
+}
+/** Absolute filesystem paths for a node (absorbs the `paths` read).
+ *  App assignment comes from the authoritative node row. */
+export async function toNodePathsDTO(nodeId, grantee) {
+    return {
+        node_dir: await nodeAgentDir(nodeId, grantee),
+        context_dir: await contextDir(nodeId, grantee),
+        meta_path: nodeMetaPath(nodeId),
+        transcript_path: transcriptPath(nodeId),
+        view_socket: viewSocketPath(nodeId),
+    };
+}
+/** Project a node's managed git worktree, if any. */
+export function toNodeWorktreeDTO(w) {
+    const dto = {
+        state: w.state,
+        path: w.path,
+        branch: w.branch,
+        repo_root: w.repo_root,
+        base_ref: w.base_ref,
+        base_sha: w.base_sha,
+        created: w.created,
+    };
+    if (w.cleanup !== undefined)
+        dto.cleanup = w.cleanup;
+    if (w.closed !== undefined)
+        dto.closed = w.closed;
+    if (w.abandoned !== undefined)
+        dto.abandoned = { ...w.abandoned };
+    return dto;
+}
+/** Project the hydrated node view (`getNode` → `NodeMeta`) into a detail DTO.
+ *  The summary fields come from the meta's runtime half (hydrated from the
+ *  authoritative row); the identity extras (description/cycles/session) come
+ *  from the meta's identity half. Edges are gathered by the handler. */
+export async function toNodeDetailDTO(meta, edges) {
+    const grantee = await appForNode(meta.node_id);
+    const dto = {
+        node_id: meta.node_id,
+        name: meta.name,
+        kind: meta.kind,
+        mode: meta.mode,
+        lifecycle: meta.lifecycle,
+        status: meta.status,
+        cwd: meta.cwd,
+        host_kind: meta.host_kind ?? null,
+        profile_id: meta.profile_id ?? null,
+        scopes: meta.scopes ?? null,
+        isolated: meta.isolated === true,
+        grantee,
+        profile_paused: isProfilePaused(meta.profile_id),
+        parent: meta.parent ?? null,
+        created: meta.created,
+        intent: (meta.intent ?? null),
+        waiting_for: (await readControllerWait(meta.node_id))?.controllerId ?? null,
+        frozen_at: meta.frozen_at ?? null,
+        terminal_reason: meta.terminal_reason ?? null,
+        pi_pid: meta.pi_pid ?? null,
+        pi_pid_identity: meta.pi_pid_identity ?? null,
+        window: meta.window ?? null,
+        tmux_session: meta.tmux_session ?? null,
+        pane: meta.pane ?? null,
+        final_report: meta.final_report ?? null,
+        finalized_at: meta.finalized_at ?? null,
+        deadline_at: meta.deadline_at ?? null,
+        telemetry_tokens_in: meta.telemetry_tokens_in ?? null,
+        telemetry_context_tokens: meta.telemetry_context_tokens ?? null,
+        telemetry_last_activity: meta.telemetry_last_activity ?? null,
+        telemetry_updated_at: meta.telemetry_updated_at ?? null,
+        outcome: await toNodeOutcomeDTO(meta),
+        fault: meta.fault && meta.fault.link !== 'broker↔crtrd' ? { ...meta.fault, link: meta.fault.link } : null,
+        streaming: meta.streaming ?? false,
+        creator: meta.creator ?? null,
+        edges: toNodeEdgesDTO(meta, edges),
+        paths: await toNodePathsDTO(meta.node_id, grantee),
+    };
+    if (meta.description !== undefined)
+        dto.description = meta.description;
+    if (meta.title !== undefined)
+        dto.title = meta.title;
+    if (meta.icon !== undefined)
+        dto.icon = meta.icon;
+    if (meta.cycles !== undefined)
+        dto.cycles = meta.cycles;
+    dto.context_tokens = meta.telemetry_context_tokens ?? meta.telemetry_tokens_in ?? null;
+    if (meta.pi_session_id !== undefined)
+        dto.pi_session_id = meta.pi_session_id ?? null;
+    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
+            : {
+                ...(meta.review_binding.kind === undefined ? {} : { kind: meta.review_binding.kind }),
+                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;
+}
+// Action-result projections
+/** Project a `reviveNode` result. `revived` is true only when a fresh launch
+ *  actually happened — the double-revive no-op (already-alive) returns without a
+ *  `launch` handle, so its absence is the "nothing relaunched" signal. `status`
+ *  is the caller's post-revive row read. */
+export function toReviveResultDTO(nodeId, result, status, ready) {
+    return {
+        node_id: nodeId,
+        revived: result.launch !== undefined,
+        resumed: result.resumed,
+        status,
+        outcome: result.outcome,
+        ready,
+    };
+}
+/** Project a `closeNode` cascade result. Field names align 1:1. */
+export function toCloseResultDTO(result) {
+    return {
+        root: result.root,
+        closed: [...result.closed],
+        spared: [...result.spared],
+    };
+}
+/** Project a feed `push` result into a push-report result. `transitioned` is
+ *  supplied by the handler only for a `final` push (the server-side lifecycle
+ *  flip); an update/urgent push omits it. */
+export function toReportResultDTO(result, transitioned, autoDroppedWorktreePath) {
+    const dto = {
+        report: result.report,
+        notified: [...result.deliveredTo],
+    };
+    if (transitioned !== undefined)
+        dto.transitioned = transitioned;
+    if (autoDroppedWorktreePath !== undefined) {
+        dto.worktree_auto_dropped = true;
+        dto.worktree_auto_dropped_path = autoDroppedWorktreePath;
+    }
+    return dto;
+}
+/** Project a subscription ref as seen from one endpoint. */
+export function toSubscriptionDTO(ref) {
+    return {
+        node_id: ref.node_id,
+        active: ref.active,
+        created: ref.created,
+    };
+}
+/** The NAMES of a cron's snapshotted extra env vars. Keys only — the values
+ *  stay server-side because a chosen env can carry a credential. A malformed
+ *  stored value reads as no extra env rather than crashing a list. */
+function envKeys(envJson) {
+    if (envJson === null || envJson === '')
+        return [];
+    try {
+        const parsed = JSON.parse(envJson);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? Object.keys(parsed) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Project a cron row into its DTO — a straight column projection minus the
+ *  internal lease plumbing (run_pid/run_lease_owner/env_json/last_output_hash/
+ *  queued stay server-side); the sink JSON is rendered back to its display
+ *  spec. `lastRun` is the most recent settled run — the recent health every
+ *  cron projection carries so `cron list` needs no `cron show` per row. */
+export function toCronDTO(c, lastRun) {
+    return {
+        cron_id: c.cron_id,
+        name: c.name,
+        created_by: c.created_by,
+        command: c.command,
+        grant_id: c.grant_id,
+        scopes: c.scopes,
+        origin_run_id: c.origin_run_id,
+        isolated: c.isolated,
+        fire_at: c.fire_at,
+        recur: c.recur,
+        tz: c.tz,
+        expires_at: c.expires_at,
+        anchor_node: c.anchor_node,
+        cancel_on_wake: c.cancel_on_wake,
+        cwd: c.cwd,
+        profile: c.profile,
+        scope: c.scope,
+        env_keys: envKeys(c.env_json),
+        run_timeout_s: c.run_timeout_s,
+        overlap: c.overlap,
+        on_output: c.on_output,
+        sink: cronSinkDisplay(c.sink),
+        tier: c.tier,
+        state: c.state,
+        held: c.held,
+        run_state: c.run_state,
+        last_run: lastRun === undefined || lastRun === null
+            ? null
+            : { finished: lastRun.finished, exit_code: lastRun.exit_code, delivered: lastRun.delivered },
+        created: c.created,
+        updated: c.updated,
+    };
+}
+/** Project one settled run-log record into its DTO — a straight projection
+ *  minus the redundant cron_id (the route already names the cron). */
+export function toCronRunDTO(r) {
+    return {
+        run_id: r.run_id,
+        started: r.started,
+        finished: r.finished,
+        duration_ms: r.duration_ms,
+        exit_code: r.exit_code,
+        stdout_head: r.stdout_head,
+        stderr_head: r.stderr_head,
+        delivered: r.delivered,
+    };
+}
+/** Project a profile-manifest entry into its DTO. `default_dir` (the directory
+ *  this profile is pinned as default for) is a reverse lookup not carried on the
+ *  entry, so it is left null here — a caller that needs it resolves it
+ *  separately. Project entries are cloned: the manifest entry is shared cache
+ *  state, so handing out its objects would let a DTO consumer mutate it. */
+export function toProfileDTO(entry) {
+    return {
+        id: entry.profileId,
+        app: entry.manifest.grantee ?? 'app:terminal',
+        name: entry.manifest.name,
+        projects: entry.manifest.projects.map((p) => ({ ...p })),
+        delivery_limits: { ...entry.manifest.delivery_limits },
+        paused_at: entry.manifest.paused_at,
+        default_kind: entry.manifest.default_kind ?? 'general',
+        metadata: sanitizeProfileMetadata(entry.manifest.metadata),
+        default_dir: null,
+        created_at: entry.manifest.created_at,
+        last_used_at: entry.manifest.last_used_at,
+        profile_path: profileDir(entry.profileId),
+    };
+}
+/** 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,
+        review_dir: row.review_dir,
+        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.document_name !== null)
+        dto.document = row.document_name;
+    if (row.opened_at !== null)
+        dto.opened_at = row.opened_at;
+    if (row.submit_requested_at !== null)
+        dto.submit_requested_at = row.submit_requested_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 {
+        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 ticket-attached page feedback comment. */
+export function toPageFeedbackCommentDTO(comment) {
+    return {
+        id: comment.id,
+        quote: comment.quote,
+        ...(comment.context === undefined ? {} : { context: comment.context }),
+        note: comment.note,
+        status: comment.status,
+        created_at: comment.createdAt,
+        ...(comment.resolvedAt === undefined ? {} : { resolved_at: comment.resolvedAt }),
+    };
+}
+/** Project one ticket's page feedback state. */
+export function toPageFeedbackDTO(feedback) {
+    return {
+        companion_node_id: feedback.companionNodeId ?? null,
+        open_count: feedback.comments.filter((comment) => comment.status === 'open').length,
+        comments: feedback.comments.map(toPageFeedbackCommentDTO),
+    };
+}
+/** 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_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_terminal: { status: 409, code: 'review_terminal_conflict' },
+    review_required: { status: 400, code: 'review_required' },
+    stale_document: { status: 409, code: 'stale_document' },
+    stale_revision: { status: 409, code: 'stale_revision' },
+    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;
+ *   - a feed `FinalizationError` → 409 `already_finalized` /
+ *     `finalization_forbidden`, or 404 `node_not_found`;
+ *   - a `NodeIdConflictError` (a `--node-id`/`node_id` spawn at an id that
+ *     already exists) → 409 `node_id_exists`;
+ *   - a `WorktreeError` → its own code at 400 (404 for `unknown_node`), with
+ *     `next` + git `detail` preserved as CrtrError details;
+ *   - `reviveNode`'s finalization-latch throw → 409 `already_finalized`;
+ *   - an "unknown node" throw (reviveNode / transition / getNode-null handler) →
+ *     404 `node_not_found`;
+ *   - a `transition` illegal-move throw → 409 `illegal_transition`;
+ *   - anything already carrying a numeric `status` + string `code` (an
+ *     `ApiError`-shaped throw) → used verbatim;
+ *   - anything else → 500 `internal`.
+ *  The recognized plain-`Error` cases match on the throw sites' messages (the
+ *  only signal those sites carry); the source sites are named above so a message
+ *  change there is caught by the A-11 tests. */
+export function errorToStatus(thrown) {
+    const err = normalizeThrow(thrown);
+    // An already-shaped API-style throw (e.g. a re-thrown ApiError) — trust it.
+    if (typeof err === 'object' &&
+        err !== null &&
+        typeof err.status === 'number' &&
+        typeof err.code === 'string') {
+        return {
+            status: err.status,
+            code: err.code,
+        };
+    }
+    if (err instanceof FinalizationError) {
+        if (err.code === 'unknown_node')
+            return { status: 404, code: 'node_not_found' };
+        if (err.code === 'already_finalized')
+            return { status: 409, code: 'already_finalized' };
+        return { status: 409, code: 'finalization_forbidden' };
+    }
+    if (err instanceof NodeIdConflictError) {
+        return { status: 409, code: 'node_id_exists' };
+    }
+    if (err instanceof ScopeDeniedError) {
+        return { status: 403, code: 'scope_denied' };
+    }
+    // A caller's path met a symlink or left its permitted root (open-beneath): bad input, not a fault.
+    if (isBeneathRefusal(err))
+        return { status: 400, code: 'invalid_request' };
+    if (err instanceof ReviewOperationErrorClass) {
+        return REVIEW_ERROR_MAP[err.code];
+    }
+    if (err instanceof CrtrError) {
+        if (['kind_owned', 'name_taken', 'hop_limit', 'not_a_queue'].includes(err.code))
+            return { status: 409, code: err.code };
+        if (err.code === 'invalid_publish_token')
+            return { status: 401, code: err.code };
+        if (err.code === 'forbidden' || err.code === 'argv_forbidden' || err.code === 'scope_missing')
+            return { status: 403, code: err.code };
+        return { status: statusForExitCode(err.exitCode), code: err.code };
+    }
+    if (err instanceof Error) {
+        const m = err.message;
+        if (/unknown node/i.test(m))
+            return { status: 404, code: 'node_not_found' };
+        if (/finalization latch/i.test(m))
+            return { status: 409, code: 'already_finalized' };
+        if (/illegal lifecycle transition/i.test(m)) {
+            return { status: 409, code: 'illegal_transition' };
+        }
+    }
+    return { status: 500, code: 'internal' };
+}
+/** A `WorktreeError` is bad input or a repository-state conflict, never a daemon
+ *  fault, so it is projected onto the `CrtrError` contract: its specific code,
+ *  its `next` remediation, and its git `detail` all survive to the caller
+ *  instead of collapsing into an opaque 500. The details carry the FULL
+ *  `{error, message, next}` payload so `apiErrorToCliError` reconstructs the
+ *  worktree contract verbatim rather than degrading to `invalid_request`. */
+function normalizeThrow(err) {
+    if (!(err instanceof WorktreeError))
+        return err;
+    const exitCode = err.code === 'unknown_node' ? ExitCode.NOT_FOUND : ExitCode.GENERAL;
+    const details = { error: err.code, message: err.message, next: err.next };
+    if (err.detail !== undefined)
+        details['received'] = err.detail;
+    return new CrtrError(err.code, err.message, exitCode, details);
+}
+/** 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: terminalConflictReviewDTO(review),
+    };
+}
+function terminalConflictReviewDTO(review) {
+    if (review.state !== 'approved')
+        return toReviewDTO(review);
+    return toReviewDTO(review, { result_path: join(review.review_dir, 'result.json') });
+}
+function statusForExitCode(exitCode) {
+    switch (exitCode) {
+        case ExitCode.NOT_FOUND:
+            return 404;
+        case ExitCode.USAGE:
+            return 400;
+        case ExitCode.AMBIGUOUS:
+            return 400;
+        case ExitCode.NETWORK:
+            return 503;
+        case ExitCode.GENERAL:
+            return 400;
+        default:
+            return 500;
+    }
+}
+/** The single-line, length-bounded cause a 500 body may safely carry. A curated
+ *  `Error.message` is a diagnostic, not a raw stack trace: surfacing its first
+ *  line (capped) turns an opaque `internal error` into an actionable one while
+ *  still refusing to leak multi-line traces. The router logs the FULL error
+ *  (with stack) server-side alongside this. */
+function boundedCause(err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const firstLine = raw.split('\n', 1)[0].trim();
+    if (firstLine === '')
+        return 'internal error';
+    return firstLine.length > 500 ? `${firstLine.slice(0, 497)}…` : firstLine;
+}
+/** Build the uniform JSON error body (spec §8) for a thrown value, using
+ *  `errorToStatus` for the status/code. Structured `details` are surfaced for a
+ *  CrtrError or ApiError (they let the client reconstruct the error verbatim). A 500 still
+ *  omits `details` for hygiene, but NO LONGER strips the message to a bare
+ *  `internal error`: it surfaces the bounded cause (`boundedCause`) so a caller
+ *  is never left with a causeless internal, while the router logs the full
+ *  error (with stack) server-side. */
+export function toErrorBody(thrown) {
+    const err = normalizeThrow(thrown);
+    const { status, code } = errorToStatus(err);
+    if (status >= 500) {
+        const body = { error: { code, message: boundedCause(err), origin: 'runtime' } };
+        if (err instanceof RunError)
+            body.error.retryable = err.retryable;
+        return { status, body };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const details = err instanceof ReviewOperationErrorClass
+        ? reviewErrorDetails(err)
+        : (err instanceof CrtrError || err instanceof ApiError || err instanceof RunError) && err.details !== undefined
+            ? err.details
+            : undefined;
+    const body = { error: { code, message, origin: 'runtime' } };
+    if (details !== undefined)
+        body.error.details = details;
+    if (err instanceof RunError) {
+        if (err.param)
+            body.error.param = err.param;
+        if (err.scope)
+            body.error.scope = err.scope;
+        body.error.retryable = err.retryable;
+    }
+    return { status, body };
+}