@north-light/api 0.3.580 → 0.3.588

package/dist/core/tui/panel.js

@@ -0,0 +1,142 @@
+import { getMarkdownTheme, getSelectListTheme, getSettingsListTheme, } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { detectColorCaps } from './draw.js';
+const ansiGreen = (text) => `\x1b[32m${text}\x1b[39m`;
+const ansiYellow = (text) => `\x1b[33m${text}\x1b[39m`;
+export const theme = {
+    fg(role, text) {
+        // NO_COLOR, TERM=dumb, and non-TTY output get no foreground color; the
+        // pi themes below color unconditionally.
+        if (!detectColorCaps().color)
+            return text;
+        switch (role) {
+            case "border":
+                return getMarkdownTheme().hr(text);
+            case "accent":
+                return getMarkdownTheme().heading(text);
+            case "dim":
+                return getSettingsListTheme().description(text);
+            case "muted":
+                return getSelectListTheme().description(text);
+            case "mdLink":
+                return getMarkdownTheme().link(text);
+            case "mdLinkUrl":
+                return getMarkdownTheme().linkUrl(text);
+            case "success":
+                return ansiGreen(text);
+            case "warning":
+                return ansiYellow(text);
+        }
+    },
+    /** A real filled selection band. An identity `selectedBg` would leave the
+     *  active tab and the active row with no background at all — reverse video is
+     *  the one background every terminal theme honours. */
+    bg(_role, text) {
+        return `\x1b[7m${text}\x1b[27m`;
+    },
+    bold(text) {
+        return getMarkdownTheme().bold(text);
+    },
+};
+export function wrapText(text, width) {
+    const clean = text.trim();
+    if (clean === "")
+        return [""];
+    if (width <= 1)
+        return [truncateToWidth(clean, width)];
+    const lines = [];
+    let current = "";
+    for (const word of clean.split(/\s+/)) {
+        if (current === "") {
+            current = word;
+            continue;
+        }
+        const next = `${current} ${word}`;
+        if (truncateToWidth(next, width) === next)
+            current = next;
+        else {
+            lines.push(truncateToWidth(current, width));
+            current = word;
+        }
+    }
+    if (current !== "")
+        lines.push(truncateToWidth(current, width));
+    return lines.length > 0 ? lines : [""];
+}
+export function renderRows(lines, width) {
+    return lines.map((line) => truncateToWidth(line, width));
+}
+export function padAnsi(text, width) {
+    const used = visibleWidth(text);
+    return used >= width
+        ? truncateToWidth(text, width)
+        : `${text}${" ".repeat(width - used)}`;
+}
+export function rule(width) {
+    return theme.fg("border", "─".repeat(Math.max(0, width)));
+}
+export function visibleRange(count, selected, capacity) {
+    if (count <= 0)
+        return { start: 0, end: 0 };
+    const cap = Math.max(1, Math.min(capacity, count));
+    const start = Math.max(0, Math.min(selected - Math.floor(cap / 2), count - cap));
+    return { start, end: Math.min(count, start + cap) };
+}
+/** A bordered box for an emphasised sub-region — an input field, a modal. Panel
+ *  bodies are not boxed: the page frame and rail divider already frame them. */
+export function framed(lines, width) {
+    if (width < 4)
+        return lines.map((line) => truncateToWidth(line, width));
+    const innerWidth = width - 4;
+    const border = theme.fg("border", "│");
+    const top = theme.fg("border", `┌${"─".repeat(width - 2)}┐`);
+    const bottom = theme.fg("border", `└${"─".repeat(width - 2)}┘`);
+    return [
+        top,
+        ...lines.map((line) => `${border} ${padAnsi(truncateToWidth(line, innerWidth), innerWidth)} ${border}`),
+        bottom,
+    ];
+}
+export function fitTail(lines, budget) {
+    return budget >= lines.length ? lines : lines.slice(lines.length - budget);
+}
+// Page chrome shared by the settings shell and the setup wizard
+/** Rows the page frame spends on its own title, rules and footer. */
+export const PAGE_CHROME_ROWS = 4;
+/** Title row with right-aligned scope metadata, a rule under it, the body
+ *  padded to fill the viewport, a rule, and the footer pinned to the last row.
+ *  Every settings/setup screen goes through this so the footer never floats in
+ *  the middle of a half-empty terminal. */
+export function pageFrame(opts) {
+    const { width, height, title, meta, body, footer } = opts;
+    const heading = theme.fg("accent", theme.bold(title));
+    const right = meta ? theme.fg("dim", meta) : "";
+    const gap = width - visibleWidth(heading) - visibleWidth(right);
+    const titleRow = right !== "" && gap >= 2
+        ? `${heading}${" ".repeat(gap)}${right}`
+        : truncateToWidth(heading, width);
+    const budget = Math.max(1, height - PAGE_CHROME_ROWS);
+    const filled = body.slice(0, budget);
+    while (filled.length < budget)
+        filled.push("");
+    return [
+        truncateToWidth(titleRow, width),
+        rule(width),
+        ...filled.map((line) => truncateToWidth(line, width)),
+        rule(width),
+        truncateToWidth(footer, width),
+    ];
+}
+/** Two columns joined by a vertical divider, each already wrapped to its own
+ *  width. Short columns pad; the taller one sets the height. */
+export function columns(left, leftWidth, right, rightWidth) {
+    const divider = theme.fg("border", "\u2502");
+    const rows = Math.max(left.length, right.length);
+    const out = [];
+    for (let index = 0; index < rows; index += 1) {
+        const leftCell = padAnsi(left[index] ?? "", leftWidth);
+        const rightCell = truncateToWidth(right[index] ?? "", rightWidth);
+        out.push(`${leftCell} ${divider} ${rightCell}`);
+    }
+    return out;
+}

