@north-light/crouter 0.3.198 → 0.3.199

package/dist/daemon/api/__tests__/seam/profile-delete.test.js

@@ -0,0 +1,386 @@
+// Compiled API seam for the profile-deletion lifecycle. It drives the real CLI
+// and daemon HTTP handlers against one isolated canvas, including real broker
+// processes for detach/restart and deferred self-deletion behavior.
+import { request as httpRequest } from 'node:http';
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { ApiError, CrtrClient } from '../../../../api/index.js';
+import { createHeadlessHarness } from '../../../../core/__tests__/helpers/harness.js';
+import { updateNode } from '../../../../core/canvas/canvas.js';
+import { armCron, getCron } from '../../../../core/canvas/crons.js';
+import { closeDb } from '../../../../core/canvas/db.js';
+import { getDefaultProfileId, setDefaultProfileId, } from '../../../../core/profiles/default-binding.js';
+import { loadProfileManifest } from '../../../../core/profiles/manifest.js';
+import { createComment, getComment, listReviewEvents } from '../../../../core/review/comments.js';
+import { commitBindingReview, getReview } from '../../../../core/review/store.js';
+import { apiSocketPath, nodeDir, nodesRoot, reviewDir, } from '../../../../core/canvas/paths.js';
+import { isPidAlive } from '../../../../core/canvas/pid.js';
+import { spawnNode } from '../../../../core/runtime/nodes.js';
+let h;
+let client;
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-profile-delete' });
+    client = new CrtrClient({ socketPath: apiSocketPath(), autostart: false });
+});
+after(async () => {
+    await h?.dispose();
+});
+function managedWorktree() {
+    return {
+        state: 'open',
+        path: join(h.agentHome, 'open-worktree'),
+        branch: 'test/profile-delete-blocker',
+        repo_root: process.cwd(),
+        base_ref: 'HEAD',
+        base_sha: '0000000000000000000000000000000000000000',
+        created: new Date().toISOString(),
+    };
+}
+function armTestCron(args) {
+    armCron({
+        cron_id: args.id,
+        name: args.id,
+        created_by: null,
+        command: 'true',
+        fire_at: '2099-01-01T00:00:00.000Z',
+        recur: null,
+        tz: null,
+        expires_at: null,
+        anchor_node: args.anchor ?? null,
+        cancel_on_wake: false,
+        cwd: process.cwd(),
+        env_json: null,
+        profile: args.profile,
+        scope: 'profile',
+        run_timeout_s: 30,
+        overlap: 'skip',
+        on_output: 'silent',
+        sink: '{}',
+        tier: 'normal',
+    });
+}
+function seedTicket(dir, sourceNodeId) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'page.json'), JSON.stringify({ source: { nodeId: sourceNodeId } }));
+    writeFileSync(join(dir, 'reply-route.json'), JSON.stringify({ nodeId: sourceNodeId }));
+}
+function reviewRow(reviewId, originNodeId, sourceFile) {
+    const dir = reviewDir(reviewId);
+    return {
+        review_id: reviewId,
+        idempotency_key: `request-${reviewId}`,
+        origin_kind: 'inline',
+        origin_node_id: originNodeId,
+        bridge_node_id: null,
+        companion_node_id: `companion-${reviewId}`,
+        review_dir: dir,
+        file: sourceFile,
+        origin_session_file: join(h.agentHome, `${reviewId}-origin.jsonl`),
+        origin_session_id: `session-${reviewId}`,
+        origin_leaf_id: `leaf-${reviewId}`,
+        model_spec: 'anthropic/sonnet',
+        branch_file: join(dir, 'branch-point.jsonl'),
+        baseline_sha256: 'baseline',
+        baseline_bytes: 6,
+        anchor_base_sha256: 'anchor',
+        anchor_base_bytes: Buffer.from('source'),
+        state: 'binding',
+        created: new Date().toISOString(),
+        captured_at: new Date().toISOString(),
+        opened_at: null,
+        submit_requested_at: null,
+        output_path: null,
+        subtitle: null,
+        approved_at: null,
+        approved_sha256: null,
+        changed: null,
+        comments_total: null,
+        comments_unresolved: null,
+        result_json: null,
+        canceled_at: null,
+        cancel_reason: null,
+        cancel_actor: null,
+        delivery_entry_id: null,
+        delivered_at: null,
+        delivery_error: null,
+        projected_at: null,
+        projection_error: null,
+    };
+}
+function seedReview(reviewId, originNodeId) {
+    const sourceFile = join(h.agentHome, `${reviewId}-source.md`);
+    const dir = reviewDir(reviewId);
+    writeFileSync(sourceFile, 'source\n');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'branch-point.jsonl'), '{}\n');
+    commitBindingReview(reviewRow(reviewId, originNodeId, sourceFile));
+    const { comment } = createComment({
+        review_id: reviewId,
+        text: 'keep or delete with its review',
+        anchor: { line: 1, end_line: 1 },
+        line_text: 'source',
+        doc_hash: 'baseline',
+        actor: { kind: 'node', node_id: originNodeId },
+        operation_id: `comment-${reviewId}`,
+    });
+    return { sourceFile, commentId: comment.comment_id };
+}
+async function rawDelete(profile, body) {
+    const payload = JSON.stringify(body);
+    return new Promise((resolve, reject) => {
+        const req = httpRequest({
+            socketPath: apiSocketPath(),
+            method: 'DELETE',
+            path: `/v1/profiles/${encodeURIComponent(profile)}`,
+            headers: {
+                'content-type': 'application/json',
+                'content-length': Buffer.byteLength(payload),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                const text = Buffer.concat(chunks).toString('utf8');
+                resolve({
+                    status: res.statusCode ?? 0,
+                    body: text === '' ? {} : JSON.parse(text),
+                });
+            });
+        });
+        req.on('error', reject);
+        req.end(payload);
+    });
+}
+test('forced profile deletion owns the complete daemon lifecycle', { timeout: 90_000 }, async () => {
+    // Required confirmation is enforced by both the command parser and the API.
+    const forceProfile = await client.ensureProfile('delete-force-required');
+    const help = h.cli(null, ['profile', 'delete', '-h']);
+    assert.equal(help.code, 0);
+    assert.match(help.stdout, /--force\s+required boolean/, 'leaf help exposes --force as required');
+    const missingForce = h.cli(null, ['profile', 'delete', forceProfile.id]);
+    assert.notEqual(missingForce.code, 0, 'the CLI refuses deletion without --force');
+    assert.match(`${missingForce.stdout}\n${missingForce.stderr}`, /force/i);
+    await assert.rejects(client.deleteProfile(forceProfile.id, { force: false }), (error) => error instanceof ApiError && error.status === 400 && error.code === 'usage', 'the daemon independently rejects a request without force=true');
+    assert.equal((await client.getProfile(forceProfile.id)).id, forceProfile.id, 'force rejection does not remove the profile');
+    // An open managed worktree blocks before any profile-owned state mutates.
+    const blockedProfile = await client.ensureProfile('delete-blocked');
+    const blockedNode = h.spawnRoot('profile delete blocker', { id: 'blocked-profile-deadbeef' });
+    updateNode(blockedNode, {
+        profile_id: blockedProfile.id,
+        managed_worktree: managedWorktree(),
+    });
+    const blockedPin = join(h.agentHome, 'blocked-pin');
+    mkdirSync(blockedPin, { recursive: true });
+    setDefaultProfileId(blockedPin, blockedProfile.id);
+    armTestCron({ id: 'blocked-cron', profile: blockedProfile.id, anchor: blockedNode });
+    await assert.rejects(client.deleteProfile(blockedProfile.id, { force: true }), (error) => {
+        if (!(error instanceof ApiError) || error.status !== 400 || error.code !== 'usage')
+            return false;
+        const details = error.details;
+        return details?.error === 'open_managed_worktree';
+    }, 'an open managed worktree round-trips the blocker without mutation');
+    closeDb();
+    assert.equal(h.node(blockedNode)?.profile_id, blockedProfile.id);
+    assert.equal(getCron('blocked-cron')?.profile, blockedProfile.id);
+    assert.equal(getDefaultProfileId(blockedPin), blockedProfile.id);
+    assert.equal((await client.getProfile(blockedProfile.id)).id, blockedProfile.id);
+    // Hard deletion selects by profile identity, not by graph descent. It removes
+    // matching nodes plus profile/anchor crons, originating tickets and review
+    // audit state, while preserving a cross-profile child and the reviewed file.
+    const hardProfile = await client.ensureProfile('delete-hard');
+    const crossProfile = await client.ensureProfile('delete-cross-profile');
+    const hardNode = h.fabricateBrokerNode({
+        id: 'hard-owner-deadbeef',
+        parent: null,
+        status: 'done',
+    });
+    updateNode(hardNode, { profile_id: hardProfile.id });
+    const crossChild = h.fabricateBrokerNode({
+        id: 'cross-child-deadbeef',
+        parent: hardNode,
+        status: 'done',
+    });
+    updateNode(crossChild, { profile_id: crossProfile.id });
+    armTestCron({ id: 'hard-profile-cron', profile: hardProfile.id });
+    armTestCron({ id: 'hard-anchor-cron', profile: crossProfile.id, anchor: hardNode });
+    armTestCron({ id: 'cross-preserved-cron', profile: crossProfile.id, anchor: crossChild });
+    const hardPin = join(h.agentHome, 'hard-pin');
+    mkdirSync(hardPin, { recursive: true });
+    setDefaultProfileId(hardPin, hardProfile.id);
+    const standaloneTicket = join(nodesRoot(), 'hard-ticket-deadbeef');
+    seedTicket(standaloneTicket, hardNode);
+    seedTicket(nodeDir(crossChild), hardNode);
+    writeFileSync(join(nodeDir(crossChild), 'feedback.json'), '{}\n');
+    mkdirSync(join(nodeDir(crossChild), '.ticket-lock'));
+    writeFileSync(join(nodeDir(crossChild), 'cross-profile-state.txt'), 'preserve');
+    const hardReviewId = 'hard-review-deadbeef';
+    const hardReview = seedReview(hardReviewId, hardNode);
+    const hardResult = await client.deleteProfile(hardProfile.id, { force: true });
+    assert.deepEqual(hardResult, {
+        profile_id: hardProfile.id,
+        name: hardProfile.name,
+        mode: 'deleted',
+        nodes: 1,
+        crons: 2,
+        tickets: 2,
+        reviews: 1,
+        default_pins: 1,
+    });
+    closeDb();
+    assert.equal(h.node(hardNode), null, 'the matching node is hard-deleted');
+    assert.equal(h.node(crossChild)?.parent, hardNode, 'the cross-profile child and topology are preserved');
+    assert.equal(h.node(crossChild)?.profile_id, crossProfile.id);
+    assert.equal(getCron('hard-profile-cron'), null);
+    assert.equal(getCron('hard-anchor-cron'), null);
+    assert.equal(getCron('cross-preserved-cron')?.profile, crossProfile.id);
+    assert.equal(existsSync(standaloneTicket), false, 'standalone originating ticket directory is removed');
+    assert.equal(existsSync(join(nodeDir(crossChild), 'page.json')), false, 'ticket files are removed from a preserved node directory');
+    assert.equal(existsSync(join(nodeDir(crossChild), 'feedback.json')), false, 'default review output is removed with the ticket');
+    assert.equal(existsSync(join(nodeDir(crossChild), '.ticket-lock')), false, 'ticket lock residue is removed');
+    assert.equal(readFileSync(join(nodeDir(crossChild), 'cross-profile-state.txt'), 'utf8'), 'preserve');
+    assert.equal(getReview(hardReviewId), null);
+    assert.equal(getComment(hardReview.commentId), null);
+    assert.deepEqual(listReviewEvents(hardReviewId, {}), { events: [], next_since_seq: 0 });
+    assert.equal(existsSync(reviewDir(hardReviewId)), false, 'review-owned filesystem state is removed');
+    assert.equal(readFileSync(hardReview.sourceFile, 'utf8'), 'source\n', 'the reviewed source document is never removed');
+    assert.equal(getDefaultProfileId(hardPin), null);
+    await assert.rejects(client.getProfile(hardProfile.id), (error) => error instanceof ApiError && error.status === 404);
+    assert.throws(() => spawnNode({
+        kind: 'developer',
+        cwd: process.cwd(),
+        parent: null,
+        profile_id: hardProfile.id,
+        nodeId: 'hard-stale-birth-deadbeef',
+    }), /profile not found/, 'the final synchronous birth gate rejects a profile resolved before a completed hard deletion');
+    assert.equal(h.node('hard-stale-birth-deadbeef'), null);
+    // Detach preserves nodes, topology, ticket/review state, and conversations;
+    // matching brokers restart with no profile identity and matching crons become
+    // global rather than disappearing.
+    const detachProfile = await client.ensureProfile('delete-detach');
+    const detachNode = (await client.createNode({
+        kind: 'developer',
+        profile: detachProfile.id,
+        root: true,
+        cwd: process.cwd(),
+        prompt: 'detach lifecycle broker',
+        node_id: 'detach-live-deadbeef',
+    })).node_id;
+    await h.awaitBoot(detachNode);
+    const detachBoots = h.bootCount(detachNode);
+    const detachSessionFile = h.node(detachNode)?.pi_session_file;
+    assert.ok(detachSessionFile != null, 'the live detach fixture has a resumable conversation');
+    armTestCron({ id: 'detach-profile-cron', profile: detachProfile.id, anchor: detachNode });
+    const detachPin = join(h.agentHome, 'detach-pin');
+    mkdirSync(detachPin, { recursive: true });
+    setDefaultProfileId(detachPin, detachProfile.id);
+    const detachTicket = join(nodesRoot(), 'detach-ticket-deadbeef');
+    seedTicket(detachTicket, detachNode);
+    const detachReviewId = 'detach-review-deadbeef';
+    const detachReview = seedReview(detachReviewId, detachNode);
+    const detachPid = h.node(detachNode)?.pi_pid;
+    assert.ok(detachPid != null, 'the detach race fixture has a live broker pid');
+    process.kill(detachPid, 'SIGSTOP');
+    const detachDeletion = client.deleteProfile(detachProfile.id, { force: true, detach: true });
+    try {
+        await h.waitFor(() => h.node(detachNode)?.intent === 'idle-release', {
+            timeoutMs: 10_000,
+            intervalMs: 25,
+            label: 'detach reaches its broker-exit wait',
+        });
+        await assert.rejects(client.createNode({
+            kind: 'developer',
+            profile: detachProfile.id,
+            root: true,
+            cwd: process.cwd(),
+            prompt: 'must not escape the accepted detach plan',
+            node_id: 'detach-race-deadbeef',
+        }), (error) => {
+            if (!(error instanceof ApiError) || error.status !== 400 || error.code !== 'usage')
+                return false;
+            const details = error.details;
+            return details?.error === 'profile_deletion_in_progress';
+        }, 'a node whose async preflight crosses detach is rejected at the synchronous birth gate');
+    }
+    finally {
+        if (isPidAlive(detachPid))
+            process.kill(detachPid, 'SIGCONT');
+    }
+    const detachResult = await detachDeletion;
+    assert.deepEqual(detachResult, {
+        profile_id: detachProfile.id,
+        name: detachProfile.name,
+        mode: 'detached',
+        nodes: 1,
+        crons: 1,
+        tickets: 0,
+        reviews: 0,
+        default_pins: 1,
+    });
+    const restarted = await h.awaitBoot(detachNode, { minCount: detachBoots + 1 });
+    closeDb();
+    assert.equal(h.node(detachNode)?.profile_id, null);
+    assert.equal(h.node('detach-race-deadbeef'), null, 'no profile-scoped node escapes the fixed detach plan');
+    assert.equal(h.node(detachNode)?.pi_session_file, detachSessionFile, 'detach preserves the conversation file');
+    assert.equal(restarted.sessionFile, detachSessionFile, 'the restarted broker resumes that conversation file');
+    assert.equal(restarted.resuming, true, 'the previously live broker is restarted as a resume');
+    assert.equal(restarted.env['CRTR_PROFILE_ID'], '', 'the restarted broker no longer names the deleted profile');
+    assert.equal(getCron('detach-profile-cron')?.scope, 'global');
+    assert.equal(getCron('detach-profile-cron')?.profile, null);
+    assert.equal(existsSync(join(detachTicket, 'page.json')), true);
+    assert.equal(getReview(detachReviewId)?.origin_node_id, detachNode);
+    assert.ok(getComment(detachReview.commentId) !== null);
+    assert.equal(existsSync(reviewDir(detachReviewId)), true);
+    assert.equal(getDefaultProfileId(detachPin), null);
+    await assert.rejects(client.getProfile(detachProfile.id), (error) => error instanceof ApiError && error.status === 404);
+    // A node deleting its own profile receives HTTP 202 while its row and broker
+    // are still alive. The daemon performs the accepted hard deletion only after
+    // the response grace has elapsed.
+    const selfProfile = await client.ensureProfile('delete-self');
+    const selfNode = (await client.createNode({
+        kind: 'developer',
+        profile: selfProfile.id,
+        root: true,
+        cwd: process.cwd(),
+        prompt: 'self-delete lifecycle broker',
+        node_id: 'self-delete-deadbeef',
+    })).node_id;
+    await h.awaitBoot(selfNode);
+    const selfPid = h.node(selfNode)?.pi_pid;
+    assert.ok(selfPid != null && isPidAlive(selfPid), 'self-delete fixture starts with a live broker');
+    const accepted = await rawDelete(selfProfile.id, {
+        force: true,
+        caller_node_id: selfNode,
+    });
+    assert.equal(accepted.status, 202);
+    assert.deepEqual(accepted.body, {
+        profile_id: selfProfile.id,
+        name: selfProfile.name,
+        mode: 'deleted',
+        nodes: 1,
+        crons: 0,
+        tickets: 0,
+        reviews: 0,
+        default_pins: 0,
+        accepted: true,
+        grace_ms: 1000,
+    });
+    assert.equal(h.node(selfNode)?.profile_id, selfProfile.id, 'the 202 response settles before node mutation');
+    assert.equal(isPidAlive(selfPid), true, 'the 202 response settles before broker teardown');
+    updateNode(selfNode, { managed_worktree: managedWorktree() });
+    const repeatedAccepted = await rawDelete(selfProfile.id, {
+        force: true,
+        caller_node_id: selfNode,
+    });
+    updateNode(selfNode, { managed_worktree: null });
+    assert.equal(repeatedAccepted.status, 202, 'a retry returns the accepted result before observing new blockers');
+    assert.deepEqual(repeatedAccepted.body, accepted.body, 'a pending self-deletion is idempotent by profile identity');
+    await h.waitFor(() => h.node(selfNode) === null, {
+        timeoutMs: 15_000,
+        intervalMs: 25,
+        label: 'accepted self-deletion completes after acknowledgement grace',
+    });
+    assert.equal(loadProfileManifest(crossProfile.id).profileId, crossProfile.id, 'unrelated profiles remain resolvable');
+    await assert.rejects(client.getProfile(selfProfile.id), (error) => error instanceof ApiError && error.status === 404);
+});

