@north-light/crouter 0.3.221 → 0.3.223

package/dist/daemon/api/__tests__/profile-launch-gates.test.js

@@ -1,16 +1,17 @@
 import { after, afterEach, beforeEach, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, getNode, listNodes } from '../../../core/canvas/canvas.js';
 import { closeDb } from '../../../core/canvas/db.js';
 import { CrtrError } from '../../../core/errors.js';
-import { createProfile, loadProfileManifest, pauseProfile, setProfileDefaultKind } from '../../../core/profiles/manifest.js';
+import { createProfile, loadProfileManifest, pauseProfile, profileManifestPath, ROOT_PROFILE_ID, setProfileDefaultKind } from '../../../core/profiles/manifest.js';
 import { resetScopeCache } from '../../../core/scope.js';
 import { reviveNode } from '../../../core/runtime/revive.js';
+import { resolveLaunchTarget } from '../../../core/runtime/launch-target.js';
 import { spawnNode } from '../../../core/runtime/nodes.js';
-import { handleCreate, resolveCreateKind } from '../handlers/nodes.js';
+import { handleConfig, handleCreate, resolveCreateKind } from '../handlers/nodes.js';
 const previousCrtrHome = process.env['CRTR_HOME'];
 const previousHome = process.env.HOME;
 let home = '';
@@ -101,6 +102,54 @@ test('the birth gate refuses a paused profile for a daemon-side spawn', () => {
     });
     assert.equal(listNodes().length, beforeRows);
 });
