@north-light/crouter 0.3.217 → 0.3.219

package/dist/core/runtime/promote.js

@@ -21,75 +21,48 @@
 import { getNode, updateNode } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { ensureDaemon } from '../../daemon/manage.js';
-import { buildLaunchSpec } from './launch.js';
+import { buildLaunchSpec, buildLaunchSpecAsync } from './launch.js';
 import { hasRoadmap, seedRoadmap, roadmapPath } from './roadmap.js';
 import { readGoal, goalPath } from './kickoff.js';
-/** Shared reshape machinery: rewrite kind and/or model tier — and, when the
- *  caller supplies them, mode/lifecycle — by rebuilding the launch spec so the
- *  change is durable across a future revive. MODE-PRESERVING by default (omit
- *  `mode`/`lifecycle` and the node's own current values carry through) — this
- *  is what a plain `crtr node yield --kind/--model` reshape rides, with no
- *  mode flip and no roadmap seeding. `promote()` below is a thin wrapper that
- *  also forces mode→orchestrator and seeds the roadmap. */
-export function reshapeNode(nodeId, opts = {}, beforePersist) {
+function reshapeInputs(nodeId, opts) {
     const node = getNode(nodeId);
     if (node === null)
         throw new Error(`unknown node: ${nodeId}`);
-    // The node may specialize as it reshapes; default to its current kind.
-    const targetKind = opts.kind ?? node.kind;
-    // ...and may raise/change its model tier; default to its current pin (so a
-    // reshape with no --model preserves whatever it was running on).
-    const targetModel = opts.model ?? node.model_override ?? undefined;
-    const targetMode = opts.mode ?? node.mode;
-    const targetLifecycle = opts.lifecycle ?? node.lifecycle;
-    const targetProfileId = opts.profileId === undefined ? node.profile_id : opts.profileId;
-    // Rewrite the launch spec to the target kind/mode's persona so the *next*
-    // revive comes back as this exact shape (polymorph stage 2). nodeEnv reads
-    // meta.{kind,mode}, so CRTR_KIND/CRTR_MODE flip immediately for the live
-    // process's children too.
-    const { launch } = buildLaunchSpec(targetKind, targetMode, {
-        lifecycle: targetLifecycle,
-        hasManager: node.parent !== null,
-        // A model tier chosen on this call (opts.model) overrides the persona
-        // default and is persisted below; absent one, the existing pin carries
-        // across the polymorph (the persona default is recomputed fresh for
-        // targetKind).
-        model: targetModel,
-        // opts.model given — an explicit new pick — lets buildLaunchSpec re-decide
-        // the pin from ITS raw shape (undefined here). No opts.model — targetModel
-        // just re-supplies the current value for resolution, not a new user
-        // choice — so carry the node's existing pin verbatim instead.
-        modelProviderPinned: opts.model === undefined ? node.launch?.modelProviderPinned : undefined,
-        modelIntent: opts.model === undefined ? node.launch?.modelIntent : undefined,
-        // Exact-model human-work forks must stay fail-closed after a polymorph.
-        // Dropping this bit produces a recipe reviveNode refuses to relaunch.
-        modelExact: opts.model === undefined ? node.launch?.modelExact : undefined,
-        // Resolve kind/ladder config against the NODE's own cwd + profile, not
-        // this process's ambient scope.
-        cwd: node.cwd,
-        profileId: targetProfileId,
-    });
-    // Promotion seeds after its target launch has been built but before the
-    // mutation is persisted, preserving the original promote() failure order.
+    const kind = opts.kind ?? node.kind;
+    const mode = opts.mode ?? node.mode;
+    const lifecycle = opts.lifecycle ?? node.lifecycle;
+    const profileId = opts.profileId === undefined ? node.profile_id ?? null : opts.profileId;
+    return {
+        node, kind, mode, lifecycle, profileId,
+        launchOpts: {
+            lifecycle, hasManager: node.parent !== null, model: opts.model ?? node.model_override ?? undefined,
+            modelProviderPinned: opts.model === undefined ? node.launch?.modelProviderPinned : undefined,
+            modelIntent: opts.model === undefined ? node.launch?.modelIntent : undefined,
+            modelExact: opts.model === undefined ? node.launch?.modelExact : undefined,
+            cwd: node.cwd, profileId,
+        },
+    };
+}
+function persistReshape(nodeId, opts, input, launch, beforePersist) {
     beforePersist?.();
-    // If the handle is still the spawn-time kind default (name === old kind),
-    // carry it to the new kind so the "name === kind ⇒ default, drop it" invariant
-    // in fullName() holds across a kind change. Otherwise a node spawned `general`
-    // (name="general") that reshapes to `plan` would surface a stale "general"
-    // handle in front of its real description.
-    const carriesDefaultHandle = node.name === node.kind && targetKind !== node.kind;
+    const carriesDefaultHandle = input.node.name === input.node.kind && input.kind !== input.node.kind;
     return updateNode(nodeId, {
-        kind: targetKind,
-        mode: targetMode,
-        lifecycle: targetLifecycle,
-        profile_id: targetProfileId,
-        launch,
-        ...(carriesDefaultHandle ? { name: targetKind } : {}),
-        // Persist a newly-chosen tier so it is durable across future revives; omit
-        // when unchanged so the existing pin (or persona default) stands.
+        kind: input.kind, mode: input.mode, lifecycle: input.lifecycle, profile_id: input.profileId, launch,
+        ...(carriesDefaultHandle ? { name: input.kind } : {}),
         ...(opts.model !== undefined ? { model_override: opts.model } : {}),
     });
 }
+/** Synchronous reshape for CLI callers outside the daemon. */
+export function reshapeNode(nodeId, opts = {}, beforePersist) {
+    const input = reshapeInputs(nodeId, opts);
+    return persistReshape(nodeId, opts, input, buildLaunchSpec(input.kind, input.mode, input.launchOpts).launch, beforePersist);
+}
+/** Daemon-safe reshape: network-backed config resolution happens off its event loop. */
+export async function reshapeNodeAsync(nodeId, opts = {}, beforePersist) {
+    const input = reshapeInputs(nodeId, opts);
+    const { launch } = await buildLaunchSpecAsync(input.kind, input.mode, input.launchOpts);
+    return persistReshape(nodeId, opts, input, launch, beforePersist);
+}
 /** Promote a node to an orchestrator (mode→orchestrator), optionally
  *  specializing its kind (e.g. a `general` worker becoming a
  *  `developer.orchestrator`) and optionally also making it resident. Idempotent:
@@ -129,6 +102,25 @@ export function promote(nodeId, opts = {}) {
         goalPath: goalPath(nodeId),
     };
 }
+/** Daemon-safe promotion variant; preserves the same validation/seed ordering. */
+export async function promoteAsync(nodeId, opts = {}) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    let roadmapWritten = false;
+    const meta = await reshapeNodeAsync(nodeId, {
+        ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+        ...(opts.model !== undefined ? { model: opts.model } : {}),
+        mode: 'orchestrator', lifecycle: opts.resident === true ? 'resident' : node.lifecycle,
+    }, () => {
+        if (!hasRoadmap(nodeId)) {
+            const goal = readGoal(nodeId);
+            seedRoadmap(nodeId, goal !== null && goal.trim() !== '' ? { goal: goal.trim() } : {});
+            roadmapWritten = true;
+        }
+    });
+    return { meta, roadmapWritten, roadmapPath: roadmapPath(nodeId), goalPath: goalPath(nodeId) };
+}
 /** Request a refresh-yield: discard in-memory context and revive fresh, mode
  *  and lifecycle UNCHANGED, against the roadmap if one exists else the
  *  original goal (`buildReviveKickoff` falls back to it). A plain yield is
@@ -138,6 +130,18 @@ export function promote(nodeId, opts = {}) {
  *  same path `crtr node promote` would — mode flips to orchestrator and a
  *  roadmap scaffold is seeded. Sets intent='refresh'; the stophook shuts the
  *  process down on the next stop and the daemon revives it fresh. */
