@north-light/crouter 0.3.311 → 0.3.313

package/dist/core/canvas/worktrees.js

@@ -0,0 +1,93 @@
+import { openDb, withCanvasWrite } from './db.js';
+function json(value) {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new TypeError('worktree value must be JSON-serializable');
+    return encoded;
+}
+function parse(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return JSON.parse(value);
+}
+export function readWorktree(nodeId) {
+    const row = openDb().prepare('SELECT * FROM worktrees WHERE node_id = ?').get(nodeId);
+    if (row === undefined)
+        return null;
+    const sweepObserved = parse(row['sweep_observed_json']);
+    const attempts = row['attempts'];
+    const sweep = sweepObserved === undefined ? undefined : {
+        reason: row['sweep_reason'],
+        ...(row['sweep_detail'] === null ? {} : { detail: row['sweep_detail'] }),
+        observed: sweepObserved,
+        attempts,
+        last_attempt: row['sweep_last_at'],
+        next_attempt: row['next_attempt_at'],
+        ...(row['quarantined'] === 1 ? { quarantined: true } : {}),
+    };
+    return {
+        state: row['state'],
+        ...(row['cleanup_state'] === null ? {} : { cleanup: row['cleanup_state'] }),
+        path: row['path'],
+        branch: row['branch'],
+        repo_root: row['repo_root'],
+        base_ref: row['base_ref'],
+        base_sha: row['base_sha'],
+        created: row['created_at'],
+        ...(row['closed_at'] === null ? {} : { closed: row['closed_at'] }),
+        ...(parse(row['abandoned_json']) === undefined ? {} : { abandoned: parse(row['abandoned_json']) }),
+        ...(parse(row['land_intent_json']) === undefined ? {} : { land_intent: parse(row['land_intent_json']) }),
+        ...(sweep === undefined ? {} : { sweep }),
+        ...(parse(row['disposal_json']) === undefined ? {} : { disposal: parse(row['disposal_json']) }),
+    };
+}
+export function openWorktree(nodeId, worktree, db = openDb()) {
+    db.prepare(`INSERT INTO worktrees (node_id, state, cleanup_state, path, branch, repo_root, base_ref, base_sha, created_at, closed_at, next_attempt_at, attempts, quarantined, sweep_reason, sweep_detail, sweep_last_at, sweep_observed_json, abandoned_json, land_intent_json, disposal_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL)`).run(nodeId, worktree.state, worktree.cleanup ?? null, worktree.path, worktree.branch, worktree.repo_root, worktree.base_ref, worktree.base_sha, worktree.created, worktree.closed ?? null);
+}
+export function closeWorktree(nodeId, input) {
+    openDb().prepare("UPDATE worktrees SET state = 'closed', cleanup_state = ?, closed_at = ?, land_intent_json = NULL, sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(input.cleanup, input.closedAt, nodeId);
+}
+/** Complete a worktree close and repoint the node in the same SQL transaction.
+ * A close invalidates the active transcript because Pi remains in the old
+ * checkout; the next launch starts from the durable base checkout. */
+export function closeWorktreeAndRepoint(nodeId, input) {
+    withCanvasWrite((db) => {
+        db.prepare('UPDATE nodes SET cwd = ? WHERE node_id = ?').run(input.cwd, nodeId);
+        if (input.unbindSession)
+            db.prepare('UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL').run(input.closedAt, nodeId);
+        db.prepare("UPDATE worktrees SET state = 'closed', cleanup_state = ?, closed_at = ?, land_intent_json = NULL, sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(input.cleanup, input.closedAt, nodeId);
+    });
+}
+export function abandonWorktree(nodeId, abandoned) {
+    openDb().prepare("UPDATE worktrees SET state = 'abandoned', abandoned_json = ? WHERE node_id = ? AND abandoned_json IS NULL").run(json(abandoned), nodeId);
+}
+export function abandonWorktreeAndRepoint(nodeId, input) {
+    withCanvasWrite((db) => {
+        db.prepare('UPDATE nodes SET cwd = ? WHERE node_id = ?').run(input.cwd, nodeId);
+        db.prepare("UPDATE worktrees SET state = 'abandoned', abandoned_json = ? WHERE node_id = ? AND abandoned_json IS NULL").run(json(input.abandoned), nodeId);
+    });
+}
+export function recordLandIntent(nodeId, intent) {
+    openDb().prepare('UPDATE worktrees SET land_intent_json = ? WHERE node_id = ? AND land_intent_json IS NULL').run(json(intent), nodeId);
+}
+export function recordDisposalGrant(nodeId, disposal) {
+    openDb().prepare('UPDATE worktrees SET disposal_json = ? WHERE node_id = ? AND disposal_json IS NULL').run(json(disposal), nodeId);
+}
+export function recordSweepAttempt(nodeId, input) {
+    openDb().prepare('UPDATE worktrees SET sweep_reason = ?, sweep_detail = ?, sweep_observed_json = ?, attempts = ?, sweep_last_at = ?, next_attempt_at = ?, quarantined = ? WHERE node_id = ?').run(input.reason, input.detail ?? null, json(input.observed), input.attempts, input.lastAttemptAt, input.nextAttemptAt, input.quarantined ? 1 : 0, nodeId);
+}
+export function completeCleanup(nodeId) {
+    openDb().prepare("UPDATE worktrees SET state = 'closed', cleanup_state = 'complete', sweep_reason = NULL, sweep_detail = NULL, sweep_last_at = NULL, sweep_observed_json = NULL, next_attempt_at = NULL, attempts = 0, quarantined = 0 WHERE node_id = ?").run(nodeId);
+}
+export function hasUnreconciledWorktree(nodeId) {
+    return openDb().prepare("SELECT 1 FROM worktrees WHERE node_id = ? AND state != 'abandoned' AND (state = 'open' OR cleanup_state IS NULL OR cleanup_state != 'complete')").get(nodeId) !== undefined;
+}
+export function sweepCandidates(now) {
+    return openDb().prepare(`SELECT w.node_id FROM worktrees w JOIN nodes n ON n.node_id = w.node_id WHERE n.status IN ('done', 'dead', 'canceled') AND n.frozen_at IS NULL AND w.state IN ('open', 'closed') AND (w.state = 'open' OR w.cleanup_state IS NULL OR w.cleanup_state != 'complete') AND (w.state = 'closed' OR (n.status = 'done' AND n.final_report IS NOT NULL)) AND (w.next_attempt_at IS NULL OR w.next_attempt_at <= ?) ORDER BY w.next_attempt_at, w.node_id`).all(now).map(({ node_id }) => node_id);
+}
+export function quarantinedWorktrees() {
+    return openDb().prepare('SELECT node_id FROM worktrees WHERE quarantined = 1 ORDER BY sweep_last_at').all().flatMap(({ node_id }) => {
+        const worktree = readWorktree(node_id);
+        return worktree === null ? [] : [{ nodeId: node_id, worktree }];
+    });
+}

package/dist/core/command-hooks/artifact.d.ts

@@ -1,9 +1,15 @@
 import type { PluginManifest } from '../../types.js';
 import { type HookManifestIssue, type ValidatedHookManifest } from './schema.js';
+export interface LifecycleDeclarationCandidate {
+    event: string;
+    op: string;
+    index: number;
+}
 export interface HookArtifactValidation {
     manifestPath?: string;
     executablePath?: string;
     manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
     issues: HookManifestIssue[];
 }
 /** Statically validates the local hook artifact a source plugin ships. */

package/dist/core/command-hooks/artifact.js

@@ -1,6 +1,21 @@
 import { readFileSync, realpathSync, statSync } from 'node:fs';
 import { isAbsolute, resolve, sep } from 'node:path';
 import { validateHookManifest } from './schema.js';
+function lifecycleCandidates(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return [];
+    const lifecycle = raw['lifecycle'];
+    if (!Array.isArray(lifecycle))
+        return [];
+    return lifecycle.flatMap((value, index) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return [];
+        const declaration = value;
+        return typeof declaration['event'] === 'string'
+            ? [{ event: declaration['event'], op: typeof declaration['op'] === 'string' ? declaration['op'] : '<invalid>', index }]
+            : [];
+    });
+}
 function safeFilePath(root, pointer) {
     if (isAbsolute(pointer))
         return null;
@@ -29,10 +44,10 @@ export function validatePluginHookArtifact(root, manifest) {
             expected: 'both hooks and hookExecutable',
             next: hasHooks ? 'Add plugin.json.hookExecutable or remove hooks.' : 'Add plugin.json.hooks or remove hookExecutable.',
         });
-        return { issues };
+        return { lifecycleCandidates: [], issues };
     }
     if (!hasHooks)