+test('prospective root selection stays read-only before the root profile is scaffolded', async () => {
+    const manifestPath = profileManifestPath(ROOT_PROFILE_ID);
+    assert.equal(existsSync(manifestPath), false);
+    const target = await resolveLaunchTarget({ root: true, cwd }, { readOnlyProfileSelection: true });
+    assert.equal(target.profileId, ROOT_PROFILE_ID);
+    assert.equal(target.profile, null);
+    assert.equal(target.kind, 'general');
+    assert.equal(target.cwd, cwd);
+    assert.equal(existsSync(manifestPath), false);
+});
+test('target-scoped prospective validation does not rescope node writes', async () => {
+    mkdirSync(join(cwd, '.crouter'), { recursive: true });
+    writeFileSync(join(cwd, '.crouter', 'config.json'), JSON.stringify({
+        kinds: { 'target-only': { whenToUse: 'Only in this project.' } },
+    }));
+    const target = await resolveLaunchTarget({ root: true, cwd, kind: 'target-only' }, { readOnlyProfileSelection: true });
+    assert.equal(target.kind, 'target-only');
+    const create = {
+        method: 'POST',
+        path: '/v1/nodes',
+        params: {},
+        query: new URLSearchParams(),
+        body: { root: true, profile: null, cwd, kind: 'target-only' },
+    };
+    await assert.rejects(() => handleCreate(create), /unknown kind: target-only/);
+    const id = 'ambient-kind-write';
+    createNode({
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent: null,
+        profile_id: null,
+    });
+    const patch = {
+        method: 'PATCH',
+        path: `/v1/nodes/${id}/config`,
+        params: { id },
+        query: new URLSearchParams(),
+        body: { kind: 'target-only' },
+    };
+    await assert.rejects(() => handleConfig(patch), /unknown kind: target-only/);
+    assert.equal(getNode(id)?.kind, 'general');
+});
 test('create kind resolves from the profile default when omitted', () => {
     const profile = createProfile('default kind', [{ path: cwd, memory: 'content' }]);
     setProfileDefaultKind(profile.profileId, 'developer');

package/dist/daemon/api/handlers/human-requests.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const humanRequestRoutes: RouteTable;

package/dist/daemon/api/handlers/human-requests.js

@@ -0,0 +1,409 @@
+// Durable programmatic human requests — crtrd `/v1/human/requests`. A request
+// is an ordinary page ticket with an optional frozen completion action, so it
+// is the same record the inbox lists, answers, and dismisses. Creation is the
+// only surface that writes the action binding; every settlement path funnels
+// through the shared first-writer-wins store.
+import { randomBytes } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { basename, isAbsolute } from 'node:path';
+import { ApiError } from '../../../api/index.js';
+import { readActionDelivery } from '../../../core/canvas/human-deliveries.js';
+import { resolvePageComponents } from '../../../core/config.js';
+import { resolveHumanAction } from '../../../core/human-actions.js';
+import { HUMAN_ACTION_NAME_PATTERN, publishTicketActionBinding, readTicketActionBinding, } from '../../../core/human/action-binding.js';
+import { completionEventFor } from '../../../core/human/completion.js';
+import { parsePage } from '../../../core/human/page.js';
+import { opaqueInboxTicketId, ticketDir } from '../../../core/human/root.js';
+import { preparePageSource, publishPage, readPageTicket, readTicketResult, validatePageTicketResponses, } from '../../../core/human/tickets.js';
+import { cancelHumanTicket, resolvePageTicket } from '../../human/finish.js';
+import { resolveTicket, requireTicketId } from './inbox.js';
+const REASON_MAX = 1000;
+const ACTOR_MAX = 200;
+const DEFAULT_DELIVERY = { placement: 'inline', inbox: true, reply: false };
+const SOURCE_FIELDS = ['sessionName', 'askedBy', 'emittedAt', 'profileName', 'nodeId'];
+// ===========================================================================
+// Body validation
+// ===========================================================================
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNoExtraKeys(obj, allowed, where) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key))
+            throw new ApiError(400, 'invalid_request', `unexpected field in ${where}: ${key}`);
+    }
+}
+function invalid(message) {
+    return new ApiError(400, 'invalid_request', message);
+}
+function validatePage(raw) {
+    if (!isPlainObject(raw))
+        throw invalid('`page` must be an object');
+    requireNoExtraKeys(raw, ['dialect', 'source'], '`page`');
+    const dialect = raw['dialect'];
+    if (dialect !== 'jsx' && dialect !== 'html')
+        throw invalid('`page.dialect` must be "jsx" or "html"');
+    const source = raw['source'];
+    if (typeof source !== 'string' || source.trim() === '')
+        throw invalid('`page.source` must be the authored page text');
+    return { dialect, source };
+}
+/** Creation pins a programmatic request to the inbox with no bridge to reply to. */
+function validateCreateDelivery(raw) {
+    if (raw === undefined)
+        return DEFAULT_DELIVERY;
+    if (!isPlainObject(raw))
+        throw invalid('`delivery` must be an object');
+    requireNoExtraKeys(raw, ['placement', 'inbox', 'reply'], '`delivery`');
+    const placement = validatePlacement(raw['placement'], DEFAULT_DELIVERY.placement);
+    const inbox = raw['inbox'] ?? true;
+    const reply = raw['reply'] ?? false;
+    if (inbox !== true)
+        throw invalid('`delivery.inbox` must be true: a programmatic request must stay answerable');
+    if (reply !== false)
+        throw invalid('`delivery.reply` must be false: a programmatic request has no agent bridge to reply to');
+    return { placement, inbox: true, reply: false };
+}
+/** Replace re-presents a pending page; where the ticket is routed is fixed at
+ * creation, so only placement is replaceable. */
+function validateReplaceDelivery(raw, prior) {
+    if (raw === undefined)
+        return prior;
+    if (!isPlainObject(raw))
+        throw invalid('`delivery` must be an object');
+    requireNoExtraKeys(raw, ['placement'], '`delivery`');
+    return { ...prior, placement: validatePlacement(raw['placement'], prior.placement) };
+}
+function validatePlacement(raw, fallback) {
+    const placement = raw ?? fallback;
+    if (placement !== 'inline' && placement !== 'panel')
+        throw invalid('`delivery.placement` must be "inline" or "panel"');
+    return placement;
+}
+function validateSource(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isPlainObject(raw))
+        throw invalid('`source` must be an object');
+    requireNoExtraKeys(raw, SOURCE_FIELDS, '`source`');
+    const source = {};
+    for (const field of SOURCE_FIELDS) {
+        const value = raw[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'string' || value === '')
+            throw invalid(`\`source.${field}\` must be a nonempty string`);
+        source[field] = value;
+    }
+    return source;
+}
+function validateCreatorCwd(raw) {
+    if (typeof raw !== 'string' || raw === '')
+        throw invalid('`creator_cwd` is required');
+    if (!isAbsolute(raw))
+        throw invalid('`creator_cwd` must be an absolute path');
+    try {
+        if (!statSync(raw).isDirectory())
+            throw invalid(`\`creator_cwd\` is not a directory: ${raw}`);
+    }
+    catch (error) {
+        if (error instanceof ApiError)
+            throw error;
+        throw invalid(`\`creator_cwd\` does not exist: ${raw}`);
+    }
+    return raw;
+}
+function validateActionSelection(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isPlainObject(raw))
+        throw invalid('`action` must be an object');
+    requireNoExtraKeys(raw, ['name', 'payload'], '`action`');
+    const name = raw['name'];
+    if (typeof name !== 'string' || !HUMAN_ACTION_NAME_PATTERN.test(name)) {
+        throw invalid('`action.name` must be a declared action name');
+    }
+    // The completion document always carries `action.payload`, so an omitted one
+    // is normalized here rather than serialized away downstream.
+    return { name, payload: raw['payload'] ?? null };
+}
+function validateCreateRequest(raw) {
+    if (!isPlainObject(raw))
+        throw invalid('request body is required');
+    requireNoExtraKeys(raw, ['page', 'delivery', 'source', 'creator_cwd', 'action'], 'the request body');
+    const source = validateSource(raw['source']);
+    const action = validateActionSelection(raw['action']);
+    return {
+        page: validatePage(raw['page']),
+        delivery: validateCreateDelivery(raw['delivery']),
+        ...(source === undefined ? {} : { source }),
+        creatorCwd: validateCreatorCwd(raw['creator_cwd']),
+        ...(action === undefined ? {} : { action }),
+    };
+}
+function validateReplaceRequest(raw, priorDelivery) {
+    if (!isPlainObject(raw))
+        throw invalid('request body is required');
+    requireNoExtraKeys(raw, ['page', 'delivery'], 'the request body');
+    return { page: validatePage(raw['page']), delivery: validateReplaceDelivery(raw['delivery'], priorDelivery) };
+}
+function optionalBoundedString(raw, field, max) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string')
+        throw invalid(`\`${field}\` must be a string`);
+    if (raw.trim() === '' || raw.length > max)
+        throw invalid(`\`${field}\` must be nonempty after trim and at most ${max} characters`);
+    return raw;
+}
+function validateRespondRequest(raw) {
+    if (!isPlainObject(raw))
+        throw invalid('request body is required');
+    requireNoExtraKeys(raw, ['responses', 'actor'], 'the request body');
+    if (!isPlainObject(raw['responses']))
+        throw invalid('`responses` must be an object');
+    const actor = optionalBoundedString(raw['actor'], 'actor', ACTOR_MAX);
+    return { responses: raw['responses'], ...(actor === undefined ? {} : { actor }) };
+}
+function validateSettleRequest(raw) {
+    if (raw === undefined)
+        return {};
+    if (!isPlainObject(raw))
+        throw invalid('request body must be an object');
+    requireNoExtraKeys(raw, ['reason', 'actor'], 'the request body');
+    const reason = optionalBoundedString(raw['reason'], 'reason', REASON_MAX);
+    const actor = optionalBoundedString(raw['actor'], 'actor', ACTOR_MAX);
+    return { ...(reason === undefined ? {} : { reason }), ...(actor === undefined ? {} : { actor }) };
+}
+function resolveRequest(ctx) {
+    const requestId = requireTicketId({ ticket_id: ctx.params['request_id'] ?? '' });
+    const resolved = resolveTicket(requestId);
+    if (resolved === null || resolved.kind !== 'page')
+        throw new ApiError(404, 'not_found', 'no request with that id');
+    let manifest;
+    try {
+        manifest = parsePage(resolved.dir);
+    }
+    catch {
+        throw new ApiError(500, 'internal', 'the request could not be read');
+    }
+    return {
+        requestId,
+        ticketId: resolved.ticketId,
+        dir: resolved.dir,
+        manifest,
+        result: readTicketResult(resolved.dir),
+        binding: readTicketActionBinding(resolved.dir),
+    };
+}
+function requestState(result) {
+    if (result === null)
+        return 'pending';
+    if (result.kind === 'canceled')
+        return completionEventFor(result);
+    return 'answered';
+}
+function deliveryDetail(row) {
+    if (row === null)
+        return { state: 'none', attempt: 0 };
+    const detail = { state: row.state, attempt: row.attempt };
+    // A next attempt is only meaningful for a pending retry; the enqueue instant
+    // of an untried delivery says nothing a client can act on.
+    if (row.state === 'pending' && row.lastFailure !== null)
+        detail.next_attempt_at = new Date(row.nextAttemptAt).toISOString();
+    if (row.acceptedAt !== null)
+        detail.accepted_at = new Date(row.acceptedAt).toISOString();
+    if (row.permanentFailedAt !== null)
+        detail.permanent_failed_at = new Date(row.permanentFailedAt).toISOString();
+    if (row.lastFailure !== null) {
+        const failure = row.lastFailure;
+        detail.last_failure = {
+            kind: failure.kind,
+            ...(failure.exitCode === undefined ? {} : { exit_code: failure.exitCode }),
+            ...(failure.signal === undefined ? {} : { signal: failure.signal }),
+            ...(failure.message === undefined ? {} : { message: failure.message }),
+            ...(failure.stderr === undefined ? {} : { stderr: failure.stderr }),
+        };
+    }
+    return detail;
+}
+function requestToDTO(request) {
+    const { manifest, result, binding } = request;
+    const emittedAt = manifest.source?.emittedAt;
+    if (emittedAt === undefined)
+        throw new ApiError(500, 'internal', 'the request carries no emitted time');
+    const state = requestState(result);
+    const dto = {
+        request_id: request.requestId,
+        state,
+        title: manifest.title,
+        source: manifest.source ?? {},
+        emitted_at: emittedAt,
+    };
+    if (manifest.subtitle !== undefined)
+        dto.subtitle = manifest.subtitle;
+    if (result !== null) {
+        dto.settled_at = result.kind === 'canceled' ? result.canceledAt : result.completedAt;
+        // Never fabricated for a dismissal or a withdrawal: only an answer has responses.
+        if (state === 'answered' && result.kind === 'page')
+            dto.responses = result.responses;
+        if (result.kind === 'canceled' && result.reason !== undefined)
+            dto.reason = result.reason;
+        const actor = result.kind === 'review' ? undefined : result.actor;
+        if (actor !== undefined)
+            dto.actor = actor;
+    }
+    if (binding !== null) {
+        dto.action = { name: binding.name, payload: binding.payload };
+        dto.delivery = deliveryDetail(readActionDelivery(request.requestId));
+    }
+    return dto;
+}
+// ===========================================================================
+// POST /v1/human/requests — create
+// ===========================================================================
+/** Authoring failure is the caller's malformed page, never a server fault. */
+function prepareOrReject(dialect, document, source, delivery) {
+    try {
+        return preparePageSource({ dialect, document, source, delivery, productKinds: resolvePageComponents() });
+    }
+    catch (error) {
+        throw invalid(error instanceof Error ? error.message : 'the page could not be prepared');
+    }
+}
+function handleCreate(ctx) {
+    const request = validateCreateRequest(ctx.body);
+    // Action resolution precedes every write: a rejected action must leave no
+    // inbox row for a human to answer.
+    let resolvedAction;
+    if (request.action !== undefined) {
+        const resolution = resolveHumanAction(request.action.name, request.creatorCwd);
+        if ('kind' in resolution) {
+            const detail = resolution.kind === 'unknown_action'
+                ? `no action named ${resolution.name} is declared from ${request.creatorCwd}`
+                : `${resolution.name} is declared in ${resolution.configOrigin} but unusable: ${resolution.reason}`;
+            throw new ApiError(400, resolution.kind, detail);
+        }
+        resolvedAction = resolution;
+    }
+    const prepared = prepareOrReject(request.page.dialect, request.page.source, request.source, request.delivery);
+    const dir = ticketDir(`page-${randomBytes(8).toString('hex')}`);
+    // The binding is written before the page exists, so a visible request is
+    // never momentarily unbound and `replace` can never reach the approved effect.
+    if (request.action !== undefined && resolvedAction !== undefined) {
+        publishTicketActionBinding(dir, {
+            schema: 'crtr.human-action-binding/v1',
+            name: request.action.name,
+            payload: request.action.payload,
+            creatorCwd: request.creatorCwd,
+            configOrigin: resolvedAction.configOrigin,
+            argv: resolvedAction.argv,
+            cwd: resolvedAction.cwd,
+        });
+    }
+    const published = publishPage(dir, prepared);
+    return {
+        status: 201,
+        body: {
+            request_id: opaqueInboxTicketId(basename(published.dir)),
+            state: 'pending',
+            ...(request.action === undefined ? {} : { action: { name: request.action.name } }),
+            delivery_state: 'none',
+        },
+    };
+}
+// ===========================================================================
+// GET /v1/human/requests/:request_id — read
+// ===========================================================================
+function handleGet(ctx) {
+    return { status: 200, body: requestToDTO(resolveRequest(ctx)) };
+}
+// ===========================================================================
+// POST /v1/human/requests/:request_id/replace — revise the pending page
+// ===========================================================================
+function handleReplace(ctx) {
+    const request = resolveRequest(ctx);
+    if (request.result !== null)
+        throw new ApiError(409, 'already_settled', 'the request already has a terminal result');
+    const body = validateReplaceRequest(ctx.body, request.manifest.delivery);
+    // Identity and provenance are the creation's, verbatim — a revision changes
+    // only what is on screen, never who asked or when.
+    const prepared = prepareOrReject(body.page.dialect, body.page.source, request.manifest.source, body.delivery);
+    publishPage(request.dir, prepared);
+    return { status: 200, body: requestToDTO({ ...request, manifest: prepared.manifest }) };
+}
+// ===========================================================================
+// Settlement — respond, dismiss, cancel
+// ===========================================================================
+/** The settlement funnels speak the inbox's error vocabulary; requests speak
+ * the wire contract's. This is the one translation. */
+function settlementError(error) {
+    if (error instanceof ApiError) {
+        if (error.code === 'ticket_already_resolved')
+            return new ApiError(409, 'already_settled', 'the request already has a terminal result');
+        if (error.code === 'page_has_no_response_lifecycle')
+            return new ApiError(409, 'not_settleable', 'this request carries no response lifecycle');
+        return error;
+    }
+    if (error instanceof Error && error.message === 'page_has_no_response_lifecycle') {
+        return new ApiError(409, 'not_settleable', 'this request carries no response lifecycle');
+    }
+    return new ApiError(500, 'internal', 'the request could not be settled');
+}
+function requireSettleable(request) {
+    if (request.result !== null)
+        throw new ApiError(409, 'already_settled', 'the request already has a terminal result');
+    if (readPageTicket(request.dir).state === 'passive') {
+        throw new ApiError(409, 'not_settleable', 'this request carries no response lifecycle');
+    }
+}
+async function handleRespond(ctx) {
+    const request = resolveRequest(ctx);
+    const body = validateRespondRequest(ctx.body);
+    requireSettleable(request);
+    try {
+        validatePageTicketResponses(request.dir, body.responses);
+    }
+    catch (error) {
+        // `requireSettleable` already refused a page with no response lifecycle, so
+        // anything left here is the caller's response map.
+        throw invalid(error instanceof Error ? error.message : 'the response map is invalid');
+    }
+    let result;
+    try {
+        result = await resolvePageTicket(request.ticketId, body.responses, body.actor === undefined ? {} : { actor: body.actor });
+    }
+    catch (error) {
+        throw settlementError(error);
+    }
+    return { status: 200, body: requestToDTO({ ...request, result, binding: request.binding }) };
+}
+async function settle(ctx, disposition) {
+    const request = resolveRequest(ctx);
+    const body = validateSettleRequest(ctx.body);
+    requireSettleable(request);
+    let result;
+    try {
+        result = await cancelHumanTicket(request.ticketId, { ...body, disposition });
+    }
+    catch (error) {
+        throw settlementError(error);
+    }
+    return { status: 200, body: requestToDTO({ ...request, result }) };
+}
+/** The recipient surface deliberately closing the request without answering. */
+function handleDismiss(ctx) {
+    return settle(ctx, 'dismissed');
+}
+/** The requester withdrawing its own request. */
+function handleCancel(ctx) {
+    return settle(ctx, 'canceled');
+}
+export const humanRequestRoutes = [
+    { method: 'POST', pattern: '/v1/human/requests', handler: handleCreate },
+    { method: 'GET', pattern: '/v1/human/requests/:request_id', handler: handleGet },
+    { method: 'POST', pattern: '/v1/human/requests/:request_id/replace', handler: handleReplace },
+    { method: 'POST', pattern: '/v1/human/requests/:request_id/respond', handler: handleRespond },
+    { method: 'POST', pattern: '/v1/human/requests/:request_id/dismiss', handler: handleDismiss },
+    { method: 'POST', pattern: '/v1/human/requests/:request_id/cancel', handler: handleCancel },
+];