package/dist/core/tui/terminal.d.ts

@@ -0,0 +1,23 @@
+export interface Key {
+    upArrow: boolean;
+    downArrow: boolean;
+    leftArrow: boolean;
+    rightArrow: boolean;
+    return: boolean;
+    escape: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    tab: boolean;
+    shiftTab: boolean;
+    backspace: boolean;
+}
+export declare function parseKeypress(data: Buffer): {
+    input: string;
+    key: Key;
+};
+export declare function setupTerminal(): void;
+export declare function restoreTerminal(): void;
+export declare function getTerminalSize(): {
+    cols: number;
+    rows: number;
+};

package/dist/core/tui/terminal.js

@@ -0,0 +1,100 @@
+// terminal.ts — raw-mode helpers shared by every crtr raw-ANSI TUI.
+//
+// Moved verbatim from src/core/canvas/browse/terminal.ts (it was already
+// generic). Hand-rolled (no deps). Extends basic key parsing beyond up/down/return/escape/tab/backspace/ctrl +
+// printable input: adds leftArrow/rightArrow (cursor keys) and shiftTab
+// (`\x1b[Z`) so callers can drive tree expand/collapse and tab cycling.
+function emptyKey() {
+    return {
+        upArrow: false,
+        downArrow: false,
+        leftArrow: false,
+        rightArrow: false,
+        return: false,
+        escape: false,
+        ctrl: false,
+        meta: false,
+        tab: false,
+        shiftTab: false,
+        backspace: false,
+    };
+}
+export function parseKeypress(data) {
+    const str = data.toString('utf8');
+    const key = emptyKey();
+    if (str === '\x1b[A') {
+        key.upArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[B') {
+        key.downArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[C') {
+        key.rightArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[D') {
+        key.leftArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[Z') {
+        key.shiftTab = true;
+        return { input: '', key };
+    }
+    if (str === '\r' || str === '\n') {
+        key.return = true;
+        return { input: '', key };
+    }
+    // Alt+Backspace: terminals send ESC followed by DEL/BS. Must precede the
+    // bare-ESC check so the two-byte sequence isn't swallowed as plain escape.
+    if (str === '\x1b\x7f' || str === '\x1b\b') {
+        key.meta = true;
+        key.backspace = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b') {
+        key.escape = true;
+        return { input: '', key };
+    }
+    if (str === '\t') {
+        key.tab = true;
+        return { input: '', key };
+    }
+    if (str === '\x7f' || str === '\b') {
+        key.backspace = true;
+        return { input: '', key };
+    }
+    if (str.length === 1 && str.charCodeAt(0) < 32) {
+        key.ctrl = true;
+        const ch = String.fromCharCode(str.charCodeAt(0) + 64).toLowerCase();
+        return { input: ch, key };
+    }
+    // Multi-byte chunks (paste, multi-byte UTF-8, unknown escape sequences) are
+    // returned as-is in `input`; the input-mode handler sanitises them before
+    // appending to its buffer. Top-level handlers ignore strings of length > 1.
+    return { input: str, key };
+}
+export function setupTerminal() {
+    if (!process.stdin.isTTY) {
+        throw new Error('this TUI requires an interactive terminal (TTY)');
+    }
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write('\x1b[?25l'); // hide cursor
+    process.stdout.write('\x1b[?1049h'); // alt screen
+    process.stdout.write('\x1b[2J\x1b[H'); // clear
+}
+export function restoreTerminal() {
+    process.stdout.write('\x1b[?25h'); // show cursor
+    process.stdout.write('\x1b[?1049l'); // restore screen
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+}
+export function getTerminalSize() {
+    return {
+        cols: process.stdout.columns || 80,
+        rows: process.stdout.rows || 24,
+    };
+}

package/dist/core/wake.d.ts

@@ -0,0 +1,89 @@
+/** Error codes this module owns (a subset of surface-design §4.3). */
+export type WakeErrorCode = 'wake_in_past' | 'bad_when' | 'bad_cadence' | 'unknown_zone' | 'cadence_too_fast';
+export interface WakeError {
+    code: WakeErrorCode;
+    message: string;
+    /** The offending input, echoed back for the rendered error block. */
+    received: string;
+}
+export type WhenResult = {
+    fireAt: string;
+} | {
+    error: WakeError;
+};
+export type CadenceResult = {
+    recur: string;
+    firstFireAt: string;
+} | {
+    error: WakeError;
+};
+export interface ParseOpts {
+    /** IANA zone for bare wall-clock / calendar cadence; defaults to host-local. */
+    tz?: string;
+    /** Resolution anchor (frozen "now"). */
+    now: Date;
+}
+/**
+ * The two `recur` JSON shapes (pinned in the plan's Shared contracts). Stored
+ * as a JSON string in the `crons.recur` column; consumed by `nextSlotAfter`.
+ */
+export type Recur = {
+    every: string;
+} | {
+    cron: string;
+    tz: string;
+};
+/** Cadence floor: reject any interval / cron min-spacing below this (AC-N4). */
+export declare const CADENCE_FLOOR_MS = 60000;
+/** Total ms for a relative-duration string (`90s`, `10m`, `1h30m`), or null if
+ * it is not one. */
+export declare function parseDurationMs(s: string): number | null;
+/**
+ * Resolve a `<when>` to a single UTC `fireAt`:
+ *   - relative duration (`90s`, `1h30m`)        -> now + Σ
+ *   - absolute zoned ISO (`…Z` / `±HH:MM`)       -> that exact instant
+ *   - absolute bare ISO (`2026-06-07T09:00`)     -> wall clock in `tz`
+ *                                                   (default host-local) -> UTC
+ *
+ * A bare wall-clock time is interpreted in `opts.tz` when given, else the host
+ * zone, and frozen to a UTC instant (DST never re-enters a one-shot). A
+ * resolved instant not strictly in the future is rejected (`wake_in_past`).
+ */
+export declare function parseWhen(when: string, opts: ParseOpts): WhenResult;
+/**
+ * Resolve a `<cadence>` (the `--every` value) to a stored `recur` JSON string
+ * plus the first `fireAt`:
+ *   - fixed interval (a duration)  -> {"every":"<dur>"},   first = now + interval
+ *   - calendar cron / @alias       -> {"cron":"<5-field>","tz":"<iana>"},
+ *                                     first = next match strictly after now
+ *
+ * Aliases (`@daily`) are expanded to a 5-field cron before baking, and the
+ * IANA zone (from `opts.tz`, else host-local) is baked in so the engine stays a
+ * pure UTC evaluator (design D7). Rejects sub-floor spacing (`cadence_too_fast`,
+ * < 60s — for both intervals and seconds-granular crons), ungrammatical input
+ * (`bad_cadence`), and unknown zones (`unknown_zone`).
+ */
+export declare function parseCadence(every: string, opts: ParseOpts): CadenceResult;
+/**
+ * Render a stored `recur` JSON as a compact, human-readable cadence:
+ *   - {"every":"6h"}                         -> `every 6h`
+ *   - {"cron":"0 9 * * *","tz":"America/…"}  -> ``cron `0 9 * * *` (America/…)``
+ *   - null / undefined / unparseable         -> `none`
+ *
+ * The ONE cadence-display helper, shared by the cron CLI surface and the
+ * <crtr-wake> wake-provenance block (bearings.ts), so the cadence an agent
+ * reads in its wake block matches `crtr cron` exactly. Cadence only — never an
+ * instance count.
+ */
+export declare function cadenceDisplay(recur: string | null | undefined): string;
+/**
+ * Earliest occurrence of `recur` strictly greater than `now`, as a UTC ISO
+ * string. Anchors on `now` (not the stored `fire_at`), so it structurally
+ * coalesces every slot missed while the daemon was down (design §5.3, AC-E2).
+ * DST-correct because the IANA zone is baked into a calendar `recur`.
+ *
+ * parseCadence validates the cadence at arm time, so a throw here is a rare
+ * backstop (a corrupted/foreign row) — T4 must quarantine such a row, never
+ * re-query it each tick.
+ */
+export declare function nextSlotAfter(recur: string, now: Date): string;

package/dist/core/wake.js

@@ -0,0 +1,296 @@
+// Time grammar + recurrence evaluation for crons.
+//
+// This is the ONE place that owns cron time logic. Both the CLI surface and the
+// daemon's firing pass import from here, so there is no duplicated cron usage
+// and no surface<->daemon inverted dependency:
+//   - parseWhen / parseCadence  — arm-time grammar (surface)
+//   - nextSlotAfter             — per-tick advance / coalescing (daemon)
+//
+// Design refs: surface-design §4 (grammar), §5 (timezone/DST ruling),
+// design §5.3 + D7 (engine evaluates UTC; the surface bakes the IANA zone
+// into a calendar `recur`). Tick-scale only — no sub-second precision.
+import { CronExpressionParser } from 'cron-parser';
+// Constants
+/** Cadence floor: reject any interval / cron min-spacing below this (AC-N4). */
+export const CADENCE_FLOOR_MS = 60_000;
+const DURATION_UNIT_MS = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+// `<int><unit>` repeated; units s/m/h/d (surface-design §4.1).
+const DURATION_RE = /^\+?(?:\d+[smhd])+$/;
+const DURATION_PART_RE = /(\d+)([smhd])/g;
+// ISO-8601 date-time core (no zone). Captures Y M D h m [s] [ms].
+const ISO_CORE_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d{1,3}))?/;
+// Trailing zone designator: Z | ±HH[:MM] | ±HHMM.
+const ZONE_SUFFIX_RE = /^(Z|[+-]\d{2}(?::?\d{2})?)$/;
+// Cron `@alias` -> 5-field expansion (the engine never stores a bare alias).
+const CRON_ALIASES = {
+    '@yearly': '0 0 1 1 *',
+    '@annually': '0 0 1 1 *',
+    '@monthly': '0 0 1 * *',
+    '@weekly': '0 0 * * 0',
+    '@daily': '0 0 * * *',
+    '@midnight': '0 0 * * *',
+    '@hourly': '0 * * * *',
+};
+// Internal helpers
+function whenError(code, message, received) {
+    return { error: { code, message, received } };
+}
+function cadenceError(code, message, received) {
+    return { error: { code, message, received } };
+}
+/** Total ms for a relative-duration string (`90s`, `10m`, `1h30m`), or null if
+ * it is not one. */
+export function parseDurationMs(s) {
+    if (!DURATION_RE.test(s))
+        return null;
+    let total = 0;
+    DURATION_PART_RE.lastIndex = 0;
+    let m;
+    while ((m = DURATION_PART_RE.exec(s)) !== null) {
+        total += Number(m[1]) * DURATION_UNIT_MS[m[2]];
+    }
+    return total;
+}
+/** Host-configured IANA zone (crtr is a single-machine runtime). */
+function hostZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+}
+/** True iff `tz` is a resolvable IANA zone name. */
+function isValidZone(tz) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Offset (ms) of `tz` at the given UTC instant: wall-clock-as-UTC minus instant. */
+function zoneOffsetMs(tz, utcMs) {
+    const dtf = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+    });
+    const parts = {};
+    for (const p of dtf.formatToParts(new Date(utcMs))) {
+        if (p.type !== 'literal')
+            parts[p.type] = p.value;
+    }
+    const asUTC = Date.UTC(Number(parts['year']), Number(parts['month']) - 1, Number(parts['day']), Number(parts['hour']), Number(parts['minute']), Number(parts['second']));
+    return asUTC - utcMs;
+}
+/** Interpret a wall-clock instant in `tz` and return the UTC ms instant. */
+function wallClockToUtc(y, mo, d, h, mi, s, ms, tz) {
+    const guess = Date.UTC(y, mo - 1, d, h, mi, s, ms);
+    const off1 = zoneOffsetMs(tz, guess);
+    let utc = guess - off1;
+    // Second pass settles DST-boundary cases where the offset at the candidate
+    // instant differs from the offset at the naive guess.
+    const off2 = zoneOffsetMs(tz, utc);
+    if (off2 !== off1)
+        utc = guess - off2;
+    return utc;
+}
+/** Classify a string as a zoned/bare ISO date-time, or null if it is neither. */
+function classifyIso(s) {
+    const m = ISO_CORE_RE.exec(s);
+    if (!m || m.index !== 0)
+        return null;
+    const rest = s.slice(m[0].length);
+    if (rest === '') {
+        return {
+            zoned: false,
+            y: Number(m[1]),
+            mo: Number(m[2]),
+            d: Number(m[3]),
+            h: Number(m[4]),
+            mi: Number(m[5]),
+            s: m[6] ? Number(m[6]) : 0,
+            ms: m[7] ? Number(m[7].padEnd(3, '0')) : 0,
+        };
+    }
+    if (ZONE_SUFFIX_RE.test(rest))
+        return { zoned: true };
+    return null; // trailing garbage -> not a valid ISO instant
+}
+// parseWhen — resolve a one-shot <when> to an absolute UTC instant
+/**
+ * Resolve a `<when>` to a single UTC `fireAt`:
+ *   - relative duration (`90s`, `1h30m`)        -> now + Σ
+ *   - absolute zoned ISO (`…Z` / `±HH:MM`)       -> that exact instant
+ *   - absolute bare ISO (`2026-06-07T09:00`)     -> wall clock in `tz`
+ *                                                   (default host-local) -> UTC
+ *
+ * A bare wall-clock time is interpreted in `opts.tz` when given, else the host
+ * zone, and frozen to a UTC instant (DST never re-enters a one-shot). A
+ * resolved instant not strictly in the future is rejected (`wake_in_past`).
+ */
+export function parseWhen(when, opts) {
+    const received = when;
+    const raw = when.trim();
+    const nowMs = opts.now.getTime();
+    // 1. relative duration
+    const durMs = parseDurationMs(raw);
+    if (durMs !== null) {
+        const fireMs = nowMs + durMs;
+        if (fireMs <= nowMs) {
+            return whenError('wake_in_past', `That resolves to now or the past. Use a positive future duration (e.g. "5m", "2h").`, received);
+        }
+        return { fireAt: new Date(fireMs).toISOString() };
+    }
+    // 2/3. absolute ISO (zoned or bare)
+    const iso = classifyIso(raw);
+    if (iso) {
+        let fireMs;
+        if (iso.zoned) {
+            const d = new Date(raw);
+            if (Number.isNaN(d.getTime())) {
+                return whenError('bad_when', `Not a valid ISO-8601 instant: "${received}".`, received);
+            }
+            fireMs = d.getTime();
+        }
+        else {
+            const tz = opts.tz ?? hostZone();
+            if (!isValidZone(tz)) {
+                return whenError('unknown_zone', `Unknown time zone: "${tz}". Use an IANA name (e.g. "America/New_York").`, opts.tz ?? tz);
+            }
+            fireMs = wallClockToUtc(iso.y, iso.mo, iso.d, iso.h, iso.mi, iso.s, iso.ms, tz);
+            if (Number.isNaN(fireMs)) {
+                return whenError('bad_when', `Not a valid date-time: "${received}".`, received);
+            }
+        }
+        if (fireMs <= nowMs) {
+            return whenError('wake_in_past', `That time is now or in the past. Pick a future instant.`, received);
+        }
+        return { fireAt: new Date(fireMs).toISOString() };
+    }
+    return whenError('bad_when', `Could not parse "${received}". Use a duration ("5m", "1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00").`, received);
+}
+// parseCadence — resolve --every to a stored recur + first fire
+/**
+ * Resolve a `<cadence>` (the `--every` value) to a stored `recur` JSON string
+ * plus the first `fireAt`:
+ *   - fixed interval (a duration)  -> {"every":"<dur>"},   first = now + interval
+ *   - calendar cron / @alias       -> {"cron":"<5-field>","tz":"<iana>"},
+ *                                     first = next match strictly after now
+ *
+ * Aliases (`@daily`) are expanded to a 5-field cron before baking, and the
+ * IANA zone (from `opts.tz`, else host-local) is baked in so the engine stays a
+ * pure UTC evaluator (design D7). Rejects sub-floor spacing (`cadence_too_fast`,
+ * < 60s — for both intervals and seconds-granular crons), ungrammatical input
+ * (`bad_cadence`), and unknown zones (`unknown_zone`).
+ */
+export function parseCadence(every, opts) {
+    const received = every;
+    const raw = every.trim();
+    const nowMs = opts.now.getTime();
+    // 1. fixed interval
+    const durMs = parseDurationMs(raw);
+    if (durMs !== null) {
+        if (durMs < CADENCE_FLOOR_MS) {
+            return cadenceError('cadence_too_fast', `Interval too fast: minimum cadence is 60s. Use a longer --every (e.g. "1m", "5m", "1h").`, received);
+        }
+        return {
+            recur: JSON.stringify({ every: raw }),
+            firstFireAt: new Date(nowMs + durMs).toISOString(),
+        };
+    }
+    // 2. calendar cron / alias
+    const expanded = CRON_ALIASES[raw] ?? raw;
+    const tz = opts.tz ?? hostZone();
+    if (opts.tz !== undefined && !isValidZone(opts.tz)) {
+        return cadenceError('unknown_zone', `Unknown time zone: "${opts.tz}". Use an IANA name (e.g. "America/New_York").`, opts.tz);
+    }
+    let interval;
+    let firstFireAt;
+    try {
+        interval = CronExpressionParser.parse(expanded, { currentDate: opts.now, tz });
+        firstFireAt = interval.next().toDate().toISOString();
+    }
+    catch {
+        return cadenceError('bad_cadence', `Could not parse cadence "${received}". Use a duration ("6h"), a 5-field cron ("0 9 * * *"), or an @alias ("@daily").`, received);
+    }
+    // Cadence floor: a 5-field cron is always >=60s; only a seconds-granular cron
+    // (multiple values in the seconds field) can resolve below the floor.
+    const secField = interval.fields?.second;
+    const secValues = secField && Array.isArray(secField.values) ? secField.values : [0];
+    if (secValues.length > 1) {
+        return cadenceError('cadence_too_fast', `Cron resolves below the 60s floor (sub-minute spacing). Use a cadence of at least one minute.`, received);
+    }
+    return {
+        recur: JSON.stringify({ cron: expanded, tz }),
+        firstFireAt,
+    };
+}
+// cadenceDisplay — a recur JSON rendered for humans + agents
+/**
+ * Render a stored `recur` JSON as a compact, human-readable cadence:
+ *   - {"every":"6h"}                         -> `every 6h`
+ *   - {"cron":"0 9 * * *","tz":"America/…"}  -> ``cron `0 9 * * *` (America/…)``
+ *   - null / undefined / unparseable         -> `none`
+ *
+ * The ONE cadence-display helper, shared by the cron CLI surface and the
+ * <crtr-wake> wake-provenance block (bearings.ts), so the cadence an agent
+ * reads in its wake block matches `crtr cron` exactly. Cadence only — never an
+ * instance count.
+ */
+export function cadenceDisplay(recur) {
+    if (recur === null || recur === undefined)
+        return 'none';
+    try {
+        const r = JSON.parse(recur);
+        if (typeof r.every === 'string')
+            return `every ${r.every}`;
+        if (typeof r.cron === 'string') {
+            return `cron \`${r.cron}\`${typeof r.tz === 'string' ? ` (${r.tz})` : ''}`;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return 'none';
+}
+// nextSlotAfter — the coalescing primitive (daemon advance)
+/**
+ * Earliest occurrence of `recur` strictly greater than `now`, as a UTC ISO
+ * string. Anchors on `now` (not the stored `fire_at`), so it structurally
+ * coalesces every slot missed while the daemon was down (design §5.3, AC-E2).
+ * DST-correct because the IANA zone is baked into a calendar `recur`.
+ *
+ * parseCadence validates the cadence at arm time, so a throw here is a rare
+ * backstop (a corrupted/foreign row) — T4 must quarantine such a row, never
+ * re-query it each tick.
+ */
+export function nextSlotAfter(recur, now) {
+    let parsed;
+    try {
+        parsed = JSON.parse(recur);
+    }
+    catch {
+        throw new Error(`nextSlotAfter: malformed recur JSON: ${recur}`);
+    }
+    if (typeof parsed.every === 'string') {
+        const ms = parseDurationMs(parsed.every);
+        if (ms === null || ms <= 0) {
+            throw new Error(`nextSlotAfter: invalid interval recur: ${recur}`);
+        }
+        return new Date(now.getTime() + ms).toISOString();
+    }
+    if (typeof parsed.cron === 'string') {
+        const tz = typeof parsed.tz === 'string' ? parsed.tz : 'UTC';
+        const interval = CronExpressionParser.parse(parsed.cron, { currentDate: now, tz });
+        return interval.next().toDate().toISOString(); // strictly after `now`
+    }
+    throw new Error(`nextSlotAfter: recur has neither 'every' nor 'cron': ${recur}`);
+}

package/dist/core/worktree-containment.d.ts

@@ -0,0 +1,14 @@
+import type { ManagedWorktree } from './canvas/index.js';
+export interface BranchContainmentProof {
+    containingRef: string;
+    containingSha: string;
+}
+/** Resolve the base branch's configured upstream, or its origin fallback. */
+export declare function upstreamTip(cwd: string, baseRef: string): Promise<{
+    ref: string;
+    sha: string;
+} | null>;
+/** Prove that a recorded base or its upstream already carries a branch's
+ * committed content. This is the one decision point for explicit close and
+ * sweep cleanup: destination resolution happens only when this returns null. */
+export declare function proveBranchContained(cwd: string, wt: Pick<ManagedWorktree, 'base_ref'>, branchSha: string): Promise<BranchContainmentProof | null>;