@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/canvas/types.d.ts

@@ -1,6 +1,10 @@
-/** What a node is doing right now. UI shows active+idle; `done` is hidden but
- *  revivable; `canceled` is a user-closed node (also hidden, also revivable —
- *  not a fault); only `dead` is a fault. */
+import type { SpawnChildOpts } from '../runtime/spawn.js';
+/** What a node is doing right now. `active` means the engine process is live on
+ *  its host — a tmux pane OR a headless broker (`host_kind`) — NOT that it holds
+ *  a window or that anyone is watching it (attachment is a separate axis: the
+ *  `focuses` table for tmux, the broker's viewer set for headless). UI shows
+ *  active+idle; `done` is hidden but revivable; `canceled` is a user-closed node
+ *  (also hidden, also revivable — not a fault); only `dead` is a fault. */
 export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
 /** Does stopping finalize the node? terminal = worker (finalizes on push --final);
  *  resident = manager/orchestrator (stays dormant, woken by inbox). */
@@ -44,6 +48,11 @@ export interface NodeIdentity {
     created: string;
     /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
     cwd: string;
+    /** Which HOST launches + supervises this node: 'tmux' (a pane) or 'broker' (the
+     *  headless in-process engine). Durable IDENTITY (mirrored to the row like
+     *  `cwd`, re-derived on index rebuild), NOT live runtime like `pane`.
+     *  NULL ⇒ 'tmux' (every pre-broker node). */
+    host_kind?: 'tmux' | 'broker' | null;
     /** Role the node was born as: explore | developer | plan | review | general… */
     kind: string;
     mode: Mode;
@@ -65,6 +74,14 @@ export interface NodeIdentity {
      *  `parent` so an INDEPENDENT root (parent=null) still records its lineage.
      *  Audit only; null for a user-opened root. Defaults to `parent` for a child. */
     spawned_by?: string | null;
+    /** Fork provenance — the `--fork-from` source this node was forked from at
+     *  spawn (the node id / session path / pi session uuid the caller passed). pi
+     *  COPIED that conversation into this node's first session, so the node boots
+     *  carrying the SOURCE's first-person history. Persisted here so the boot
+     *  intro can assert this node's OWN identity over that inherited narrative
+     *  (without it a fork impersonates its source). Undefined for a fresh node;
+     *  identity/audit only. */
+    fork_from?: string | null;
     /** New subscriptions this node opens default to passive when true. */
     passive_default?: boolean;
     /** REVIVE-HOME — the tmux session a node is (re)opened into when it must
@@ -87,6 +104,12 @@ export interface NodeIdentity {
      *  PATH is opened directly — immune to any cwd discrepancy. Null for older
      *  nodes booted before this field existed → revive falls back to the bare id. */
     pi_session_file?: string | null;
+    /** A caller-pinned model TIER (ultra/strong/medium/light) that overrides the
+     *  persona's declared default. Durable so it survives a polymorph: every
+     *  spec-rebuild path (promote/demote/lifecycle/reset) re-passes it to
+     *  buildLaunchSpec, while the persona default is recomputed fresh for the
+     *  (possibly new) kind. Null/undefined ⇒ use the persona default. */
+    model_override?: string | null;
     /** Full pi launch recipe; rewritten on every polymorph. */
     launch?: LaunchSpec;
 }
@@ -143,6 +166,8 @@ export interface NodeRow {
     lifecycle: Lifecycle;
     status: NodeStatus;
     cwd: string;
+    /** Which HOST launches + supervises this node; see NodeIdentity.host_kind. */
+    host_kind: 'tmux' | 'broker' | null;
     parent: string | null;
     created: string;
     /** Authoritative runtime columns (see NodeRuntime). */
@@ -188,3 +213,66 @@ export interface SubscriptionRef {
     active: boolean;
     created: string;
 }
+/** The four firing actions a wakeup can carry (design §4):
+ *  - bare     → revive the target node directly (resume:false), no inbox entry.
+ *  - noted    → deliver a note to the target's inbox (normal tier).
+ *  - deadline → deliver a timeout note to the target's inbox (urgent tier); ≤1 per node.
+ *  - spawn    → spawnChild a fresh node from a stored recipe (detached, node_id NULL). */
+export type WakeKind = 'bare' | 'noted' | 'deadline' | 'spawn';
+/** payload for a `bare` wake — `null`, or a label carried only for list rendering. */
+export interface BareWakePayload {
+    label?: string;
+}
+/** payload for a `noted` wake — a non-empty note body + a ≤120-char first-line label. */
+export interface NotedWakePayload {
+    body: string;
+    label: string;
+}
+/** payload for a `deadline` wake — a non-empty timeout note + the machine-readable
+ *  `timeout` mirror. The VISIBLE timeout signal rides the RENDERED label/body, not
+ *  this flag (inbox digests never surface arbitrary data keys). ≤1 per node. */
+export interface DeadlineWakePayload {
+    body: string;
+    timeout: true;
+    label: string;
+}
+/** The parsed per-kind payload union (Maj-1): the data-access layer JSON.stringifies
+ *  this on write and JSON.parses it back on read, so callers consume `payload.body`
+ *  / `payload as SpawnChildOpts` directly with no re-parse. A `spawn` payload is a
+ *  SpawnChildOpts recipe with `parent` resolved to a NON-NULL armer id at arm time. */
+export type WakePayload = null | BareWakePayload | NotedWakePayload | DeadlineWakePayload | SpawnChildOpts;
+/** A wakeup row as stored in the `wakeups` table (canvas.db, migration v7). One row =
+ *  "do <kind> at fire_at [every recur]". `node_id` is the revive TARGET + node-anchored
+ *  cancel anchor (NULL = canvas-detached); `owner_id` is the ARMER (set on every row).
+ *  `payload` is the PARSED per-kind union, never the raw JSON string (Maj-1). */
+export interface Wakeup {
+    /** Stable id (caller-supplied at arm time, minted as `wk-${newNodeId()}`). */
+    wakeup_id: string;
+    /** Revive target + node-anchored cancel anchor; NULL = canvas-detached (spawn). */
+    node_id: string | null;
+    /** The node that armed this wake; set on EVERY row. == node_id for a self-alarm. */
+    owner_id: string;
+    /** Next absolute fire time, ISO 8601 UTC; lexicographic <= compare. */
+    fire_at: string;
+    kind: WakeKind;
+    /** NULL = one-shot/adaptive; else the recur JSON the daemon advances. */
+    recur: string | null;
+    /** Parsed per-kind payload (NULL for a bare one-shot with no label). */
+    payload: WakePayload;
+    /** ISO 8601, audit/order. */
+    created: string;
+}
+/** The arm-a-wake spec (the pinned shared contract). `wakeup_id` is CALLER-SUPPLIED —
+ *  the canvas layer never mints ids (importing newNodeId from runtime/nodes.ts would
+ *  force a canvas → runtime → canvas cycle, Min-1); the command surface mints
+ *  `wk-${newNodeId()}` and passes it in. `owner_id` is required on every row;
+ *  `node_id` is NULL for a detached wake (deferred spawn / spawn-cron). */
+export interface ArmWakeSpec {
+    wakeup_id: string;
+    node_id?: string | null;
+    owner_id: string;
+    fire_at: string;
+    kind: WakeKind;
+    recur?: string | null;
+    payload?: WakePayload;
+}

package/dist/core/canvas/wakeups.d.ts

@@ -0,0 +1,76 @@
+import type { ArmWakeSpec, Wakeup } from './types.js';
+/** A thrown integrity-backstop error from armWake. `code` is the AC-N3 code the
+ *  command surface (the ONLY sanctioned caller of armWake) maps to a rendered
+ *  error block — armWake carries integrity backstops only (empty body / recur-on-
+ *  deadline / unknown kind); target-resolvability + recoverable-state + the
+ *  per-owner cap live in the surface (Min-6), so a non-surface armer could insert
+ *  a dangling wake — every armer MUST route through the surface. */
+export declare class WakeArmError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Which wakes a listWakes call returns. Distinguished by which key is present
+ *  (mirrors listNodes' filter shape):
+ *   - { node }    — wakes anchored to this node (node_id = ?).
+ *   - { owner }   — wakes this node ARMED (owner_id = ?); the per-owner cap count.
+ *   - { subtree } — wakes anchored to any node in this id set (node_id IN (…)).
+ *   - { due }     — wakes whose fire_at <= this ISO instant.
+ *   - { canvas }  — every wake on the canvas. */
+export type WakeScope = {
+    node: string;
+} | {
+    owner: string;
+} | {
+    subtree: string[];
+} | {
+    due: string;
+} | {
+    canvas: true;
+};
+/** INSERT one wakeup row from the pinned spec, returning its (caller-supplied)
+ *  `wakeup_id`. JSON.stringifies the typed `payload` union into the TEXT column
+ *  and stamps `created`.
+ *
+ *  Deadline upsert (design Q3, "≤1 deadline per node"): for `kind === 'deadline'`
+ *  the node's existing deadline is canceled first, then the new one inserted — the
+ *  partial unique index `idx_wakeups_deadline` is the schema-level backstop.
+ *
+ *  Integrity backstops (throw WakeArmError; the surface maps the code to AC-N3):
+ *   - empty/whitespace note `body` for `noted`/`deadline` → `empty_note`.
+ *   - non-NULL `recur` on a `deadline`                    → `deadline_cannot_recur`.
+ *   - unknown `kind`                                      → `bad_kind`.
+ *  NO target-resolvability / recoverable-state / cap backstop here (Min-6). */
+export declare function armWake(spec: ArmWakeSpec): string;
+/** UPDATE the next fire time — recurrence advancement (the daemon settles a
+ *  recurring row to its next slot BEFORE enacting, crash-safe; design D4). */
+export declare function advanceWake(wakeup_id: string, nextFireIso: string): void;
+/** DELETE one wakeup by id — one-shot consumption (the daemon settles a one-shot
+ *  row BEFORE enacting, crash-safe; design D4). */
+export declare function consumeWake(wakeup_id: string): void;
+/** DELETE one wakeup by id — the explicit user/surface cancel. Idempotent:
+ *  0 rows ⇒ no error (AC-C2). */
+export declare function cancelWake(wakeup_id: string): void;
+/** DELETE every wake anchored to this node AND every detached wake it ARMED —
+ *  deliberate close/reap (ruling A). Hooked at transition('cancel'). */
+export declare function cancelWakesFor(node_id: string): void;
+/** DELETE this node's one-shot self-alarms (recur IS NULL); node-anchored crons
+ *  SURVIVE — finalize is the instance finishing, not a teardown of standing
+ *  schedules (design Q1). Hooked at transition('finalize'). */
+export declare function cancelSelfAlarms(node_id: string): void;
+/** DELETE this node's pending deadline(s) — cancel-on-wake (design §6.4).
+ *  Hooked at reviveNode, so the deadline always belongs to the dormancy left. */
+export declare function cancelDeadlinesFor(node_id: string): void;
+/** The daemon's per-tick due query: every row whose fire_at has arrived, in
+ *  fire_at order, with `payload` parsed into the typed union. Returns exactly ONE
+ *  row per recurring wake regardless of missed slots — coalescing is structural
+ *  (AC-E2). */
+export declare function dueWakes(nowIso: string): Wakeup[];
+/** List wakes for a scope (node / owner / subtree / due / canvas), `payload`
+ *  parsed as in dueWakes. The subtree variant binds the id set with `?`
+ *  placeholders (mirroring listNodes — the codebase's one safe dynamic-IN spot);
+ *  ids are NEVER string-concatenated (Min-10). */
+export declare function listWakes(scope: WakeScope): Wakeup[];
+/** True if the node has ANY pending self-anchored wake (of any kind). Consumed by
+ *  the stop-guard self-wake seam so a no-child poll node releases dormant after
+ *  arming instead of being nagged to finish (AC-X3/AC-R1). */
+export declare function hasPendingSelfWake(node_id: string): boolean;

package/dist/core/canvas/wakeups.js

@@ -0,0 +1,185 @@
+// wakeups.ts — the WAKEUPS table data-access layer (canvas.db, migration v7).
+//
+// One-module-per-table (the focuses.ts precedent): ALL SQL that touches the
+// `wakeups` table lives HERE and nowhere else — never appended to canvas.ts,
+// which keeps the node/edge model. A WAKEUP is one durable row = "do <kind> at
+// fire_at [every recur]", carrying a fire time, a kind, an optional payload, an
+// optional recurrence cadence, a nullable TARGET node_id, and the owner_id of
+// the node that ARMED it.
+//
+// Two anchors, two reap rules (design D1/D2):
+//   - node_id  → the revive target AND the node-anchored cancel anchor; it
+//     carries the `ON DELETE CASCADE` FK, so a pruned node's node-anchored wakes
+//     are reaped FOR FREE in pruneNodes' same `DELETE FROM nodes` (canvas.ts is
+//     UNTOUCHED — the cascade does it; there is no pruneNodes wakeups code).
+//     NULL = canvas-detached (a deferred spawn / spawn-cron).
+//   - owner_id → the armer; a PLAIN indexed column with NO FK, so a crashed-
+//     then-pruned armer's detached cron is NOT cascade-dropped (Invariant E).
+//     Reaped only by the explicit cancelWakesFor DELETE on deliberate close.
+//
+// Each function is a single-statement query mirroring the canvas.ts atomic-setter
+// pattern (setStatus/setIntent/setPresence) — no read-modify-write, serialized by
+// WAL. The data-access layer OWNS payload serialization: armWake JSON.stringifies
+// the typed per-kind union on write; dueWakes/listWakes JSON.parse it back on read
+// (Maj-1), so callers consume `payload.body` / `payload as SpawnChildOpts` directly.
+//
+// `wakeup_id` is CALLER-SUPPLIED (the command surface mints `wk-${newNodeId()}`):
+// the canvas layer never imports newNodeId from runtime/nodes.ts — that would
+// force a canvas → runtime → canvas import cycle (Min-1).
+import { openDb } from './db.js';
+/** A thrown integrity-backstop error from armWake. `code` is the AC-N3 code the
+ *  command surface (the ONLY sanctioned caller of armWake) maps to a rendered
+ *  error block — armWake carries integrity backstops only (empty body / recur-on-
+ *  deadline / unknown kind); target-resolvability + recoverable-state + the
+ *  per-owner cap live in the surface (Min-6), so a non-surface armer could insert
+ *  a dangling wake — every armer MUST route through the surface. */
+export class WakeArmError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WakeArmError';
+    }
+}
+/** Hydrate a raw row into a Wakeup, JSON.parsing `payload` back into the typed
+ *  per-kind union (NULL column → null). */
+function wakeupFrom(r) {
+    const raw = r['payload'];
+    return {
+        wakeup_id: r['wakeup_id'],
+        node_id: r['node_id'] ?? null,
+        owner_id: r['owner_id'],
+        fire_at: r['fire_at'],
+        kind: r['kind'],
+        recur: r['recur'] ?? null,
+        payload: raw == null ? null : JSON.parse(raw),
+        created: r['created'],
+    };
+}
+// ---------------------------------------------------------------------------
+// Writes — each a single-statement INSERT/UPDATE/DELETE.
+// ---------------------------------------------------------------------------
+/** INSERT one wakeup row from the pinned spec, returning its (caller-supplied)
+ *  `wakeup_id`. JSON.stringifies the typed `payload` union into the TEXT column
+ *  and stamps `created`.
+ *
+ *  Deadline upsert (design Q3, "≤1 deadline per node"): for `kind === 'deadline'`
+ *  the node's existing deadline is canceled first, then the new one inserted — the
+ *  partial unique index `idx_wakeups_deadline` is the schema-level backstop.
+ *
+ *  Integrity backstops (throw WakeArmError; the surface maps the code to AC-N3):
+ *   - empty/whitespace note `body` for `noted`/`deadline` → `empty_note`.
+ *   - non-NULL `recur` on a `deadline`                    → `deadline_cannot_recur`.
+ *   - unknown `kind`                                      → `bad_kind`.
+ *  NO target-resolvability / recoverable-state / cap backstop here (Min-6). */
+export function armWake(spec) {
+    const { kind } = spec;
+    if (kind !== 'bare' && kind !== 'noted' && kind !== 'deadline' && kind !== 'spawn') {
+        throw new WakeArmError('bad_kind', `unknown wake kind: ${String(kind)}`);
+    }
+    if (kind === 'noted' || kind === 'deadline') {
+        const body = spec.payload?.body;
+        if (typeof body !== 'string' || body.trim() === '') {
+            throw new WakeArmError('empty_note', `a ${kind} wake requires a non-empty note body.`);
+        }
+    }
+    if (kind === 'deadline' && spec.recur != null) {
+        throw new WakeArmError('deadline_cannot_recur', 'a deadline wake cannot recur.');
+    }
+    // Deadline upsert: clear the node's existing deadline before inserting the new one.
+    if (kind === 'deadline' && spec.node_id != null) {
+        cancelDeadlinesFor(spec.node_id);
+    }
+    const payloadText = spec.payload == null ? null : JSON.stringify(spec.payload);
+    openDb()
+        .prepare(`INSERT INTO wakeups (wakeup_id, node_id, owner_id, fire_at, kind, recur, payload, created)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(spec.wakeup_id, spec.node_id ?? null, spec.owner_id, spec.fire_at, kind, spec.recur ?? null, payloadText, new Date().toISOString());
+    return spec.wakeup_id;
+}
+/** UPDATE the next fire time — recurrence advancement (the daemon settles a
+ *  recurring row to its next slot BEFORE enacting, crash-safe; design D4). */
+export function advanceWake(wakeup_id, nextFireIso) {
+    openDb().prepare('UPDATE wakeups SET fire_at = ? WHERE wakeup_id = ?').run(nextFireIso, wakeup_id);
+}
+/** DELETE one wakeup by id — one-shot consumption (the daemon settles a one-shot
+ *  row BEFORE enacting, crash-safe; design D4). */
+export function consumeWake(wakeup_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE wakeup_id = ?').run(wakeup_id);
+}
+/** DELETE one wakeup by id — the explicit user/surface cancel. Idempotent:
+ *  0 rows ⇒ no error (AC-C2). */
+export function cancelWake(wakeup_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE wakeup_id = ?').run(wakeup_id);
+}
+/** DELETE every wake anchored to this node AND every detached wake it ARMED —
+ *  deliberate close/reap (ruling A). Hooked at transition('cancel'). */
+export function cancelWakesFor(node_id) {
+    openDb()
+        .prepare('DELETE FROM wakeups WHERE node_id = ? OR owner_id = ?')
+        .run(node_id, node_id);
+}
+/** DELETE this node's one-shot self-alarms (recur IS NULL); node-anchored crons
+ *  SURVIVE — finalize is the instance finishing, not a teardown of standing
+ *  schedules (design Q1). Hooked at transition('finalize'). */
+export function cancelSelfAlarms(node_id) {
+    openDb().prepare('DELETE FROM wakeups WHERE node_id = ? AND recur IS NULL').run(node_id);
+}
+/** DELETE this node's pending deadline(s) — cancel-on-wake (design §6.4).
+ *  Hooked at reviveNode, so the deadline always belongs to the dormancy left. */
+export function cancelDeadlinesFor(node_id) {
+    openDb().prepare("DELETE FROM wakeups WHERE node_id = ? AND kind = 'deadline'").run(node_id);
+}
+// ---------------------------------------------------------------------------
+// Reads.
+// ---------------------------------------------------------------------------
+/** The daemon's per-tick due query: every row whose fire_at has arrived, in
+ *  fire_at order, with `payload` parsed into the typed union. Returns exactly ONE
+ *  row per recurring wake regardless of missed slots — coalescing is structural
+ *  (AC-E2). */
+export function dueWakes(nowIso) {
+    return openDb()
+        .prepare('SELECT * FROM wakeups WHERE fire_at <= ? ORDER BY fire_at')
+        .all(nowIso).map(wakeupFrom);
+}
+/** List wakes for a scope (node / owner / subtree / due / canvas), `payload`
+ *  parsed as in dueWakes. The subtree variant binds the id set with `?`
+ *  placeholders (mirroring listNodes — the codebase's one safe dynamic-IN spot);
+ *  ids are NEVER string-concatenated (Min-10). */
+export function listWakes(scope) {
+    const db = openDb();
+    let rows;
+    if ('node' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE node_id = ? ORDER BY fire_at')
+            .all(scope.node);
+    }
+    else if ('owner' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE owner_id = ? ORDER BY fire_at')
+            .all(scope.owner);
+    }
+    else if ('subtree' in scope) {
+        if (scope.subtree.length === 0)
+            return [];
+        const placeholders = scope.subtree.map(() => '?').join(',');
+        rows = db
+            .prepare(`SELECT * FROM wakeups WHERE node_id IN (${placeholders}) ORDER BY fire_at`)
+            .all(...scope.subtree);
+    }
+    else if ('due' in scope) {
+        rows = db
+            .prepare('SELECT * FROM wakeups WHERE fire_at <= ? ORDER BY fire_at')
+            .all(scope.due);
+    }
+    else {
+        rows = db.prepare('SELECT * FROM wakeups ORDER BY fire_at').all();
+    }
+    return rows.map(wakeupFrom);
+}
+/** True if the node has ANY pending self-anchored wake (of any kind). Consumed by
+ *  the stop-guard self-wake seam so a no-child poll node releases dormant after
+ *  arming instead of being nagged to finish (AC-X3/AC-R1). */
+export function hasPendingSelfWake(node_id) {
+    return (openDb().prepare('SELECT 1 FROM wakeups WHERE node_id = ? LIMIT 1').get(node_id) !== undefined);
+}

package/dist/core/config.js

@@ -137,7 +137,10 @@ function mergeConfig(partial) {
         ? Math.floor(rawMaxPanes)
         : defaults.max_panes_per_window;
     const canvasNav = mergeCanvasNav(partial.canvasNav);
-    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window, canvasNav };
+    // The merge drops unknown keys, so `headless` must be carried explicitly or it
+    // is lost on every read-modify-write of config.json.
+    const headless = typeof partial.headless === 'boolean' ? partial.headless : defaults.headless;
+    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window, canvasNav, headless };
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);

package/dist/core/frontmatter.js

@@ -1,3 +1,4 @@
+import { parse as parseYaml } from 'yaml';
 import { isSkillType } from '../types.js';
 const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
 export function parseFrontmatter(source) {
@@ -7,7 +8,7 @@ export function parseFrontmatter(source) {
     }
     const raw = match[1];
     const body = source.slice(match[0].length);
-    return { data: toSkillFrontmatter(parseYamlRecord(raw)), body, raw };
+    return { data: toSkillFrontmatter(parseYamlBlock(raw)), body, raw };
 }
 /** Like parseFrontmatter but returns the raw key/value record instead of
  *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
@@ -19,138 +20,50 @@ export function parseFrontmatterGeneric(source) {
     }
     const raw = match[1];
     const body = source.slice(match[0].length);
-    return { data: parseYamlRecord(raw), body, raw };
+    return { data: parseYamlBlock(raw), body, raw };
 }
 function toSkillFrontmatter(out) {
     const fm = {
-        name: typeof out.name === 'string' ? out.name : '',
-        description: typeof out.description === 'string' ? out.description : undefined,
-        keywords: Array.isArray(out.keywords) ? out.keywords : undefined,
+        name: scalarToString(out.name) ?? '',
+        description: scalarToString(out.description),
+        keywords: Array.isArray(out.keywords) ? out.keywords.map((k) => String(k)) : undefined,
         type: isSkillType(out.type) ? out.type : undefined,
     };
     return fm;
 }
-function parseYamlRecord(yaml) {
-    const lines = yaml.split(/\r?\n/);
-    const out = {};
-    let i = 0;
-    while (i < lines.length) {
-        const raw = lines[i];
-        if (!raw.trim()) {
-            i++;
-            continue;
-        }
-        const idx = raw.indexOf(':');
-        if (idx === -1) {
-            i++;
-            continue;
-        }
-        const key = raw.slice(0, idx).trim();
-        const rest = raw.slice(idx + 1).trim();
-        // Block scalar: `key: |` or `key: >` with optional chomp indicator (-/+)
-        const blockMatch = rest.match(/^([|>])([-+]?)\s*$/);
-        if (blockMatch) {
-            const style = blockMatch[1];
-            const chomp = blockMatch[2];
-            const collected = [];
-            let blockIndent = null;
-            let j = i + 1;
-            while (j < lines.length) {
-                const r = lines[j];
-                if (r.trim() === '') {
-                    collected.push('');
-                    j++;
-                    continue;
-                }
-                const ind = r.match(/^(\s*)/)?.[1].length ?? 0;
-                if (blockIndent === null) {
-                    if (ind === 0)
-                        break;
-                    blockIndent = ind;
-                }
-                if (ind < blockIndent)
-                    break;
-                collected.push(r.slice(blockIndent));
-                j++;
-            }
-            while (collected.length > 0 && collected[collected.length - 1] === '')
-                collected.pop();
-            let value;
-            if (style === '|') {
-                value = collected.join('\n');
-            }
-            else {
-                const parts = [];
-                let para = [];
-                for (const ln of collected) {
-                    if (ln === '') {
-                        if (para.length > 0) {
-                            parts.push(para.join(' '));
-                            para = [];
-                        }
-                        parts.push('');
-                    }
-                    else {
-                        para.push(ln);
-                    }
-                }
-                if (para.length > 0)
-                    parts.push(para.join(' '));
-                const folded = [];
-                for (let k = 0; k < parts.length; k++) {
-                    if (parts[k] === '' && (k === 0 || parts[k - 1] === ''))
-                        continue;
-                    folded.push(parts[k]);
-                }
-                value = folded.join('\n').replace(/\n+$/, '');
-            }
-            if (chomp !== '+')
-                value = value.replace(/\n+$/, '');
-            out[key] = value;
-            i = j;
-            continue;
-        }
-        // Empty value: could be a list on subsequent lines
-        if (rest === '') {
-            const buf = [];
-            let j = i + 1;
-            while (j < lines.length) {
-                const r = lines[j];
-                if (r.trim() === '') {
-                    j++;
-                    continue;
-                }
-                if (/^\s*-\s+/.test(r)) {
-                    buf.push(stripQuotes(r.replace(/^\s*-\s+/, '').trim()));
-                    j++;
-                    continue;
-                }
-                break;
-            }
-            if (buf.length > 0)
-                out[key] = buf;
-            i = j;
-            continue;
-        }
-        if (rest.startsWith('[') && rest.endsWith(']')) {
-            out[key] = rest
-                .slice(1, -1)
-                .split(',')
-                .map((s) => stripQuotes(s.trim()))
-                .filter(Boolean);
-            i++;
-            continue;
-        }
-        out[key] = stripQuotes(rest);
-        i++;
-    }
-    return out;
+/** Coerce a YAML scalar (string/number/boolean) to its string form. A skill's
+ *  `name`/`description` are always strings to consumers; native non-string
+ *  scalars (a numeric/boolean value) render as their string form, and
+ *  non-scalars (null/undefined/array/object) yield undefined. */
+function scalarToString(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return undefined;
+}
+/** Parse the inner YAML of a frontmatter block into a key/value record.
+ *
+ *  ONE strict parser, no fallback. The frontmatter contract IS "valid YAML":
+ *  the single `yaml`-package path handles the substrate's nested `gate:` maps,
+ *  inline `{…}` objects, and native scalar typing — and a doc whose frontmatter
+ *  is NOT valid YAML THROWS, by design. There is deliberately no second lenient
+ *  parser; a dual parsing strategy is the hedge we reject. Callers that iterate
+ *  MANY docs isolate a per-doc throw at the COLLECTION layer (a clear scoped
+ *  notice naming the bad file, then continue); single-doc callers let the error
+ *  surface so the user learns their one requested doc is malformed.
+ *
+ *  A VALID non-object document (a bare scalar, a top-level list, or an empty
+ *  block) normalizes to an empty record, preserving the contract that callers
+ *  always receive a Record for well-formed-but-non-mapping frontmatter. */
+function parseYamlBlock(raw) {
+    return normalizeToRecord(parseYaml(raw));
 }
-function stripQuotes(s) {
-    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
-        return s.slice(1, -1);
+function normalizeToRecord(parsed) {
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
     }
-    return s;
+    return {};
 }
 export function serializeFrontmatter(data) {
     const lines = ['---'];

package/dist/core/memory-resolver.d.ts

@@ -0,0 +1,49 @@
+import type { Scope } from '../types.js';
+/**
+ * Thin memory-document resolver for the document substrate. Mirrors the SHAPE
+ * of the skill resolver (qualifier parse → scope precedence → direct path
+ * lookup → leaf-name fallback) but drops ALL plugin machinery: memory
+ * resolution is scope + leaf/path ONLY. The three memory scopes resolve in
+ * precedence order project > user > builtin (the same precedence concept as
+ * orderPluginsByResolution, minus plugins). It returns the raw parsed
+ * frontmatter + body; it does NOT interpret the schema, kind, gate, or rungs —
+ * that is the schema/gate layer's job (callers filter by `frontmatter.kind`).
+ */
+export interface MemoryDoc {
+    /** Path-derived identity: the doc's path under the scope's memory/ root, no
+     *  extension, slash-separated — e.g. memory/taste/foo.md → "taste/foo". */
+    name: string;
+    scope: Scope;
+    /** Absolute path to the resolved .md file. */
+    path: string;
+    /** Raw, uncoerced frontmatter record (null when the doc has no frontmatter). */
+    frontmatter: Record<string, unknown> | null;
+    /** Document body, with the frontmatter block stripped. */
+    body: string;
+}
+export interface MemoryResolutionOpts {
+    /** Restrict resolution to a single scope. Conflicts with a scope prefix on
+     *  the identifier (e.g. `user/foo` with scope=project) throw. */
+    scope?: Scope;
+}
+/** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
+export declare function memoryDocId(doc: MemoryDoc): string;
+/** All memory docs in one scope's memory/ dir, scanned recursively for *.md
+ *  (topical subdirs supported), sorted by path-derived name. */
+export declare function listMemoryDocs(scope: Scope): MemoryDoc[];
+/** All memory docs across the resolved scopes, in precedence order
+ *  (project, then user, then builtin), each scope's docs name-sorted within. */
+export declare function listAllMemoryDocs(scope?: Scope): MemoryDoc[];
+/**
+ * Resolve a path-derived name to a single memory document.
+ *
+ * Accepted identifier forms (mirroring parseSkillQualifier, no plugins):
+ *   <name>            — bare name; resolved by scope precedence project>user>builtin
+ *   <scope>/<name>    — pinned to one scope (user|project)
+ * `<name>` may carry topical subdirs (`taste/foo`); a bare leaf (`foo`) falls
+ * back to a last-segment match across the resolved scopes.
+ *
+ * Resolution order: parse qualifier → direct memory/<name>.md lookup
+ * (precedence-first) → leaf-name fallback (ambiguity error listing candidates).
+ */
+export declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutionOpts): MemoryDoc;