+export async function requestYieldAsync(nodeId, opts = {}, deps = {}) {
+    const node = getNode(nodeId);
+    if (node === null)
+        throw new Error(`unknown node: ${nodeId}`);
+    if (opts.promote === true) {
+        await promoteAsync(nodeId, { ...(opts.kind !== undefined ? { kind: opts.kind } : {}), ...(opts.model !== undefined ? { model: opts.model } : {}) });
+    }
+    else if (opts.kind !== undefined || opts.model !== undefined) {
+        await reshapeNodeAsync(nodeId, { ...(opts.kind !== undefined ? { kind: opts.kind } : {}), ...(opts.model !== undefined ? { model: opts.model } : {}) });
+    }
+    return { ...requestYield(nodeId, {}, deps), promoted: opts.promote === true };
+}
 export function requestYield(nodeId, opts = {}, deps = {}) {
     const ensure = deps.ensure ?? ensureDaemon;
     const node = getNode(nodeId);

package/dist/core/runtime/recycle.js

@@ -21,7 +21,7 @@ import { getNode, setPresence, setFocusOccupant, fullName } from '../canvas/inde
 import { reportsDir } from '../canvas/paths.js';
 import { pushFinal } from '../feed/feed.js';
 import { spawnNode, rootOfSpine } from './nodes.js';
-import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { focusOf, respawnPaneSync, setPaneOption } from './placement.js';
 import { waitForBrokerViewSocket, viewerSplitEnv } from './placement-tmux.js';
 import { headlessBrokerHost } from './host.js';
@@ -102,7 +102,7 @@ export async function recycleNode(nodeId, callerPane) {
     // ambient scope) and carry the profile onto the fresh root — it is the same
     // person's seat, so profile-scope defaults (e.g. a persisted /model default)
     // must keep applying.
-    const { launch } = buildLaunchSpec('general', 'base', { lifecycle: 'resident', hasManager: false, cwd: meta.cwd, profileId: meta.profile_id });
+    const { launch } = await buildLaunchSpecAsync('general', 'base', { lifecycle: 'resident', hasManager: false, cwd: meta.cwd, profileId: meta.profile_id });
     const root = spawnNode({
         kind: 'general',
         mode: 'base',

package/dist/core/runtime/reset.js

@@ -25,7 +25,7 @@ import { transition } from './lifecycle.js';
 import { headlessBrokerHost } from './host.js';
 import { tearDownNode, focusOf, registerViewerFocus, respawnPaneSync, windowOfPane, renameWindow, } from './placement.js';
 import { viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
-import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { spawnNode, rootOfSpine } from './nodes.js';
 // ---------------------------------------------------------------------------
 // reapDescendants — tear down a root's descendant sub-DAG (shared helper)
@@ -83,7 +83,7 @@ export async function relaunchRoot(oldId, deps = {}) {
     // --- mint + boot the NEW broker FIRST (a failure here leaves the old root
     //     untouched) ---
     // A relaunched root is a fresh resident base, exactly like the front door.
-    const { launch } = buildLaunchSpec(old.kind, 'base', {
+    const { launch } = await buildLaunchSpecAsync(old.kind, 'base', {
         lifecycle: 'resident',
         hasManager: false,
         model: old.model_override ?? undefined,

package/dist/core/runtime/spawn.js

@@ -14,7 +14,7 @@ import { isAbsolute, resolve, join } from 'node:path';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId } from './nodes.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
 import { selectProfileForCwd } from '../profiles/select.js';
-import { buildLaunchSpec, buildPiArgv } from './launch.js';
+import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
 import { usage, brokerLaunchFailed } from '../errors.js';
 import { writeGoal } from './kickoff.js';
@@ -237,7 +237,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
     if (opts.nodeId !== undefined)
         preflightNodeId(opts.nodeId);
     const profileId = await resolveProfileId(opts.profile, spawner, opts.cwd);
-    const preflightLaunch = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: opts.cwd, profileId }).launch;
+    const preflightLaunch = (await buildLaunchSpecAsync(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: opts.cwd, profileId })).launch;
     await assertLaunchModelRegistered(requestFromLaunch(preflightLaunch), { cwd: opts.cwd, profileId });
     const forkFrom = opts.forkFrom !== undefined ? resolveForkSource(opts.forkFrom) : undefined;
     let managedWorktree;
@@ -255,7 +255,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // this process's ambient scope (a front-door shell has no CRTR_PROFILE_ID,
         // which silently hid every profile-scope kind override).
         const launch = wantsWorktree
-            ? buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: spawnCwd, profileId }).launch
+            ? (await buildLaunchSpecAsync(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model, cwd: spawnCwd, profileId })).launch
             : preflightLaunch;
         if (wantsWorktree) {
             await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd: spawnCwd, profileId });

package/dist/core/runtime/warm-pool.js

@@ -62,7 +62,7 @@ import { claimWarmSpare, deleteNode, getNode, listNodes, listWarmSpares, registe
 import { recordedPidLiveness } from '../canvas/pid.js';
 import { nowIso } from '../fs-utils.js';
 import { spawnChildPrepared } from './spawn.js';
-import { buildLaunchSpec } from './launch.js';
+import { buildLaunchSpecAsync } from './launch.js';
 import { setModelLive } from './model-swap.js';
 import { setSituationalContextLive } from './situational-live.js';
 import { deliverBearingsLive } from './deliver-live.js';
@@ -100,8 +100,8 @@ function warmRecipeKey(cwd, profileId, launch) {
 }
 /** Resolve a request's frozen half. Both cwd and profile arrive already
  *  resolved from the create handler, so this is pure launch-spec construction. */
-function resolveRecipe(request) {
-    const { launch } = buildLaunchSpec(request.kind, request.mode, {
+async function resolveRecipe(request) {
+    const { launch } = await buildLaunchSpecAsync(request.kind, request.mode, {
         lifecycle: 'resident',
         hasManager: false,
         ...(request.model !== null ? { model: request.model } : {}),
@@ -114,7 +114,7 @@ function resolveRecipe(request) {
  *  pool cannot serve it. The caller falls back to a cold spawn; a claim never
  *  fails the create. */
 export async function claimWarmNode(request) {
-    const recipe = resolveRecipe(request);
+    const recipe = await resolveRecipe(request);
     const created = nowIso();
     // The row's stamp moves inside the claim transaction; meta.json (the identity
     // source of truth `rebuildIndex` re-derives the row from) follows with the
@@ -261,7 +261,9 @@ export function refillWarmPool(request) {
         // Mint at the kind's DEFAULT model and with NO situational context: both
         // are claim-time properties, so baking either in would only narrow who the
         // spare can serve.
-        mint(resolveRecipe({ ...request, model: null, situationalContext: null }));
+        void resolveRecipe({ ...request, model: null, situationalContext: null })
+            .then(mint)
+            .catch((err) => console.error(`[warm-pool] recipe resolution failed: ${err.message}`));
     }
     catch (err) {
         console.error(`[warm-pool] recipe resolution failed: ${err.message}`);
@@ -349,7 +351,7 @@ export function prewarmRecentRecipes() {
             // `general`/`base` is only the shape the spare BOOTS as — the key it is
             // filed under excludes everything a claim can reshape, so any kind can
             // claim it.
-            mint(resolveRecipe({
+            void resolveRecipe({
                 kind: 'general',
                 mode: 'base',
                 cwd: candidate.cwd,
@@ -357,7 +359,7 @@ export function prewarmRecentRecipes() {
                 model: null,
                 situationalContext: null,
                 name: null,
-            }));
+            }).then(mint).catch((err) => console.error(`[warm-pool] prewarm failed for ${candidate.cwd}: ${err.message}`));
         }
         catch (err) {
             console.error(`[warm-pool] prewarm failed for ${candidate.cwd}: ${err.message}`);

package/dist/core/substrate/frontmatter-validation.d.ts

@@ -0,0 +1,13 @@
+/** Strict validation of one raw routing entry. Runtime parsing deliberately
+ * tolerates malformed docs; this authoring/preflight contract does not. */
+export declare function lintSubstrateSurfaces(value: unknown): string | null;
+/** Strict substrate frontmatter checker shared by lint and package preflight. */
+export declare function lintSubstrateFrontmatter(fm: Record<string, unknown> | null): string | null;
+/** Compatibility name for consumers that adopted lint's former export. */
+export declare const lintSubstrateSchema: typeof lintSubstrateFrontmatter;
+/** Parsed routing entries for checks that run after strict validation. */
+export declare function parsedSubstrateSurfaces(fm: Record<string, unknown>): {
+    on: string;
+    at: string;
+    match?: string[];
+}[];

package/dist/core/substrate/frontmatter-validation.js

@@ -0,0 +1,101 @@
+import { isDocKind, parseSubstrateFrontmatter, SURFACE_EVENTS, SURFACE_RUNGS } from './schema.js';
+const RETIRED_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
+const SURFACE_ENTRY_KEYS = ['on', 'match', 'match-frontmatter', 'at'];
+const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read'];
+/** Strict validation of one raw routing entry. Runtime parsing deliberately
+ * tolerates malformed docs; this authoring/preflight contract does not. */
+export function lintSubstrateSurfaces(value) {
+    if (value === undefined)
+        return null;
+    if (!Array.isArray(value))
+        return `invalid surfaces: ${JSON.stringify(value)} (expected a list of {on, at, match?, match-frontmatter?} entries)`;
+    for (const raw of value) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            return `invalid surfaces entry: ${JSON.stringify(raw)} (expected an {on, at, match?, match-frontmatter?} object)`;
+        }
+        const entry = raw;
+        for (const key of Object.keys(entry)) {
+            if (!SURFACE_ENTRY_KEYS.includes(key)) {
+                return `invalid surfaces entry: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, at)`;
+            }
+        }
+        const on = entry['on'];
+        if (typeof on !== 'string' || !SURFACE_EVENTS.includes(on)) {
+            return `invalid surfaces entry \`on\`: ${JSON.stringify(on)} (expected ${SURFACE_EVENTS.join('|')})`;
+        }
+        const at = entry['at'];
+        if (typeof at !== 'string' || !SURFACE_RUNGS.includes(at)) {
+            return `invalid surfaces entry \`at\`: ${JSON.stringify(at)} (expected ${SURFACE_RUNGS.join('|')})`;
+        }
+        let hasMatch = false;
+        if (entry['match'] !== undefined) {
+            if (on === 'boot' || on === 'workspace-open') {
+                return `invalid surfaces entry: \`match\` is meaningless on \`${on}\` — the entry's presence is the match; drop it`;
+            }
+            const match = entry['match'];
+            const globs = typeof match === 'string' ? [match] : Array.isArray(match) && match.every((glob) => typeof glob === 'string') ? match : null;
+            if (globs === null || globs.length === 0 || globs.some((glob) => glob.trim() === '')) {
+                return `invalid surfaces entry \`match\`: ${JSON.stringify(match)} (expected a non-empty glob or non-empty glob list)`;
+            }
+            hasMatch = true;
+        }
+        const matchFrontmatter = entry['match-frontmatter'];
+        if (matchFrontmatter !== undefined) {
+            if (on !== 'read')
+                return 'invalid surfaces entry: `match-frontmatter` is a `read`-event predicate only';
+            if (matchFrontmatter === null || typeof matchFrontmatter !== 'object' || Array.isArray(matchFrontmatter)) {
+                return `invalid surfaces entry \`match-frontmatter\`: ${JSON.stringify(matchFrontmatter)} (expected a field→matcher object)`;
+            }
+        }
+        if ((on === 'read' || on === 'memory-read' || on === 'command') && !hasMatch && matchFrontmatter === undefined) {
+            return `invalid surfaces entry: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`;
+        }
+    }
+    return null;
+}
+/** Strict substrate frontmatter checker shared by lint and package preflight. */
+export function lintSubstrateFrontmatter(fm) {
+    if (fm === null)
+        return 'missing frontmatter: a memory store doc requires `kind: knowledge|preference`';
+    if (!isDocKind(fm.kind))
+        return `invalid kind: ${JSON.stringify(fm.kind)} (expected knowledge|preference)`;
+    if ('when' in fm || 'why' in fm) {
+        return 'retired `when`/`why` keys: merge them into one `when-and-why-to-read` line — "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the benefit unlocked by reading, not the document summary, rule, or obedience rationale.';
+    }
+    if (typeof fm['when-and-why-to-read'] !== 'string' || fm['when-and-why-to-read'].trim() === '') {
+        return 'missing `when-and-why-to-read`: one routing line — "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the benefit unlocked by reading, not the document summary, rule, or obedience rationale.';
+    }
+    for (const field of RETIRED_FIELDS) {
+        if (field in fm) {
+            return `retired \`${field}\` key: the visibility axes were replaced by \`surfaces\` event routing — run \`crtr sys migrate\` to convert old-format docs, or author \`surfaces\` entries by hand (\`crtr memory write -h\`)`;
+        }
+    }
+    if (fm['unlisted'] !== undefined && typeof fm['unlisted'] !== 'boolean') {
+        return `invalid unlisted: ${JSON.stringify(fm['unlisted'])} (expected a boolean)`;
+    }
+    const surfacesError = lintSubstrateSurfaces(fm['surfaces']);
+    if (surfacesError !== null)
+        return surfacesError;
+    if (fm.gate !== undefined && (fm.gate === null || typeof fm.gate !== 'object' || Array.isArray(fm.gate))) {
+        return `invalid gate: ${JSON.stringify(fm.gate)} (expected a field→matcher object)`;
+    }
+    if (fm.slash !== undefined && typeof fm.slash !== 'boolean') {
+        return `invalid slash: ${JSON.stringify(fm.slash)} (expected a boolean)`;
+    }
+    if (fm.rationale !== undefined && typeof fm.rationale !== 'string') {
+        return `invalid rationale: ${JSON.stringify(fm.rationale)} (expected a string)`;
+    }
+    if (fm['lint-ignore'] !== undefined) {
+        const rules = Array.isArray(fm['lint-ignore']) ? fm['lint-ignore'] : [fm['lint-ignore']];
+        if (rules.length === 0 || !rules.every((rule) => typeof rule === 'string' && SUPPRESSIBLE_RULES.includes(rule))) {
+            return `invalid lint-ignore: ${JSON.stringify(fm['lint-ignore'])} (suppressible rules: ${SUPPRESSIBLE_RULES.map((rule) => `\`${rule}\``).join(', ')})`;
+        }
+    }
+    return null;
+}
+/** Compatibility name for consumers that adopted lint's former export. */
+export const lintSubstrateSchema = lintSubstrateFrontmatter;
+/** Parsed routing entries for checks that run after strict validation. */
+export function parsedSubstrateSurfaces(fm) {
+    return parseSubstrateFrontmatter(fm)?.surfaces ?? [];
+}

package/dist/core/substrate/index.d.ts

@@ -1,5 +1,6 @@
 export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, SURFACE_EVENTS, SURFACE_RUNGS, bootRung, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, resolveDocName, } from './schema.js';
 export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc, SurfaceEntry, SurfaceEvent, SurfaceRung } from './schema.js';
+export { lintSubstrateFrontmatter, lintSubstrateSchema, lintSubstrateSurfaces, parsedSubstrateSurfaces } from './frontmatter-validation.js';
 export { matchesReadEntry, matchesMemoryReadEntry, matchesCommandEntry, readDeliveryRung, workspaceOpenRung, memoryReadDeliveryRung, commandDeliveryRung, owningRootOf, underOwningRoot } from './surface-match.js';
 export { dirDedupKey, docsByName, isDirName, ancestorDirsOf, renderDirListing } from './listings.js';
 export { deliveredAtOrAbove, recordDelivery, mergeInjectedDocs } from './injected-store.js';

package/dist/core/substrate/index.js

@@ -16,6 +16,7 @@ parseSubstrateFrontmatter, parseSubstrateDoc, previewLine,
 normalizeNameSegment, normalizeDocName, 
 // substrate identity (explicit-name-then-path-fallback)
 resolveDocName, } from './schema.js';
+export { lintSubstrateFrontmatter, lintSubstrateSchema, lintSubstrateSurfaces, parsedSubstrateSurfaces } from './frontmatter-validation.js';
 export { matchesReadEntry, matchesMemoryReadEntry, matchesCommandEntry, readDeliveryRung, workspaceOpenRung, memoryReadDeliveryRung, commandDeliveryRung, owningRootOf, underOwningRoot } from './surface-match.js';
 export { dirDedupKey, docsByName, isDirName, ancestorDirsOf, renderDirListing } from './listings.js';
 export { deliveredAtOrAbove, recordDelivery, mergeInjectedDocs } from './injected-store.js';

package/dist/daemon/api/__tests__/bridge-heartbeat.test.d.ts

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

package/dist/daemon/api/__tests__/bridge-heartbeat.test.js

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import test from 'node:test';
+import { startRemoteAttachHeartbeat } from '../bridge.js';
+class FakeSocket extends EventEmitter {
+    pings = 0;
+    terminated = 0;
+    ping() { this.pings += 1; }
+    terminate() { this.terminated += 1; }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+test('remote attach heartbeat pings an idle viewer and keeps a ponging observer alive', async () => {
+    const ws = new FakeSocket();
+    const stop = startRemoteAttachHeartbeat(ws, 20);
+    await sleep(25);
+    assert.equal(ws.pings, 1, 'an idle attach receives a WebSocket ping before proxy idle timeout');
+    ws.emit('pong');
+    await sleep(10);
+    assert.equal(ws.terminated, 0, 'a pong renews the heartbeat without terminating the observer');
+    stop();
+});
+test('remote attach heartbeat drops only an unresponsive observer socket', async () => {
+    const ws = new FakeSocket();
+    const stop = startRemoteAttachHeartbeat(ws, 5);
+    await sleep(16);
+    assert.equal(ws.terminated, 1, 'two missed heartbeat intervals terminate the detached viewer');
+    stop();
+});

package/dist/daemon/api/__tests__/nodes-activity-query.test.d.ts

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

package/dist/daemon/api/__tests__/nodes-activity-query.test.js

@@ -0,0 +1,101 @@
+import { after, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode } from '../../../core/canvas/canvas.js';
+import { closeDb } from '../../../core/canvas/db.js';
+import { reportsDir } from '../../../core/canvas/paths.js';
+import { invalidateTicketCounts } from '../../../core/canvas/attention.js';
+import { bindTicketReplyRoute } from '../../../core/human/convention.js';
+import { ticketDir } from '../../../core/human/root.js';
+import { submitPage } from '../../../core/human/tickets.js';
+import { handleList } from '../handlers/nodes.js';
+const previousCrtrHome = process.env['CRTR_HOME'];
+let home = '';
+before(() => {
+    closeDb();
+    home = mkdtempSync(join(tmpdir(), 'crtr-nodes-activity-query-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    invalidateTicketCounts();
+    rmSync(home, { recursive: true, force: true });
+    mkdirSync(home, { recursive: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    if (previousCrtrHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = previousCrtrHome;
+});
+function node(id, overrides = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: '2026-08-17T00:00:00.000Z',
+        cwd: home,
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent: null,
+        profile_id: 'activity-profile-7f3a9c01',
+        launch: { model: 'anthropic/original', extensions: [], env: {} },
+        ...overrides,
+    };
+}
+function list(query) {
+    const result = handleList({
+        method: 'GET',
+        path: '/v1/nodes',
+        params: {},
+        query: new URLSearchParams(query),
+        body: null,
+    });
+    assert.equal(result.status, 200);
+    return result.body;
+}
+function report(nodeId, stamp, tier, body) {
+    const filename = `${stamp}-${tier}.md`;
+    writeFileSync(join(reportsDir(nodeId), filename), `---\nkind: ${tier}\nts: ${stamp}\n---\n${body}\n`);
+    return filename;
+}
+test('list activity query composes profile, lifecycle, topology filters and report enrichment', () => {
+    const finalName = '20260817T100000-final.md';
+    createNode(node('root', {
+        status: 'done',
+        final_report: finalName,
+        finalized_at: '2026-08-17T10:00:00.000Z',
+    }));
+    report('root', '20260817T090000', 'update', 'Started the task');
+    report('root', '20260817T100000', 'final', 'Finished the task');
+    report('root', '20260817T110000', 'update', 'Still monitoring the task');
+    createNode(node('bridge', { kind: 'human', parent: 'root' }));
+    const page = join(home, 'pending-page.tsx');
+    writeFileSync(page, `export default function PendingPage() {
+  return <Page title="Need a decision"><UserText id="answer" initialText="" /></Page>;
+}
+`);
+    const ticket = submitPage({
+        dir: ticketDir('bridge'),
+        sourceFile: page,
+        delivery: { placement: 'inline', inbox: true, reply: true },
+    });
+    bindTicketReplyRoute(ticket.dir, 'bridge');
+    invalidateTicketCounts();
+    createNode(node('child', { parent: 'root' }));
+    createNode(node('resident', { lifecycle: 'resident' }));
+    createNode(node('other-profile', { profile_id: 'other-profile-7f3a9c01' }));
+    const roots = list('profile_prefix=activity-profile-&lifecycle=terminal&top_level=true&include=activity');
+    assert.deepEqual(roots.map((row) => row.node_id), ['root']);
+    assert.equal(roots[0].activity?.final_report?.body, 'Finished the task');
+    assert.equal(roots[0].activity?.latest_report?.body, 'Still monitoring the task');
+    assert.equal(roots[0].activity?.pending_human_count, 1);
+    const children = list('profile_id=activity-profile-7f3a9c01&parent=root');
+    assert.deepEqual(children.map((row) => row.node_id), ['bridge', 'child']);
+    assert.equal(children[1].activity, undefined);
+});

package/dist/daemon/api/__tests__/seam/api-server.test.js

@@ -169,6 +169,36 @@ test('A4a: WS attach welcome.snapshot is byte-identical to a direct ViewSocketCl
     assert.equal(JSON.stringify(wsWelcome.snapshot), JSON.stringify(direct.welcome.snapshot), 'WS welcome.snapshot is byte-identical to the direct ViewSocketClient snapshot');
     direct.close();
 });
+test('A4a regression: reconnecting an observer keeps the live broker instance', async () => {
+    const root = h.spawnRoot('a4 reconnect root');
+    const id = (await client.createNode({ kind: 'developer', parent: root, prompt: 'a4 reconnect worker' })).node_id;
+    await h.awaitBoot(id);
+    const pid = h.node(id)?.pi_pid;
+    const boots = h.bootCount(id);
+    const attachOnce = () => new Promise((resolveAttach, rejectAttach) => {
+        const ws = new WebSocket(`ws+unix://${sockPath}:/v1/nodes/${id}/attach`);
+        const timer = setTimeout(() => {
+            ws.terminate();
+            rejectAttach(new Error('timed out waiting for observer welcome'));
+        }, 15_000);
+        ws.on('open', () => ws.send(JSON.stringify({ type: 'hello', role: 'observer', client_id: `a4-reconnect-${Math.random()}` })));
+        ws.on('message', (data) => {
+            if (JSON.parse(data.toString('utf8'))['type'] !== 'welcome')
+                return;
+            clearTimeout(timer);
+            ws.close();
+            resolveAttach();
+        });
+        ws.on('error', (error) => {
+            clearTimeout(timer);
+            rejectAttach(error);
+        });
+    });
+    await attachOnce();
+    await attachOnce();
+    assert.equal(h.bootCount(id), boots, 'observer reconnect did not relaunch the broker');
+    assert.equal(h.node(id)?.pi_pid, pid, 'the in-flight broker instance was retained');
+});
 test('A4b: ?revive=0 on a dormant node refuses 409 without launching a broker', async () => {
     const root = h.spawnRoot('a4b root');
     // A dormant row: no live broker, no pi_pid, view.sock absent.

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

@@ -1,5 +1,11 @@
 import type { IncomingMessage } from 'node:http';
 import type { Duplex } from 'node:stream';
+import { type WebSocket } from 'ws';
+/** Keep an otherwise quiet observer connection alive through common 60s proxy
+ * idle limits. A viewer only observes a broker, so a missed heartbeat may close
+ * this socket but must never affect the broker or its in-flight work. */
+export declare const REMOTE_ATTACH_HEARTBEAT_MS = 25000;
+export declare function startRemoteAttachHeartbeat(ws: WebSocket, intervalMs?: number): () => void;
 /** Handle the HTTP upgrade for `GET /v1/nodes/{id}/attach`. A-9 matches the
  *  route, extracts `{id}`, and calls this with the raw upgrade triplet; this
  *  owns the WS handshake (its own noServer `wss` above) AND the spec §5.3