@north-light/crouter 0.3.154

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

@@ -0,0 +1,354 @@
+// Cron handlers (the cron-spec scheduler).
+//
+//   POST   /v1/crons                 arm one cron (server mints the cron_id)
+//   GET    /v1/crons                 the crons in the caller's scope
+//   GET    /v1/crons/:cronId         one cron + its run-log ring
+//   POST   /v1/crons/:cronId/pause   stop firing, keep config + history
+//   POST   /v1/crons/:cronId/resume  re-arm a paused cron
+//   POST   /v1/crons/:cronId/run     fire NOW, out of band (synchronous)
+//   DELETE /v1/crons/:cronId         cancel one cron (idempotent, kills in-flight run)
+//
+// The CLI resolves timing client-side (parseWhen/parseCadence) and sends the
+// settled fire_at/recur/tz plus its chosen-else-inherited execution context;
+// this handler validates the full arm surface (timing SHAPE and
+// advanceability, enums, env, sink shape + arm-time target existence, anchor
+// coupling), applies spec defaults for the rest, and inserts through the DAO.
+// crtrd is the sole state owner and the CLI is only one of its clients (the
+// web UI and Northlight Core call the same routes), so nothing here trusts a
+// client-resolved value it can check itself. Every per-cron route resolves
+// through `requireCron`, which enforces the caller's profile scope. The sink is stored as JSON (`{"node":…}` /
+// `{"spawn":…}` / `{"human":true}` / `{}`); the DTO renders it back to the
+// display spec.
+import { randomUUID } from 'node:crypto';
+import { ApiError } from '../../../api/errors.js';
+import { armCron, cancelCron, getCron, listCrons, listCronRuns, setCronState, } from '../../../core/canvas/crons.js';
+import { getNode } from '../../../core/canvas/canvas.js';
+import { InputError } from '../../../core/io.js';
+import { nextSlotAfter } from '../../../core/wake.js';
+import { executeCron } from '../../cron-run.js';
+import { toCronDTO, toCronRunDTO } from '../map.js';
+function requireString(req, field) {
+    const v = req[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+        throw new InputError({
+            error: 'missing_field',
+            message: `cron arm request requires a non-empty "${field}"`,
+            field,
+            next: `Send a non-empty string "${field}".`,
+        });
+    }
+    return v;
+}
+function requireEnum(value, field, allowed, fallback) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value === 'string' && allowed.includes(value))
+        return value;
+    throw new InputError({
+        error: `bad_${field}`,
+        message: `"${String(value)}" is not a valid ${field}`,
+        field,
+        next: `Use one of: ${allowed.join(', ')}.`,
+    });
+}
+/** Parse + validate the raw sink display spec (`node:<id>` | `spawn:<kind>` |
+ *  `human`) into its stored JSON. An armed node target must exist NOW (a later
+ *  disappearance is the fire-time failure path, not an arm-time concern). */
+function parseSinkSpec(raw) {
+    if (raw === 'human')
+        return JSON.stringify({ human: true });
+    if (raw.startsWith('node:')) {
+        const id = raw.slice('node:'.length).trim();
+        if (id === '') {
+            throw new InputError({ error: 'bad_sink', message: 'node sink requires a node id', field: 'sink', next: 'Use sink "node:<node-id>".' });
+        }
+        if (getNode(id) === null) {
+            throw new InputError({
+                error: 'sink_node_not_found',
+                message: `sink node ${id} does not exist on the canvas`,
+                field: 'sink',
+                next: 'Name a live node id, or use spawn:<kind> for a delivery that outlives any one node.',
+            });
+        }
+        return JSON.stringify({ node: id });
+    }
+    if (raw.startsWith('spawn:')) {
+        const kind = raw.slice('spawn:'.length).trim();
+        if (kind === '') {
+            throw new InputError({ error: 'bad_sink', message: 'spawn sink requires a node kind', field: 'sink', next: 'Use sink "spawn:<kind>" (e.g. spawn:general).' });
+        }
+        return JSON.stringify({ spawn: kind });
+    }
+    throw new InputError({
+        error: 'bad_sink',
+        message: `"${raw}" is not a valid sink`,
+        field: 'sink',
+        next: 'Use node:<node-id>, spawn:<kind>, or human.',
+    });
+}
+/** The exact instant shape every stored clock column must have: a UTC ISO
+ *  timestamp as `Date.prototype.toISOString` emits it. The daemon compares
+ *  `fire_at`/`expires_at` LEXICOGRAPHICALLY against `new Date().toISOString()`,
+ *  so a value in any other shape (a local-zone offset, a bare date, "soon")
+ *  silently arms a row that never fires and never expires. crtrd is the sole
+ *  state owner and the CLI is only one of its clients — this is validated here,
+ *  not trusted from the client that resolved it. */
+const UTC_ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+function requireUtcIso(raw, field) {
+    if (!UTC_ISO.test(raw) || Number.isNaN(Date.parse(raw))) {
+        throw new InputError({
+            error: `bad_${field}`,
+            message: `"${raw}" is not a UTC ISO instant`,
+            field,
+            next: 'Send a resolved UTC instant like "2026-06-07T09:00:00.000Z" (the client resolves the time grammar).',
+        });
+    }
+    return raw;
+}
+/** Validate a `recur` the daemon must be able to advance. An unparseable recur
+ *  is a row the scheduler cannot slot — reject it at arm time rather than let
+ *  it fail at the first fire. */
+function requireRecur(raw) {
+    try {
+        nextSlotAfter(raw, new Date());
+    }
+    catch (err) {
+        throw new InputError({
+            error: 'bad_recur',
+            message: `recur is not advanceable: ${err instanceof Error ? err.message : String(err)}`,
+            field: 'recur',
+            next: 'Send recur JSON the daemon can advance: {"every":"6h"} or {"cron":"0 9 * * *","tz":"America/New_York"}.',
+        });
+    }
+    return raw;
+}
+/** Validate the chosen extra run env: a JSON object of string values, since
+ *  that is exactly what the executor can put in a child process env. */
+function requireEnvJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new InputError({ error: 'bad_env_json', message: 'env_json is not valid JSON', field: 'env_json', next: 'Send a JSON object of string values, e.g. {"API_BASE":"https://x"}.' });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new InputError({ error: 'bad_env_json', message: 'env_json must be a JSON object', field: 'env_json', next: 'Send a JSON object of string values, e.g. {"API_BASE":"https://x"}.' });
+    }
+    for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v !== 'string') {
+            throw new InputError({ error: 'bad_env_json', message: `env_json value for "${k}" is not a string`, field: 'env_json', next: 'Every env value must be a string.' });
+        }
+    }
+    return raw;
+}
+/** The caller's profile, as declared on the request. Scoping is what this
+ *  means: a profile-scoped cron belongs to its profile; a global one is
+ *  canvas-home-wide. A caller that declares no profile stands outside every
+ *  profile (a plain shell, or a provenance read) and sees the whole canvas
+ *  home — this is a namespacing boundary between profiles, not a security
+ *  boundary (the profile is client-declared, like `created_by`). */
+function callerProfile(ctx) {
+    const p = ctx.query.get('profile');
+    return p !== null && p.trim() !== '' ? p.trim() : null;
+}
+/** Is this cron in the caller's scope? */
+function inScope(c, caller) {
+    return caller === null || c.scope === 'global' || c.profile === caller;
+}
+/** `POST /v1/crons` — arm one cron. Validates the full spec surface; every
+ *  omitted optional takes its spec default. */
+function handleArm(ctx) {
+    const req = (ctx.body ?? {});
+    const name = requireString(req, 'name');
+    const command = requireString(req, 'command');
+    const fireAt = requireUtcIso(requireString(req, 'fire_at'), 'fire_at');
+    const cwd = requireString(req, 'cwd');
+    const recur = typeof req.recur === 'string' && req.recur !== '' ? requireRecur(req.recur) : null;
+    const expiresAt = typeof req.expires_at === 'string' && req.expires_at !== ''
+        ? requireUtcIso(req.expires_at, 'expires_at')
+        : null;
+    const envJson = typeof req.env_json === 'string' && req.env_json !== '' ? requireEnvJson(req.env_json) : null;
+    const onOutput = requireEnum(req.on_output, 'on_output', ['silent', 'on-failure', 'always', 'on-change'], 'on-failure');
+    const overlap = requireEnum(req.overlap, 'overlap', ['skip', 'queue', 'replace'], 'skip');
+    const tier = requireEnum(req.tier, 'tier', ['normal', 'urgent', 'critical'], 'normal');
+    // Sink: required by the delivering dispositions, meaningless otherwise —
+    // progressive disclosure via the error that names the need.
+    const rawSink = typeof req.sink === 'string' && req.sink.trim() !== '' ? req.sink.trim() : null;
+    const delivers = onOutput === 'always' || onOutput === 'on-change';
+    if (delivers && rawSink === null) {
+        throw new InputError({
+            error: 'sink_required',
+            message: `on_output "${onOutput}" delivers stdout every qualifying run — it needs a sink`,
+            field: 'sink',
+            next: 'Pass sink node:<node-id> (a living node\'s inbox), spawn:<kind> (birth a fresh node per delivery), or human (the humanloop inbox).',
+        });
+    }
+    if (!delivers && rawSink !== null) {
+        throw new InputError({
+            error: 'sink_unused',
+            message: `on_output "${onOutput}" never delivers stdout — a sink would be dead config`,
+            field: 'sink',
+            next: 'Drop the sink, or use on_output "always"/"on-change" if delivery is the point.',
+        });
+    }
+    const sink = rawSink !== null ? parseSinkSpec(rawSink) : '{}';
+    // Node coupling: an anchor must exist at arm time; cancel_on_wake is the
+    // deadline rule and only means anything WITH an anchor.
+    const anchorNode = typeof req.anchor_node === 'string' && req.anchor_node !== '' ? req.anchor_node : null;
+    if (anchorNode !== null && getNode(anchorNode) === null) {
+        throw new InputError({
+            error: 'anchor_not_found',
+            message: `anchor node ${anchorNode} does not exist on the canvas`,
+            field: 'anchor_node',
+            next: 'Name a live node id, or drop the anchor — an unanchored cron outlives every node.',
+        });
+    }
+    const cancelOnWake = req.cancel_on_wake === true;
+    if (cancelOnWake && anchorNode === null) {
+        throw new InputError({
+            error: 'cancel_on_wake_needs_anchor',
+            message: 'cancel_on_wake couples the cron to a node\'s dormancy — it requires an anchor node',
+            field: 'anchor_node',
+            next: 'Pass anchor_node with the node whose wake should cancel this cron.',
+        });
+    }
+    const runTimeoutS = req.run_timeout_s ?? 300;
+    if (typeof runTimeoutS !== 'number' || !Number.isInteger(runTimeoutS) || runTimeoutS <= 0) {
+        throw new InputError({
+            error: 'bad_run_timeout',
+            message: `run_timeout_s must be a positive integer (got ${String(req.run_timeout_s)})`,
+            field: 'run_timeout_s',
+            next: 'Send the timeout in whole seconds, e.g. 300.',
+        });
+    }
+    // Execution context: chosen (this request) else inherited (whatever the
+    // client resolved from its own node), always snapshotted onto the row.
+    const profile = typeof req.profile === 'string' && req.profile !== '' ? req.profile : null;
+    const scope = requireEnum(req.scope, 'scope', ['profile', 'global'], profile !== null ? 'profile' : 'global');
+    if (scope === 'profile' && profile === null) {
+        throw new InputError({
+            error: 'scope_needs_profile',
+            message: 'scope "profile" names the profile the cron lists and cancels within — it requires a profile',
+            field: 'profile',
+            next: 'Send a profile, or use scope "global" for a canvas-home-wide cron.',
+        });
+    }
+    // A cancel-on-wake arm REPLACES the anchor's pending deadline (armCron does
+    // the displace-then-insert under one canvas write boundary) — at most one
+    // cancel-on-wake cron per anchor, whoever arms it.
+    const cronId = randomUUID();
+    armCron({
+        cron_id: cronId,
+        name,
+        created_by: typeof req.created_by === 'string' && req.created_by !== '' ? req.created_by : null,
+        command,
+        fire_at: fireAt,
+        recur,
+        tz: typeof req.tz === 'string' ? req.tz : null,
+        expires_at: expiresAt,
+        anchor_node: anchorNode,
+        cancel_on_wake: cancelOnWake,
+        cwd,
+        env_json: envJson,
+        profile,
+        scope,
+        run_timeout_s: runTimeoutS,
+        overlap,
+        on_output: onOutput,
+        sink,
+        tier,
+    });
+    return { status: 201, body: toCronDTO(getCron(cronId), null) };
+}
+/** `GET /v1/crons` — the crons in the caller's scope, next-fire order: that
+ *  profile's own rows plus every canvas-home-wide global one. A caller that
+ *  declares no profile gets the whole canvas home. */
+function handleList(ctx) {
+    const caller = callerProfile(ctx);
+    const rows = caller === null
+        ? listCrons({ all: true })
+        : [...listCrons({ profile: caller }), ...listCrons({ global: true })].sort((a, b) => a.fire_at < b.fire_at ? -1 : a.fire_at > b.fire_at ? 1 : 0);
+    return { status: 200, body: rows.map((c) => toCronDTO(c, lastRunOf(c))) };
+}
+/** The most recent settled run of one cron (recent health for its projection). */
+function lastRunOf(c) {
+    return listCronRuns(c.cron_id)[0] ?? null;
+}
+/** Resolve one cron the caller may see. A cron outside the caller's scope is
+ *  404 with the reason named — profiles namespace crons, so "not here" and
+ *  "not anywhere" are the same answer to this caller. */
+function requireCron(ctx) {
+    const cronId = ctx.params['cronId'];
+    const c = getCron(cronId);
+    if (c === null)
+        throw new ApiError(404, 'cron_not_found', `no cron ${cronId}`);
+    if (!inScope(c, callerProfile(ctx))) {
+        throw new ApiError(404, 'cron_not_found', `no cron ${cronId} in this profile — it is scoped to another profile`);
+    }
+    return c;
+}
+/** `GET /v1/crons/:cronId` — one cron with its run-log ring (most recent first). */
+function handleShow(ctx) {
+    const c = requireCron(ctx);
+    const runs = listCronRuns(c.cron_id);
+    return { status: 200, body: { cron: toCronDTO(c, runs[0] ?? null), runs: runs.map(toCronRunDTO) } };
+}
+/** `POST /v1/crons/:cronId/pause` — stop firing without losing config/history.
+ *  Idempotent on an already-paused row; 404 on a gone one. */
+function handlePause(ctx) {
+    const c = requireCron(ctx);
+    // An already-paused row reports false; pausing is idempotent by contract, so
+    // that is a no-op, not an error — the returned row is the answer either way.
+    setCronState(c.cron_id, 'paused');
+    const updated = getCron(c.cron_id);
+    return { status: 200, body: toCronDTO(updated, lastRunOf(updated)) };
+}
+/** `POST /v1/crons/:cronId/resume` — re-arm a paused cron. fire_at is NOT
+ *  touched: a past-due fire fires on the next tick, so an un-wedged cron
+ *  proves itself immediately (recurrence then advances naturally). */
+function handleResume(ctx) {
+    const c = requireCron(ctx);
+    setCronState(c.cron_id, 'active');
+    const updated = getCron(c.cron_id);
+    return { status: 200, body: toCronDTO(updated, lastRunOf(updated)) };
+}
+/** `POST /v1/crons/:cronId/run` — fire NOW, out of band. Synchronous: the
+ *  response is the settled run record. Does not advance the schedule, does
+ *  not consume a one-shot, delivers per disposition, never escalates/pauses.
+ *  Works on a paused cron (that is the escalation node's verification path). */
+async function handleRun(ctx) {
+    const c = requireCron(ctx);
+    if (c.run_state === 'running') {
+        throw new ApiError(409, 'cron_running', `cron ${c.cron_id} has a run in flight — wait for it to settle`);
+    }
+    const record = await executeCron(c, { outOfBand: true });
+    if (record === null) {
+        // Lost the idle→running lease race (a scheduled fire or cancel won).
+        throw new ApiError(409, 'cron_running', `cron ${c.cron_id} was claimed by a concurrent run — check \`cron show\` for its result`);
+    }
+    return { status: 200, body: toCronRunDTO(record) };
+}
+/** `DELETE /v1/crons/:cronId` — cancel one cron. Idempotent: an already-absent
+ *  cron is a no-op 204 (`cancelCron` kills any in-flight run process group
+ *  before deleting). */
+function handleCancel(ctx) {
+    const cronId = ctx.params['cronId'];
+    const c = getCron(cronId);
+    // Idempotent: an already-absent cron is a no-op. A cron scoped to ANOTHER
+    // profile is equally not-here for this caller — it must not be cancellable.
+    if (c !== null && !inScope(c, callerProfile(ctx))) {
+        throw new ApiError(404, 'cron_not_found', `no cron ${cronId} in this profile — it is scoped to another profile`);
+    }
+    cancelCron(cronId);
+    return { status: 204 };
+}
+export const cronRoutes = [
+    { method: 'POST', pattern: '/v1/crons', handler: handleArm },
+    { method: 'GET', pattern: '/v1/crons', handler: handleList },
+    { method: 'GET', pattern: '/v1/crons/:cronId', handler: handleShow },
+    { method: 'POST', pattern: '/v1/crons/:cronId/pause', handler: handlePause },
+    { method: 'POST', pattern: '/v1/crons/:cronId/resume', handler: handleResume },
+    { method: 'POST', pattern: '/v1/crons/:cronId/run', handler: handleRun },
+    { method: 'DELETE', pattern: '/v1/crons/:cronId', handler: handleCancel },
+];

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

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

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

