@north-light/crouter 0.3.312 → 0.3.313

package/dist/daemon/__tests__/startup-block-marker.test.js

@@ -1,86 +0,0 @@
-import { test, beforeEach, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { blockedMigrationIn, clearDaemonStartupBlocked, daemonStartupBlocked, recordDaemonStartupBlocked, } from '../startup-block-marker.js';
-import { exclusiveLockOwnerPid, withExclusiveDirectoryLockAsync } from '../../core/exclusive-lock.js';
-import { MigrationBlockedError } from '../../migrations/activation.js';
-// REGRESSION (daemon respawn storm, cross-process half): the first fix for the
-// storm kept its suppression in module state, which caps exactly ONE process.
-// The storm is made of many — every CLI invocation and every scheduled tick is
-// its own process — so 10 separate invocations against a permanently blocked
-// home still produced 10 spawns. Suppression has to outlive a pid, and it has
-// to retire itself when the corpus is repaired or it wedges a fixed install.
-let home;
-const previousHome = process.env['CRTR_HOME'];
-beforeEach(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-block-'));
-    process.env['CRTR_HOME'] = home;
-});
-afterEach(() => {
-    if (previousHome === undefined)
-        delete process.env['CRTR_HOME'];
-    else
-        process.env['CRTR_HOME'] = previousHome;
-    rmSync(home, { recursive: true, force: true });
-});
-test('a recorded block is visible to a DIFFERENT process reading the same home', () => {
-    const blocker = join(home, 'INDEX.md');
-    writeFileSync(blocker, 'front door');
-    assert.equal(daemonStartupBlocked(), null, 'nothing recorded yet');
-    recordDaemonStartupBlocked('migration blocked\nRepair: crtr sys migrate', [blocker]);
-    // A fresh process shares no memory with the recorder — only this file.
-    assert.match(daemonStartupBlocked() ?? '', /Repair: crtr sys migrate/);
-});
-test('the marker retires itself once the corpus it named changes', () => {
-    const blocker = join(home, 'INDEX.md');
-    writeFileSync(blocker, 'front door');
-    recordDaemonStartupBlocked('blocked', [blocker]);
-    assert.equal(daemonStartupBlocked(), 'blocked');
-    // The repair — by `crtr sys migrate`, an editor, or a delete. Whatever did
-    // it, the user must never need to know this marker exists.
-    writeFileSync(blocker, 'front door removed, plus enough bytes to change size');
-    assert.equal(daemonStartupBlocked(), null, 'a changed blocker lifts suppression');
-});
-test('a deleted blocker also retires the marker', () => {
-    const blocker = join(home, 'INDEX.md');
-    writeFileSync(blocker, 'front door');
-    recordDaemonStartupBlocked('blocked', [blocker]);
-    rmSync(blocker);
-    assert.equal(daemonStartupBlocked(), null);
-});
-test('a marker naming no blockers cannot wedge autostart forever', () => {
-    // Nothing about it can be observed to change, so it is advisory only.
-    recordDaemonStartupBlocked('blocked with no paths', []);
-    assert.equal(daemonStartupBlocked(), null);
-});
-test('clearing is idempotent and safe on a home with no marker', () => {
-    clearDaemonStartupBlocked();
-    clearDaemonStartupBlocked();
-    assert.equal(daemonStartupBlocked(), null);
-});
-// REGRESSION (reap kills a healthy daemon mid-migration): the reap escalates to
-// SIGKILL, so it must be able to tell a child that is DOING the migration from
-// one merely queued behind it. The lock marker already names its owner's pid.
-test('the migration lock names its holder, so a reap can spare the one doing the work', async () => {
-    const lock = join(home, 'lock');
-    assert.equal(exclusiveLockOwnerPid(lock), null, 'a free lock names nobody');
-    await withExclusiveDirectoryLockAsync(lock, async () => {
-        assert.equal(exclusiveLockOwnerPid(lock), process.pid, 'the holder is named while held');
-    });
-    assert.equal(exclusiveLockOwnerPid(lock), null, 'released again');
-});
-// REGRESSION (the aggregate swallows the one error that matters): startup
-// releases its ownership claim before rethrowing a migration failure, and a
-// release that ALSO fails is reported as an AggregateError. The blocked
-// migration must still be recognised through that wrapper, or the daemon exits
-// generically and every downstream suppression stops working.
-test('a blocked migration is still recognised inside a cleanup aggregate', () => {
-    const blocked = new MigrationBlockedError('blocked', ['/some/INDEX.md']);
-    const aggregate = new AggregateError([blocked, new Error('cleanup also failed')], 'startup failed');
-    const found = blockedMigrationIn(aggregate);
-    assert.ok(found instanceof MigrationBlockedError, 'found through the wrapper');
-    assert.deepEqual(found.blockerPaths, ['/some/INDEX.md']);
-    assert.equal(blockedMigrationIn(new Error('unrelated')), null, 'an ordinary failure is not claimed');
-});

