@crouton-kit/crouter 0.3.36 → 0.3.38

package/dist/core/profiles/manifest.js

@@ -0,0 +1,332 @@
+// The profile store: `~/.crouter/profiles/<slug>-<id>/` — a manifest
+// (`profile.json`) naming N project directories, plus the profile's own
+// `memory/` store (spec §2.1). This module is the SOLE place that resolves a
+// profile id/name to a path and writes/mutates a manifest: every join against
+// the canonical profiles root goes through the id-shape + containment checks
+// here, so no caller ever passes a raw CLI operand or `CRTR_PROFILE_ID`
+// straight into `join(profilesRoot(), value)`.
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, join, resolve as resolvePath, sep } from 'node:path';
+import { SCHEMA_VERSION, PROFILE_DIR } from '../../types.js';
+import { userScopeRoot, resetScopeCache } from '../scope.js';
+import { ensureDir, nowIso } from '../fs-utils.js';
+import { usage, notFound, ambiguous, general } from '../errors.js';
+// ---------------------------------------------------------------------------
+// Path safety — the only code in the tree that builds a path under the
+// profiles root. Every other module reaches profile paths through this file.
+// ---------------------------------------------------------------------------
+/** `<slug>-<shortid>`: slug is lower-case, non-alphanumeric collapsed to `-`,
+ *  trimmed to 40 chars (defaulting to `profile`); shortid is 8 lowercase hex
+ *  chars. The char class alone rules out `/`, `\`, `.`, and `..` segments —
+ *  this is the "generated id shape" check every exact-id lookup requires. */
+const ID_SHAPE = /^[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}$/;
+export function profilesRoot() {
+    return join(userScopeRoot(), PROFILE_DIR);
+}
+function assertSafeProfileId(profileId) {
+    if (!ID_SHAPE.test(profileId)) {
+        throw usage(`invalid profile id: ${profileId}`, {
+            received: profileId,
+            next: 'Profile ids look like <slug>-<8-hex-chars> (as printed by `crtr profile new`). Pass an exact id or a profile name, not a raw path.',
+        });
+    }
+}
+/** Before any read/write/lock/delete: the resolved target must live INSIDE
+ *  the canonical profiles root, even after symlink resolution. Every caller
+ *  below reaches this only via `profileRoot`, which already ran
+ *  `assertSafeProfileId` first — this is defense-in-depth, not the primary
+ *  guard, and is what makes an unexpected symlink under a profile dir inert. */
+function assertInsideProfilesRoot(path) {
+    const root = profilesRoot();
+    const resolvedRoot = existsSync(root) ? realpathSync(root) : resolvePath(root);
+    const resolvedPath = existsSync(path) ? realpathSync(path) : resolvePath(path);
+    if (resolvedPath !== resolvedRoot && !resolvedPath.startsWith(resolvedRoot + sep)) {
+        throw usage(`profile path escapes the profiles root: ${path}`);
+    }
+}
+export function profileRoot(profileId) {
+    assertSafeProfileId(profileId);
+    const root = join(profilesRoot(), profileId);
+    assertInsideProfilesRoot(root);
+    return root;
+}
+export function profileManifestPath(profileId) {
+    return join(profileRoot(profileId), 'profile.json');
+}
+export function profileMemoryDir(profileId) {
+    return join(profileRoot(profileId), 'memory');
+}
+// ---------------------------------------------------------------------------
+// Enumeration + resolution — the ONLY functions that turn a CLI operand into
+// a profile id. Both walk immediate children of the canonical root; neither
+// ever joins an unvalidated operand into a path.
+// ---------------------------------------------------------------------------
+function readManifestFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Every profile with a readable manifest, in directory-listing order.
+ *  Enumerates ONLY immediate children of `profilesRoot()` — never recurses,
+ *  never trusts a caller-supplied id. A dir whose name doesn't match the
+ *  generated id shape, or whose `profile.json` is missing/corrupt, is skipped
+ *  rather than crashing the whole listing. */
+export function listProfiles() {
+    const root = profilesRoot();
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const dirent of readdirSync(root, { withFileTypes: true })) {
+        if (!dirent.isDirectory())
+            continue;
+        const profileId = dirent.name;
+        if (!ID_SHAPE.test(profileId))
+            continue;
+        const manifest = readManifestFile(join(root, profileId, 'profile.json'));
+        if (manifest === null)
+            continue;
+        out.push({ profileId, manifest });
+    }
+    return out;
+}
+/** Resolve a CLI operand to its profile — exact id first (checked against the
+ *  actually-enumerated dirs, never a blind join), then a unique manifest
+ *  `name` match. Ambiguous names fail listing every matching id; no match
+ *  fails naming `profile list`/`profile new` as recovery. This is the ONLY
+ *  function every command leaf and future runtime consumer (Phase 5/6) should
+ *  call to turn a `<profile>` operand or `CRTR_PROFILE_ID` into a concrete,
+ *  safe profile id. */
+export function loadProfileManifest(profileIdOrName) {
+    const all = listProfiles();
+    if (ID_SHAPE.test(profileIdOrName)) {
+        const byId = all.find((p) => p.profileId === profileIdOrName);
+        if (byId !== undefined)
+            return byId;
+    }
+    const byName = all.filter((p) => p.manifest.name === profileIdOrName);
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        const ids = byName.map((p) => p.profileId);
+        throw ambiguous(`profile name "${profileIdOrName}" matches ${ids.length} profiles: ${ids.join(', ')}`, {
+            received: profileIdOrName,
+            candidates: ids,
+            next: `Re-run with one exact profile id: ${ids.join(', ')}.`,
+        });
+    }
+    throw notFound(`profile not found: ${profileIdOrName}`, {
+        received: profileIdOrName,
+        next: 'Run `crtr profile list` to see available profiles, or `crtr profile new --name <name>` to create one.',
+    });
+}
+// ---------------------------------------------------------------------------
+// Locking — a plain mkdir-based mutex under `profilesRoot()/.locks/`. mkdir is
+// atomic (EEXIST when already held), so this needs no extra dependency. The
+// blocking wait uses Atomics.wait on a throwaway SharedArrayBuffer to stay
+// synchronous, matching every other sync fs call in this module.
+// ---------------------------------------------------------------------------
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_POLL_MS = 25;
+function locksDir() {
+    return join(profilesRoot(), '.locks');
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
+ *  mutations (create/rename/add-project/remove-project/delete/last-used)
+ *  below run inside this. */
+export function withProfileManifestLock(profileId, fn) {
+    assertSafeProfileId(profileId);
+    ensureDir(locksDir());
+    const lockPath = join(locksDir(), `${profileId}.lock`);
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            mkdirSync(lockPath);
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (Date.now() > deadline) {
+                throw general(`timed out waiting for the profile lock: ${profileId}`, {
+                    next: 'Retry — another `crtr profile` command may be running concurrently on this profile.',
+                });
+            }
+            sleepSync(LOCK_POLL_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            rmSync(lockPath, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort release */
+        }
+    }
+}
+function writeManifestAtomic(path, manifest) {
+    ensureDir(dirname(path));
+    const tmp = `${path}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    renameSync(tmp, path);
+}
+// ---------------------------------------------------------------------------
+// Project dirs — resolved to absolute real paths, must exist + be a directory
+// on add/create, deduped by real path, stored in manifest order.
+// ---------------------------------------------------------------------------
+function resolveExistingProjectDir(dir) {
+    const abs = resolvePath(dir);
+    if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+        throw usage(`project directory does not exist or is not a directory: ${dir}`, {
+            received: dir,
+            next: 'Pass an existing directory path.',
+        });
+    }
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+function dedupeOrdered(values) {
+    const seen = new Set();
+    const out = [];
+    for (const v of values) {
+        if (seen.has(v))
+            continue;
+        seen.add(v);
+        out.push(v);
+    }
+    return out;
+}
+function slugify(name) {
+    let slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    if (slug.length > 40)
+        slug = slug.slice(0, 40).replace(/-+$/g, '');
+    return slug.length > 0 ? slug : 'profile';
+}
+function generateProfileId(name) {
+    const slug = slugify(name);
+    const root = profilesRoot();
+    for (let attempt = 0; attempt < 20; attempt++) {
+        const shortId = randomUUID().replace(/-/g, '').slice(0, 8);
+        const candidate = `${slug}-${shortId}`;
+        if (!existsSync(join(root, candidate)))
+            return candidate;
+    }
+    throw general(`failed to generate a unique profile id for "${name}" after 20 attempts`);
+}
+// ---------------------------------------------------------------------------
+// Mutations — all under withProfileManifestLock, all atomic writes, all call
+// resetScopeCache() when they can change project dirs or the profile name
+// (never for a bare last-used-at touch).
+// ---------------------------------------------------------------------------
+export function createProfile(name, projects = []) {
+    const trimmed = name.trim();
+    if (trimmed === '')
+        throw usage('profile name must not be empty');
+    const resolvedProjects = dedupeOrdered(projects.map(resolveExistingProjectDir));
+    const profileId = generateProfileId(trimmed);
+    return withProfileManifestLock(profileId, () => {
+        const root = profileRoot(profileId);
+        ensureDir(root);
+        ensureDir(join(root, 'memory'));
+        const manifest = {
+            schema_version: SCHEMA_VERSION,
+            name: trimmed,
+            projects: resolvedProjects,
+            created_at: nowIso(),
+            last_used_at: null,
+        };
+        writeManifestAtomic(profileManifestPath(profileId), manifest);
+        resetScopeCache();
+        return { profileId, manifest };
+    });
+}
+function requireExistingProfile(profileId) {
+    assertSafeProfileId(profileId);
+    if (!existsSync(profileManifestPath(profileId))) {
+        throw notFound(`profile not found: ${profileId}`, {
+            received: profileId,
+            next: 'Run `crtr profile list` to see available profiles.',
+        });
+    }
+}
+function mutateManifest(profileId, mutate) {
+    requireExistingProfile(profileId);
+    return withProfileManifestLock(profileId, () => {
+        const path = profileManifestPath(profileId);
+        const current = readManifestFile(path);
+        if (current === null) {
+            throw notFound(`profile not found: ${profileId}`, { received: profileId });
+        }
+        const next = mutate(current);
+        writeManifestAtomic(path, next);
+        return { profileId, manifest: next };
+    });
+}
+export function updateProfileLastUsed(profileId) {
+    return mutateManifest(profileId, (m) => ({ ...m, last_used_at: nowIso() }));
+}
+export function renameProfile(profileId, name) {
+    const trimmed = name.trim();
+    if (trimmed === '')
+        throw usage('profile name must not be empty');
+    const result = mutateManifest(profileId, (m) => ({ ...m, name: trimmed }));
+    resetScopeCache();
+    return result;
+}
+export function addProfileProject(profileId, dir) {
+    const resolved = resolveExistingProjectDir(dir);
+    const result = mutateManifest(profileId, (m) => ({
+        ...m,
+        projects: dedupeOrdered([...m.projects, resolved]),
+    }));
+    resetScopeCache();
+    return result;
+}
+export function removeProfileProject(profileId, dir) {
+    // Lenient resolution: a project dir may have been deleted since it was
+    // added, so removal must not require it to still exist on disk. Compare
+    // against both its real path (if still resolvable) and its plain resolved
+    // path (how it would have been stored had it never been a symlink).
+    const abs = resolvePath(dir);
+    let real = abs;
+    try {
+        real = realpathSync(abs);
+    }
+    catch {
+        /* dir no longer exists — fall back to comparing by its resolved path */
+    }
+    const result = mutateManifest(profileId, (m) => {
+        const filtered = m.projects.filter((p) => p !== real && p !== abs);
+        if (filtered.length === m.projects.length) {
+            throw notFound(`project not found on profile: ${dir}`, {
+                received: dir,
+                next: `Current projects: ${m.projects.length > 0 ? m.projects.join(', ') : '(none)'}.`,
+            });
+        }
+        return { ...m, projects: filtered };
+    });
+    resetScopeCache();
+    return result;
+}
+export function deleteProfile(profileId) {
+    requireExistingProfile(profileId);
+    withProfileManifestLock(profileId, () => {
+        rmSync(profileRoot(profileId), { recursive: true, force: true });
+    });
+    resetScopeCache();
+}

package/dist/core/profiles/select.d.ts

@@ -0,0 +1,11 @@
+/** Select the profile a node about to boot at `cwd` should run under.
+ *
+ *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`,
+ *     bump `last_used_at`, return the id.
+ *  2. Else, among profiles whose project list COVERS `cwd`, pick the
+ *     most-recently-used (nulls oldest), bump its `last_used_at`, return it.
+ *  3. Else — nothing covers cwd. Interactive session: prompt synchronously to
+ *     create a profile here or proceed as root, BEFORE pi boots. Non-
+ *     interactive (no TTY): default to root (null) and print the recovery
+ *     instruction to STDERR — never stdout, which the caller may be piping. */
+export declare function selectProfileForCwd(cwd: string, explicitProfile?: string | null): Promise<string | null>;

package/dist/core/profiles/select.js

@@ -0,0 +1,115 @@
+// Startup profile selection — the CTO-decided order applied at the front door
+// and at any non-inherited `crtr node new`: explicit `--profile` > MRU profile
+// covering cwd > synchronous create-or-root decision. This is the ONLY place
+// that decision runs; front-door.ts/spawn.ts call it, never re-derive it.
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, resolve as resolvePath, sep } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, } from './manifest.js';
+/** Resolve cwd to an absolute, realpath'd form so it compares against the
+ *  realpath'd project dirs `createProfile`/`addProfileProject` already store
+ *  (manifest.ts resolves every project dir through `realpathSync`). Falls back
+ *  to the plain resolved path when the dir can't be stat'd (mirrors
+ *  `resolveExistingProjectDir`'s own fallback). */
+function resolveCwd(cwd) {
+    const abs = resolvePath(cwd);
+    if (!existsSync(abs))
+        return abs;
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** A project dir "covers" cwd when cwd sits at or below it, OR — the
+ *  workspace-root case — the project dir itself sits below cwd (a profile can
+ *  point at one project nested under a wider workspace cwd). */
+function projectCovers(cwd, project) {
+    if (cwd === project)
+        return true;
+    if (cwd.startsWith(project + sep))
+        return true;
+    if (project.startsWith(cwd + sep))
+        return true;
+    return false;
+}
+function profileCoversCwd(entry, cwd) {
+    return entry.manifest.projects.some((p) => projectCovers(cwd, p));
+}
+/** `a` more recent than `b`, treating null as the oldest possible value (never
+ *  wins over a real timestamp). ISO 8601 strings compare correctly lexically. */
+function isMoreRecent(a, b) {
+    if (a === null)
+        return false;
+    if (b === null)
+        return true;
+    return a > b;
+}
+function pickMostRecent(entries) {
+    return entries.reduce((best, cur) => isMoreRecent(cur.manifest.last_used_at, best.manifest.last_used_at) ? cur : best);
+}
+function isInteractive() {
+    return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}
+function recoveryMessage(cwd) {
+    return (`crtr: no profile covers ${cwd}, and this session is non-interactive — starting without a profile (root).\n` +
+        `Run \`crtr profile new --name <name> --project ${cwd}\` to create one, or pass --profile <id-or-name> next time.\n`);
+}
+/** The one synchronous (pre-boot) decision point: no profile covers cwd, and
+ *  the session IS interactive. Ask on the controlling terminal — create a
+ *  profile pointing at cwd, or proceed as root — and block until answered.
+ *  Deliberately a minimal `readline` prompt, not `crtr human ask`: that bridge
+ *  is asynchronous (writes a deck, waits for a separate process to answer it)
+ *  and cannot gate pi's boot; the codebase's other humanloop entry points
+ *  (`launchReview`, the `human _run` bridge) are built for reviewing an
+ *  artifact or a queued interaction, not a two-choice gate on the same TTY pi
+ *  is about to take over — a raw `readline` question is the actual minimal
+ *  fit here. */
+async function promptCreateOrRoot(cwd) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        process.stdout.write(`\nNo profile covers this directory:\n  ${cwd}\n\n`);
+        const choice = (await rl.question('Create a profile here, or run as root? [c]reate / [r]oot: '))
+            .trim()
+            .toLowerCase();
+        if (choice !== 'c' && choice !== 'create')
+            return null;
+        const defaultName = basename(cwd) || 'profile';
+        const nameInput = (await rl.question(`Profile name [${defaultName}]: `)).trim();
+        const name = nameInput !== '' ? nameInput : defaultName;
+        return createProfile(name, [cwd]).profileId;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Select the profile a node about to boot at `cwd` should run under.
+ *
+ *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`,
+ *     bump `last_used_at`, return the id.
+ *  2. Else, among profiles whose project list COVERS `cwd`, pick the
+ *     most-recently-used (nulls oldest), bump its `last_used_at`, return it.
+ *  3. Else — nothing covers cwd. Interactive session: prompt synchronously to
+ *     create a profile here or proceed as root, BEFORE pi boots. Non-
+ *     interactive (no TTY): default to root (null) and print the recovery
+ *     instruction to STDERR — never stdout, which the caller may be piping. */
+export async function selectProfileForCwd(cwd, explicitProfile) {
+    if (explicitProfile !== undefined && explicitProfile !== null && explicitProfile !== '') {
+        const entry = loadProfileManifest(explicitProfile);
+        updateProfileLastUsed(entry.profileId);
+        return entry.profileId;
+    }
+    const resolvedCwd = resolveCwd(cwd);
+    const covering = listProfiles().filter((p) => profileCoversCwd(p, resolvedCwd));
+    if (covering.length > 0) {
+        const winner = pickMostRecent(covering);
+        updateProfileLastUsed(winner.profileId);
+        return winner.profileId;
+    }
+    if (!isInteractive()) {
+        process.stderr.write(recoveryMessage(resolvedCwd));
+        return null;
+    }
+    return await promptCreateOrRoot(resolvedCwd);
+}

package/dist/core/render.js

@@ -6,7 +6,7 @@
 // The raw JSON object is still available behind the `--json` global for tooling.
 //
 // A leaf may hand `defineLeaf` a bespoke `render(result)` for instruction-shaped
-// output that leads with the outcome (see `node new`, `push`, `feed read`).
+// output that leads with the outcome (see `node new`, `push`).
 // Everything else falls through to the schema-driven generic renderer here, so
 // every command obeys the markdown paradigm without a hand-written renderer.
 // `renderError` is the one sanctioned exception: a failure is a different domain

package/dist/core/runtime/bearings.d.ts

@@ -9,6 +9,15 @@ export declare function buildProjectContextBlock(cwd: string): string;
  *  Present for every node, rendered as the `## Your context directory`
  *  subsection of <crtr-bearings>. */
 export declare function contextDirNote(nodeId: string): string;
+/** The profile-purview note — rendered ONLY when `profile_id` resolves to a
+ *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd
+ *  replacement: the node's cwd is still its one working dir (bash/edits run
+ *  there), the profile just widens what it may ALSO read/act on. Omitted
+ *  entirely for a root/no-profile node or a deleted/unreadable manifest —
+ *  never throws (mirrors `assembleNodeSubject`'s profile resolution). This
+ *  absolute-path disclosure is intentional (spec-approved): the agent must
+ *  know its full purview, not a redacted count. */
+export declare function profileNote(nodeId: string): string;
 /** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
  *  so its context dir is also where a future cycle of itself resumes the work.
  *  Used inside the bearings block AND in the promotion guidance dump, so a

package/dist/core/runtime/bearings.js

@@ -41,6 +41,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { cadenceDisplay } from '../wake.js';
 import { renderKnowledgeBlock } from '../substrate/index.js';
+import { loadProfileManifest } from '../profiles/manifest.js';
 // ---------------------------------------------------------------------------
 // Project context (<project_context>) — the AGENTS.md/CLAUDE.md files pi would
 // otherwise inject into its SYSTEM PROMPT, rendered here so they ride the
@@ -206,6 +207,32 @@ export function contextDirNote(nodeId) {
         'this directory, so a bare relative `context/...` lands in the repo, not here — and other nodes ' +
         'can only read what is actually here. When you report a file, report its absolute path.');
 }
+/** The profile-purview note — rendered ONLY when `profile_id` resolves to a
+ *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd
+ *  replacement: the node's cwd is still its one working dir (bash/edits run
+ *  there), the profile just widens what it may ALSO read/act on. Omitted
+ *  entirely for a root/no-profile node or a deleted/unreadable manifest —
+ *  never throws (mirrors `assembleNodeSubject`'s profile resolution). This
+ *  absolute-path disclosure is intentional (spec-approved): the agent must
+ *  know its full purview, not a redacted count. */
+export function profileNote(nodeId) {
+    const meta = getNode(nodeId);
+    const profileId = meta?.profile_id;
+    if (profileId === undefined || profileId === null || profileId === '')
+        return '';
+    let entry;
+    try {
+        entry = loadProfileManifest(profileId);
+    }
+    catch {
+        return '';
+    }
+    const projects = entry.manifest.projects;
+    if (projects.length === 0)
+        return '';
+    return (`Your working dir is \`${meta.cwd}\`. Your profile **${entry.manifest.name}** also has purview ` +
+        `over: ${projects.join(', ')}.`);
+}
 /** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
  *  so its context dir is also where a future cycle of itself resumes the work.
  *  Used inside the bearings block AND in the promotion guidance dump, so a
@@ -415,6 +442,10 @@ export function buildContextBearings(nodeId) {
     if (map !== '')
         bearings.push('', '## Your place in the canvas', map);
     bearings.push('', '## Your context directory', contextDirNote(nodeId));
+    // Profile purview — omitted entirely for a root/no-profile node (see profileNote).
+    const profileSection = profileNote(nodeId);
+    if (profileSection !== '')
+        bearings.push('', profileSection);
     // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
     if (node?.mode === 'orchestrator')
         bearings.push('', orchestratorContextNote(nodeId));

package/dist/core/runtime/busy.d.ts

@@ -6,3 +6,18 @@ export declare function clearBusy(nodeId: string): void;
  *  site — a stale marker from a crashed pi is harmless because the dead pid
  *  fails the AND. */
 export declare function isBusy(nodeId: string): boolean;
+/** Re-touch the mid-turn marker's mtime — the daemon's wedge-detection
+ *  heartbeat (crtrd.ts `handleWedgeDetection`). Called from canvas-stophook on
+ *  every engine-level sign of life WITHIN a turn (a tool starting/streaming/
+ *  ending, a streamed assistant token, a turn ending) so the marker's mtime
+ *  always reflects the last moment the engine visibly did something, not just
+ *  when the turn began. No-ops when the node isn't currently busy — a touch
+ *  arriving after `clearBusy` (e.g. a late/queued event racing agent_end) must
+ *  never resurrect a stale marker. Best-effort. */
+export declare function touchBusy(nodeId: string): void;
+/** The mid-turn marker's mtime: the last moment ANY engine-level progress was
+ *  observed while the node was busy (see `touchBusy`). Null when the node isn't
+ *  busy or the marker is unreadable. This is the sole heartbeat the daemon's
+ *  wedge detector reads — it needs no new instrumentation beyond re-touching an
+ *  already-existing file. */
+export declare function busySince(nodeId: string): number | null;

package/dist/core/runtime/busy.js

@@ -13,7 +13,7 @@
 // read site, so a stale marker (process crashed mid-turn without firing
 // agent_end) is harmless — the dead pid fails the AND and the node is reaped.
 // No db migration, atomic touch/unlink, best-effort (never throws).
-import { existsSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { existsSync, writeFileSync, rmSync, mkdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { jobDir } from '../canvas/index.js';
 function busyPath(nodeId) {
@@ -44,3 +44,34 @@ export function clearBusy(nodeId) {
 export function isBusy(nodeId) {
     return existsSync(busyPath(nodeId));
 }
+/** Re-touch the mid-turn marker's mtime — the daemon's wedge-detection
+ *  heartbeat (crtrd.ts `handleWedgeDetection`). Called from canvas-stophook on
+ *  every engine-level sign of life WITHIN a turn (a tool starting/streaming/
+ *  ending, a streamed assistant token, a turn ending) so the marker's mtime
+ *  always reflects the last moment the engine visibly did something, not just
+ *  when the turn began. No-ops when the node isn't currently busy — a touch
+ *  arriving after `clearBusy` (e.g. a late/queued event racing agent_end) must
+ *  never resurrect a stale marker. Best-effort. */
+export function touchBusy(nodeId) {
+    try {
+        if (!existsSync(busyPath(nodeId)))
+            return;
+        writeFileSync(busyPath(nodeId), '');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** The mid-turn marker's mtime: the last moment ANY engine-level progress was
+ *  observed while the node was busy (see `touchBusy`). Null when the node isn't
+ *  busy or the marker is unreadable. This is the sole heartbeat the daemon's
+ *  wedge detector reads — it needs no new instrumentation beyond re-touching an
+ *  already-existing file. */
+export function busySince(nodeId) {
+    try {
+        return statSync(busyPath(nodeId)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/runtime/close.d.ts

@@ -1,3 +1,13 @@
+import { type SubscriptionRef } from '../canvas/index.js';
+/** The doctrine wake: fan a system notice to every given subscriber of a node
+ *  whose lifecycle just ended out from under it (closed, or crashed to dead) —
+ *  the runtime guarantee that a manager waiting dormant on a child always
+ *  learns of its terminal outcome instead of hanging forever. Active subscriber
+ *  → inbox (wakes a dormant manager via its live watcher / the daemon's
+ *  dormant-revive pass); passive → the passive accumulator (delivered, not
+ *  woken). Shared by closeNode (step 4, below) and reviveNode's launch-refusal
+ *  crash path (revive.ts). */
+export declare function fanDoctrineWake(fromId: string, subscribers: readonly SubscriptionRef[], label: string, data: Record<string, unknown>): void;
 export interface CloseNodeResult {
     /** The focused node that was closed — the cascade root. */
     root: string;

package/dist/core/runtime/close.js

@@ -36,6 +36,23 @@ import { headlessBrokerHost } from './host.js';
 import { tearDownNode, reapIfEmpty } from './placement.js';
 import { appendInbox } from '../feed/inbox.js';
 import { appendPassive } from '../feed/passive.js';
+/** The doctrine wake: fan a system notice to every given subscriber of a node
+ *  whose lifecycle just ended out from under it (closed, or crashed to dead) —
+ *  the runtime guarantee that a manager waiting dormant on a child always
+ *  learns of its terminal outcome instead of hanging forever. Active subscriber
+ *  → inbox (wakes a dormant manager via its live watcher / the daemon's
+ *  dormant-revive pass); passive → the passive accumulator (delivered, not
+ *  woken). Shared by closeNode (step 4, below) and reviveNode's launch-refusal
+ *  crash path (revive.ts). */
+export function fanDoctrineWake(fromId, subscribers, label, data) {
+    for (const sub of subscribers) {
+        const notice = { from: fromId, tier: 'normal', kind: 'message', label, data };
+        if (sub.active)
+            appendInbox(sub.node_id, notice);
+        else
+            appendPassive(sub.node_id, notice);
+    }
+}
 /** The set of nodes to close: the root plus every descendant reachable down the
  *  subscriptions spine, all of whose managers are themselves in the set. Grown
  *  to a fixpoint — a node added this pass can qualify its own children next
@@ -186,19 +203,7 @@ export function closeNode(rootId, opts = {}) {
             //    never fires inside a self-contained cascade. Active → inbox (wakes a
             //    dormant manager via its live watcher / the daemon's dormant-revive
             //    second pass); passive → passive accumulator (delivered, not woken).
-            for (const sub of survivors) {
-                const notice = {
-                    from: id,
-                    tier: 'normal',
-                    kind: 'message',
-                    label: `Child closed — ${m.name} (${id}) was closed from the canvas and is no longer running.`,
-                    data: { reason: 'child-closed', child: id },
-                };
-                if (sub.active)
-                    appendInbox(sub.node_id, notice);
-                else
-                    appendPassive(sub.node_id, notice);
-            }
+            fanDoctrineWake(id, survivors, `Child closed — ${m.name} (${id}) was closed from the canvas and is no longer running.`, { reason: 'child-closed', child: id });
             closed.push(id);
         }
         catch {