-        return { issues };
+        return { lifecycleCandidates: [], issues };
     if (typeof hooks !== 'string' || hooks.length === 0) {
         issues.push({
             code: 'hook_manifest_invalid',
@@ -54,7 +69,7 @@ export function validatePluginHookArtifact(root, manifest) {
         });
     }
     if (issues.length > 0)
-        return { issues };
+        return { lifecycleCandidates: [], issues };
     const hooksPointer = hooks;
     const executablePointer = executable;
     const manifestPath = safeFilePath(root, hooksPointer);
@@ -90,7 +105,7 @@ export function validatePluginHookArtifact(root, manifest) {
         });
     }
     if (manifestPath === null)
-        return { ...(executablePath === null ? {} : { executablePath }), issues };
+        return { lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
     let text;
     try {
         text = readFileSync(manifestPath, 'utf8');
@@ -103,7 +118,7 @@ export function validatePluginHookArtifact(root, manifest) {
             expected: 'a readable JSON file',
             next: 'Reinstall or update the plugin.',
         });
-        return { manifestPath, ...(executablePath === null ? {} : { executablePath }), issues };
+        return { manifestPath, lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
     }
     let raw;
     try {
@@ -117,11 +132,12 @@ export function validatePluginHookArtifact(root, manifest) {
             expected: 'a JSON object',
             next: 'Regenerate hooks.json.',
         });
-        return { manifestPath, ...(executablePath === null ? {} : { executablePath }), issues };
+        return { manifestPath, lifecycleCandidates: [], ...(executablePath === null ? {} : { executablePath }), issues };
     }
     const validation = validateHookManifest(raw);
     return {
         manifestPath,
+        lifecycleCandidates: lifecycleCandidates(raw),
         ...(executablePath === null ? {} : { executablePath }),
         ...(validation.manifest === undefined ? {} : { manifest: validation.manifest }),
         issues: [...issues, ...validation.issues],

package/dist/core/command-hooks/discovery.d.ts

@@ -1,4 +1,5 @@
 import type { InstalledPlugin } from '../../types.js';
+import { type LifecycleDeclarationCandidate } from './artifact.js';
 import type { CoreHookCatalog } from './catalog.js';
 import type { HookManifestIssue, HookPhase, LifecycleHookPhase, ValidatedHookManifest } from './schema.js';
 import type { LifecycleEvent } from './lifecycle-catalog.js';
@@ -65,6 +66,7 @@ export interface HookPluginValidation {
     manifestPath?: string;
     executablePath?: string;
     manifest?: ValidatedHookManifest;
+    lifecycleCandidates: readonly LifecycleDeclarationCandidate[];
     hooks: readonly EffectiveHook[];
     issues: readonly HookDiscoveryIssue[];
 }

package/dist/core/command-hooks/discovery.js

@@ -109,6 +109,7 @@ export function compileHookRegistry(catalog, plugins) {
             ...(artifact.manifestPath === undefined ? {} : { manifestPath: artifact.manifestPath }),
             ...(artifact.executablePath === undefined ? {} : { executablePath: artifact.executablePath }),
             ...(artifact.manifest === undefined ? {} : { manifest: artifact.manifest }),
+            lifecycleCandidates: Object.freeze([...artifact.lifecycleCandidates]),
             hooks: Object.freeze(compiled),
             issues: Object.freeze(pluginIssues),
         }));
