@north-light/crouter 0.3.217 → 0.3.219

package/dist/core/manifest.d.ts

@@ -2,4 +2,6 @@ import type { MarketplaceManifest, PluginManifest } from '../types.js';
 export declare function pluginManifestPath(pluginRoot: string): string;
 export declare function marketplaceManifestPath(mktRoot: string): string;
 export declare function readPluginManifest(pluginRoot: string): PluginManifest | null;
+/** Validate an optional memory-extension declaration at package preflight. */
+export declare function validatePluginManifestMemoryExtensions(manifest: PluginManifest): void;
 export declare function readMarketplaceManifest(mktRoot: string): MarketplaceManifest | null;

package/dist/core/manifest.js

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { MARKETPLACE_MANIFEST_DIR, MARKETPLACE_MANIFEST_FILE, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE, } from '../types.js';
+import { validatePluginMemoryExtensions } from './memory/extensions.js';
 import { readJsonIfExists } from './fs-utils.js';
 export function pluginManifestPath(pluginRoot) {
     return join(pluginRoot, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
@@ -10,6 +11,10 @@ export function marketplaceManifestPath(mktRoot) {
 export function readPluginManifest(pluginRoot) {
     return readJsonIfExists(pluginManifestPath(pluginRoot));
 }
+/** Validate an optional memory-extension declaration at package preflight. */
+export function validatePluginManifestMemoryExtensions(manifest) {
+    validatePluginMemoryExtensions(manifest);
+}
 export function readMarketplaceManifest(mktRoot) {
     return readJsonIfExists(marketplaceManifestPath(mktRoot));
 }

package/dist/core/memory/extensions.d.ts

@@ -0,0 +1,30 @@
+import type { MemoryExtensionDeclarations, MemoryExtensionScalar, PluginManifest } from '../../types.js';
+import type { MemoryDoc } from '../memory-resolver.js';
+export type MemoryExtensionCatalog = Record<string, MemoryExtensionDeclarations>;
+export interface MemoryExtensionValidationIssue {
+    path: string;
+    message: string;
+}
+export interface MemoryExtensionCatalogOptions {
+    /** The manifest currently being staged. Its namespace shadows an installed copy only for that candidate validation. */
+    candidate?: Pick<PluginManifest, 'name' | 'memory_extensions'>;
+}
+export declare function isMemoryExtensionScalar(value: unknown): value is MemoryExtensionScalar;
+/** Parse the closed declaration addendum. Callers that accept a plugin manifest
+ * invoke this at their install/preflight boundary; normal runtime catalogs only
+ * admit declarations which have already cleared that boundary. */
+export declare function validateMemoryExtensionDeclarations(raw: unknown): MemoryExtensionDeclarations;
+/** Throw when a manifest carries an invalid addendum; absent is valid. */
+export declare function validatePluginMemoryExtensions(manifest: Pick<PluginManifest, 'memory_extensions'>): void;
+/** Installed declarations used for validation and authoring. Disabled plugins
+ * remain present so existing values can still be checked and edited. */
+export declare function memoryExtensionValidationCatalog(doc: Pick<MemoryDoc, 'scope' | 'path'>, options?: MemoryExtensionCatalogOptions): MemoryExtensionCatalog;
+/** Winning enabled declarations used only to interpret structured output. */
+export declare function memoryExtensionEffectiveCatalog(doc: Pick<MemoryDoc, 'scope' | 'path'>): MemoryExtensionCatalog;
+/** Validate the raw `extensions` frontmatter value. Unresolved namespaces are
+ * intentionally reported rather than discarded: removal leaves raw metadata
+ * intact but lint-invalid until its plugin returns. */
+export declare function validateMemoryExtensionValues(raw: unknown, catalog: MemoryExtensionCatalog): MemoryExtensionValidationIssue[];
+/** Effective plugin metadata for structured consumers. It overlays only valid
+ * explicit scalars onto defaults and never mutates or serializes frontmatter. */
+export declare function projectEffectiveMemoryExtensions(raw: unknown, catalog: MemoryExtensionCatalog): Record<string, Record<string, MemoryExtensionScalar>>;

package/dist/core/memory/extensions.js

@@ -0,0 +1,219 @@
+import { sep } from 'node:path';
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
+const LOCAL_FIELD_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const DECLARATION_KEYS = new Set(['type', 'values', 'default', 'write_help', 'edit_help']);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function isMemoryExtensionScalar(value) {
+    return typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+}
+function declarationError(path, message) {
+    return new Error(`invalid memory_extensions declaration at ${path}: ${message}`);
+}
+function validHelp(value) {
+    return typeof value === 'string' && value.trim() !== '' && !/[\r\n]/.test(value);
+}
+function validDefault(declaration, value) {
+    if (!isMemoryExtensionScalar(value))
+        return false;
+    if (declaration.type === 'enum')
+        return typeof value === 'string' && declaration.values.includes(value);
+    return typeof value === declaration.type;
+}
+/** Parse the closed declaration addendum. Callers that accept a plugin manifest
+ * invoke this at their install/preflight boundary; normal runtime catalogs only
+ * admit declarations which have already cleared that boundary. */
+export function validateMemoryExtensionDeclarations(raw) {
+    if (!isRecord(raw))
+        throw declarationError('memory_extensions', 'expected a non-empty object');
+    const declarations = {};
+    const fields = Object.entries(raw);
+    if (fields.length === 0)
+        throw declarationError('memory_extensions', 'must not be empty');
+    for (const [field, value] of fields) {
+        const path = `memory_extensions.${field}`;
+        if (!LOCAL_FIELD_NAME.test(field)) {
+            throw declarationError(path, 'field names must be lowercase kebab-case');
+        }
+        if (!isRecord(value))
+            throw declarationError(path, 'expected a declaration object');
+        for (const key of Object.keys(value)) {
+            if (!DECLARATION_KEYS.has(key))
+                throw declarationError(path, `unknown key \`${key}\``);
+        }
+        const type = value['type'];
+        if (type !== 'boolean' && type !== 'string' && type !== 'number' && type !== 'enum') {
+            throw declarationError(`${path}.type`, 'expected boolean, string, number, or enum');
+        }
+        if (!validHelp(value['write_help']))
+            throw declarationError(`${path}.write_help`, 'expected a nonblank single-line string');
+        if (!validHelp(value['edit_help']))
+            throw declarationError(`${path}.edit_help`, 'expected a nonblank single-line string');
+        if (type === 'enum') {
+            const values = value['values'];
+            if (!Array.isArray(values) || values.length === 0 || !values.every((entry) => typeof entry === 'string' && entry !== '')) {
+                throw declarationError(`${path}.values`, 'expected a non-empty string list');
+            }
+            if (new Set(values).size !== values.length)
+                throw declarationError(`${path}.values`, 'values must be unique');
+            const declaration = {
+                type,
+                values: [...values],
+                write_help: value['write_help'],
+                edit_help: value['edit_help'],
+            };
+            if ('default' in value) {
+                if (!validDefault(declaration, value['default'])) {
+                    throw declarationError(`${path}.default`, 'must be one of the declared enum values');
+                }
+                declaration.default = value['default'];
+            }
+            declarations[field] = declaration;
+            continue;
+        }
+        if ('values' in value)
+            throw declarationError(`${path}.values`, 'is allowed only for enum declarations');
+        const declaration = {
+            type,
+            write_help: value['write_help'],
+            edit_help: value['edit_help'],
+        };
+        if ('default' in value) {
+            if (!validDefault(declaration, value['default'])) {
+                throw declarationError(`${path}.default`, `must be a ${type}`);
+            }
+            declaration.default = value['default'];
+        }
+        declarations[field] = declaration;
+    }
+    return declarations;
+}
+/** Throw when a manifest carries an invalid addendum; absent is valid. */
+export function validatePluginMemoryExtensions(manifest) {
+    if (manifest.memory_extensions !== undefined)
+        validateMemoryExtensionDeclarations(manifest.memory_extensions);
+}
+function declarationsFromManifest(manifest, strict) {
+    if (manifest.memory_extensions === undefined)
+        return undefined;
+    try {
+        return validateMemoryExtensionDeclarations(manifest.memory_extensions);
+    }
+    catch (error) {
+        if (strict)
+            throw error;
+        return undefined;
+    }
+}
+function catalogForPlugins(groups, enabledOnly, candidate) {
+    const catalog = {};
+    const shadowed = new Set();
+    if (candidate !== undefined) {
+        // A candidate that removes its addendum must still hide an installed copy
+        // while that package's own documents are being validated.
+        shadowed.add(candidate.name);
+        const declarations = declarationsFromManifest(candidate, true);
+        if (declarations !== undefined)
+            catalog[candidate.name] = declarations;
+    }
+    for (const plugins of groups) {
+        for (const plugin of plugins) {
+            if (enabledOnly && !plugin.enabled)
+                continue;
+            const namespace = plugin.manifest.name;
+            if (shadowed.has(namespace) || catalog[namespace] !== undefined)
+                continue;
+            const declarations = declarationsFromManifest(plugin.manifest, false);
+            if (declarations !== undefined)
+                catalog[namespace] = declarations;
+        }
+    }
+    return catalog;
+}
+/** Declarations for a native document. Project documents use their owning
+ * project scope only, then user scope; profile/node/user docs use user scope. */
+function pluginGroupsForDocument(doc) {
+    if (doc.scope === 'project') {
+        const marker = `${sep}.crouter${sep}`;
+        const markerIndex = doc.path.lastIndexOf(marker);
+        if (markerIndex >= 0) {
+            const root = doc.path.slice(0, markerIndex + `${sep}.crouter`.length);
+            return [listInstalledPluginsInRoot('project', root), listInstalledPlugins('user')];
+        }
+    }
+    return [listInstalledPlugins('user')];
+}
+/** Installed declarations used for validation and authoring. Disabled plugins
+ * remain present so existing values can still be checked and edited. */
+export function memoryExtensionValidationCatalog(doc, options = {}) {
+    return catalogForPlugins(pluginGroupsForDocument(doc), false, options.candidate);
+}
+/** Winning enabled declarations used only to interpret structured output. */
+export function memoryExtensionEffectiveCatalog(doc) {
+    return catalogForPlugins(pluginGroupsForDocument(doc), true);
+}
+/** Validate the raw `extensions` frontmatter value. Unresolved namespaces are
+ * intentionally reported rather than discarded: removal leaves raw metadata
+ * intact but lint-invalid until its plugin returns. */
+export function validateMemoryExtensionValues(raw, catalog) {
+    if (raw === undefined)
+        return [];
+    if (!isRecord(raw))
+        return [{ path: 'extensions', message: 'expected a mapping' }];
+    const issues = [];
+    for (const [namespace, fields] of Object.entries(raw)) {
+        const namespacePath = `extensions.${namespace}`;
+        if (!isRecord(fields)) {
+            issues.push({ path: namespacePath, message: 'expected a mapping' });
+            continue;
+        }
+        const declarations = catalog[namespace];
+        if (declarations === undefined) {
+            issues.push({ path: namespacePath, message: 'unresolved extension namespace' });
+            for (const [field, value] of Object.entries(fields)) {
+                if (!isMemoryExtensionScalar(value)) {
+                    issues.push({ path: `${namespacePath}.${field}`, message: 'expected a string, boolean, or finite number' });
+                }
+            }
+            continue;
+        }
+        for (const [field, value] of Object.entries(fields)) {
+            const path = `${namespacePath}.${field}`;
+            if (!isMemoryExtensionScalar(value)) {
+                issues.push({ path, message: 'expected a string, boolean, or finite number' });
+                continue;
+            }
+            const declaration = declarations[field];
+            if (declaration === undefined) {
+                issues.push({ path, message: 'undeclared extension field' });
+                continue;
+            }
+            if (!validDefault(declaration, value)) {
+                const expected = declaration.type === 'enum' ? `one of ${declaration.values.join('|')}` : declaration.type;
+                issues.push({ path, message: `expected ${expected}` });
+            }
+        }
+    }
+    return issues;
+}
+/** Effective plugin metadata for structured consumers. It overlays only valid
+ * explicit scalars onto defaults and never mutates or serializes frontmatter. */
+export function projectEffectiveMemoryExtensions(raw, catalog) {
+    const source = isRecord(raw) ? raw : {};
+    const effective = {};
+    for (const [namespace, declarations] of Object.entries(catalog)) {
+        const values = {};
+        const explicit = isRecord(source[namespace]) ? source[namespace] : {};
+        for (const [field, declaration] of Object.entries(declarations)) {
+            if (declaration.default !== undefined)
+                values[field] = declaration.default;
+            const value = explicit[field];
+            if (validDefault(declaration, value))
+                values[field] = value;
+        }
+        if (Object.keys(values).length > 0)
+            effective[namespace] = values;
+    }
+    return effective;
+}

package/dist/core/preview-result-path.d.ts

@@ -0,0 +1,4 @@
+export declare const PREVIEW_RESULT_PATH_ENV = "CRTR_PREVIEW_RESULT_PATH";
+/** Deterministic from the tool call id, so the spawning side and the result
+ *  side derive the same path without sharing state. */
+export declare function previewResultPath(toolCallId: string): string;

package/dist/core/preview-result-path.js

@@ -0,0 +1,25 @@
+// The private structured-result side channel between a crtr CLI invocation and
+// the canvas broker that spawned it: the broker names one file per bash tool
+// call, the leaf mirrors its record there, and the broker attaches the record
+// to Pi's ToolResult.details.
+//
+// The path travels in the child process environment. It must never be spliced
+// into the command text — the executed script has to stay exactly what the
+// agent wrote, because `cmd.sh`, job inspection, and the doc substrate's
+// `command` surfaces all read that text as the agent's own words.
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const PREVIEW_RESULT_PATH_ENV = 'CRTR_PREVIEW_RESULT_PATH';
+/** A tool call id is unique only within one broker: some provider adapters
+ *  synthesize a missing id from a process-local counter and a millisecond
+ *  clock, so two brokers can mint the same one and collide on a shared file.
+ *  Node id and pid are equal across both sides of the transport (they run in
+ *  the same broker process) without either side sharing state. */
+function brokerToken() {
+    return `${encodeURIComponent(process.env['CRTR_NODE_ID'] ?? 'no-node')}-${process.pid}`;
+}
+/** Deterministic from the tool call id, so the spawning side and the result
+ *  side derive the same path without sharing state. */
+export function previewResultPath(toolCallId) {
+    return join(tmpdir(), 'crouter-preview-results', `${brokerToken()}-${encodeURIComponent(toolCallId)}.json`);
+}

package/dist/core/runtime/launch-config-worker.d.ts

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

package/dist/core/runtime/launch-config-worker.js

@@ -0,0 +1,12 @@
+// Runs the synchronous configuration resolver outside crtrd's process. A
+// network filesystem can block a native read indefinitely; unlike a worker
+// thread, this subprocess can be killed at the launch-config timeout.
+import { readMergedLaunchConfig } from '../config.js';
+process.once('message', (message) => {
+    try {
+        process.send?.({ config: readMergedLaunchConfig(message.cwd, message.profileId) });
+    }
+    catch (error) {
+        process.send?.({ error: error instanceof Error ? error.message : String(error) });
+    }
+});

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

@@ -1,3 +1,4 @@
+import { type MergedLaunchConfig } from '../config.js';
 import type { PiInvocation } from './invocation.js';
 export { CANVAS_EXTENSIONS, CANVAS_STOPHOOK_PATH, CANVAS_INBOX_WATCHER_PATH, CANVAS_RECAP_PATH, CANVAS_GOAL_CAPTURE_PATH, CANVAS_PASSIVE_CONTEXT_PATH, CANVAS_CONTEXT_INTRO_PATH, CANVAS_TOOL_GUIDE_PATH, CANVAS_DOC_SUBSTRATE_PATH, CANVAS_STRUCTURED_OUTPUT_PATH, CANVAS_BASH_VALVE_PATH, } from './canvas-extensions.js';
 import type { NodeMeta, LaunchSpec, Mode, Lifecycle } from '../canvas/index.js';
@@ -59,7 +60,7 @@ export declare function nextLadderModel(currentSpec: string, direction?: 1 | -1,
  *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
  *  as-given, never derived from persona frontmatter. The two canvas
  *  extensions are always first; kind-declared extensions follow. */
-export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
+export interface LaunchBuildOptions {
     lifecycle: Lifecycle;
     hasManager: boolean;
     extraEnv?: Record<string, string>;
@@ -101,10 +102,23 @@ export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
      *  broker's launch-time/turn-time resolution paths must bypass every
      *  fallback for and fail closed on unavailability. */
     modelExact?: boolean;
-}): {
+}
+/** Build a launch recipe for callers that are not on crtrd's event loop. */
+export declare function buildLaunchSpec(kind: string, mode: Mode, opts: LaunchBuildOptions): {
     launch: LaunchSpec;
     lifecycle: 'terminal' | 'resident';
 };
+/**
+ * Resolve launch config in a bounded subprocess before building a recipe.
+ * crtrd is single-threaded: project/profile roots can live on a network
+ * filesystem, so even an ordinary synchronous config read must never run on
+ * its event loop.
+ */
+export declare function buildLaunchSpecAsync(kind: string, mode: Mode, opts: LaunchBuildOptions): Promise<{
+    launch: LaunchSpec;
+    lifecycle: 'terminal' | 'resident';
+}>;
+export declare function readMergedLaunchConfigAsync(cwd: string, profileId: string | null): Promise<MergedLaunchConfig>;
 export type { PiInvocation } from './invocation.js';
 /** Construct the pi invocation for a node.
  *  - fresh start: pass `prompt` (the node's first user message), no resume.

package/dist/core/runtime/launch.js

@@ -11,6 +11,8 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { readMergedLaunchConfig } from '../config.js';
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { LAUNCH_SYSTEM_PROMPT } from './launch-prompt.js';
 import { nodeEnv } from './nodes.js';
 import { editorLabel } from '../canvas/index.js';
@@ -232,27 +234,7 @@ export function nextLadderModel(currentSpec, direction = 1, providers) {
         return order[0];
     return order[(idx + direction + order.length) % order.length];
 }
-// ---------------------------------------------------------------------------
-// Build the launch spec from {kind, mode}
-// ---------------------------------------------------------------------------
-/** Compose a node's full pi launch recipe from the kind registry. The system
- *  prompt is now a minimal static scaffold (`LAUNCH_SYSTEM_PROMPT`) — runtime/
- *  spine/lifecycle/kind prose is spliced per-turn from gated builtin memory docs,
- *  not baked in here. Launch KNOBS (model/tools/extensions) still come from the
- *  kind registry (`resolveKindConfig`), keyed on the FULL kind string (top-level
- *  or sub-kind). Model precedence, strongest to weakest:
- *   1. Caller-supplied `opts.model` (durable on `meta.model_override`, re-passed
- *      on every polymorph).
- *   2. The kind's registered model — mode-aware: orchestrator mode prefers
- *      `orchestratorModel`, falling back to `model`; base mode always uses
- *      `model`.
- *   3. Unset → pi default.
- *  Callers pass the authoritative lifecycle + hasManager (`parent !== null`) so
- *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
- *  as-given, never derived from persona frontmatter. The two canvas
- *  extensions are always first; kind-declared extensions follow. */
-export function buildLaunchSpec(kind, mode, opts) {
-    const merged = readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null));
+function buildLaunchSpecFromMerged(kind, mode, opts, merged) {
     const kindConfig = merged.kinds[kind];
     const ladders = merged.modelLadders;
     const kindModel = mode === 'orchestrator' ? kindConfig?.orchestratorModel ?? kindConfig?.model : kindConfig?.model;
@@ -274,6 +256,58 @@ export function buildLaunchSpec(kind, mode, opts) {
     };
     return { launch, lifecycle: opts.lifecycle };
 }
+/** Build a launch recipe for callers that are not on crtrd's event loop. */
+export function buildLaunchSpec(kind, mode, opts) {
+    return buildLaunchSpecFromMerged(kind, mode, opts, readMergedLaunchConfig(opts.cwd ?? process.cwd(), opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null)));
+}
+/**
+ * Resolve launch config in a bounded subprocess before building a recipe.
+ * crtrd is single-threaded: project/profile roots can live on a network
+ * filesystem, so even an ordinary synchronous config read must never run on
+ * its event loop.
+ */
+export async function buildLaunchSpecAsync(kind, mode, opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const profileId = opts.profileId !== undefined ? opts.profileId : (process.env['CRTR_PROFILE_ID'] || null);
+    const merged = await readMergedLaunchConfigAsync(cwd, profileId);
+    return buildLaunchSpecFromMerged(kind, mode, opts, merged);
+}
+const LAUNCH_CONFIG_TIMEOUT_MS = 15_000;
+export function readMergedLaunchConfigAsync(cwd, profileId) {
+    return new Promise((resolve, reject) => {
+        const child = fork(fileURLToPath(new URL('./launch-config-worker.js', import.meta.url)), [], {
+            stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+            serialization: 'advanced',
+        });
+        child.send({ cwd, profileId });
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (child.connected)
+                child.disconnect();
+            if (!child.killed)
+                child.kill('SIGKILL');
+            fn();
+        };
+        const timeout = setTimeout(() => finish(() => reject(new Error(`timed out after ${LAUNCH_CONFIG_TIMEOUT_MS}ms reading launch config for ${cwd}`))), LAUNCH_CONFIG_TIMEOUT_MS);
+        child.once('message', (message) => {
+            if (message.error !== undefined)
+                finish(() => reject(new Error(message.error)));
+            else if (message.config !== undefined)
+                finish(() => resolve(message.config));
+            else
+                finish(() => reject(new Error('launch config subprocess returned no result')));
+        });
+        child.once('error', (error) => finish(() => reject(error)));
+        child.once('exit', (code, signal) => {
+            if (code !== 0 && signal !== 'SIGKILL')
+                finish(() => reject(new Error(`launch config subprocess exited with code ${code}`)));
+        });
+    });
+}
 // ---------------------------------------------------------------------------
 // Build the pi argv to launch / revive a node
 // ---------------------------------------------------------------------------

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