package/dist/daemon/api/__tests__/review-terminal-conflict.test.d.ts

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

package/dist/daemon/api/__tests__/review-terminal-conflict.test.js

@@ -1,98 +0,0 @@
-import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { test } from 'node:test';
-import { closeDb, openDb } from '../../../core/canvas/db.js';
-import { reviewResultPath } from '../../../core/canvas/paths.js';
-import { toErrorBody } from '../map.js';
-import { reviewCommentRoutes } from '../handlers/review-comments.js';
-test('comment create reports the terminal review winner', async () => {
-    const home = mkdtempSync(join(tmpdir(), 'crtr-review-terminal-conflict-'));
-    const previousHome = process.env['CRTR_HOME'];
-    process.env['CRTR_HOME'] = home;
-    try {
-        const route = reviewCommentRoutes.find((candidate) => candidate.method === 'POST' && candidate.pattern === '/v1/human/reviews/:review_id/comments');
-        assert.ok(route, 'the canonical comment-create route is registered');
-        for (const terminal of [
-            {
-                state: 'canceled',
-                terminalColumns: ['2026-01-02T00:00:00.000Z', null, null, null, null, 'out of band cancel', 'human'],
-                terminalDTO: {
-                    canceled_at: '2026-01-02T00:00:00.000Z',
-                    cancel_reason: 'out of band cancel',
-                    cancel_actor: 'human',
-                },
-            },
-            {
-                state: 'approved',
-                terminalColumns: [null, '2026-01-03T00:00:00.000Z', 1, 2, 1, null, null],
-                terminalDTO: {
-                    approved_at: '2026-01-03T00:00:00.000Z',
-                    changed: true,
-                    comments_total: 2,
-                    comments_unresolved: 1,
-                },
-            },
-        ]) {
-            const reviewId = `${terminal.state}-review`;
-            openDb().prepare(`
-        INSERT INTO reviews
-          (review_id, idempotency_key, origin_kind, origin_node_id, companion_node_id, review_dir,
-           file, origin_session_file, origin_session_id, origin_leaf_id, model_spec, branch_file,
-           baseline_sha256, baseline_bytes, anchor_base_sha256, anchor_base_bytes, state, created, captured_at,
-           canceled_at, approved_at, changed, comments_total, comments_unresolved, cancel_reason, cancel_actor)
-        VALUES (?, ?, 'inline', 'origin', ?, '/tmp/review', '/tmp/source.md',
-                '/tmp/session.jsonl', 'session', 'leaf', 'anthropic/claude', '/tmp/branch.jsonl',
-                'baseline', 4, 'baseline', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(reviewId, `idempotency-${reviewId}`, `${terminal.state}-companion`, Buffer.from('base'), terminal.state, '2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z', ...terminal.terminalColumns);
-            let thrown;
-            try {
-                await route.handler({
-                    method: 'POST',
-                    path: `/v1/human/reviews/${reviewId}/comments`,
-                    params: { review_id: reviewId },
-                    query: new URLSearchParams(),
-                    body: {
-                        text: 'late comment',
-                        anchor: { line: 1, end_line: 1 },
-                        doc_hash: 'a'.repeat(64),
-                        actor_node_id: null,
-                    },
-                });
-            }
-            catch (error) {
-                thrown = error;
-            }
-            const { status, body } = toErrorBody(thrown);
-            assert.equal(status, 409);
-            assert.equal(body.error.code, 'review_terminal_conflict');
-            assert.deepEqual(body.error.details, {
-                state: terminal.state,
-                requested: 'comment',
-                review: {
-                    review_id: reviewId,
-                    origin_kind: 'inline',
-                    origin_node_id: 'origin',
-                    bridge_node_id: null,
-                    companion_node_id: `${terminal.state}-companion`,
-                    file: '/tmp/source.md',
-                    state: terminal.state,
-                    created: '2026-01-01T00:00:00.000Z',
-                    source_missing: true,
-                    anchor_base_sha256: 'baseline',
-                    ...terminal.terminalDTO,
-                    ...(terminal.state === 'approved' ? { result_path: reviewResultPath(reviewId) } : {}),
-                },
-            });
-        }
-    }
-    finally {
-        closeDb();
-        rmSync(home, { recursive: true, force: true });
-        if (previousHome === undefined)
-            delete process.env['CRTR_HOME'];
-        else
-            process.env['CRTR_HOME'] = previousHome;
-    }
-});

package/dist/daemon/human/deliver-action.d.ts

@@ -1,3 +0,0 @@
-import { type ActionDeliveryRecord } from '../../core/canvas/human-deliveries.js';
-/** Spawn and settle one already-claimed action delivery. */
-export declare function deliverAction(delivery: ActionDeliveryRecord, claimOwner: string): Promise<void>;

package/dist/daemon/human/deliver-action.js

@@ -1,9 +0,0 @@
-// Delivery of one settled human request to its declared completion action.
-// The process contract lives in `daemon/delivery/run-delivery.ts`; this file
-// binds it to the action-delivery row.
-import { settleActionDelivery, } from '../../core/canvas/human-deliveries.js';
-import { runDelivery } from '../delivery/run-delivery.js';
-/** Spawn and settle one already-claimed action delivery. */
-export async function deliverAction(delivery, claimOwner) {
-    await runDelivery({ argv: delivery.argv, cwd: delivery.cwd, document: delivery.completion, attempt: delivery.attempt }, (settlement) => settleActionDelivery(delivery.requestId, delivery.attempt, claimOwner, settlement, Date.now()));
-}

package/dist/daemon/node-outcome/deliver-outcome.d.ts

@@ -1,3 +0,0 @@
-import { type OutcomeDeliveryRecord } from '../../core/canvas/node-outcome-deliveries.js';
-/** Spawn and settle one already-claimed outcome delivery. */
-export declare function deliverOutcome(delivery: OutcomeDeliveryRecord, claimOwner: string): Promise<void>;

package/dist/daemon/node-outcome/deliver-outcome.js

@@ -1,9 +0,0 @@
-// Delivery of one node's terminal outcome to its registered action target.
-// The process contract lives in `daemon/delivery/run-delivery.ts`; this file
-// binds it to the outcome-delivery row.
-import { settleOutcomeDelivery, } from '../../core/canvas/node-outcome-deliveries.js';
-import { runDelivery } from '../delivery/run-delivery.js';
-/** Spawn and settle one already-claimed outcome delivery. */
-export async function deliverOutcome(delivery, claimOwner) {
-    await runDelivery({ argv: delivery.argv, cwd: delivery.cwd, document: delivery.document, attempt: delivery.attempt }, (settlement) => settleOutcomeDelivery(delivery.nodeId, delivery.attempt, claimOwner, settlement, Date.now()));
-}

package/dist/daemon/reconcilers/human-delivery-lane.d.ts

@@ -1,10 +0,0 @@
-import type { DetachedWorkLifecycle } from './broker-supervision.js';
-/** One daemon-life identity for guarded action-delivery claims. */
-export declare const humanDeliveryDaemonInstanceId: `${string}-${string}-${string}-${string}-${string}`;
-export interface HumanDeliveryLaneContext {
-    lifecycle: DetachedWorkLifecycle;
-}
-/** Admit due action deliveries without making the daemon's serial tick await subprocesses. */
-export declare class HumanDeliveryLaneReconciler {
-    run(now: number, ctx: HumanDeliveryLaneContext): void;
-}

package/dist/daemon/reconcilers/human-delivery-lane.js

@@ -1,41 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { claimActionDelivery, dueActionDeliveries } from '../../core/canvas/human-deliveries.js';
-import { emitEvent } from '../../core/events/emit.js';
-import { operationIdContext } from '../../core/events/operation-id.js';
-import { deliverAction } from '../human/deliver-action.js';
-/** One daemon-life identity for guarded action-delivery claims. */
-export const humanDeliveryDaemonInstanceId = randomUUID();
-/** Admit due action deliveries without making the daemon's serial tick await subprocesses. */
-export class HumanDeliveryLaneReconciler {
-    run(now, ctx) {
-        if (!ctx.lifecycle.acceptsDetachedWork())
-            return;
-        let due;
-        try {
-            due = dueActionDeliveries(now);
-        }
-        catch (error) {
-            operationIdContext.fresh(() => {
-                emitEvent({ level: 'error', event: 'human.action_delivery.scan_failed', error });
-            });
-            return;
-        }
-        for (const candidate of due) {
-            try {
-                const claimed = claimActionDelivery(candidate.requestId, now, humanDeliveryDaemonInstanceId);
-                if (claimed === null)
-                    continue;
-                ctx.lifecycle.registerDetached(deliverAction(claimed, humanDeliveryDaemonInstanceId).catch((error) => {
-                    operationIdContext.fresh(() => {
-                        emitEvent({ level: 'error', event: 'human.action_delivery.failed', error, fields: { request_id: claimed.requestId } });
-                    });
-                }));
-            }
-            catch (error) {
-                operationIdContext.fresh(() => {
-                    emitEvent({ level: 'error', event: 'human.action_delivery.claim_failed', error, fields: { request_id: candidate.requestId } });
-                });
-            }
-        }
-    }
-}

package/dist/daemon/reconcilers/node-outcome-delivery-lane.d.ts

@@ -1,10 +0,0 @@
-import type { DetachedWorkLifecycle } from './broker-supervision.js';
-/** One daemon-life identity for guarded outcome-delivery claims. */
-export declare const outcomeDeliveryDaemonInstanceId: `${string}-${string}-${string}-${string}-${string}`;
-export interface NodeOutcomeDeliveryLaneContext {
-    lifecycle: DetachedWorkLifecycle;
-}
-/** Admit due outcome deliveries without making the daemon's serial tick await subprocesses. */
-export declare class NodeOutcomeDeliveryLaneReconciler {
-    run(now: number, ctx: NodeOutcomeDeliveryLaneContext): void;
-}

package/dist/daemon/reconcilers/node-outcome-delivery-lane.js

@@ -1,41 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { claimOutcomeDelivery, dueOutcomeDeliveries } from '../../core/canvas/node-outcome-deliveries.js';
-import { emitEvent } from '../../core/events/emit.js';
-import { operationIdContext } from '../../core/events/operation-id.js';
-import { deliverOutcome } from '../node-outcome/deliver-outcome.js';
-/** One daemon-life identity for guarded outcome-delivery claims. */
-export const outcomeDeliveryDaemonInstanceId = randomUUID();
-/** Admit due outcome deliveries without making the daemon's serial tick await subprocesses. */
-export class NodeOutcomeDeliveryLaneReconciler {
-    run(now, ctx) {
-        if (!ctx.lifecycle.acceptsDetachedWork())
-            return;
-        let due;
-        try {
-            due = dueOutcomeDeliveries(now);
-        }
-        catch (error) {
-            operationIdContext.fresh(() => {
-                emitEvent({ level: 'error', event: 'node_outcome.delivery.scan_failed', error });
-            });
-            return;
-        }
-        for (const candidate of due) {
-            try {
-                const claimed = claimOutcomeDelivery(candidate.nodeId, now, outcomeDeliveryDaemonInstanceId);
-                if (claimed === null)
-                    continue;
-                ctx.lifecycle.registerDetached(deliverOutcome(claimed, outcomeDeliveryDaemonInstanceId).catch((error) => {
-                    operationIdContext.fresh(() => {
-                        emitEvent({ level: 'error', event: 'node_outcome.delivery.failed', error, fields: { node_id: claimed.nodeId } });
-                    });
-                }));
-            }
-            catch (error) {
-                operationIdContext.fresh(() => {
-                    emitEvent({ level: 'error', event: 'node_outcome.delivery.claim_failed', error, fields: { node_id: candidate.nodeId } });
-                });
-            }
-        }
-    }
-}

package/dist/daemon/startup-block-marker.d.ts

@@ -1,25 +0,0 @@
-import { MigrationBlockedError } from '../migrations/activation.js';
-export declare function daemonStartupBlockMarkerPath(): string;
-/** Record that startup is blocked, so no OTHER process spawns into the same
- *  wall. Best-effort: a home we cannot write to still gets in-process
- *  suppression, which is strictly better than nothing. */
-export declare function recordDaemonStartupBlocked(message: string, blockerPaths: readonly string[]): void;
-/** Clear the marker — for a repair path that knows startup should be retried
- *  (a successful migration, a successful daemon start, an explicit reset). */
-export declare function clearDaemonStartupBlocked(): void;
-/** The recorded block message when startup is still blocked by the SAME corpus
- *  that produced it, or null when nothing is recorded or the corpus has since
- *  changed. A changed corpus retires the marker as a side effect of the read,
- *  so the very next spawner is free to try again.
- *
- *  A marker naming no blocker paths at all is not self-healing — nothing about
- *  it can be observed to change — so it is treated as advisory only and
- *  retired on read rather than left to wedge autostart forever. */
-export declare function daemonStartupBlocked(): string | null;
-/** The blocked-migration failure, wherever it ended up in a thrown value.
- *  Startup releases its ownership claim before rethrowing, and a claim release
- *  that ALSO fails is reported as an aggregate — so the one error the spawner
- *  must react to can arrive nested. Matching only the bare instance would let
- *  the aggregate path fall through to a generic exit, and every suppression
- *  downstream is keyed on getting that exit code right. */
-export declare function blockedMigrationIn(error: unknown): MigrationBlockedError | null;

package/dist/daemon/startup-block-marker.js

@@ -1,99 +0,0 @@
-// A blocked daemon startup is a STANDING condition, and the processes that
-// keep retrying it are not one process. Every CLI invocation, every scheduled
-// job tick, and every long-lived client is its own process with its own module
-// state, so an in-memory suppression flag caps exactly one of them and lets the
-// rest storm unchanged. This marker is that suppression made durable: one file
-// in the canvas home, written by whoever first proved startup is blocked, and
-// read by every would-be spawner before it spawns.
-//
-// The hazard of a durable "stop trying" record is that it outlives the problem
-// and wedges a repaired install. So the marker is self-healing rather than
-// permanent: it records the identity (path + size + mtime) of each blocker the
-// daemon named, and any change to any of them retires the marker on the next
-// read. Repairing the corpus — by `crtr sys migrate`, an editor, or deleting
-// the offending file — is itself the thing that lifts the suppression, so no
-// user is ever required to know this file exists.
-import { rmSync } from 'node:fs';
-import { statSync } from 'node:fs';
-import { join } from 'node:path';
-import { crtrHome } from '../core/canvas/paths.js';
-import { MigrationBlockedError } from '../migrations/activation.js';
-import { atomicWriteJson, readJsonOrNull } from '../core/fs-utils.js';
-export function daemonStartupBlockMarkerPath() {
-    return join(crtrHome(), 'daemon-startup-blocked.json');
-}
-function fingerprint(path) {
-    try {
-        const stat = statSync(path);
-        return { path, sizeBytes: stat.size, mtimeMs: stat.mtimeMs };
-    }
-    catch {
-        return { path, sizeBytes: null, mtimeMs: null };
-    }
-}
-function sameFingerprint(a, b) {
-    return a.sizeBytes === b.sizeBytes && a.mtimeMs === b.mtimeMs;
-}
-/** Record that startup is blocked, so no OTHER process spawns into the same
- *  wall. Best-effort: a home we cannot write to still gets in-process
- *  suppression, which is strictly better than nothing. */
-export function recordDaemonStartupBlocked(message, blockerPaths) {
-    const marker = {
-        recordedAt: Date.now(),
-        message,
-        blockers: blockerPaths.map(fingerprint),
-    };
-    try {
-        atomicWriteJson(daemonStartupBlockMarkerPath(), marker);
-    }
-    catch { /* best effort */ }
-}
-/** Clear the marker — for a repair path that knows startup should be retried
- *  (a successful migration, a successful daemon start, an explicit reset). */
-export function clearDaemonStartupBlocked() {
-    try {
-        rmSync(daemonStartupBlockMarkerPath(), { force: true });
-    }
-    catch { /* best effort */ }
-}
-/** The recorded block message when startup is still blocked by the SAME corpus
- *  that produced it, or null when nothing is recorded or the corpus has since
- *  changed. A changed corpus retires the marker as a side effect of the read,
- *  so the very next spawner is free to try again.
- *
- *  A marker naming no blocker paths at all is not self-healing — nothing about
- *  it can be observed to change — so it is treated as advisory only and
- *  retired on read rather than left to wedge autostart forever. */
-export function daemonStartupBlocked() {
-    const marker = readJsonOrNull(daemonStartupBlockMarkerPath());
-    if (marker === null || typeof marker.message !== 'string' || !Array.isArray(marker.blockers))
-        return null;
-    if (marker.blockers.length === 0) {
-        clearDaemonStartupBlocked();
-        return null;
-    }
-    const changed = marker.blockers.some((recorded) => !sameFingerprint(recorded, fingerprint(recorded.path)));
-    if (changed) {
-        clearDaemonStartupBlocked();
-        return null;
-    }
-    return marker.message;
-}
-/** The blocked-migration failure, wherever it ended up in a thrown value.
- *  Startup releases its ownership claim before rethrowing, and a claim release
- *  that ALSO fails is reported as an aggregate — so the one error the spawner
- *  must react to can arrive nested. Matching only the bare instance would let
- *  the aggregate path fall through to a generic exit, and every suppression
- *  downstream is keyed on getting that exit code right. */
-export function blockedMigrationIn(error) {
-    if (error instanceof MigrationBlockedError)
-        return error;
-    if (error instanceof AggregateError) {
-        for (const nested of error.errors) {
-            const found = blockedMigrationIn(nested);
-            if (found !== null)
-                return found;
-        }
-    }
-    return null;
-}