@north-light/crouter 0.3.192 → 0.3.193

package/dist/core/bash-jobs.d.ts

@@ -14,10 +14,42 @@ export interface BashJobPaths {
     jobPgid: string;
 }
 export declare function bashJobsDir(contextDir: string): string;
+/** Whether a job id can safely be used as one path segment. Generated ids are
+ * numeric epoch prefixes plus a hex suffix; this broader safe alphabet keeps
+ * older file-backed ids readable without allowing path or request delimiters. */
+export declare function isSafeBashJobId(jobId: string): boolean;
 export declare function bashJobPaths(contextDir: string, jobId: string): BashJobPaths;
 /** The job's supervisor process group, or undefined for a job started before
  * pgid was persisted (or a partially-written dir). */
 export declare function readJobPgid(contextDir: string, jobId: string): number | undefined;
+/** Whether a persisted job supervisor process group is still present. EPERM
+ *  means the group exists but cannot be signaled by this process; it is still
+ *  live for the status surface. */
+export declare function isBashJobProcessGroupAlive(pgid: number): boolean;
+export type StopBackgroundBashJobResult = {
+    kind: 'stopped';
+    signaled: boolean;
+    pgid: number;
+    logPath: string;
+} | {
+    kind: 'missing';
+} | {
+    kind: 'retired';
+    logPath: string;
+} | {
+    kind: 'not-stoppable';
+    logPath: string;
+};
+/** Stop one live background job using the same process-group and sentinel
+ *  semantics as `crtr node bash kill`. The caller owns the user-facing
+ *  notification; this primitive owns only the job control-plane mutation.
+ *
+ *  Only a job in the live-background state the roster projects (job.bg
+ *  present, job.exit absent) may be signaled. Job directories persist after
+ *  the supervisor exits, so a retired, still-foreground, or already-stopped
+ *  job would otherwise have its recorded pgid signaled long after the OS
+ *  could have reused that id for an unrelated process group. */
+export declare function stopBackgroundBashJob(contextDir: string, jobId: string): Promise<StopBackgroundBashJobResult>;
 /** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB
  * rather than the whole file, which for a long-running job can be enormous. */
 export declare function tailJobLog(logPath: string, count: number): string[];

package/dist/core/bash-jobs.js

@@ -3,11 +3,20 @@
 // job.bg, while foreground completion renames it to job.done. The detached
 // supervisor can therefore outlive pi and still decide whether to report exit.
 import { randomBytes } from 'node:crypto';
-import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 export function bashJobsDir(contextDir) {
     return join(contextDir, 'jobs');
 }