@@ -14,13 +14,17 @@ export interface PromoteResult {
  *  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 declare function reshapeNode(nodeId: string, opts?: {
+type ReshapeOptions = {
     kind?: string;
     model?: string;
     mode?: Mode;
     lifecycle?: Lifecycle;
     profileId?: string | null;
-}, beforePersist?: () => void): NodeMeta;
+};
+/** Synchronous reshape for CLI callers outside the daemon. */
+export declare function reshapeNode(nodeId: string, opts?: ReshapeOptions, beforePersist?: () => void): NodeMeta;
+/** Daemon-safe reshape: network-backed config resolution happens off its event loop. */
+export declare function reshapeNodeAsync(nodeId: string, opts?: ReshapeOptions, beforePersist?: () => void): Promise<NodeMeta>;
 /** 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:
@@ -33,6 +37,12 @@ export declare function promote(nodeId: string, opts?: {
     resident?: boolean;
     model?: string;
 }): PromoteResult;
+/** Daemon-safe promotion variant; preserves the same validation/seed ordering. */
+export declare function promoteAsync(nodeId: string, opts?: {
+    kind?: string;
+    resident?: boolean;
+    model?: string;
+}): Promise<PromoteResult>;
 export interface YieldResult {
     meta: NodeMeta;
     /** True iff `promote:true` was passed — a plain yield never flips mode. */
@@ -49,6 +59,13 @@ export interface YieldResult {
  *  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 declare function requestYieldAsync(nodeId: string, opts?: {
+    kind?: string;
+    model?: string;
+    promote?: boolean;
+}, deps?: {
+    ensure?: () => void;
+}): Promise<YieldResult>;
 export declare function requestYield(nodeId: string, opts?: {
     kind?: string;
     model?: string;
@@ -56,3 +73,4 @@ export declare function requestYield(nodeId: string, opts?: {
 }, deps?: {
     ensure?: () => void;
 }): YieldResult;
+export {};