package/dist/daemon/api/handlers/bash-jobs.js

@@ -66,7 +66,7 @@ async function handleStop(ctx) {
     // that same fail-loud behavior here after the job control-plane mutation.
     assertNotFinalized(nodeId);
     const paths = bashJobPaths(dir, jobId);
-    const body = `Background bash job ${jobId} was stopped by the human before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`;
+    const body = `Background bash job ${jobId} was stopped by the user before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`;
     appendInbox(nodeId, {
         from: null,
         tier: 'urgent',

package/dist/daemon/api/handlers/broker-ops.js

@@ -11,6 +11,7 @@ import { readCursor, readInboxSince, writeCursor } from '../../../core/feed/inbo
 import { clearYieldMessage } from '../../../core/runtime/kickoff.js';
 import { transition } from '../../../core/runtime/lifecycle.js';
 import { focusOf, tearDownNode } from '../../../core/runtime/placement.js';
+import { hasAttachedBrokerViewers } from '../../../core/runtime/broker/client-registry.js';
 import { handleNewSession } from '../../../core/runtime/reset.js';
 import { evaluateStop } from '../../../core/runtime/stop-guard.js';
 import { clearFault } from '../../../core/runtime/fault.js';
@@ -46,7 +47,7 @@ function parseSettleBody(body) {
     const value = objectBody(body, 'broker settle');
     if (typeof value['stopReason'] !== 'string')
         throw usage('stopReason must be a string');
-    for (const field of ['backgroundJobsRunning', 'pushedFinal', 'askedHuman']) {
+    for (const field of ['backgroundJobsRunning', 'pushedFinal', 'requestedHumanReply']) {
         if (typeof value[field] !== 'boolean')
             throw usage(`${field} must be a boolean`);
     }
@@ -97,6 +98,7 @@ function extensionNode(node) {
         profile_id: node.profile_id ?? null,
         ...(node.managed_worktree === undefined ? {} : { managed_worktree: node.managed_worktree === null ? null : {
                 state: node.managed_worktree.state,
+                ...(node.managed_worktree.cleanup === undefined ? {} : { cleanup: node.managed_worktree.cleanup }),
                 path: node.managed_worktree.path,
                 branch: node.managed_worktree.branch,
                 base_ref: node.managed_worktree.base_ref,
@@ -234,7 +236,7 @@ function settleBroker(nodeId, request) {
         // broker alive while never fabricating a replacement canvas row.
         if (request.pushedFinal)
             return { action: 'shutdown' };
-        if (request.askedHuman)
+        if (request.requestedHumanReply)
             return { action: 'stay_dormant' };
         throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
     }
@@ -254,7 +256,7 @@ function settleBroker(nodeId, request) {
         clearFault(nodeId, { link: 'daemon→node' });
         return node.intent === 'refresh' ? { action: 'shutdown' } : { action: 'stay_dormant' };
     }
-    const signals = { pushedFinal: request.pushedFinal, askedHuman: request.askedHuman };
+    const signals = { pushedFinal: request.pushedFinal, requestedHumanReply: request.requestedHumanReply };
     // Two current-state outcomes: terminal broker consequences, not Pi decisions.
     if (signals.pushedFinal || node.status === 'done') {
         clearFault(nodeId);
@@ -263,7 +265,7 @@ function settleBroker(nodeId, request) {
         setPresence(nodeId, { pane: null, tmux_session: null, window: null });
         return { action: 'shutdown' };
     }
-    if (signals.askedHuman) {
+    if (signals.requestedHumanReply) {
         clearFault(nodeId);
         return { action: 'stay_dormant' };
     }
@@ -281,7 +283,9 @@ function settleBroker(nodeId, request) {
     if (decision.reason !== 'awaiting' && decision.reason !== 'scheduled') {
         return { action: 'stay_dormant' };
     }
-    if (focusOf(nodeId) !== null || hasUnseenNonDeferredInbox(nodeId))
+    if (focusOf(nodeId) !== null
+        || hasAttachedBrokerViewers(nodeId)
+        || hasUnseenNonDeferredInbox(nodeId))
         return { action: 'stay_dormant' };
     transition(nodeId, 'release');
     return { action: 'shutdown' };

package/dist/daemon/api/handlers/feedback-comments.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const feedbackCommentRoutes: RouteTable;

package/dist/daemon/api/handlers/feedback-comments.js

@@ -0,0 +1,207 @@
+// Page feedback-comment routes — notes the human leaves on highlighted page
+// content, addressed by the same opaque inbox ticket ids as the page routes.
+// The first comment on a ticket realizes its companion conversation — a fork
+// of the sending node's current state, bound to the ticket for good — and
+// every comment is then delivered to that companion as the person's own turn,
+// post-commit and best-effort. A sent comment is immutable: the only mutations
+// are create and the companion's resolve. Feedback never enters the page
+// response the sender reads at settle — it was already delivered; only
+// unresolved items ride the completion as an addendum.
+import { basename } from 'node:path';
+import { ApiError } from '../../../api/index.js';
+import { createPageFeedbackComment, readPageFeedback, resolvePageFeedbackComment, PageFeedbackCommentAlreadyResolvedError, PageTicketTerminalError, UnknownPageFeedbackCommentError, } from '../../../core/human/feedback.js';
+import { discardFeedbackCompanion, pageDocumentSha256, realizeFeedbackCompanion } from '../../../core/human/feedback-companion.js';
+import { parsePage } from '../../../core/human/page.js';
+import { pageTicketState } from '../../../core/human/tickets.js';
+import { deliverNodeMessage } from '../../messaging/node-message.js';
+import { requireTicketId, resolveTicket } from './inbox.js';
+import { invalidRequest, objectBody, optionalString, requiredString } from './validate.js';
+import { toPageFeedbackDTO, toPageFeedbackCommentDTO } from '../map.js';
+const COMMENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+// ---------------------------------------------------------------------------
+// Shared guards
+// ---------------------------------------------------------------------------
+/** Resolve a mutable page ticket: it must exist, be a page, and not have a
+ * terminal outcome. Passive pages never settle, so they stay commentable.
+ * A terminal ticket refuses every feedback action — settlement won. */
+function requireMutablePageTicket(ctx) {
+    const ticketId = requireTicketId(ctx.params);
+    const resolved = resolveTicket(ticketId);
+    if (resolved === null)
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    if (resolved.kind === 'review') {
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have no feedback comments');
+    }
+    const state = pageTicketState(resolved.dir);
+    if (state === 'resolved' || state === 'canceled') {
+        throw new ApiError(409, 'ticket_terminal', 'ticket already has a terminal outcome');
+    }
+    return resolved;
+}
+function requireCommentId(params) {
+    const commentId = params['comment_id'];
+    if (commentId === undefined || !COMMENT_ID.test(commentId)) {
+        throw new ApiError(400, 'invalid_request', 'invalid feedback comment id');
+    }
+    return commentId;
+}
+// ---------------------------------------------------------------------------
+// Delivery — the person's turn in the companion conversation
+// ---------------------------------------------------------------------------
+/** The comment as the person's own words: the quoted page content and the
+ * note, nothing else. The companion's briefing rides its bearings and
+ * persona, never the human turn. */
+function renderCommentTurn(comment) {
+    const quoted = comment.quote.split('\n').map((line) => `> ${line}`);
+    return [...quoted, '', comment.note].join('\n');
+}
+async function deliverCommentTurn(args) {
+    const target = args.mutation.feedback.companionNodeId;
+    if (target === undefined) {
+        // Comments exist only after a create recorded the companion, so a missing
+        // companion here is corrupted feedback state, not a deliverable situation.
+        throw new ApiError(500, 'internal', 'feedback has comments but no companion conversation');
+    }
+    try {
+        const delivery = await deliverNodeMessage({
+            node_id: target,
+            body: renderCommentTurn(args.mutation.comment),
+            label: args.title,
+            from: 'human',
+            mode: 'interactive',
+            data: { page_id: basename(args.dir), comment_id: args.mutation.comment.id, verb: 'create' },
+        });
+        return { target_node_id: target, status: 'delivered', via: delivery.via, woke: delivery.revived };
+    }
+    catch (error) {
+        // State was committed before delivery; a delivery failure remains a
+        // successful mutation.
+        return { target_node_id: target, status: 'failed', woke: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+// ---------------------------------------------------------------------------
+// POST /v1/human/inbox/:ticket_id/feedback-comments — create
+// ---------------------------------------------------------------------------
+function parseCreate(ctx) {
+    const violations = [];
+    const body = objectBody(ctx.body, ['quote', 'context', 'note'], violations);
+    const quote = requiredString(body, 'quote', violations);
+    const context = optionalString(body, 'context', violations);
+    const note = requiredString(body, 'note', violations);
+    if (violations.length > 0 || quote === undefined || note === undefined) {
+        invalidRequest('page feedback comment request', violations);
+    }
+    return { quote, ...(context === undefined ? {} : { context }), note };
+}
+async function handleCreate(ctx) {
+    const request = parseCreate(ctx);
+    const resolved = requireMutablePageTicket(ctx);
+    const manifest = parsePage(resolved.dir);
+    if (manifest.dialect !== 'jsx') {
+        throw new ApiError(409, 'page_dialect_unsupported', 'feedback comments exist only on TSX pages');
+    }
+    // Realize the companion before taking the ticket lock — forking is async and
+    // must not hold it. The store keeps an already-recorded companion, so a
+    // concurrent first comment wastes at most one idle fork (accepted
+    // single-human race). Any realization failure refuses the comment: no
+    // feedback is accepted without a visible conversation able to receive it.
+    let companionNodeId = readPageFeedback(resolved.dir).companionNodeId;
+    let firstCommentedSha256;
+    let realizedNow = false;
+    if (companionNodeId === undefined) {
+        const sender = manifest.source?.nodeId;
+        if (sender === undefined) {
+            throw new ApiError(409, 'ticket_has_no_sender', 'this page carries no sending node to deliver feedback to');
+        }
+        firstCommentedSha256 = pageDocumentSha256(resolved.dir);
+        try {
+            companionNodeId = await realizeFeedbackCompanion({
+                ticketId: resolved.ticketId,
+                dir: resolved.dir,
+                senderNodeId: sender,
+                title: manifest.title,
+            });
+        }
+        catch (error) {
+            throw new ApiError(409, 'fork_failed', `the sending node could not be forked: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        realizedNow = true;
+    }
+    // The fork awaited its bind outside the ticket lock, so settlement may have
+    // won meanwhile: the create mutation re-checks the ticket under the lock and
+    // refuses after a terminal outcome. A companion realized by THIS request is
+    // discarded whenever its commit did not land — refusal, write failure, or a
+    // lost first-comment race (the recorded companion wins; ours is a stray).
+    let mutation;
+    try {
+        mutation = createPageFeedbackComment(resolved.dir, { ...request, companionNodeId, firstCommentedSha256 });
+    }
+    catch (error) {
+        if (realizedNow)
+            discardFeedbackCompanion(companionNodeId);
+        if (error instanceof PageTicketTerminalError) {
+            throw new ApiError(409, 'ticket_terminal', 'ticket already has a terminal outcome');
+        }
+        throw error;
+    }
+    if (realizedNow && mutation.feedback.companionNodeId !== companionNodeId) {
+        discardFeedbackCompanion(companionNodeId);
+    }
+    const body = {
+        comment: toPageFeedbackCommentDTO(mutation.comment),
+        feedback: toPageFeedbackDTO(mutation.feedback),
+        delivery: await deliverCommentTurn({ dir: resolved.dir, title: manifest.title, mutation }),
+    };
+    return { status: 200, body };
+}
+// ---------------------------------------------------------------------------
+// POST .../feedback-comments/:comment_id/resolve — the companion's report
+// ---------------------------------------------------------------------------
+function parseResolve(ctx) {
+    const violations = [];
+    const body = objectBody(ctx.body, ['node_id'], violations);
+    const nodeId = requiredString(body, 'node_id', violations);
+    if (violations.length > 0 || nodeId === undefined) {
+        invalidRequest('feedback resolve request', violations);
+    }
+    return nodeId;
+}
+async function handleResolve(ctx) {
+    const resolved = requireMutablePageTicket(ctx);
+    const commentId = requireCommentId(ctx.params);
+    const callerNodeId = parseResolve(ctx);
+    // Resolution is the bound companion's report that an item has been dealt
+    // with; no other node may retire the person's open item out from under the
+    // settle-time addendum.
+    const companionNodeId = readPageFeedback(resolved.dir).companionNodeId;
+    if (companionNodeId === undefined || callerNodeId !== companionNodeId) {
+        throw new ApiError(403, 'not_companion', "only the ticket's bound feedback companion resolves its comments");
+    }
+    let mutation;
+    try {
+        mutation = resolvePageFeedbackComment(resolved.dir, commentId);
+    }
+    catch (error) {
+        if (error instanceof UnknownPageFeedbackCommentError) {
+            throw new ApiError(404, 'unknown_comment', error.message);
+        }
+        if (error instanceof PageFeedbackCommentAlreadyResolvedError) {
+            throw new ApiError(409, 'comment_already_resolved', error.message);
+        }
+        if (error instanceof PageTicketTerminalError) {
+            throw new ApiError(409, 'ticket_terminal', 'ticket already has a terminal outcome');
+        }
+        throw error;
+    }
+    // Resolution appends no chat turn: the companion's own conversational report
+    // explains the result.
+    const body = {
+        comment: toPageFeedbackCommentDTO(mutation.comment),
+        feedback: toPageFeedbackDTO(mutation.feedback),
+    };
+    return { status: 200, body };
+}
+export const feedbackCommentRoutes = [
+    { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/feedback-comments', handler: handleCreate },
+    { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/feedback-comments/:comment_id/resolve', handler: handleResolve },
+];