@@ -183,6 +184,7 @@ export function compileLifecycleHookRegistry(plugins) {
             ...(artifact.manifestPath === undefined ? {} : { manifestPath: artifact.manifestPath }),
             ...(artifact.executablePath === undefined ? {} : { executablePath: artifact.executablePath }),
             ...(artifact.manifest === undefined ? {} : { manifest: artifact.manifest }),
+            lifecycleCandidates: Object.freeze([...artifact.lifecycleCandidates]),
             hooks: Object.freeze([]),
             issues: Object.freeze(pluginIssues),
         }));

package/dist/core/command-hooks/lifecycle-catalog.d.ts

@@ -1,3 +1,21 @@
-export declare const LIFECYCLE_EVENTS: readonly ["node:start", "node:close"];
-export type LifecycleEvent = typeof LIFECYCLE_EVENTS[number];
+export declare const LIFECYCLE_CATALOG: {
+    readonly 'node:create': {
+        readonly phase: "before";
+        readonly hookTimeoutMs: 5000;
+        readonly eventBudgetMs: 10000;
+    };
+    readonly 'node:start': {
+        readonly phase: "on";
+        readonly hookTimeoutMs: 5000;
+        readonly eventBudgetMs: 10000;
+    };
+    readonly 'node:close': {
+        readonly phase: "on";
+        readonly hookTimeoutMs: 120000;
+        readonly eventBudgetMs: 180000;
+    };
+};
+export type LifecycleEvent = keyof typeof LIFECYCLE_CATALOG;
+export type LifecycleHookPhase = (typeof LIFECYCLE_CATALOG)[LifecycleEvent]['phase'];
+export declare const LIFECYCLE_EVENTS: readonly ("node:create" | "node:start" | "node:close")[];
 export declare function isLifecycleEvent(value: string): value is LifecycleEvent;