package/dist/daemon/api/handlers/human.js

@@ -108,6 +108,9 @@ async function handleCancel(ctx) {
     if (request !== undefined && (typeof request !== 'object' || request === null)) {
         throw new ApiError(400, 'invalid_request', 'ticket cancel body must be an object');
     }
+    if (request?.disposition !== undefined && request.disposition !== 'canceled' && request.disposition !== 'dismissed') {
+        throw new ApiError(400, 'invalid_request', '`disposition` must be "canceled" or "dismissed"');
+    }
     const dir = ticketDir(ticketId);
     const review = getReviewByBridge(ticketId);
     try {

package/dist/daemon/api/handlers/inbox.js

@@ -364,6 +364,9 @@ async function handleCancel(ctx) {
         const result = await cancelHumanTicket(resolved.ticketId, {
             reason: request.reason ?? DEFAULT_CANCEL_REASON,
             actor: 'human',
+            // This is the recipient surface: closing a request here is a dismissal,
+            // never the requester withdrawing it.
+            disposition: 'dismissed',
         });
         if (result.kind !== 'canceled')
             throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');

package/dist/daemon/api/handlers/nodes.d.ts

@@ -1,14 +1,12 @@
 import { type ModelRegistryLike } from '../../../core/model-routes.js';
-import { assertProfileActive } from '../../../core/profiles/manifest.js';
 import type { HandlerResult, RequestContext, RouteTable } from '../router.js';
 interface NodeHandlerDeps {
     modelRegistry?: ModelRegistryLike;
 }
-export declare function resolveCreateKind(kind: string | undefined, profile: ReturnType<typeof assertProfileActive>): string;
+export { resolveCreateKind } from '../../../core/runtime/launch-target.js';
 export declare function handleCreate(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare function handleList(ctx: RequestContext): HandlerResult;
 export declare function handlePromote(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare function handleYield(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare function handleConfig(ctx: RequestContext, deps?: NodeHandlerDeps): Promise<HandlerResult>;
 export declare const nodeRoutes: RouteTable;
-export {};

package/dist/daemon/api/handlers/nodes.js

@@ -7,10 +7,10 @@
 //
 // `{id}` is the target node.
 import { readdirSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
+import { basename } from 'node:path';
 import { appendSituationalContext, closeNode, getNode, listNodes, nowIso, reviveNode, } from '../../../index.js';
 import { formatSituationalProse } from '../../../core/runtime/situational-context.js';
-import { assertLaunchModelRegistered, forkNode, resolveProfileId, spawnChild } from '../../../core/runtime/spawn.js';
+import { assertLaunchModelRegistered, forkNode, spawnChild } from '../../../core/runtime/spawn.js';
 import { childrenOf, subscribersOf, subscriptionsOf, setMessageWait, updateNode } from '../../../core/canvas/canvas.js';
 import { subtreeIds } from '../../../core/canvas/nav-model.js';
 import { ticketCountsForNodes } from '../../../core/canvas/attention.js';
@@ -32,7 +32,7 @@ import { BrokerUnreachableError } from '../../../core/runtime/broker-request.js'
 import { isBrokerLive, persistDormantModel, setModelLive } from '../../../core/runtime/model-swap.js';
 import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
 import { claimWarmNode, refillWarmPool, warmPoolEnabled } from '../../../core/runtime/warm-pool.js';
-import { assertProfileActive, profileHome } from '../../../core/profiles/manifest.js';
+import { resolveLaunchTarget } from '../../../core/runtime/launch-target.js';
 import { fullName } from '../../../core/canvas/labels.js';
 import { reportsForNode } from './reports.js';
 import { getCron } from '../../../core/canvas/crons.js';
@@ -99,28 +99,6 @@ function parseCreateBody(body) {
     }
     return b;
 }
-/** The directory a new node is pinned to. An explicit `pin_cwd` wins; else a
- *  managed child inherits its spawner's cwd (which is what keeps a worktree
- *  node's whole subtree inside that worktree); else the launch's own `cwd`, the
- *  directory the create came from; else the profile's home.
- *
- *  The launch directory beating the profile home is what lets one profile cover
- *  many working directories — a root started inside a planted instance runs in
- *  that instance while still taking its identity, purview, and memory from the
- *  profile covering it. The profile supplies a home only for a create that named
- *  no directory at all. */
-function resolveNodeCwd(req, parent, profileId, contextCwd) {
-    if (req.pin_cwd !== undefined && req.pin_cwd !== '')
-        return resolve(req.pin_cwd);
-    if (parent != null) {
-        const spawner = getNode(parent);
-        if (spawner !== null)
-            return spawner.cwd;
-    }
-    if (req.cwd !== undefined && req.cwd !== '')
-        return resolve(req.cwd);
-    return profileHome(profileId) ?? contextCwd;
-}
 /** Build the immediate spawn recipe. */
 function buildRecipe(req, parent, cwd) {
     const recipe = {
@@ -185,9 +163,7 @@ function warmRequestFor(req, cwd, profileId) {
         name: req.name ?? null,
     };
 }
-export function resolveCreateKind(kind, profile) {
-    return kind ?? profile?.manifest.default_kind ?? 'general';
-}
+export { resolveCreateKind } from '../../../core/runtime/launch-target.js';
 function requestFromLaunch(launch) {
     const intent = launch.modelIntent === undefined
         ? undefined
@@ -229,20 +205,8 @@ export async function handleCreate(ctx, deps = {}) {
     // Resolve and validate the exact launch recipe before the warm pool can claim
     // a spare (or the cold path can create a worktree/node). The registry belongs
     // to this daemon, never to the possibly-remote CLI caller.
-    const contextCwd = req.cwd ?? process.cwd();
-    const profileId = await resolveProfileId(req.profile, parent ?? null, contextCwd);
-    const profile = assertProfileActive(profileId);
-    const kind = resolveCreateKind(req.kind, profile);
+    const { profileId, kind, cwd, launch } = await resolveLaunchTarget(req, { validateKind: assertKindServer });
     const resolvedReq = { ...req, kind };
-    const cwd = resolveNodeCwd(resolvedReq, parent, profileId, contextCwd);
-    await assertKindServer(kind, cwd, profileId);
-    const launch = (await buildLaunchSpecAsync(kind, (resolvedReq.mode ?? 'base'), {
-        lifecycle: req.root === true ? (req.root_lifecycle ?? 'resident') : 'terminal',
-        hasManager: req.root !== true,
-        ...(req.model !== undefined ? { model: req.model } : {}),
-        cwd,
-        profileId,
-    })).launch;
     await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd, profileId }, deps.modelRegistry);
     // --- Warm path: hand out an already-booted spare instead of paying a full
     //     engine boot. A miss is not a failure — it falls through to the cold
@@ -680,7 +644,7 @@ export async function handleConfig(ctx, deps = {}) {
     // --- kind / mode / lifecycle: reshape via canonical primitive (CLI parity). ---
     if (patch.kind !== undefined || patch.mode !== undefined || patch.lifecycle !== undefined) {
         if (patch.kind !== undefined)
-            await assertKindServer(patch.kind, meta.cwd, meta.profile_id ?? null);
+            await assertKindServer(patch.kind);
         const newKind = patch.kind ?? meta.kind;
         const newMode = (patch.mode ?? meta.mode);
         const newLifecycle = patch.lifecycle ?? meta.lifecycle;
@@ -712,10 +676,11 @@ export async function handleConfig(ctx, deps = {}) {
     // to receive it, so it is a documented Stage-A no-op here.
     return { status: 200, body: detailOf(id) };
 }
-/** Validate a `--kind` against the installed personas server-side (crtrd reads
- *  the merged launch config). Mirrors the CLI's assertKind. */
-async function assertKindServer(kind, cwd, profileId) {
-    const kinds = Object.keys((await readMergedLaunchConfigAsync(cwd, profileId)).kinds);
+/** POST /v1/nodes and PATCH /v1/nodes/:id/config validate kinds in the daemon's
+ * ambient configuration; prospective reads validate their resolved target. The
+ * read is subprocess-isolated — crtrd must never resolve config on its own loop. */
+async function assertKindServer(kind) {
+    const kinds = Object.keys((await readMergedLaunchConfigAsync(process.cwd(), process.env['CRTR_PROFILE_ID'] || null)).kinds);
     if (!kinds.includes(kind)) {
         throw usage(`unknown kind: ${kind}`, { received: kind, next: `Valid kinds: ${kinds.sort().join(', ')}.` });
     }

package/dist/daemon/api/handlers/prospective-chat-inventory.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const prospectiveChatInventoryRoutes: RouteTable;