@@ -0,0 +1,35 @@
+// Daemon self-management handlers. Today: the handover that replaces `stop`
+// followed by `start` as the way to put a new runtime generation in service.
+//
+// Why this is an API call and not a kill: the caller is almost always an agent's
+// own bash tool, and crtrd's shutdown tears down every broker it launched
+// (invariant 2) — including the caller's. A client-driven `stop` therefore kills
+// the process tree that issued it, so the command can never report its own
+// success, and the resumed agent sees an aborted tool call and re-runs it. Here
+// the daemon answers FIRST and hands over afterwards, so the ack is a settled
+// tool result in the caller's transcript before the SIGTERM lands.
+import { boundDaemonControl } from '../../control.js';
+function handleRestart() {
+    const control = boundDaemonControl();
+    if (control === null) {
+        // An API server hosted outside a live `runDaemon` (a test harness) has no
+        // process to hand over.
+        throw {
+            status: 503,
+            code: 'daemon_control_unavailable',
+            message: 'this API server is not hosted by a live daemon and cannot hand over',
+        };
+    }
+    const { graceMs } = control.requestHandover();
+    const body = {
+        accepted: true,
+        predecessor_pid: process.pid,
+        predecessor_epoch: control.epoch,
+        grace_ms: graceMs,
+    };
+    // 202: accepted, not yet performed — the handover happens after this response.
+    return { status: 202, body };
+}
+export const daemonRoutes = [
+    { method: 'POST', pattern: '/v1/daemon/restart', handler: (_ctx) => handleRestart() },
+];