package/dist/core/command-hooks/lifecycle-catalog.js

@@ -1,4 +1,9 @@
-export const LIFECYCLE_EVENTS = ['node:start', 'node:close'];
+export const LIFECYCLE_CATALOG = {
+    'node:create': { phase: 'before', hookTimeoutMs: 5_000, eventBudgetMs: 10_000 },
+    'node:start': { phase: 'on', hookTimeoutMs: 5_000, eventBudgetMs: 10_000 },
+    'node:close': { phase: 'on', hookTimeoutMs: 120_000, eventBudgetMs: 180_000 },
+};
+export const LIFECYCLE_EVENTS = Object.freeze(Object.keys(LIFECYCLE_CATALOG));
 export function isLifecycleEvent(value) {
-    return LIFECYCLE_EVENTS.includes(value);
+    return Object.hasOwn(LIFECYCLE_CATALOG, value);
 }

package/dist/core/command-hooks/lifecycle-create.d.ts

@@ -0,0 +1,4 @@
+import type { NodeCreateHookRequest } from '../../hook-authoring.js';
+export type NodeCreateRequest = NodeCreateHookRequest['create'];
+/** Admit one node creation and return the release that must run after its row exists. */
+export declare function admitNodeCreate(create: NodeCreateRequest): Promise<() => void>;

package/dist/core/command-hooks/lifecycle-create.js

