@north-light/cli 0.0.0-stage → 0.3.413

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

@@ -0,0 +1,17 @@
+import { type Span, type Style } from './draw.js';
+/** Parse inline markup left to right, recursing on delimited content with the
+ *  base style extended. Unclosed or implausible delimiters stay literal, which is
+ *  the right failure mode for a preview: never eat the user's text. */
+export declare function inlineSpans(src: string, base?: Style): Span[];
+/**
+ * Render `src` as markdown into at most `maxLines` span groups, each already
+ * wrapped to `width` visible columns.
+ *
+ * `spacing` inserts a blank line between blocks — true where the panel has room
+ * to breathe, false in a cramped one where every line counts. Consecutive list
+ * items never get one, so a tight list stays tight.
+ *
+ * `base` is the style every rendered run inherits (the caller's block style,
+ * e.g. the dim of a report body); markdown's own styles layer over it.
+ */
+export declare function renderMarkdownSpans(src: string, width: number, maxLines: number, spacing?: boolean, base?: Style): Span[][];

package/dist/core/tui/markdown.js

@@ -0,0 +1,3 @@
+var j=Object.defineProperty;var h=(t,e)=>j(t,"name",{value:e,configurable:!0});import{clip as R}from"./draw.js";const E="36";function x(t,e){const i={},n=e.fg??t.fg,r=e.bg??t.bg;return n!==void 0&&(i.fg=n),r!==void 0&&(i.bg=r),(e.bold||t.bold)&&(i.bold=!0),(e.dim||t.dim)&&(i.dim=!0),(e.italic||t.italic)&&(i.italic=!0),(e.reverse||t.reverse)&&(i.reverse=!0),i}h(x,"extend");const v=/^\s{0,3}(```|~~~)/,S=/^\s{0,3}(#{1,6})\s+(.*)$/,B=/^(\s*)[-*+]\s+(.*)$/,O=/^(\s*)(\d{1,9})[.)]\s+(.*)$/,_=/^\s{0,3}>\s?(.*)$/,A=/^\s{0,3}(?:(?:-\s*){3,}|(?:\*\s*){3,}|(?:_\s*){3,})$/,$=/^\s*\|/;function w(t){return v.test(t)||S.test(t)||A.test(t)||B.test(t)||O.test(t)||_.test(t)||$.test(t)}h(w,"isBlockStart");function q(t){const e=t.replace(/\r\n?/g,`
+`).split(`
+`),i=[];let n=0;for(;n<e.length;){const r=e[n];if(r.trim()===""){n++;continue}const f=v.exec(r);if(f!==null){const c=f[1];n++;const a=[];for(;n<e.length&&!e[n].trimStart().startsWith(c);)a.push(e[n]),n++;n<e.length&&n++,i.push({k:"code",lines:a});continue}if(A.test(r)){i.push({k:"rule"}),n++;continue}const u=S.exec(r);if(u!==null){i.push({k:"head",level:u[1].length,text:u[2].replace(/\s+#+\s*$/,"").trim()}),n++;continue}if($.test(r)){const c=[];for(;n<e.length&&$.test(e[n]);)c.push(e[n].trim()),n++;i.push({k:"table",lines:c});continue}const s=B.exec(r),o=s===null?O.exec(r):null;if(s!==null||o!==null){const c=(s!==null?s[1]:o[1]).length,a=s!==null?"\u2022 ":`${o[2]}. `;let g=s!==null?s[2]:o[3];for(n++;n<e.length&&e[n].trim()!==""&&!w(e[n]);)g+=` ${e[n].trim()}`,n++;i.push({k:"item",depth:Math.min(4,Math.floor(c/2)),marker:a,text:g.trim()});continue}const l=_.exec(r);if(l!==null){let c=l[1];for(n++;!(n>=e.length);){const a=_.exec(e[n]);if(a!==null){c+=` ${a[1]}`,n++;continue}if(e[n].trim()!==""&&!w(e[n])){c+=` ${e[n].trim()}`,n++;continue}break}i.push({k:"quote",text:c.trim()});continue}let p=r.trim();for(n++;n<e.length&&e[n].trim()!==""&&!w(e[n]);)p+=` ${e[n].trim()}`,n++;i.push({k:"para",text:p})}return i}h(q,"parseBlocks");const C=/[\\`*_~[\]()#>-]/;function m(t,e={}){const i=[];let n="";const r=h(()=>{n!==""&&(i.push({text:n,style:e}),n="")},"flush"),f=h(o=>{r();for(const l of o)i.push(l)},"emit"),u=t.length;let s=0;for(;s<u;){const o=t[s];if(o==="\\"&&s+1<u&&C.test(t[s+1])){n+=t[s+1],s+=2;continue}if(o==="`"){const l=t.indexOf("`",s+1);if(l>s+1){f([{text:t.slice(s+1,l),style:x(e,{fg:E})}]),s=l+1;continue}}if(o==="["){const l=t.indexOf("]",s+1);if(l>s+1&&t[l+1]==="("){const p=t.indexOf(")",l+2);if(p>l){f(m(t.slice(s+1,l),x(e,{fg:E}))),s=p+1;continue}}}if(o==="~"&&t[s+1]==="~"){const l=t.indexOf("~~",s+2);if(l>s+1){f(m(t.slice(s+2,l),x(e,{dim:!0}))),s=l+2;continue}}if(o==="*"||o==="_"){const l=t[s+1]===o?t[s+2]===o?3:2:1,p=o.repeat(l);if(!(o==="_"&&s>0&&/\w/.test(t[s-1]))&&s+l<u&&!/\s/.test(t[s+l])){let g=-1,y=s+l;for(;;){const d=t.indexOf(p,y);if(d<0)break;const M=!/\s/.test(t[d-1]??" "),T=o==="_"&&/\w/.test(t[d+l]??"");if(M&&!T){g=d;break}y=d+1}if(g>s){const d=l===3?{bold:!0,italic:!0}:l===2?{bold:!0}:{italic:!0};f(m(t.slice(s+l,g),x(e,d))),s=g+l;continue}}}n+=o,s++}return r(),i}h(m,"inlineSpans");function L(t){let e=0;for(const i of t)e+=[...i.text].length;return e}h(L,"spanWidth");function F(t,e){return t===e?!0:t===void 0||e===void 0?!1:t.fg===e.fg&&t.bg===e.bg&&!!t.bold==!!e.bold&&!!t.dim==!!e.dim&&!!t.italic==!!e.italic&&!!t.reverse==!!e.reverse}h(F,"sameStyle");function U(t){const e=[];for(const i of t){const n=e[e.length-1];n!==void 0&&F(n.style,i.style)?n.text+=i.text:e.push({text:i.text,...i.style===void 0?{}:{style:i.style}})}return e}h(U,"coalesce");function k(t,e,i,n){const r=[],f=h(c=>Math.max(1,e-L(c===0?i:n)),"limitFor");let u=[],s=0,o=f(0);const l=h(()=>{r.push(U([...r.length===0?i:n,...u])),u=[],s=0,o=f(r.length)},"flushLine");let p=!1;for(const c of t)for(const a of c.text.split(/(\s+)/)){if(a==="")continue;if(/^\s+$/.test(a)){s>0&&(p=!0);continue}const g=[...a].length;if(s+(p?1:0)+g<=o){p&&(u.push({text:" ",style:c.style}),s++),u.push({text:a,style:c.style}),s+=g,p=!1;continue}s>0&&l(),p=!1;let d=[...a];for(;d.length>o;)u.push({text:d.slice(0,o).join(""),style:c.style}),d=d.slice(o),l();d.length>0&&(u.push({text:d.join(""),style:c.style}),s=d.length)}return u.length>0&&l(),r}h(k,"wrapSpans");function D(t,e,i){switch(t.k){case"rule":return[[{text:"\u2500".repeat(Math.max(1,e)),style:{dim:!0}}]];case"code":return t.lines.map(n=>[{text:R(n.replace(/\t/g,"  "),e),style:x(i,{fg:E})}]);case"table":return t.lines.map(n=>[{text:R(n,e),style:x(i,{dim:!0})}]);case"head":{const n=x(i,t.level>=3?{bold:!0,dim:!0}:{bold:!0});return k(m(t.text,n),e,[],[])}case"item":{const n=" ".repeat(t.depth*2),r=[{text:n},{text:t.marker,style:x(i,{dim:!0})}],f=[{text:n+" ".repeat([...t.marker].length)}];return k(m(t.text,i),e,r,f)}case"quote":{const n=[{text:"\u258F ",style:{dim:!0}}];return k(m(t.text,x(i,{dim:!0})),e,n,n)}case"para":return k(m(t.text,i),e,[],[])}}h(D,"blockToLines");function N(t,e){const i=t[t.length-1];if(i===void 0)return;let n=L(i);for(;n>e-1&&i.length>0;){const r=i[i.length-1],f=[...r.text];f.length<=1?(i.pop(),n-=f.length):(r.text=f.slice(0,-1).join(""),n--)}i.push({text:"\u2026",style:{dim:!0}})}h(N,"appendEllipsis");function H(t,e,i,n=!1,r={}){if(e<=0||i<=0)return[];const f=q(t),u=[];let s=!1,o;for(const l of f){if(u.length>=i){s=!0;break}o!==void 0&&n&&!(o.k==="item"&&l.k==="item")&&u.push([]);for(const p of D(l,e,r)){if(u.length>=i){s=!0;break}u.push(p)}o=l}for(;u.length>0&&u[u.length-1].length===0;)u.pop();return s&&N(u,e),u}h(H,"renderMarkdownSpans");export{m as inlineSpans,H as renderMarkdownSpans};

package/dist/core/tui/page-host.d.ts

@@ -0,0 +1,31 @@
+import { ProcessTerminal, type Component, type Focusable, type TUI } from '@earendil-works/pi-tui';
+import { readRawScopeConfig } from '../config.js';
+import { type BindingId, type BindingResolution } from '../keybindings/index.js';
+/** A full-screen page: a focusable TUI component that cleans up after itself. */
+export type TuiPageSurface = Component & Focusable & {
+    dispose(): void;
+};
+export interface TuiPageContext {
+    tui: TUI;
+    terminal: ProcessTerminal;
+    bindings: BindingResolution<BindingId>;
+    rawUserConfig: ReturnType<typeof readRawScopeConfig>;
+    /**
+     * Hand the terminal to a child process ($EDITOR) and return the closure that
+     * takes it back with a full repaint. Callers must invoke the closure in a
+     * `finally` block. Same contract as the attach viewer's `SurfaceHost`.
+     */
+    suspendForChild(): () => void;
+}
+export interface TuiPageControl<Result> {
+    /** Close the page with a result. */
+    submit(result: Result): void;
+    /** Close the page with no result. */
+    cancel(): void;
+}
+/** Mount one page as the TUI's only child and resolve when it closes.
+ *
+ *  `interceptCancel` is a process-level escape hatch for surfaces that must be
+ *  abandonable while a nested component holds the keyboard; it runs before the
+ *  page sees the input and closes the page when it returns true. */
+export declare function runTuiPage<Result>(createSurface: (context: TuiPageContext, control: TuiPageControl<Result>) => TuiPageSurface, interceptCancel?: (data: string, bindings: BindingResolution<BindingId>) => boolean): Promise<Result | undefined>;

package/dist/core/tui/page-host.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var n=(i,s)=>g(i,"name",{value:s,configurable:!0});import{ProcessTerminal as w,TuiMainScreen as h}from"@earendil-works/pi-tui";import{applyTheme as y}from"../../clients/attach/config.js";import{readRawScopeConfig as T}from"../config.js";import{resolveKeybindings as I}from"../keybindings/index.js";async function R(i,s){y({cwd:process.cwd()});const d=T("user"),u=I(d?.keybindings),a=new w,e=new h(a,!0);return new Promise((p,m)=>{let t,f=!1;const c=n(()=>{if(!f){f=!0,t?.dispose();try{e.stop()}catch{}}},"restore"),o=n(r=>{c(),p(r)},"finish"),l=n(()=>(e.stop(),()=>{e.start(),e.invalidate(),e.requestRender(!0)}),"suspendForChild");try{t=i({tui:e,terminal:a,bindings:u,rawUserConfig:d,suspendForChild:l},{submit:o,cancel:n(()=>o(void 0),"cancel")}),e.addChild(t),e.setFocus(t),process.once("exit",c);for(const r of["SIGTERM","SIGHUP","SIGINT"])process.once(r,()=>o(void 0));s!==void 0&&e.addInputListener(r=>{if(s(r,u))return o(void 0),{consume:!0}}),e.start()}catch(r){c(),m(r)}})}n(R,"runTuiPage");export{R as runTuiPage};

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

@@ -0,0 +1,45 @@
+export interface SetupPanel {
+    handleInput(data: string, matches?: (id: string, input: string) => boolean): boolean;
+    render(width: number, height: number): string[];
+    /** Short live state shown on this panel's settings-rail row. */
+    badge?(): string;
+}
+type ThemeFgRole = "border" | "accent" | "dim" | "success" | "warning" | "muted" | "mdLink" | "mdLinkUrl";
+export declare const theme: {
+    fg(role: ThemeFgRole, text: string): string;
+    /** 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: "selectedBg", text: string): string;
+    bold(text: string): string;
+};
+export declare function wrapText(text: string, width: number): string[];
+export declare function renderRows(lines: string[], width: number): string[];
+export declare function padAnsi(text: string, width: number): string;
+export declare function rule(width: number): string;
+export declare function visibleRange(count: number, selected: number, capacity: number): {
+    start: number;
+    end: number;
+};
+/** 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 declare function framed(lines: string[], width: number): string[];
+export declare function fitTail(lines: string[], budget: number): string[];
+/** Rows the page frame spends on its own title, rules and footer. */
+export declare 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 declare function pageFrame(opts: {
+    width: number;
+    height: number;
+    title: string;
+    meta?: string;
+    body: string[];
+    footer: string;
+}): string[];
+/** Two columns joined by a vertical divider, each already wrapped to its own
+ *  width. Short columns pad; the taller one sets the height. */
+export declare function columns(left: string[], leftWidth: number, right: string[], rightWidth: number): string[];
+export {};

package/dist/core/tui/panel.js

@@ -0,0 +1 @@
+var T=Object.defineProperty;var i=(r,e)=>T(r,"name",{value:e,configurable:!0});import{getMarkdownTheme as p,getSelectListTheme as k,getSettingsListTheme as C}from"@earendil-works/pi-coding-agent";import{truncateToWidth as s,visibleWidth as g}from"@earendil-works/pi-tui";import{detectColorCaps as R}from"./draw.js";const L=i(r=>`\x1B[32m${r}\x1B[39m`,"ansiGreen"),W=i(r=>`\x1B[33m${r}\x1B[39m`,"ansiYellow"),m={fg(r,e){if(!R().color)return e;switch(r){case"border":return p().hr(e);case"accent":return p().heading(e);case"dim":return C().description(e);case"muted":return k().description(e);case"mdLink":return p().link(e);case"mdLinkUrl":return p().linkUrl(e);case"success":return L(e);case"warning":return W(e)}},bg(r,e){return`\x1B[7m${e}\x1B[27m`},bold(r){return p().bold(r)}};function G(r,e){const t=r.trim();if(t==="")return[""];if(e<=1)return[s(t,e)];const o=[];let n="";for(const a of t.split(/\s+/)){if(n===""){n=a;continue}const c=`${n} ${a}`;s(c,e)===c?n=c:(o.push(s(n,e)),n=a)}return n!==""&&o.push(s(n,e)),o.length>0?o:[""]}i(G,"wrapText");function O(r,e){return r.map(t=>s(t,e))}i(O,"renderRows");function b(r,e){const t=g(r);return t>=e?s(r,e):`${r}${" ".repeat(e-t)}`}i(b,"padAnsi");function $(r){return m.fg("border","\u2500".repeat(Math.max(0,r)))}i($,"rule");function U(r,e,t){if(r<=0)return{start:0,end:0};const o=Math.max(1,Math.min(t,r)),n=Math.max(0,Math.min(e-Math.floor(o/2),r-o));return{start:n,end:Math.min(r,n+o)}}i(U,"visibleRange");function w(r,e){if(e<4)return r.map(c=>s(c,e));const t=e-4,o=m.fg("border","\u2502"),n=m.fg("border",`\u250C${"\u2500".repeat(e-2)}\u2510`),a=m.fg("border",`\u2514${"\u2500".repeat(e-2)}\u2518`);return[n,...r.map(c=>`${o} ${b(s(c,t),t)} ${o}`),a]}i(w,"framed");function y(r,e){return e>=r.length?r:r.slice(r.length-e)}i(y,"fitTail");const v=4;function F(r){const{width:e,height:t,title:o,meta:n,body:a,footer:c}=r,u=m.fg("accent",m.bold(o)),l=n?m.fg("dim",n):"",f=e-g(u)-g(l),x=l!==""&&f>=2?`${u}${" ".repeat(f)}${l}`:s(u,e),h=Math.max(1,t-v),d=a.slice(0,h);for(;d.length<h;)d.push("");return[s(x,e),$(e),...d.map(M=>s(M,e)),$(e),s(c,e)]}i(F,"pageFrame");function H(r,e,t,o){const n=m.fg("border","\u2502"),a=Math.max(r.length,t.length),c=[];for(let u=0;u<a;u+=1){const l=b(r[u]??"",e),f=s(t[u]??"",o);c.push(`${l} ${n} ${f}`)}return c}i(H,"columns");export{v as PAGE_CHROME_ROWS,H as columns,y as fitTail,w as framed,b as padAnsi,F as pageFrame,O as renderRows,$ as rule,m as theme,U as visibleRange,G as wrapText};

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,2 @@
+var n=Object.defineProperty;var e=(s,t)=>n(s,"name",{value:t,configurable:!0});function u(){return{upArrow:!1,downArrow:!1,leftArrow:!1,rightArrow:!1,return:!1,escape:!1,ctrl:!1,meta:!1,tab:!1,shiftTab:!1,backspace:!1}}e(u,"emptyKey");function p(s){const t=s.toString("utf8"),r=u();return t==="\x1B[A"?(r.upArrow=!0,{input:"",key:r}):t==="\x1B[B"?(r.downArrow=!0,{input:"",key:r}):t==="\x1B[C"?(r.rightArrow=!0,{input:"",key:r}):t==="\x1B[D"?(r.leftArrow=!0,{input:"",key:r}):t==="\x1B[Z"?(r.shiftTab=!0,{input:"",key:r}):t==="\r"||t===`
+`?(r.return=!0,{input:"",key:r}):t==="\x1B\x7F"||t==="\x1B\b"?(r.meta=!0,r.backspace=!0,{input:"",key:r}):t==="\x1B"?(r.escape=!0,{input:"",key:r}):t==="	"?(r.tab=!0,{input:"",key:r}):t==="\x7F"||t==="\b"?(r.backspace=!0,{input:"",key:r}):t.length===1&&t.charCodeAt(0)<32?(r.ctrl=!0,{input:String.fromCharCode(t.charCodeAt(0)+64).toLowerCase(),key:r}):{input:t,key:r}}e(p,"parseKeypress");function a(){if(!process.stdin.isTTY)throw new Error("this TUI requires an interactive terminal (TTY)");process.stdin.setRawMode(!0),process.stdin.resume(),process.stdin.setEncoding("utf8"),process.stdout.write("\x1B[?25l"),process.stdout.write("\x1B[?1049h"),process.stdout.write("\x1B[2J\x1B[H")}e(a,"setupTerminal");function c(){process.stdout.write("\x1B[?25h"),process.stdout.write("\x1B[?1049l"),process.stdin.setRawMode(!1),process.stdin.pause()}e(c,"restoreTerminal");function f(){return{cols:process.stdout.columns||80,rows:process.stdout.rows||24}}e(f,"getTerminalSize");export{f as getTerminalSize,p as parseKeypress,c as restoreTerminal,a as setupTerminal};

package/dist/core/user-settings.d.ts

@@ -0,0 +1,377 @@
+import type { ScopeConfig } from '../types.js';
+/**
+ * Which settings destination owns a preference row. Every settings-surface row
+ * must name one, so a new preference cannot be added without deciding where a
+ * human finds it.
+ */
+export type UserSettingGroup = 'display' | 'panes' | 'providers' | 'updates';
+export interface UserSettingDefinition<Key extends string = string> {
+    key: Key;
+    label: string;
+    description: string;
+    valueConstraint: string;
+    applies: string;
+    group: UserSettingGroup;
+    order: number;
+    format: (config: ScopeConfig) => string;
+    cycle: (config: ScopeConfig, delta: number) => void;
+    /** Mutate `config` from a CLI string, returning a user-facing validation error on failure. */
+    setFromString: (config: ScopeConfig, raw: string) => string | null;
+}
+/**
+ * Exhaustive settings-surface coverage for ScopeConfig. Primitive preferences
+ * are required by the type to define a Settings row; structured registries must
+ * name the specialized surface that owns them. Adding a config field therefore
+ * fails typecheck until its user-facing settings coverage is decided. The
+ * auto_update nested record is exhaustive for the same reason.
+ */
+export declare const CONFIG_SETTINGS_COVERAGE: {
+    schema_version: {
+        surface: "specialized";
+        owner: string;
+    };
+    marketplaces: {
+        surface: "specialized";
+        owner: string;
+    };
+    plugins: {
+        surface: "specialized";
+        owner: string;
+    };
+    auto_update: {
+        surface: "settings";
+        settings: {
+            crtr: {
+                key: "auto_update.crtr";
+                label: string;
+                description: string;
+                valueConstraint: string;
+                applies: string;
+                group: "updates";
+                order: number;
+                format: (config: ScopeConfig) => "off" | "notify" | "apply";
+                cycle: (config: ScopeConfig, delta: number) => void;
+                setFromString: (config: ScopeConfig, raw: string) => "auto_update.crtr must be notify, apply, or false" | null;
+            };
+            content: {
+                key: "auto_update.content";
+                label: string;
+                description: string;
+                valueConstraint: string;
+                applies: string;
+                group: "updates";
+                order: number;
+                format: (config: ScopeConfig) => "off" | "notify" | "apply";
+                cycle: (config: ScopeConfig, delta: number) => void;
+                setFromString: (config: ScopeConfig, raw: string) => "auto_update.content must be notify, apply, or false" | null;
+            };
+            interval_hours: {
+                key: "auto_update.interval_hours";
+                label: string;
+                description: string;
+                valueConstraint: string;
+                applies: string;
+                group: "updates";
+                order: number;
+                format: (config: ScopeConfig) => string;
+                cycle: (config: ScopeConfig, delta: number) => void;
+                setFromString: (config: ScopeConfig, raw: string) => string | null;
+            };
+        };
+    };
+    max_panes_per_window: {
+        surface: "settings";
+        setting: {
+            key: "max_panes_per_window";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "panes";
+            order: number;
+            format: (config: ScopeConfig) => string;
+            cycle: (config: ScopeConfig, delta: number) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    auto_open_child_viewers: {
+        surface: "settings";
+        setting: {
+            key: "auto_open_child_viewers";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "panes";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    brokerThresholds: {
+        surface: "specialized";
+        owner: string;
+    };
+    lifecycle: {
+        surface: "specialized";
+        owner: string;
+    };
+    completion_bell: {
+        surface: "settings";
+        setting: {
+            key: "completion_bell";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    working_gerunds: {
+        surface: "specialized";
+        owner: string;
+    };
+    whip_mode: {
+        surface: "settings";
+        setting: {
+            key: "whip_mode";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    page_surface: {
+        surface: "settings";
+        setting: {
+            key: "page_surface";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    whip_messages: {
+        surface: "specialized";
+        owner: string;
+    };
+    whip_message_mode: {
+        surface: "settings";
+        setting: {
+            key: "whip_message_mode";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "random" | "go faster";
+            cycle: (config: ScopeConfig, delta: number) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    mouse_mode_default: {
+        surface: "settings";
+        setting: {
+            key: "mouse_mode_default";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off" | "follow tmux";
+            cycle: (config: ScopeConfig, delta: number) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    live_cycles: {
+        surface: "settings";
+        setting: {
+            key: "live_cycles";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => string;
+            cycle: (config: ScopeConfig, delta: number) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    condensed_history: {
+        surface: "settings";
+        setting: {
+            key: "condensed_history";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "user" | "none" | "agent" | "both";
+            cycle: (config: ScopeConfig, delta: number) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    bash_tool_purpose: {
+        surface: "settings";
+        setting: {
+            key: "bash_tool_purpose";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    fold_finished_tools: {
+        surface: "settings";
+        setting: {
+            key: "fold_finished_tools";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    summarize_tool_calls: {
+        surface: "settings";
+        setting: {
+            key: "summarize_tool_calls";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    detailed_tool_recaps: {
+        surface: "settings";
+        setting: {
+            key: "detailed_tool_recaps";
+            label: string;
+            description: string;
+            valueConstraint: string;
+            applies: string;
+            group: "display";
+            order: number;
+            format: (config: ScopeConfig) => "on" | "off";
+            cycle: (config: ScopeConfig) => void;
+            setFromString: (config: ScopeConfig, raw: string) => string | null;
+        };
+    };
+    keybindings: {
+        surface: "specialized";
+        owner: string;
+    };
+    tmux_passthrough: {
+        surface: "specialized";
+        owner: string;
+    };
+    providerOptions: {
+        surface: "settings";
+        settings: {
+            'openai-codex.fastMode': {
+                key: "providerOptions.openai-codex.fastMode";
+                label: string;
+                description: string;
+                valueConstraint: string;
+                applies: string;
+                group: "providers";
+                order: number;
+                format: (config: ScopeConfig) => "on" | "off";
+                cycle: (config: ScopeConfig) => void;
+                setFromString: (config: ScopeConfig, raw: string) => string | null;
+            };
+        };
+    };
+    modelLadders: {
+        surface: "specialized";
+        owner: string;
+    };
+    modelRoutes: {
+        surface: "specialized";
+        owner: string;
+    };
+    modelRouting: {
+        surface: "specialized";
+        owner: string;
+    };
+    kinds: {
+        surface: "specialized";
+        owner: string;
+    };
+    page_components: {
+        surface: "specialized";
+        owner: string;
+    };
+    remoteCanvas: {
+        surface: "specialized";
+        owner: string;
+    };
+    api: {
+        surface: "specialized";
+        owner: string;
+    };
+    paths: {
+        surface: "specialized";
+        owner: string;
+    };
+    store: {
+        surface: "specialized";
+        owner: string;
+    };
+    runtime: {
+        surface: "specialized";
+        owner: string;
+    };
+    spawnEnv: {
+        surface: "specialized";
+        owner: string;
+    };
+    bin: {
+        surface: "specialized";
+        owner: string;
+    };
+    humanActions: {
+        surface: "specialized";
+        owner: string;
+    };
+};
+/** The exhaustive top-level key list used by config persistence and help. */
+export declare const SCOPE_CONFIG_KEYS: (keyof ScopeConfig)[];
+/** The single row registry shared by `sys settings` and `sys config set`. */
+export declare const USER_SETTINGS: readonly UserSettingDefinition[];
+export declare function findUserSetting(key: string): UserSettingDefinition | undefined;
+/** The rows one settings destination owns, in registry order. */
+export declare function userSettingsInGroup(group: UserSettingGroup): readonly UserSettingDefinition[];

package/dist/core/user-settings.js

@@ -0,0 +1 @@
+var v=Object.defineProperty;var s=(e,t)=>v(e,"name",{value:t,configurable:!0});import{CONDENSED_HISTORY_MODES as u,MOUSE_MODE_DEFAULTS as p,WHIP_MESSAGE_MODES as d}from"../types.js";function i(e,t,o){const r=e.indexOf(t),a=r>=0?r:0;return e[(a+o+e.length)%e.length]}s(i,"cycleChoice");function c(e,t,o){const r=e.indexOf(t);return r>=0?e[(r+o+e.length)%e.length]:o>=0?e.find(a=>a>t)??e[0]:[...e].reverse().find(a=>a<t)??e[e.length-1]}s(c,"cycleNumber");function n(e,t){return e==="true"?!0:e==="false"?!1:`${t} must be true or false`}s(n,"booleanFromString");function f(e,t){if(!/^\d+$/.test(e))return`${t} must be an integer >= 0`;const o=Number(e);return Number.isSafeInteger(o)?o:`${t} must be an integer >= 0`}s(f,"nonNegativeIntegerFromString");function _(e,t){const o=f(e,t);return typeof o=="string"||o<1?`${t} must be an integer >= 1`:o}s(_,"positiveIntegerFromString");const m=[!1,"notify","apply"],w=[0,1,6,12,24,48,72,168],b=[1,2,3,4,5,6,8,10,12],l="openai-codex";function g(e,t){const o=e.providerOptions[t];if(o!==void 0)return o;const r={};return e.providerOptions[t]=r,r}s(g,"providerOptionsFor");const x=[1,2,3,4,5,6],h={schema_version:{surface:"specialized",owner:"internal schema migration"},marketplaces:{surface:"specialized",owner:"Plugins and pkg market commands"},plugins:{surface:"specialized",owner:"Plugins tab and pkg plugin commands"},auto_update:{surface:"settings",settings:{crtr:{key:"auto_update.crtr",label:"crouter updates",description:"Notify about crouter releases, install them automatically, or turn checks off.",valueConstraint:"true|false|notify|apply; true stores notify",applies:"Applies on the next crouter command.",group:"updates",order:70,format:s(e=>e.auto_update.crtr===!1?"off":e.auto_update.crtr,"format"),cycle:s((e,t)=>{e.auto_update.crtr=i(m,e.auto_update.crtr,t)},"cycle"),setFromString:s((e,t)=>{const o=t==="true"?"notify":t;return o!=="notify"&&o!=="apply"&&o!=="false"?"auto_update.crtr must be notify, apply, or false":(e.auto_update.crtr=o==="false"?!1:o,null)},"setFromString")},content:{key:"auto_update.content",label:"Content updates",description:"Notify about plugin and marketplace updates, apply them automatically, or turn checks off.",valueConstraint:"false|notify|apply",applies:"Applies on the next crouter command.",group:"updates",order:80,format:s(e=>e.auto_update.content===!1?"off":e.auto_update.content,"format"),cycle:s((e,t)=>{e.auto_update.content=i(m,e.auto_update.content,t)},"cycle"),setFromString:s((e,t)=>t!=="notify"&&t!=="apply"&&t!=="false"?"auto_update.content must be notify, apply, or false":(e.auto_update.content=t==="false"?!1:t,null),"setFromString")},interval_hours:{key:"auto_update.interval_hours",label:"Update interval",description:"Minimum hours between automatic update checks. Zero checks on every command.",valueConstraint:"integer >= 0",applies:"Applies on the next crouter command.",group:"updates",order:90,format:s(e=>`${e.auto_update.interval_hours}h`,"format"),cycle:s((e,t)=>{e.auto_update.interval_hours=c(w,e.auto_update.interval_hours,t)},"cycle"),setFromString:s((e,t)=>{const o=f(t,"auto_update.interval_hours");return typeof o=="string"?o:(e.auto_update.interval_hours=o,null)},"setFromString")}}},max_panes_per_window:{surface:"settings",setting:{key:"max_panes_per_window",label:"Maximum panes",description:"Maximum human-review panes placed in one tmux window before using another window.",valueConstraint:"integer >= 1",applies:"Applies to the next pane placement.",group:"panes",order:20,format:s(e=>String(e.max_panes_per_window),"format"),cycle:s((e,t)=>{e.max_panes_per_window=c(b,e.max_panes_per_window,t)},"cycle"),setFromString:s((e,t)=>{const o=_(t,"max_panes_per_window");return typeof o=="string"?o:(e.max_panes_per_window=o,null)},"setFromString")}},auto_open_child_viewers:{surface:"settings",setting:{key:"auto_open_child_viewers",label:"Open child panes",description:"Open each managed child beside its watched parent. Off keeps new children running in the background.",valueConstraint:"true|false",applies:"Applies to the next managed child created; independent roots still open their attended viewer.",group:"panes",order:10,format:s(e=>e.auto_open_child_viewers?"on":"off","format"),cycle:s(e=>{e.auto_open_child_viewers=!e.auto_open_child_viewers},"cycle"),setFromString:s((e,t)=>{const o=n(t,"auto_open_child_viewers");return typeof o=="string"?o:(e.auto_open_child_viewers=o,null)},"setFromString")}},brokerThresholds:{surface:"specialized",owner:"Broker limits tab"},lifecycle:{surface:"specialized",owner:"sys config set lifecycle.unattendedParkMs"},completion_bell:{surface:"settings",setting:{key:"completion_bell",label:"Completion bell",description:"Ring a short sound when the node in an attached viewer finishes a turn.",valueConstraint:"true|false",applies:"Applies on the next turn end.",group:"display",order:41,format:s(e=>e.completion_bell?"on":"off","format"),cycle:s(e=>{e.completion_bell=!e.completion_bell},"cycle"),setFromString:s((e,t)=>{const o=n(t,"completion_bell");return typeof o=="string"?o:(e.completion_bell=o,null)},"setFromString")}},working_gerunds:{surface:"specialized",owner:"sys config set working_gerunds"},whip_mode:{surface:"settings",setting:{key:"whip_mode",label:"Whip mode",description:"Play the whip animation when you send a prompt and when a viewer opens for an agent with an initial prompt.",valueConstraint:"true|false",applies:"Applies on the next attach.",group:"display",order:39,format:s(e=>e.whip_mode?"on":"off","format"),cycle:s(e=>{e.whip_mode=!e.whip_mode},"cycle"),setFromString:s((e,t)=>{const o=n(t,"whip_mode");return typeof o=="string"?o:(e.whip_mode=o,null)},"setFromString")}},page_surface:{surface:"settings",setting:{key:"page_surface",label:"Page human surface",description:"This host reads pages in a browser rather than a terminal. Agents are told the page module runs as written, HTML pages are offered, and document review and live display leave the command tree.",valueConstraint:"true|false",applies:"Applies when human command help is assembled.",group:"display",order:37,format:s(e=>e.page_surface?"on":"off","format"),cycle:s(e=>{e.page_surface=!e.page_surface},"cycle"),setFromString:s((e,t)=>{const o=n(t,"page_surface");return typeof o=="string"?o:(e.page_surface=o,null)},"setFromString")}},whip_messages:{surface:"specialized",owner:"sys config set whip_messages"},whip_message_mode:{surface:"settings",setting:{key:"whip_message_mode",label:"Whip message",description:"What the whip action sends: a random line from whip_messages, or the fixed \u201CGo faster\u201D.",valueConstraint:d.join("|"),applies:"Applies on the next attach.",group:"display",order:40,format:s(e=>e.whip_message_mode==="go-faster"?"go faster":"random","format"),cycle:s((e,t)=>{e.whip_message_mode=i(d,e.whip_message_mode,t)},"cycle"),setFromString:s((e,t)=>d.includes(t)?(e.whip_message_mode=t,null):`whip_message_mode must be one of: ${d.join("|")}`,"setFromString")}},mouse_mode_default:{surface:"settings",setting:{key:"mouse_mode_default",label:"Default mouse mode",description:"Initial mouse wheel scrolling for each attached viewer.",valueConstraint:p.join("|"),applies:"Applies on the next attach.",group:"display",order:38,format:s(e=>e.mouse_mode_default==="tmux"?"follow tmux":e.mouse_mode_default,"format"),cycle:s((e,t)=>{e.mouse_mode_default=i(p,e.mouse_mode_default,t)},"cycle"),setFromString:s((e,t)=>p.includes(t)?(e.mouse_mode_default=t,null):`mouse_mode_default must be one of: ${p.join("|")}`,"setFromString")}},live_cycles:{surface:"settings",setting:{key:"live_cycles",label:"Live cycles",description:"Trailing refresh cycles rendered at full fidelity; older cycles condense to text.",valueConstraint:"integer >= 1",applies:"Applies on the next attach.",group:"display",order:50,format:s(e=>String(e.live_cycles),"format"),cycle:s((e,t)=>{e.live_cycles=c(x,e.live_cycles,t)},"cycle"),setFromString:s((e,t)=>{const o=_(t,"live_cycles");return typeof o=="string"?o:(e.live_cycles=o,null)},"setFromString")}},condensed_history:{surface:"settings",setting:{key:"condensed_history",label:"Condensed history",description:"Messages retained from condensed cycles. Tool calls are never kept.",valueConstraint:u.join("|"),applies:"Applies on the next attach.",group:"display",order:60,format:s(e=>e.condensed_history,"format"),cycle:s((e,t)=>{e.condensed_history=i(u,e.condensed_history,t)},"cycle"),setFromString:s((e,t)=>u.includes(t)?(e.condensed_history=t,null):`condensed_history must be one of: ${u.join("|")}`,"setFromString")}},bash_tool_purpose:{surface:"settings",setting:{key:"bash_tool_purpose",label:"Bash purpose field",description:"Expose the optional purpose label to agents in the bash tool schema. Off removes the field without disabling the bash valve.",valueConstraint:"true|false",applies:"Applies on the next node session.",group:"display",order:25,format:s(e=>e.bash_tool_purpose?"on":"off","format"),cycle:s(e=>{e.bash_tool_purpose=!e.bash_tool_purpose},"cycle"),setFromString:s((e,t)=>{const o=n(t,"bash_tool_purpose");return typeof o=="string"?o:(e.bash_tool_purpose=o,null)},"setFromString")}},fold_finished_tools:{surface:"settings",setting:{key:"fold_finished_tools",label:"Fold finished tools",description:"Fold every settled tool call to its call line. Toggle live with /fold-tools.",valueConstraint:"true|false",applies:"Applies on the next attach.",group:"display",order:30,format:s(e=>e.fold_finished_tools?"on":"off","format"),cycle:s(e=>{e.fold_finished_tools=!e.fold_finished_tools},"cycle"),setFromString:s((e,t)=>{const o=n(t,"fold_finished_tools");return typeof o=="string"?o:(e.fold_finished_tools=o,null)},"setFromString")}},summarize_tool_calls:{surface:"settings",setting:{key:"summarize_tool_calls",label:"Summarize tool calls",description:"Replace completed folded tool-call groups with a one-line broker summary when available.",valueConstraint:"true|false",applies:"Applies when the next visible message closes a tool-call group.",group:"display",order:35,format:s(e=>e.summarize_tool_calls?"on":"off","format"),cycle:s(e=>{e.summarize_tool_calls=!e.summarize_tool_calls},"cycle"),setFromString:s((e,t)=>{const o=n(t,"summarize_tool_calls");return typeof o=="string"?o:(e.summarize_tool_calls=o,null)},"setFromString")}},detailed_tool_recaps:{surface:"settings",setting:{key:"detailed_tool_recaps",label:"Detailed tool recaps",description:"Show each document read and edited file in folded tool recaps. Off shows a compact count line instead.",valueConstraint:"true|false",applies:"Applies on the next attach.",group:"display",order:36,format:s(e=>e.detailed_tool_recaps?"on":"off","format"),cycle:s(e=>{e.detailed_tool_recaps=!e.detailed_tool_recaps},"cycle"),setFromString:s((e,t)=>{const o=n(t,"detailed_tool_recaps");return typeof o=="string"?o:(e.detailed_tool_recaps=o,null)},"setFromString")}},keybindings:{surface:"specialized",owner:"Keybindings tab"},tmux_passthrough:{surface:"specialized",owner:"Keybindings tab"},providerOptions:{surface:"settings",settings:{"openai-codex.fastMode":{key:`providerOptions.${l}.fastMode`,label:"Codex fast mode",description:"Serve Codex turns at the ChatGPT priority tier: about 1.5x faster generation for about 2x the credits. Displayed cost does not reflect the premium.",valueConstraint:"true|false",applies:"Applies on each node's next turn.",group:"providers",order:40,format:s(e=>e.providerOptions[l]?.fastMode?"on":"off","format"),cycle:s(e=>{const t=g(e,l);t.fastMode=!t.fastMode},"cycle"),setFromString:s((e,t)=>{const o=n(t,`providerOptions.${l}.fastMode`);return typeof o=="string"?o:(g(e,l).fastMode=o,null)},"setFromString")}}},modelLadders:{surface:"specialized",owner:"Models tab"},modelRoutes:{surface:"specialized",owner:"Models route declarations"},modelRouting:{surface:"specialized",owner:"Models route declarations"},kinds:{surface:"specialized",owner:"Models tab and kind registry"},page_components:{surface:"specialized",owner:"Page component catalog: product-registered page component kinds"},remoteCanvas:{surface:"specialized",owner:"canvas config commands"},api:{surface:"specialized",owner:"sys connect"},paths:{surface:"specialized",owner:"runtime layout"},store:{surface:"specialized",owner:"daemon conversation store"},runtime:{surface:"specialized",owner:"app-facing listener"},spawnEnv:{surface:"specialized",owner:"spawn environment allow-list"},bin:{surface:"specialized",owner:"bare-binary contributions on every node PATH"},humanActions:{surface:"specialized",owner:"scope-configured human completion actions"}},O=Object.keys(h);function S(){const e=[];for(const t of Object.values(h))t.surface==="settings"&&("setting"in t?e.push(t.setting):e.push(...Object.values(t.settings)));return e.sort((t,o)=>t.order-o.order)}s(S,"collectUserSettings");const y=S();function z(e){return y.find(t=>t.key===e)}s(z,"findUserSetting");function A(e){return y.filter(t=>t.group===e)}s(A,"userSettingsInGroup");export{h as CONFIG_SETTINGS_COVERAGE,O as SCOPE_CONFIG_KEYS,y as USER_SETTINGS,z as findUserSetting,A as userSettingsInGroup};

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;