package/dist/daemon/api/handlers/files.d.ts

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

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

@@ -0,0 +1,64 @@
+// Host file-read handler — `GET /v1/files/peek?path=<abs>` (spec §6). Reads an
+// absolute host path as UTF-8 for the browser file-peek panel (the transcript's
+// "any file path opens here" surface). The read is byte-capped → `truncated`,
+// so an accidental peek of a huge log/binary never streams unbounded memory.
+//
+// Trust model: crtrd runs as the single local user behind a unix socket; the
+// browser reaches this only through the web shell's auth-gated `/v1` proxy —
+// the same boundary as every other route. No node scoping: a peeked path is an
+// arbitrary host path shown in the transcript, not a node-owned artifact.
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { notFound, usage } from '../../../core/errors.js';
+import { ApiError } from '../../../api/index.js';
+/** Max bytes returned by a single peek. Generous for source/markdown/logs while
+ *  keeping an accidental peek of a huge file bounded; the panel renders the
+ *  prefix and shows a partial-content notice when `truncated`. */
+const PEEK_MAX_BYTES = 512 * 1024;
+function handlePeek(ctx) {
+    const path = ctx.query.get('path');
+    if (path === null || path === '') {
+        throw usage('a file peek requires a `path` query param');
+    }
+    if (!isAbsolute(path)) {
+        throw usage('file peek path must be absolute', { received: path });
+    }
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            throw notFound(`no such file: ${path}`, { received: path });
+        // A permission failure is a client-visible access denial (403); any other
+        // read failure is a server-side I/O condition (500). Neither is a 400 usage
+        // error, and the raw OS error string is kept out of the response body
+        // (`toErrorBody` suppresses the message on a 5xx; it is logged server-side).
+        if (code === 'EACCES' || code === 'EPERM') {
+            throw new ApiError(403, 'forbidden', `permission denied reading ${path}`);
+        }
+        throw new ApiError(500, 'internal', `cannot read ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    try {
+        const stat = fstatSync(fd);
+        if (stat.isDirectory()) {
+            throw usage(`file peek path is a directory: ${path}`, { received: path });
+        }
+        const size = stat.size;
+        // Read one byte past the cap so a file exactly at the cap is not falsely
+        // flagged truncated, and anything larger is.
+        const buf = Buffer.allocUnsafe(Math.min(size, PEEK_MAX_BYTES) + 1);
+        const bytesRead = readSync(fd, buf, 0, buf.length, 0);
+        const truncated = bytesRead > PEEK_MAX_BYTES;
+        const content = buf.toString('utf8', 0, Math.min(bytesRead, PEEK_MAX_BYTES));
+        const body = { path, content, truncated };
+        return { status: 200, body };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export const fileRoutes = [
+    { method: 'GET', pattern: '/v1/files/peek', handler: handlePeek },
+];

package/dist/daemon/api/handlers/focus.d.ts

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

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

@@ -0,0 +1,92 @@
+// Focus (viewer-registry) handlers — the canvas.db `focuses` table over the API
+// (the viewer registry: one on-screen pane bound to one node, UNIQUE node_id).
+//
+// crtrd owns canvas.db, so the focus-row reads/writes run HERE, in-process. The
+// tmux verbs that OPEN/move/close a viewer pane stay LOCAL to the CLI caller
+// (placement-tmux.ts); only the durable focus rows route through this surface.
+// The reads compose over placement.focusOf/focusByPane/listFocuses, which GC a
+// row whose pane is gone on read (paneExists via tmux) — so a returned row is
+// always live. The mutations (register/set-pane/close) are the raw focuses.ts
+// setters keyed by focus_id.
+//
+// The FocusRow→FocusDTO shape is 1:1 (a flat pane↔node binding), so the
+// projection is inlined here rather than in map.ts (frozen under concurrency
+// with the sibling projector author).
+import { focusByPane, focusOf, listFocuses, registerViewerFocus } from '../../../core/runtime/placement.js';
+import { closeFocusRow, setFocusPane } from '../../../core/canvas/focuses.js';
+import { usage } from '../../../core/errors.js';
+/** FocusRow → FocusDTO — an identity projection (the wire shape mirrors the
+ *  row). null passes through as the "no viewer" body. */
+function toFocusDTO(row) {
+    if (row === null)
+        return null;
+    return { focus_id: row.focus_id, pane: row.pane, session: row.session, node_id: row.node_id };
+}
+function handleListFocuses() {
+    const body = listFocuses().map((r) => toFocusDTO(r));
+    return { status: 200, body };
+}
+function handleFocusByNode(ctx) {
+    const nodeId = ctx.query.get('node_id');
+    if (nodeId === null || nodeId === '')
+        throw usage('focuses/by-node requires a node_id query param');
+    return { status: 200, body: toFocusDTO(focusOf(nodeId)) };
+}
+function handleFocusByPane(ctx) {
+    const pane = ctx.query.get('pane');
+    if (pane === null || pane === '')
+        throw usage('focuses/by-pane requires a pane query param');
+    return { status: 200, body: toFocusDTO(focusByPane(pane)) };
+}
+function parseRegisterBody(body) {
+    if (typeof body !== 'object' || body === null)
+        throw usage('register-focus body must be a JSON object');
+    const b = body;
+    if (typeof b['node_id'] !== 'string' || b['node_id'] === '')
+        throw usage('node_id is required');
+    if (typeof b['pane'] !== 'string' || b['pane'] === '')
+        throw usage('pane is required');
+    return {
+        node_id: b['node_id'],
+        pane: b['pane'],
+        session: typeof b['session'] === 'string' ? b['session'] : null,
+        window: typeof b['window'] === 'string' ? b['window'] : null,
+    };
+}
+function handleRegisterFocus(ctx) {
+    const req = parseRegisterBody(ctx.body);
+    const row = registerViewerFocus(req.node_id, req.pane, req.session, req.window);
+    return { status: 200, body: toFocusDTO(row) };
+}
+function parseSetPaneBody(body) {
+    if (typeof body !== 'object' || body === null)
+        throw usage('set-focus-pane body must be a JSON object');
+    const b = body;
+    return {
+        pane: typeof b['pane'] === 'string' ? b['pane'] : null,
+        session: typeof b['session'] === 'string' ? b['session'] : null,
+    };
+}
+function handleSetFocusPane(ctx) {
+    const focusId = ctx.params['focus_id'];
+    if (focusId === undefined || focusId === '')
+        throw usage('focus_id is required');
+    const req = parseSetPaneBody(ctx.body);
+    setFocusPane(focusId, req.pane, req.session);
+    return { status: 204 };
+}
+function handleCloseFocus(ctx) {
+    const focusId = ctx.params['focus_id'];
+    if (focusId === undefined || focusId === '')
+        throw usage('focus_id is required');
+    closeFocusRow(focusId);
+    return { status: 204 };
+}
+export const focusRoutes = [
+    { method: 'GET', pattern: '/v1/focuses', handler: handleListFocuses },
+    { method: 'POST', pattern: '/v1/focuses', handler: handleRegisterFocus },
+    { method: 'GET', pattern: '/v1/focuses/by-node', handler: handleFocusByNode },
+    { method: 'GET', pattern: '/v1/focuses/by-pane', handler: handleFocusByPane },
+    { method: 'PATCH', pattern: '/v1/focuses/:focus_id', handler: handleSetFocusPane },
+    { method: 'DELETE', pattern: '/v1/focuses/:focus_id', handler: handleCloseFocus },
+];

package/dist/daemon/api/handlers/health.d.ts

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

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

@@ -0,0 +1,65 @@
+// Health / status handlers (spec §6.1). `GET /healthz` is the unversioned
+// substrate-readiness probe (any-version clients, incl. the P2 provisioning
+// ladder, must reach it); `GET /v1/status` is the informational daemon snapshot
+// backing `crtr sys daemon status` and the dashboard header.
+//
+// Both run INSIDE crtrd, so `daemon_up` is trivially true and `daemon_pid` is
+// this process. Store access is probed by a cheap `listNodes()` — a throw means
+// the store is inaccessible.
+import { listNodes } from '../../../index.js';
+import { apiSocketPath } from '../../../core/canvas/paths.js';
+import { currentVersion } from '../../../core/self-update.js';
+import { API_VERSION } from '../../../api/index.js';
+import { DEFAULT_INTERVAL_MS } from '../../supervise-cadence.js';
+// The daemon's supervise-loop cadence, echoed as an informational field; the
+// loop itself is unchanged (hard constraint). Derived from the single shared
+// constant so it can never drift from crtrd's actual interval.
+const TICK_INTERVAL_MS = DEFAULT_INTERVAL_MS;
+/** Count the canvas rows by status — a cheap store-access probe doubling as the
+ *  status snapshot's `node_counts`. Returns null when the store throws. */
+function nodeCounts() {
+    try {
+        const counts = {};
+        for (const row of listNodes()) {
+            counts[row.status] = (counts[row.status] ?? 0) + 1;
+        }
+        return counts;
+    }
+    catch {
+        return null;
+    }
+}
+function handleHealthz() {
+    const storeAccessible = nodeCounts() !== null;
+    const body = {
+        ok: storeAccessible,
+        daemon_up: true,
+        store_accessible: storeAccessible,
+        brokers_reconciled: true,
+    };
+    return { status: storeAccessible ? 200 : 503, body };
+}
+function handleStatus() {
+    const counts = nodeCounts();
+    if (counts === null) {
+        // The store is unreachable — spec §8 store_unavailable.
+        throw { status: 503, code: 'store_unavailable', message: 'canvas store is inaccessible' };
+    }
+    const tcp = process.env['CRTRD_TCP'];
+    const body = {
+        daemon_pid: process.pid,
+        tick_interval_ms: TICK_INTERVAL_MS,
+        node_counts: counts,
+        listeners: {
+            socket_path: apiSocketPath(),
+            tcp: tcp !== undefined && tcp !== '' ? tcp : null,
+        },
+        runtime_version: currentVersion(),
+        api_version: API_VERSION,
+    };
+    return { status: 200, body };
+}
+export const healthRoutes = [
+    { method: 'GET', pattern: '/healthz', handler: (_ctx) => handleHealthz() },
+    { method: 'GET', pattern: '/v1/status', handler: (_ctx) => handleStatus() },
+];

package/dist/daemon/api/handlers/human.d.ts

@@ -0,0 +1,12 @@
+import type { CompletionHandler } from '@crouton-kit/humanloop';
+import type { RouteTable } from '../router.js';
+/** A broker retains its sealed runtime generation across installs. Humanloop
+ * freezes that generation's `_visual` argv into the request, while crtrd may
+ * already run a newer sibling generation when the human opens the ticket.
+ * Accept only a Node invocation of the same leaf from an immutable 64-hex
+ * generation beneath the current handler's exact generations directory. The
+ * command differs legitimately: CLI registrations use the system Node path,
+ * while the daemon runs through crouter's stable copied-Node host. */
+export declare function trustedCrouterHandler(candidate: CompletionHandler | undefined, current: CompletionHandler, leaf: '_visual' | '_consult'): boolean;
+export declare function trustedCrouterVisualHandler(candidate: CompletionHandler | undefined, current?: CompletionHandler): boolean;
+export declare const humanRoutes: RouteTable;