@@ -0,0 +1,51 @@
+import { crtrHome } from '../canvas/paths.js';
+import { nodeCreateRefused } from '../errors.js';
+import { discoverLifecycleHookRegistry } from './discovery.js';
+import { invokeBlockingLifecycleHooks } from './transport/exec-lifecycle.js';
+let nodeCreateGate = Promise.resolve();
+async function enterNodeCreateGate() {
+    let resolve;
+    const previous = nodeCreateGate;
+    nodeCreateGate = new Promise((release) => { resolve = release; });
+    await previous;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        resolve();
+    };
+}
+function refusedCreateHookDiscovery(cwd, profileId) {
+    const registry = discoverLifecycleHookRegistry(cwd, profileId);
+    const plan = registry.plans.get('node:create') ?? [];
+    const failed = registry.validations.flatMap((validation) => validation.lifecycleCandidates
+        .filter((candidate) => candidate.event === 'node:create' && !plan.some((hook) => hook.plugin.name === validation.plugin.name && hook.declarationIndex === candidate.index))
+        .map((candidate) => ({
+        validation,
+        candidate,
+        issue: validation.issues.find((issue) => issue.path === `lifecycle[${candidate.index}]` || issue.path?.startsWith(`lifecycle[${candidate.index}].`)) ?? validation.issues[0],
+    })))[0];
+    if (failed === undefined)
+        return registry;
+    const { validation, candidate, issue } = failed;
+    throw nodeCreateRefused(`plugin "${validation.plugin.name}" lifecycle hook "${candidate.op}" for node:create could not be discovered: ${issue.message}`, `Refused by plugin ${validation.plugin.name}, op ${candidate.op}.`);
+}
+/** Admit one node creation and return the release that must run after its row exists. */
+export async function admitNodeCreate(create) {
+    const release = await enterNodeCreateGate();
+    try {
+        const registry = refusedCreateHookDiscovery(create.cwd, create.profile);
+        const refusal = await invokeBlockingLifecycleHooks(registry.plans.get('node:create') ?? [], {
+            create,
+            runtime: { canvasHome: crtrHome(), profile: create.profile },
+        });
+        if (refusal !== null)
+            throw nodeCreateRefused(refusal.message, refusal.next);
+        return release;
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+}

package/dist/core/command-hooks/schema.d.ts

@@ -1,6 +1,6 @@
-import { type LifecycleEvent } from './lifecycle-catalog.js';
+import { type LifecycleEvent, type LifecycleHookPhase } from './lifecycle-catalog.js';
+export type { LifecycleHookPhase } from './lifecycle-catalog.js';
 export type HookPhase = 'before' | 'after' | 'replace';
-export type LifecycleHookPhase = 'on';
 export interface DeclaredHook {
     target: string;
     phase: HookPhase;

package/dist/core/command-hooks/schema.js

@@ -1,5 +1,5 @@
 import { isRecord } from '../../shared/predicates.js';
-import { LIFECYCLE_EVENTS, isLifecycleEvent } from './lifecycle-catalog.js';
+import { LIFECYCLE_CATALOG, LIFECYCLE_EVENTS, isLifecycleEvent } from './lifecycle-catalog.js';
 function typeName(value) {
     if (value === null)
         return 'null';
@@ -61,8 +61,9 @@ function validateLifecycleDeclaration(value, index, issue) {
         issue('hook_manifest_invalid', 'event must name a supported lifecycle event', String(value['event']), LIFECYCLE_EVENTS.join(' | '), `Set event to one of: ${LIFECYCLE_EVENTS.join(', ')}.`, `${path}.event`);
         return undefined;
     }
-    if (value['phase'] !== 'on') {
-        issue('hook_manifest_invalid', 'phase must be on', String(value['phase']), 'on', 'Set phase to on.', `${path}.phase`);
+    const phase = LIFECYCLE_CATALOG[value['event']].phase;
+    if (value['phase'] !== phase) {
+        issue('hook_manifest_invalid', `phase must be ${phase}`, String(value['phase']), phase, `Set phase to ${phase}.`, `${path}.phase`);
         return undefined;
     }
     if (!isEffects(value['effects'])) {
@@ -71,7 +72,7 @@ function validateLifecycleDeclaration(value, index, issue) {
     }
     return {
         event: value['event'],
-        phase: 'on',
+        phase,
         op: value['op'],
         description: value['description'],
         effects: value['effects'],

package/dist/core/command-hooks/transport/exec-invoke.js

@@ -170,7 +170,9 @@ function buildRequest(spec, invocation, cwd) {
     if (invocation.result !== undefined) {
         throw protocolError(spec, invocation, `${spec.phase} hook invocation included a result`, 'result only for after hooks');
     }
-    return { ...base, phase: spec.phase };
+    if (spec.phase === 'before')
+        return { ...base, phase: 'before' };
+    return { ...base, phase: 'replace' };
 }
 function parseEnvelope(spec, invocation, stdout) {
     let value;

package/dist/core/command-hooks/transport/exec-lifecycle.d.ts

@@ -1,12 +1,22 @@
-import type { LifecycleHookRequest } from '../../../hook-authoring.js';
+import type { LifecycleHookRequest, NodeCreateHookRequest } from '../../../hook-authoring.js';
 import type { EffectiveLifecycleHook } from '../discovery.js';
-export declare const LIFECYCLE_HOOK_TIMEOUT_MS = 5000;
-export declare const LIFECYCLE_EVENT_BUDGET_MS = 10000;
-export interface LifecycleHookInvocation {
+export interface NodeLifecycleHookInvocation {
     node: LifecycleHookRequest['node'];
     runtime: LifecycleHookRequest['runtime'];
 }
-/** Runs one lifecycle hook. The node launch remains authoritative on every failure. */
-export declare function invokeLifecycleHook(hook: EffectiveLifecycleHook, invocation: LifecycleHookInvocation, timeoutMs: number): Promise<void>;
-/** Executes lifecycle hooks in discovery order, within one bounded event budget. */
-export declare function invokeLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: LifecycleHookInvocation): Promise<void>;
+export interface NodeCreateHookInvocation {
+    create: NodeCreateHookRequest['create'];
+    runtime: NodeCreateHookRequest['runtime'];
+}
+export interface BlockingLifecycleHookRefusal {
+    hook: EffectiveLifecycleHook;
+    message: string;
+    next: string;
+}
+/** Runs one lifecycle hook. `node:start` and `node:close` remain best-effort. */
+export declare function invokeLifecycleHook(hook: EffectiveLifecycleHook, invocation: NodeLifecycleHookInvocation, timeoutMs: number): Promise<void>;
+/** Executes non-blocking lifecycle hooks in discovery order within the event's catalogued budget. */
+export declare function invokeLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: NodeLifecycleHookInvocation): Promise<void>;
+/** Runs blocking `node:create` hooks. Every protocol or process failure refuses the create. */
+export declare function invokeBlockingLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: NodeCreateHookInvocation): Promise<BlockingLifecycleHookRefusal | null>;
+export declare function lifecycleHookAttribution(hook: EffectiveLifecycleHook): string;

package/dist/core/command-hooks/transport/exec-lifecycle.js

@@ -3,53 +3,109 @@ import { spawn } from 'node:child_process';
 import { PROCESS_GROUP_KILL_GRACE_MS, posixProcessGroupSpawnOptions, terminateProcessGroup } from '../../../hook-process.js';
 import { isRecord } from '../../../shared/predicates.js';
 import { diag } from '../../io.js';
+import { LIFECYCLE_CATALOG } from '../lifecycle-catalog.js';
 const MAX_STDOUT = 10 * 1024 * 1024;
-export const LIFECYCLE_HOOK_TIMEOUT_MS = 5_000;
-export const LIFECYCLE_EVENT_BUDGET_MS = 10_000;
-/** Runs one lifecycle hook. The node launch remains authoritative on every failure. */
+/** Runs one lifecycle hook. `node:start` and `node:close` remain best-effort. */
 export async function invokeLifecycleHook(hook, invocation, timeoutMs) {
     try {
-        const request = {
-            protocolVersion: 1,
-            op: hook.op,
-            event: hook.event,
-            phase: hook.phase,
-            operationId: randomBytes(16).toString('hex'),
-            node: invocation.node,
-            runtime: invocation.runtime,
-            context: { cwd: invocation.node.cwd },
-        };
-        const result = await runLifecycleProcess(hook, JSON.stringify(request), timeoutMs);
-        if (result.signal !== null)
-            throw new Error(`executable was killed by signal ${result.signal}`);
-        const envelope = parseEnvelope(result.stdout);
-        if (envelope.ok) {
-            if (result.status !== 0)
-                diag(`crtr: ${label(hook)} returned ok:true but exited ${result.status} (honoring the envelope)`);
-            return;
-        }
-        diag(`crtr: ${label(hook)} failed: ${envelope.error.code}: ${envelope.error.message}`);
+        const envelope = await executeLifecycleHook(hook, invocation, timeoutMs);
+        if (!envelope.ok)
+            diag(`crtr: ${label(hook)} failed: ${envelope.error.code}: ${envelope.error.message}`);
     }
     catch (error) {
         diag(`crtr: ${label(hook)} failed: ${describeError(error)}`);
     }
 }
-/** Executes lifecycle hooks in discovery order, within one bounded event budget. */
+/** Executes non-blocking lifecycle hooks in discovery order within the event's catalogued budget. */
 export async function invokeLifecycleHooks(hooks, invocation) {
-    const deadline = Date.now() + LIFECYCLE_EVENT_BUDGET_MS;
+    if (hooks.length === 0)
+        return;
+    const { hookTimeoutMs, eventBudgetMs } = LIFECYCLE_CATALOG[hooks[0].event];
+    const deadline = Date.now() + eventBudgetMs;
     for (const hook of hooks) {
         const remaining = deadline - Date.now();
-        // A timed-out hook must be reaped before launch can proceed. Reserve the
-        // process-group termination grace inside the event budget rather than
-        // letting the final cleanup extend the node-start critical path.
-        const timeoutMs = Math.min(LIFECYCLE_HOOK_TIMEOUT_MS, remaining - PROCESS_GROUP_KILL_GRACE_MS);
+        const timeoutMs = Math.min(hookTimeoutMs, remaining - PROCESS_GROUP_KILL_GRACE_MS);
         if (timeoutMs <= 0) {
-            diag(`crtr: lifecycle hook event ${hook.event} exceeded its ${LIFECYCLE_EVENT_BUDGET_MS}ms aggregate budget; skipped ${label(hook)}`);
+            diag(`crtr: lifecycle hook event ${hook.event} exceeded its ${eventBudgetMs}ms aggregate budget; skipped ${label(hook)}`);
             return;
         }
         await invokeLifecycleHook(hook, invocation, timeoutMs);
     }
 }
+/** Runs blocking `node:create` hooks. Every protocol or process failure refuses the create. */
+export async function invokeBlockingLifecycleHooks(hooks, invocation) {
+    if (hooks.length === 0)
+        return null;
+    const { hookTimeoutMs, eventBudgetMs } = LIFECYCLE_CATALOG['node:create'];
+    const deadline = Date.now() + eventBudgetMs;
+    for (const hook of hooks) {
+        const remaining = deadline - Date.now();
+        const timeoutMs = Math.min(hookTimeoutMs, remaining - PROCESS_GROUP_KILL_GRACE_MS);
+        if (timeoutMs <= 0) {
+            return refusal(hook, `lifecycle hook event node:create exceeded its ${eventBudgetMs}ms aggregate budget`);
+        }
+        try {
+            const envelope = await executeLifecycleHook(hook, invocation, timeoutMs);
+            if (!envelope.ok)
+                return {
+                    hook,
+                    message: envelope.error.message,
+                    next: envelope.error.next ?? attribution(hook),
+                };
+        }
+        catch (error) {
+            return refusal(hook, describeError(error));
+        }
+    }
+    return null;
+}
+function refusal(hook, cause) {
+    return {
+        hook,
+        message: `${label(hook)} failed: ${cause}`,
+        next: attribution(hook),
+    };
+}
+export function lifecycleHookAttribution(hook) {
+    return attribution(hook);
+}
+async function executeLifecycleHook(hook, invocation, timeoutMs) {
+    const request = hook.event === 'node:create'
+        ? createRequest(hook, invocation)
+        : nodeRequest(hook, invocation);
+    const result = await runLifecycleProcess(hook, JSON.stringify(request), timeoutMs);
+    if (result.signal !== null)
+        throw new Error(`executable was killed by signal ${result.signal}`);
+    const envelope = parseEnvelope(result.stdout);
+    if (envelope.ok && result.status !== 0) {
+        diag(`crtr: ${label(hook)} returned ok:true but exited ${result.status} (honoring the envelope)`);
+    }
+    return envelope;
+}
+function nodeRequest(hook, invocation) {
+    return {
+        protocolVersion: 1,
+        op: hook.op,
+        event: hook.event,
+        phase: hook.phase,
+        operationId: randomBytes(16).toString('hex'),
+        node: invocation.node,
+        runtime: invocation.runtime,
+        context: { cwd: invocation.node.cwd },
+    };
+}
+function createRequest(hook, invocation) {
+    return {
+        protocolVersion: 1,
+        op: hook.op,
+        event: 'node:create',
+        phase: 'before',
+        operationId: randomBytes(16).toString('hex'),
+        create: invocation.create,
+        runtime: invocation.runtime,
+        context: { cwd: invocation.create.cwd },
+    };
+}
 async function runLifecycleProcess(hook, input, timeoutMs) {
     let child;
     try {
@@ -147,6 +203,9 @@ function exactKeys(value, required, optional = []) {
 function label(hook) {
     return `plugin "${hook.plugin.name}" lifecycle hook "${hook.op}" for ${hook.event}`;
 }
+function attribution(hook) {
+    return `Refused by plugin ${hook.plugin.name}, op ${hook.op}.`;
+}
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/core/config.d.ts

@@ -3,23 +3,28 @@ import { type BindingId } from './keybindings/catalog.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
 export declare function readConfig(scope: Scope): ResolvedScopeConfig;
-/** Read the config that lives at an EXACT scope-root dir, rather than the
- *  resolved nearest root for a scope. Lets a caller iterate each visible
- *  project root's own config when several are in scope (nested `.crouter` dirs
- *  or a profile-widened stack), instead of collapsing them onto the nearest. */
 export declare function readConfigAtRoot(root: string): ResolvedScopeConfig;
 export declare function readState(scope: Scope): ScopeState;
+export type RawSettingsTarget = {
+    scope: 'user';
+} | {
+    scope: 'profile';
+    profileId: string;
+};
+export declare class InvalidRawSettingsError extends Error {
+    constructor(cause: unknown);
+}
+export declare function readRawSettingsForTarget(target: RawSettingsTarget): {
+    settings: Record<string, unknown> | null;
+    revision: string;
+};
+export declare function replaceRawSettingsForTarget(target: RawSettingsTarget, next: Record<string, unknown>, ifRevision: string): {
+    revision: string;
+    changed: boolean;
+};
 type RawConfig = Record<string, unknown>;
 export declare function updateRawConfigAtomically(scope: Scope, mutate: (latest: RawConfig) => RawConfig): RawConfig;
 export declare function writeConfig(scope: Scope, config: ScopeConfig): void;
-/** Persist a RAW PARTIAL config to a scope's config.json exactly as given.
- *  Unlike `writeConfig`, this makes no promise that every field is present --
- *  callers pass the sparse partial that should live on disk, so an untouched
- *  key stays absent (and `readConfig`/`mergeConfig` re-derive it live from
- *  whichever build is running). This is the single central primitive every
- *  mutation path funnels through so no writer ever freezes a fully
- *  materialized `modelLadders` (concrete model ids that go stale across
- *  builds -- the live-Hearth freeze bug) onto disk. */
 export declare function writeRawConfig(scope: Scope, config: Partial<ScopeConfig>): void;
 export declare function writeState(scope: Scope, state: ScopeState): void;
 export declare function ensureScopeInitialized(scope: Scope, root: string): void;