+/** Whether a job id can safely be used as one path segment. Generated ids are
+ * numeric epoch prefixes plus a hex suffix; this broader safe alphabet keeps
+ * older file-backed ids readable without allowing path or request delimiters. */
+export function isSafeBashJobId(jobId) {
+    return typeof jobId === 'string'
+        && jobId !== '' && jobId !== '.' && jobId !== '..'
+        && /^[A-Za-z0-9._~-]+$/u.test(jobId)
+        && Buffer.byteLength(jobId, 'utf8') <= 128;
+}
 export function bashJobPaths(contextDir, jobId) {
     const dir = join(bashJobsDir(contextDir), jobId);
     return {
@@ -33,6 +42,68 @@ export function readJobPgid(contextDir, jobId) {
         return undefined;
     }
 }
+/** Whether a persisted job supervisor process group is still present. EPERM
+ *  means the group exists but cannot be signaled by this process; it is still
+ *  live for the status surface. */
+export function isBashJobProcessGroupAlive(pgid) {
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Stop one live background job using the same process-group and sentinel
+ *  semantics as `crtr node bash kill`. The caller owns the user-facing
+ *  notification; this primitive owns only the job control-plane mutation.
+ *
+ *  Only a job in the live-background state the roster projects (job.bg
+ *  present, job.exit absent) may be signaled. Job directories persist after
+ *  the supervisor exits, so a retired, still-foreground, or already-stopped
+ *  job would otherwise have its recorded pgid signaled long after the OS
+ *  could have reused that id for an unrelated process group. */
+export async function stopBackgroundBashJob(contextDir, jobId) {
+    const paths = bashJobPaths(contextDir, jobId);
+    if (!existsSync(paths.dir))
+        return { kind: 'missing' };
+    if (!existsSync(paths.jobBg) || existsSync(paths.jobExit))
+        return { kind: 'retired', logPath: paths.jobLog };
+    const pgid = readJobPgid(contextDir, jobId);
+    if (pgid === undefined)
+        return { kind: 'not-stoppable', logPath: paths.jobLog };
+    // Claim the stop by creating job.exit exclusively, before signaling. The
+    // loser of two concurrent stops — and a stop that races the supervisor's own
+    // completion — reports retired instead of signaling a departed group and
+    // sending the owning node a second "was stopped" notice.
+    try {
+        const fd = openSync(paths.jobExit, 'wx');
+        try {
+            writeFileSync(fd, '143\n');
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return { kind: 'retired', logPath: paths.jobLog };
+        throw err;
+    }
+    let signaled = true;
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        signaled = false;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    try {
+        process.kill(-pgid, 'SIGKILL');
+    }
+    catch { /* already gone */ }
+    return { kind: 'stopped', signaled, pgid, logPath: paths.jobLog };
+}
 /** Last `count` lines of a job log, cheaply: read at most the trailing 64 KiB
  * rather than the whole file, which for a long-running job can be enormous. */
 export function tailJobLog(logPath, count) {

package/dist/core/canvas/__tests__/attention.test.js

@@ -4,7 +4,7 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { atomicWriteJson, deckPath } from '../../human/convention.js';
+import { atomicWriteJson, pageManifestPath } from '../../human/convention.js';
 import { createNode } from '../canvas.js';
 import { closeDb } from '../db.js';
 import { nodeDir } from '../paths.js';
@@ -22,12 +22,18 @@ function meta(id, cwd, extra) {
         ...extra,
     };
 }
-function seedDeck(bridgeId) {
+function seedPage(bridgeId) {
     const dir = nodeDir(bridgeId);
     mkdirSync(dir, { recursive: true });
-    atomicWriteJson(deckPath(dir), {
+    atomicWriteJson(pageManifestPath(dir), {
+        schema: 'crtr.page/v1',
+        dialect: 'md',
         title: bridgeId,
-        interactions: [{ id: 'q', title: bridgeId, subtitle: 'Acknowledge this ticket so the request can proceed.', options: [] }],
+        subtitle: 'Acknowledge this ticket so the request can proceed.',
+        placement: 'inline',
+        document: 'page.md',
+        steps: 1,
+        slots: [],
     });
 }
 function bridge(id, parent, cwd) {
@@ -61,10 +67,10 @@ test('ticketCountsForNodes follows bridge parents even when asking nodes share a
     bridge('ha2', 'a', sharedCwd);
     bridge('hb', 'b', sharedCwd);
     bridge('hc', 'c', soloCwd);
-    seedDeck('ha1');
-    seedDeck('ha2');
-    seedDeck('hb');
-    seedDeck('hc');
+    seedPage('ha1');
+    seedPage('ha2');
+    seedPage('hb');
+    seedPage('hc');
     assert.deepEqual(ticketCountsForNodes(['a', 'b', 'c']), { a: 2, b: 1, c: 1 });
 });
 test('pendingTicketsForView returns the asking node rather than a cwd bucket', () => {
@@ -72,8 +78,8 @@ test('pendingTicketsForView returns the asking node rather than a cwd bucket', (
     createNode(meta('b', sharedCwd));
     bridge('ha', 'a', sharedCwd);
     bridge('hb', 'b', sharedCwd);
-    seedDeck('ha');
-    seedDeck('hb');
+    seedPage('ha');
+    seedPage('hb');
     assert.deepEqual(pendingTicketsForView('a').map(({ node_id, count }) => ({ node_id, count })), [
         { node_id: 'a', count: 1 },
     ]);

package/dist/core/canvas/__tests__/render-remote.test.js

@@ -19,7 +19,7 @@ import { createServer } from 'node:http';
 import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { atomicWriteJson, deckPath } from '#core/human/convention';
+import { atomicWriteJson, pageManifestPath } from '#core/human/convention';
 import { RemoteCanvasSource } from '../remote-canvas-source.js';
 import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render.js';
 import { createNode } from '../canvas.js';
@@ -113,9 +113,15 @@ function seedPoisonedLocalState() {
     createNode(meta('a', { cwd: localCwd }));
     const askDir = nodeDir('poison-ask');
     mkdirSync(askDir, { recursive: true });
-    atomicWriteJson(deckPath(askDir), {
+    atomicWriteJson(pageManifestPath(askDir), {
+        schema: 'crtr.page/v1',
+        dialect: 'md',
         title: 'poison',
-        interactions: [{ id: 'q', kind: 'ask', title: 'poison', subtitle: 'This local ticket must not affect the remote rendering.' }],
+        subtitle: 'This local ticket must not affect the remote rendering.',
+        placement: 'inline',
+        document: 'page.md',
+        steps: 1,
+        slots: [],
     });
     // A local focus + broker viewer — poison both `viewed` signals.
     openFocusRow('poison-focus', null, null, 'a');

package/dist/core/canvas/attention.js

@@ -3,7 +3,7 @@
 // Every ticket is a direct child of the single registered `<canvas>/nodes` root,
 // named for its terminal human bridge node. The bridge's parent is the asking
 // node, so storage identity and attribution come from the canvas graph rather
-// than duplicated attribution fields in deck/review data.
+// than duplicated attribution fields in page/review data.
 import { basename } from 'node:path';
 import { scanInbox } from '../human/scan.js';
 import { filterTerminalReviewTickets } from '../review/ticket-filter.js';

package/dist/core/canvas/browse/app.js

@@ -55,7 +55,7 @@ export async function runBrowse(opts) {
         process.stdout.write(await renderForestFromSource(source) + '\n');
         return;
     }
-    // Snapshot the canvas. Drop kind:'human' control-plane decks — they have no pi
+    // Snapshot the canvas. Drop kind:'human' control-plane pages — they have no pi
     // session, so `surface node focus` refuses them; they are never a navigation/resume
     // target (mirrors the surface-node focus guard).
     let rows;

package/dist/core/canvas/nav-model.d.ts

@@ -3,7 +3,7 @@ import type { NodeMeta } from './index.js';
 export { PI_MAX_WIDGET_LINES, VIEWPORT_FALLBACK_ROWS, ESC, RESET, BOLD, DIM, REVERSE, BG_ATTACHED, GREEN, RED, YELLOW, CYAN, GRAY, nodeGlyph, visibleWidth, truncate, fillWidth, fillBar, readTelemetry, fmtTokens, tokensCell, activityCell, cycleBadge, navLabel, shortId, askBadge, liveBelowBadge, isAttached, hasBrokerViewers, fetchAsksMap, graphWidgetBudget, GRAPH_HINT, type Telemetry, type FlatRow, type FoldState, type SubtreeActivity, } from './nav-render.js';
 /** First manager (by created) — the UP step for the ancestry spine. */
 export declare function managerOf(id: string): string | undefined;
-/** A kind:'human' node is a control-plane ASK (a deck on the human's
+/** A kind:'human' node is a control-plane ASK (a page on the human's
  *  screen), NOT a pi conversation — it has no session, so focusing/reviving it
  *  boots a confused blank "you have been revived" pi. Its pending-ask signal
  *  already rides the ⚑ badge on the ASKING node (attention.ts follows the

package/dist/core/canvas/nav-model.js

@@ -73,7 +73,7 @@ function mgrsOf(id) {
 export function managerOf(id) {
     return mgrsOf(id)[0]?.node_id;
 }
-/** A kind:'human' node is a control-plane ASK (a deck on the human's
+/** A kind:'human' node is a control-plane ASK (a page on the human's
  *  screen), NOT a pi conversation — it has no session, so focusing/reviving it
  *  boots a confused blank "you have been revived" pi. Its pending-ask signal
  *  already rides the ⚑ badge on the ASKING node (attention.ts follows the

package/dist/core/canvas/remote-canvas-source.js

@@ -208,7 +208,7 @@ export class RemoteCanvasSource {
     }
     async ticketCountsForView(root) {
         // The `canvas attention map` transport is unchanged; its `counts` values now
-        // mean all pending human tickets (deck/review/notify), not just asks.
+        // mean all pending human tickets (page/review), not just asks.
         const res = await this.execJson(['canvas', 'attention', 'map', '--view', root]);
         return isPlainObject(res) && isPlainObject(res['counts']) ? res['counts'] : {};
     }

package/dist/core/config.js

@@ -10,6 +10,7 @@ import { profileRoot } from './profiles/manifest.js';
 import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
 import { normalizeWorkingGerunds } from '../shared/working-activity.js';
+import { normalizePageComponents } from './human/page-catalog.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -478,6 +479,8 @@ function mergeConfig(partial) {
         ? [...defaults.working_gerunds]
         : normalizeWorkingGerunds(partial.working_gerunds);
     const whip_mode = typeof partial.whip_mode === 'boolean' ? partial.whip_mode : defaults.whip_mode;
+    const html_pages = typeof partial.html_pages === 'boolean' ? partial.html_pages : defaults.html_pages;
+    const page_components = normalizePageComponents(partial.page_components);
     const whip_messages = normalizeWhipMessages(partial.whip_messages);
     const mouse_mode_default = MOUSE_MODE_DEFAULTS.includes(partial.mouse_mode_default)
         ? partial.mouse_mode_default
@@ -497,7 +500,7 @@ function mergeConfig(partial) {
     const kinds = mergeKinds(partial.kinds);
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, whip_messages, mouse_mode_default, live_cycles, condensed_history, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, html_pages, page_components, whip_messages, mouse_mode_default, live_cycles, condensed_history, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer

package/dist/core/human/__tests__/page-render.test.d.ts

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

package/dist/core/human/__tests__/page-render.test.js

@@ -0,0 +1,49 @@
+// Two properties of the default page template whose absence would be SILENT —
+// every ordinary page still renders and still looks right when either breaks.
+// Nothing else about rendering is pinned here; prose shape is the renderer's
+// own business and a change there is visible the moment anyone looks at a page.
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { derivePageManifest } from '../page.js';
+import { renderPageHtml } from '../page-render.js';
+function render(name, source) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-page-render-test-'));
+    try {
+        const path = join(dir, name);
+        writeFileSync(path, source);
+        return renderPageHtml(derivePageManifest(path, name.endsWith('.md') ? 'md' : 'html'), readFileSync(path, 'utf8'));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+test('a config value carrying script markup cannot end its own <script> element', () => {
+    const html = render('page.md', [
+        '---', 'title: Escaping', '---', '',
+        'Pick one.', '',
+        '```slot:options',
+        '{"id":"esc","mode":"single","options":[{"id":"a","label":"</script><script>x</script>"},{"id":"b","label":"<!-- c -->"}]}',
+        '```', '',
+    ].join('\n'));
+    const config = /<crtr-options slot-id="esc"><script type="application\/json">([\s\S]*?)<\/script>/.exec(html)?.[1];
+    assert.ok(config !== undefined, `no options config in payload:\n${html}`);
+    // The mutation this catches: dropping the `<` escape for a plain JSON.stringify.
+    assert.ok(!config.includes('<'), `config text still carries a raw "<": ${config}`);
+    assert.equal(JSON.parse(config).options[0].label, '</script><script>x</script>');
+});
+test('an authored html slot id is mirrored to the slot-id the runtime reads', () => {
+    const html = render('page.html', [
+        '<!doctype html><html><head><meta name="crtr-page-title" content="Sign-off"></head><body>',
+        '<crtr-pages><crtr-page label="Window">',
+        '<crtr-options id="window"><script type="application/json">{"mode":"single","options":[{"id":"sat","label":"Saturday"}]}</script></crtr-options>',
+        '</crtr-page></crtr-pages>',
+        '</body></html>',
+    ].join('\n'));
+    // Without this, every element mounts and renders and no response ever
+    // reaches the host, because `src/pages` keys responses by `slot-id`.
+    assert.match(html, /<crtr-options id="window" slot-id="window">/);
+    assert.match(html, /<crtr-page label="Window">/);
+});

package/dist/core/human/__tests__/page-tickets.test.d.ts

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

package/dist/core/human/__tests__/page-tickets.test.js

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+const home = mkdtempSync(join(tmpdir(), 'crtr-page-tickets-'));
+process.env['CRTR_HOME'] = home;
+const { atomicWriteJson, pageManifestPath, pagePath, progressPath, responsePath } = await import('../convention.js');
+const { claimTicket } = await import('../claim.js');
+const { scanInbox, scanPageHistory } = await import('../scan.js');
+const { ticketDir } = await import('../root.js');
+const { cancelTicket, completePage, readPageProgress, readPageTicket, readTicketResult, submitPage, takeoverAndCompletePage, writePageProgress, } = await import('../tickets.js');
+const sources = mkdtempSync(join(tmpdir(), 'crtr-page-sources-'));
+function sourceFile(name, body) {
+    const path = join(sources, name);
+    writeFileSync(path, body);
+    return path;
+}
+const askPage = sourceFile('ask.md', `---
+title: Rollout scope
+subtitle: Pick tonight's rollout
+placement: inline
+---
+
+Which rollout do you want?
+
+\`\`\`slot:options
+{"id": "rollout", "mode": "single", "options": [{"id": "canary", "label": "Canary first"}, {"id": "full", "label": "Full"}]}
+\`\`\`
+`);
+const displayPage = sourceFile('display.html', '<!doctype html><html><head><meta name="crtr-page-title" content="Nightly report"></head><body><h1>All green</h1></body></html>');
+function submit(id, source, dialect, blockedSince, nodeId = 'node-1') {
+    return submitPage({ dir: ticketDir(id), sourceFile: source, dialect, source: { nodeId, blockedSince } }).dir;
+}
+test('submitPage publishes the authored source, the derived manifest and the blockedSince stamp', () => {
+    const submitted = submitPage({ dir: ticketDir('ask'), sourceFile: askPage, dialect: 'md', source: { nodeId: 'node-1' } });
+    assert.equal(submitted.kind, 'page');
+    assert.equal(submitted.id, 'ask');
+    assert.equal(readFileSync(pagePath(submitted.dir, 'md'), 'utf8'), readFileSync(askPage, 'utf8'));
+    const manifest = JSON.parse(readFileSync(pageManifestPath(submitted.dir), 'utf8'));
+    assert.equal(manifest['schema'], 'crtr.page/v1');
+    assert.equal(manifest['document'], 'page.md');
+    assert.equal(manifest['placement'], 'inline');
+    const source = manifest['source'];
+    assert.equal(source.nodeId, 'node-1');
+    assert.ok(Date.parse(source.blockedSince) > 0, 'submission stamps blockedSince');
+    assert.throws(() => submitPage({ dir: ticketDir('ask'), sourceFile: askPage, dialect: 'md' }), /already exists/);
+    const listed = scanInbox().find((item) => item.id === 'ask');
+    assert.equal(listed?.kind, 'page');
+    assert.equal(listed?.kind === 'page' ? listed.awaitsResponse : undefined, true);
+    assert.deepEqual(listed?.kind === 'page' ? listed.slotKinds : undefined, ['options']);
+});
+test('progress round-trips through validation and rejects malformed saved work', () => {
+    const dir = ticketDir('ask');
+    assert.equal(readPageProgress(dir), null, 'no progress file reads as null');
+    writePageProgress(dir, { rollout: { selectedOptionIds: ['canary'], comments: [] } });
+    assert.deepEqual(readPageProgress(dir), { rollout: { selectedOptionIds: ['canary'], comments: [] } });
+    assert.throws(() => writePageProgress(dir, { rollout: { selectedOptionIds: ['nope'], comments: [] } }), /nope/);
+    assert.throws(() => writePageProgress(dir, { unknown: { selectedOptionIds: [], comments: [] } }), /unknown/);
+    atomicWriteJson(progressPath(dir), { kind: 'page', responses: { rollout: 'not an object' }, savedAt: new Date().toISOString() });
+    assert.throws(() => readPageProgress(dir), /malformed/, 'malformed progress is an error, never silently discarded');
+    writePageProgress(dir, { rollout: { selectedOptionIds: ['canary'], comments: [] } });
+});
+test('readPageTicket derives pending, resolved and canceled state and carries the document', () => {
+    const dir = ticketDir('ask');
+    const pending = readPageTicket(dir);
+    assert.equal(pending.state, 'pending');
+    assert.equal(pending.manifest.title, 'Rollout scope');
+    assert.ok(pending.document.includes('Which rollout do you want?'));
+    assert.deepEqual(pending.progress, { rollout: { selectedOptionIds: ['canary'], comments: [] } });
+    const claim = claimTicket(dir);
+    assert.notEqual(claim, null, 'a page ticket is claimable');
+    assert.throws(() => completePage(dir, { rollout: { selectedOptionIds: [], comments: [] } }, claim.token), /rollout/, 'single-select requires one selection');
+    const completed = completePage(dir, { rollout: { selectedOptionIds: ['full'], comments: [] }, }, claim.token);
+    assert.equal(completed.won, true);
+    const written = JSON.parse(readFileSync(responsePath(dir), 'utf8'));
+    assert.equal(written['schema'], 'crtr.page-response/v1');
+    assert.equal(written['kind'], 'page');
+    assert.deepEqual(written['responses'], { rollout: { selectedOptionIds: ['full'], comments: [] } });
+    assert.equal(written['summary'], 'rollout: Full');
+    assert.equal(readTicketResult(dir)?.kind, 'page', 'the strict decoder accepts the page result');
+    assert.equal(existsSync(progressPath(dir)), false, 'completion clears owned work');
+    const resolved = readPageTicket(dir);
+    assert.equal(resolved.state, 'resolved');
+    assert.equal(resolved.progress, null);
+    assert.equal(scanInbox().some((item) => item.id === 'ask'), false, 'a resolved page leaves the pending list');
+    const canceledDir = submit('canceled', askPage, 'md', '2026-01-03T00:00:00.000Z');
+    cancelTicket(canceledDir, { reason: 'no longer needed' });
+    assert.equal(readPageTicket(canceledDir).state, 'canceled');
+});
+test('a display page acknowledges with the empty responses map', () => {
+    const dir = submit('display', displayPage, 'html', '2026-01-04T00:00:00.000Z');
+    const ticket = readPageTicket(dir);
+    assert.equal(ticket.manifest.dialect, 'html');
+    assert.equal(ticket.manifest.slots.length, 0);
+    assert.equal(scanInbox().find((item) => item.id === 'display')?.kind === 'page', true);
+    const acknowledged = takeoverAndCompletePage(dir, {}, { host: 'crtrd', pid: process.pid });
+    assert.equal(acknowledged.won, true);
+    const written = JSON.parse(readFileSync(responsePath(dir), 'utf8'));
+    assert.equal(written['schema'], 'crtr.page-response/v1');
+    assert.deepEqual(written['responses'], {});
+    assert.equal(written['summary'], '');
+});
+test('scanPageHistory returns every page of one node, oldest first, regardless of terminal file', () => {
+    submit('older', askPage, 'md', '2026-01-01T00:00:00.000Z');
+    submit('other-node', askPage, 'md', '2026-01-02T00:00:00.000Z', 'node-2');
+    const history = scanPageHistory('node-1');
+    assert.deepEqual(history.map((entry) => entry.id), ['older', 'canceled', 'display', 'ask']);
+    assert.deepEqual(history.map((entry) => entry.state), ['pending', 'canceled', 'resolved', 'resolved']);
+    assert.deepEqual(scanPageHistory('node-2').map((entry) => entry.id), ['other-node']);
+    assert.deepEqual(scanPageHistory('node-missing'), []);
+});

package/dist/core/human/__tests__/page.test.d.ts

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

package/dist/core/human/__tests__/page.test.js

@@ -0,0 +1,139 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { derivePageManifest, parsePageSource } from '../page.js';
+import { isResponseBearingSlot, validatePageResponses, validatePartialPageResponses } from '../page-schema.js';
+function withSource(name, source, run) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-page-test-'));
+    try {
+        const path = join(dir, name);
+        writeFileSync(path, source);
+        run(path);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+const htmlHead = '<!doctype html><html><head><meta name="crtr-page-title" content="Test"></head><body>';
+const htmlTail = '</body></html>';
+const optionsScript = '<script type="application/json">{"mode":"single","options":[{"id":"yes","label":"Yes"}]}</script>';
+function deriveHtml(body, head = htmlHead) {
+    let manifest;
+    withSource('input.html', `${head}${body}${htmlTail}`, (path) => { manifest = derivePageManifest(path, 'html'); });
+    return manifest;
+}
+function expectHtmlError(body, pattern, head = htmlHead) {
+    withSource('input.html', `${head}${body}${htmlTail}`, (path) => assert.throws(() => derivePageManifest(path, 'html'), pattern));
+}
+test('md dialect derives a normalized manifest and preserves top-level slot scanning', () => {
+    const source = `---
+title: Rollout
+subtitle: Choose carefully
+placement: inline
+---
+
+Before.
+
+\`\`\`\`markdown
+\`\`\`slot:text
+{"id":"nested","initialText":"not a slot"}
+\`\`\`
+\`\`\`\`
+
+\`\`\`slot:table
+{"columns":[{"id":"day","label":"Day"}],"rows":[{"id":"r1","cells":{"day":"Mon"}}]}
+\`\`\`
+
+\`\`\`slot:options
+{"id":"rollout","mode":"single","options":[{"id":"yes","label":"Yes"}]}
+\`\`\`
+`;
+    withSource('input.md', source, (path) => {
+        const manifest = derivePageManifest(path, 'md');
+        // A display-only table's schema defaults must survive the manifest→source round trip.
+        assert.deepEqual(parsePageSource(source, manifest).at(-1), { kind: 'slot', slotIndex: 1 });
+        assert.equal(manifest.title, 'Rollout');
+        assert.equal(manifest.subtitle, 'Choose carefully');
+        assert.equal(manifest.placement, 'inline');
+        assert.equal(manifest.document, 'page.md');
+        assert.equal(manifest.steps, 1);
+        assert.deepEqual(manifest.slots.map(({ id, kind, step }) => ({ id, kind, step })), [{ id: undefined, kind: 'table', step: 0 }, { id: 'rollout', kind: 'options', step: 0 }]);
+    });
+});
+test('html dialect derives document-order slots and wrapper steps', () => {
+    const body = `<crtr-pages><crtr-page><section><crtr-options id="choice">${optionsScript}</crtr-options></section></crtr-page><crtr-page><crtr-chart><script type="application/json">{"kind":"bar","x":"day","y":[{"field":"count"}]}</script></crtr-chart></crtr-page></crtr-pages>`;
+    const manifest = deriveHtml(body, '<!doctype html><html placement="inline"><head><meta name="crtr-page-title" content="HTML"><meta name="crtr-page-subtitle" content="Two steps"><meta name="crtr-page-placement" content="inline"></head><body>');
+    assert.equal(manifest.title, 'HTML');
+    assert.equal(manifest.placement, 'inline');
+    assert.equal(manifest.steps, 2);
+    assert.deepEqual(manifest.slots.map(({ kind, step }) => ({ kind, step })), [{ kind: 'options', step: 0 }, { kind: 'chart', step: 1 }]);
+});
+test('html wrapper rejects multiple crtr-pages', () => expectHtmlError('<crtr-pages><crtr-page></crtr-page></crtr-pages><crtr-pages><crtr-page></crtr-page></crtr-pages>', /more than one <crtr-pages>/));
+test('html wrapper rejects crtr-page outside crtr-pages', () => expectHtmlError('<crtr-page></crtr-page>', /<crtr-page> outside <crtr-pages>/));
+test('html wrapper rejects empty crtr-pages', () => expectHtmlError('<crtr-pages></crtr-pages>', /empty <crtr-pages>/));
+test('html wrapper rejects a response-bearing element outside a step with the fix', () => expectHtmlError(`<crtr-options id="choice">${optionsScript}</crtr-options>`, /response-bearing element <crtr-options>[\s\S]*<crtr-pages><crtr-page>…<\/crtr-page><\/crtr-pages>/));
+test('html wrapper rejects nested crtr-pages', () => expectHtmlError('<crtr-pages><crtr-page><crtr-pages><crtr-page></crtr-page></crtr-pages></crtr-page></crtr-pages>', /nested <crtr-pages>/));
+test('md front matter names unknown, empty-title, and placement errors', () => {
+    for (const [source, pattern] of [
+        ['---\ntitle: T\nother: no\n---\n', /unknown page front matter key "other"/],
+        ['---\ntitle:   \n---\n', /title is required and must be nonempty/],
+        ['---\ntitle: T\nplacement: sidebar\n---\n', /placement must be exactly inline or panel/],
+    ])
+        withSource('input.md', source, (path) => assert.throws(() => derivePageManifest(path, 'md'), pattern));
+});
+test('html metadata enforces cardinality, known names, and placement content', () => {
+    const duplicateTitle = '<!doctype html><html><head><meta name="crtr-page-title" content="A"><meta name="crtr-page-title" content="B"></head><body>';
+    const duplicateSubtitle = '<!doctype html><html><head><meta name="crtr-page-title" content="A"><meta name="crtr-page-subtitle" content="A"><meta name="crtr-page-subtitle" content="B"></head><body>';
+    const unknown = '<!doctype html><html><head><meta name="crtr-page-title" content="A"><meta name="crtr-page-extra" content="x"></head><body>';
+    const badPlacement = '<!doctype html><html><head><meta name="crtr-page-title" content="A"><meta name="crtr-page-placement" content="drawer"></head><body>';
+    expectHtmlError('', /Expected exactly one <meta name="crtr-page-title">, found 2/, duplicateTitle);
+    expectHtmlError('', /Expected at most one <meta name="crtr-page-subtitle">, found 2/, duplicateSubtitle);
+    expectHtmlError('', /unknown page metadata element <meta name="crtr-page-extra">/, unknown);
+    expectHtmlError('', /content must be exactly inline or panel/, badPlacement);
+});
+test('the response-bearing predicate handles table selection and catalog edges', () => {
+    const slot = (kind, config, unvalidated) => ({ kind, step: 0, config, ...(unvalidated ? { unvalidated } : {}) });
+    assert.equal(isResponseBearingSlot(slot('table', { columns: [{ id: 'c', label: 'C' }], rowSelect: 'none', columnSelect: 'none' })), false);
+    assert.equal(isResponseBearingSlot(slot('table', { columns: [{ id: 'c', label: 'C' }], rowSelect: 'single', columnSelect: 'none' })), true);
+    assert.equal(isResponseBearingSlot(slot('chart', { kind: 'bar', x: 'x', y: [{ field: 'y' }] })), false);
+    assert.equal(isResponseBearingSlot(slot('product-kind', {}, true)), true);
+});
+test('final and partial response validation share slot-addressed rules', () => {
+    const manifest = deriveHtml(`<crtr-pages><crtr-page><crtr-options id="choice">${optionsScript}</crtr-options><crtr-text id="note"><script type="application/json">{"initialText":""}</script></crtr-text></crtr-page></crtr-pages>`);
+    assert.deepEqual(validatePartialPageResponses(manifest, { choice: { selectedOptionIds: ['yes'], comments: [] } }), { choice: { selectedOptionIds: ['yes'], comments: [] } });
+    assert.throws(() => validatePageResponses(manifest, { choice: { selectedOptionIds: ['yes'], comments: [] } }), /missing response-bearing slot id "note"/);
+    assert.deepEqual(validatePageResponses(manifest, { choice: { selectedOptionIds: ['yes'], comments: [] }, note: { text: '', edited: false, comments: [] } }), { choice: { selectedOptionIds: ['yes'], comments: [] }, note: { text: '', edited: false, comments: [] } });
+    assert.throws(() => validatePartialPageResponses(manifest, { choice: { selectedOptionIds: ['maybe'], comments: [] } }), /unknown option id "maybe"/);
+    assert.throws(() => validatePartialPageResponses(manifest, { extra: {} }), /unknown or non-response-bearing slot id "extra"/);
+});
+test('PageSourceProjection associates leading, interstitial, and trailing prose', () => {
+    const source = `---
+title: Projection
+---
+Leading prose.
+
+\`\`\`slot:text
+{"id":"first","initialText":""}
+\`\`\`
+
+Interstitial prose.
+
+\`\`\`slot:text
+{"id":"second","initialText":""}
+\`\`\`
+
+Trailing prose.
+`;
+    withSource('input.md', source, (path) => {
+        const manifest = derivePageManifest(path, 'md');
+        assert.deepEqual(parsePageSource(source, manifest), [
+            { kind: 'prose', markdown: 'Leading prose.' },
+            { kind: 'slot', slotIndex: 0 },
+            { kind: 'prose', markdown: 'Interstitial prose.' },
+            { kind: 'slot', slotIndex: 1 },
+            { kind: 'prose', markdown: 'Trailing prose.' },
+        ]);
+    });
+});