@north-light/api 0.3.560 → 0.3.562

package/dist/core/profiles/manifest.js

@@ -1,15 +1,13 @@
 // Profile definitions live in scoped state; memory and environment have separate roots.
 import { randomUUID } from 'node:crypto';
 import { existsSync, realpathSync, rmSync, statSync } from 'node:fs';
-import { join, resolve as resolvePath } from 'node:path';
+import { resolve as resolvePath } from 'node:path';
 import { SCHEMA_VERSION } from '../../types.js';
 import { profileSpace } from '../layout.js';
 import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
-import { userScopeRoot } from '../scope.js';
 import { ensureDir, nowIso } from '../fs-utils.js';
-import { deleteStoredProfile, getStoredProfile, insertStoredProfile, listStoredProfiles, pausedProfileIds, profilePaused, updateStoredProfile } from '../scoped-state/profiles.js';
+import { cachedPausedProfileIds, cachedProfilePaused, getCachedProfile as getStoredProfile, listCachedProfiles, writeSettings } from '../scoped-state/person-store.js';
 import { usage, notFound, ambiguous, general } from '../errors.js';
-import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 import { fuzzyMatchProfile } from './fuzzy-match.js';
 // A generated id and its stored app determine the memory and environment paths.
 /** `<slug>-<shortid>`: slug is lower-case, non-alphanumeric collapsed to `-`,
@@ -33,7 +31,7 @@ function assertSafeProfileId(profileId) {
 }
 export function profileDir(profileId) {
     assertSafeProfileId(profileId);
-    const stored = getStoredProfile(userScopeRoot(), profileId);
+    const stored = getStoredProfile(profileId);
     if (stored === null)
         throw notFound(`profile not found: ${profileId}`, { received: profileId });
     return profileSpace(profileApp(stored.manifest), profileId).dir;
@@ -61,7 +59,7 @@ export function assertDeliveryLimits(value) {
             throw usage(`invalid delivery limit for ${handle}: ${JSON.stringify(level)}`, { received: String(level), field: 'delivery_limits', next: `Set ${handle} to one of: ${levels}.` });
     }
 }
-function enumerateProfiles() { return { entries: listStoredProfiles(userScopeRoot()), unreadableIds: [] }; }
+function enumerateProfiles() { return { entries: listCachedProfiles(), unreadableIds: [] }; }
 export function listProfiles() { return enumerateProfiles().entries; }
 export function lookupProfile(profileIdOrName) { const entries = listProfiles(); const exact = findExactProfile(entries, profileIdOrName, entryCandidate); return exact ? { kind: 'resolved', entry: exact } : { kind: 'absent' }; }
 // Three resolvers, in descending tolerance. `resolveProfileOperand` is what a
@@ -75,7 +73,7 @@ export function lookupProfile(profileIdOrName) { const entries = listProfiles();
  * Used at persistence gates that already hold a resolved durable identity. */
 export function loadExactProfileManifest(profileId) {
     assertSafeProfileId(profileId);
-    const stored = getStoredProfile(userScopeRoot(), profileId);
+    const stored = getStoredProfile(profileId);
     if (stored !== null)
         return stored;
     throw notFound(`profile not found: ${profileId}`, { received: profileId, next: 'Run `crtr profile list` to see available profiles.' });
@@ -159,19 +157,6 @@ export function matchProfileOperand(all, operand, key) {
     }
     throw profileNotFound(all, operand, key);
 }
-function locksDir() { return join(userScopeRoot(), 'profile-locks'); }
-/** 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());
-    return withExclusiveDirectoryLock(join(locksDir(), `${profileId}.lock`), fn, {
-        timeoutError: () => general(`timed out waiting for the profile lock: ${profileId}`, {
-            next: 'Retry — another `crtr profile` command may be running concurrently on this profile.',
-        }),
-    });
-}
 // 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) {
@@ -212,32 +197,30 @@ function generateProfileId(name) {
     for (let attempt = 0; attempt < 20; attempt++) {
         const shortId = randomUUID().replace(/-/g, '').slice(0, 8);
         const candidate = `${slug}-${shortId}`;
-        if (getStoredProfile(userScopeRoot(), candidate) === null)
+        if (getStoredProfile(candidate) === null)
             return candidate;
     }
     throw general(`failed to generate a unique profile id for "${name}" after 20 attempts`);
 }
 // Mutations — all under withProfileManifestLock, all atomic writes.
-export function ensureRootProfile() {
-    return withProfileManifestLock(ROOT_PROFILE_ID, () => {
-        const existing = getStoredProfile(userScopeRoot(), ROOT_PROFILE_ID);
-        if (existing !== null) {
-            scaffoldProfile(ROOT_PROFILE_ID, existing.manifest);
-            return existing;
-        }
-        const next = {
-            schema_version: SCHEMA_VERSION,
-            name: ROOT_PROFILE_NAME,
-            projects: [],
-            grantee: 'app:terminal',
-            paused_at: null,
-            created_at: nowIso(),
-            last_used_at: nowIso(),
-        };
-        scaffoldProfile(ROOT_PROFILE_ID, next);
-        insertStoredProfile(userScopeRoot(), { profileId: ROOT_PROFILE_ID, manifest: next });
-        return { profileId: ROOT_PROFILE_ID, manifest: next };
-    });
+export async function ensureRootProfile() {
+    const existing = getStoredProfile(ROOT_PROFILE_ID);
+    if (existing !== null) {
+        scaffoldProfile(ROOT_PROFILE_ID, existing.manifest);
+        return existing;
+    }
+    const next = {
+        schema_version: SCHEMA_VERSION,
+        name: ROOT_PROFILE_NAME,
+        projects: [],
+        grantee: 'app:terminal',
+        paused_at: null,
+        created_at: nowIso(),
+        last_used_at: nowIso(),
+    };
+    scaffoldProfile(ROOT_PROFILE_ID, next);
+    await writeSettings((snapshot) => snapshot.profiles.some((p) => p.profileId === ROOT_PROFILE_ID) ? [] : [{ op: 'profile.insert', profile: { profileId: ROOT_PROFILE_ID, manifest: next } }]);
+    return getStoredProfile(ROOT_PROFILE_ID);
 }
 /** Key shape every stored metadata entry must satisfy — kept env-mappable
  *  (`CRTR_PROFILE_META_<KEY>`, see `core/runtime/spawn-env.ts`) by
@@ -316,7 +299,7 @@ export function sanitizeProfileMetadata(stored) {
     }
     return out;
 }
-export function createProfile(name, projects = [], opts = {}) {
+export async function createProfile(name, projects = [], opts = {}) {
     const trimmed = name.trim();
     if (trimmed === '')
         throw usage('profile name must not be empty');
@@ -325,24 +308,22 @@ export function createProfile(name, projects = [], opts = {}) {
     assertProfileProjects(projects);
     const resolvedProjects = dedupeProjects(projects.map((p) => ({ path: resolveExistingProjectDir(p.path) })));
     const profileId = generateProfileId(trimmed);
-    return withProfileManifestLock(profileId, () => {
-        const manifest = {
-            schema_version: SCHEMA_VERSION,
-            name: trimmed,
-            projects: resolvedProjects,
-            paused_at: null,
-            ...(opts.grantee === undefined ? {} : { grantee: opts.grantee }),
-            ...(opts.defaultKind !== undefined ? { default_kind: opts.defaultKind } : {}),
-            ...(opts.metadata !== undefined && Object.keys(opts.metadata).length > 0 ? { metadata: { ...opts.metadata } } : {}),
-            created_at: nowIso(),
-            last_used_at: null,
-        };
-        scaffoldProfile(profileId, manifest);
-        insertStoredProfile(userScopeRoot(), { profileId, manifest });
-        return { profileId, manifest };
-    });
-}
-export function ensureAppProfile(grantee) {
+    const manifest = {
+        schema_version: SCHEMA_VERSION,
+        name: trimmed,
+        projects: resolvedProjects,
+        paused_at: null,
+        ...(opts.grantee === undefined ? {} : { grantee: opts.grantee }),
+        ...(opts.defaultKind !== undefined ? { default_kind: opts.defaultKind } : {}),
+        ...(opts.metadata !== undefined && Object.keys(opts.metadata).length > 0 ? { metadata: { ...opts.metadata } } : {}),
+        created_at: nowIso(),
+        last_used_at: null,
+    };
+    scaffoldProfile(profileId, manifest);
+    await writeSettings(() => [{ op: 'profile.insert', profile: { profileId, manifest } }]);
+    return { profileId, manifest };
+}
+export async function ensureAppProfile(grantee) {
     if (!grantee.startsWith('app:') || grantee.length <= 4)
         throw usage('an app grantee is required');
     const name = `app-${grantee.slice(4)}`;
@@ -351,24 +332,27 @@ export function ensureAppProfile(grantee) {
         throw new Error(`duplicate default profile for ${grantee}`);
     if (existing[0])
         return existing[0];
-    return createProfile(name, [], { grantee });
+    return await createProfile(name, [], { grantee });
 }
 function requireExistingProfile(profileId) {
     assertSafeProfileId(profileId);
-    if (getStoredProfile(userScopeRoot(), profileId) === null)
+    if (getStoredProfile(profileId) === null)
         throw notFound(`profile not found: ${profileId}`, { received: profileId, next: 'Run `crtr profile list` to see available profiles.' });
 }
-function mutateManifest(profileId, mutate) {
+async function mutateManifest(profileId, mutate) {
     requireExistingProfile(profileId);
-    return withProfileManifestLock(profileId, () => {
-        const result = updateStoredProfile(userScopeRoot(), profileId, mutate);
-        if (result === null)
+    let result;
+    await writeSettings((snapshot) => {
+        const current = snapshot.profiles.find((p) => p.profileId === profileId);
+        if (current === undefined)
             throw notFound(`profile not found: ${profileId}`, { received: profileId });
-        return result;
+        result = { profileId, manifest: mutate(structuredClone(current.manifest)) };
+        return [{ op: 'profile.update', profile: result }];
     });
+    return result;
 }
-export function updateProfileLastUsed(profileId) {
-    return mutateManifest(profileId, (m) => ({ ...m, last_used_at: nowIso() }));
+export async function updateProfileLastUsed(profileId) {
+    return await mutateManifest(profileId, (m) => ({ ...m, last_used_at: nowIso() }));
 }
 /** Resolve an existing profile for a launch gate without making stale durable
  * profile ids a new failure mode on a hot path. */
@@ -390,17 +374,13 @@ function loadProfileManifestOrNull(profileId) {
 export function isProfilePaused(profileId) {
     if (profileId === null || profileId === undefined || profileId === '')
         return false;
-    try {
-        assertSafeProfileId(profileId);
-        return profilePaused(userScopeRoot(), profileId);
-    }
-    catch {
+    if (!ID_SHAPE.test(profileId))
         return false;
-    }
+    return cachedProfilePaused(profileId);
 }
 /** One set-based pause read for canvas-wide projections. */
 export function pausedCanvasProfiles() {
-    return pausedProfileIds(userScopeRoot());
+    return cachedPausedProfileIds();
 }
 /** Refuse a launch under a paused profile, naming the resume command. Shared by
  * every gate that already holds a loaded manifest. */
@@ -419,25 +399,25 @@ export function assertProfileActive(profileId) {
     assertProfileEntryActive(entry);
     return entry;
 }
-export function pauseProfile(profileId) {
-    return mutateManifest(profileId, (m) => ({ ...m, paused_at: m.paused_at ?? nowIso() }));
+export async function pauseProfile(profileId) {
+    return await mutateManifest(profileId, (m) => ({ ...m, paused_at: m.paused_at ?? nowIso() }));
 }
-export function resumeProfile(profileId) {
+export async function resumeProfile(profileId) {
     let pausedAt = null;
-    const entry = mutateManifest(profileId, (m) => {
+    const entry = await mutateManifest(profileId, (m) => {
         pausedAt = m.paused_at;
         return { ...m, paused_at: null };
     });
     return { ...entry, pausedAt };
 }
-export function setProfileDefaultKind(profileId, defaultKind) {
-    return mutateManifest(profileId, (m) => ({ ...m, default_kind: defaultKind }));
+export async function setProfileDefaultKind(profileId, defaultKind) {
+    return await mutateManifest(profileId, (m) => ({ ...m, default_kind: defaultKind }));
 }
 /** Merge `set` entries over the stored map and drop `unset` keys; the
  *  `metadata` field is omitted entirely when the result is empty. */
-export function updateProfileMetadata(profileId, set, unset = []) {
+export async function updateProfileMetadata(profileId, set, unset = []) {
     assertProfileMetadata(set);
-    return mutateManifest(profileId, (m) => {
+    return await mutateManifest(profileId, (m) => {
         const next = { ...sanitizeProfileMetadata(m.metadata), ...set };
         for (const key of unset)
             delete next[key];
@@ -467,32 +447,32 @@ export function readProfileMetadata(profileId) {
 /** Change the manifest `name` only. Callers that own the canvas (the daemon's
  *  `PATCH /v1/profiles/:name`) must also rename the profile's canvas handle —
  *  use `renameProfileAndHandle` there; the CLI and panels go through that route. */
-export function renameProfile(profileId, name) {
+export async 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 }));
+    const result = await mutateManifest(profileId, (m) => ({ ...m, name: trimmed }));
     return result;
 }
 /** A new path appends; a path already listed keeps its position. */
-export function addProfileProject(profileId, dir) {
+export async function addProfileProject(profileId, dir) {
     assertProfileProjects([{ path: dir }]);
     const resolved = resolveExistingProjectDir(dir);
-    const result = mutateManifest(profileId, (m) => ({ ...m, projects: dedupeProjects([...m.projects, { path: resolved }]) }));
+    const result = await mutateManifest(profileId, (m) => ({ ...m, projects: dedupeProjects([...m.projects, { path: resolved }]) }));
     return result;
 }
 /** Set one owner's automatic delivery limit. `content` is the uncapped level,
  *  so it removes the owner's entry instead of storing it. */
-export function setProfileDeliveryLimit(profileId, owner, level) {
+export async function setProfileDeliveryLimit(profileId, owner, level) {
     assertDeliveryLimits({ [owner]: level });
-    return mutateManifest(profileId, (m) => {
+    return await mutateManifest(profileId, (m) => {
         const { [owner]: _previous, ...rest } = m.delivery_limits ?? {};
         const limits = level === 'content' ? rest : { ...rest, [owner]: level };
         const { delivery_limits: _old, ...base } = m;
         return Object.keys(limits).length === 0 ? base : { ...base, delivery_limits: limits };
     });
 }
-export function removeProfileProject(profileId, dir) {
+export async 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
@@ -505,7 +485,7 @@ export function removeProfileProject(profileId, dir) {
     catch {
         /* dir no longer exists — fall back to comparing by its resolved path */
     }
-    const result = mutateManifest(profileId, (m) => {
+    const result = await mutateManifest(profileId, (m) => {
         const filtered = m.projects.filter((p) => p.path !== real && p.path !== abs);
         if (filtered.length === m.projects.length) {
             throw notFound(`project not found on profile: ${dir}`, {
@@ -517,13 +497,14 @@ export function removeProfileProject(profileId, dir) {
     });
     return result;
 }
-export function deleteProfile(profileId) {
+export async function deleteProfile(profileId) {
     requireExistingProfile(profileId);
-    withProfileManifestLock(profileId, () => {
-        const space = profileSpace(profileApp(loadExactProfileManifest(profileId).manifest), profileId);
-        if (!deleteStoredProfile(userScopeRoot(), profileId))
+    const space = profileSpace(profileApp(loadExactProfileManifest(profileId).manifest), profileId);
+    await writeSettings((snapshot) => {
+        if (!snapshot.profiles.some((p) => p.profileId === profileId))
             throw notFound(`profile not found: ${profileId}`, { received: profileId });
-        rmSync(space.dir, { recursive: true, force: true });
-        rmSync(space.env, { force: true });
+        return [{ op: 'profile.delete', profileId }];
     });
+    rmSync(space.dir, { recursive: true, force: true });
+    rmSync(space.env, { force: true });
 }

package/dist/core/runtime/broker/attachments-fetch.d.ts

@@ -0,0 +1,5 @@
+/** Download every attachment of this node's run that is not already on the broker's disk (D98). The control plane puts
+ *  each fetched upload in the blob store and records it on the run; the files are written where the run's prompt names
+ *  them. Run before the broker hands the agent a prompt or mail. A failed download throws: the agent must not be told
+ *  of a path that holds nothing. */
+export declare function fetchRunAttachments(nodeId: string): Promise<void>;

package/dist/core/runtime/broker/attachments-fetch.js

@@ -0,0 +1,20 @@
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { daemonClient } from './daemon-ops.js';
+/** Download every attachment of this node's run that is not already on the broker's disk (D98). The control plane puts
+ *  each fetched upload in the blob store and records it on the run; the files are written where the run's prompt names
+ *  them. Run before the broker hands the agent a prompt or mail. A failed download throws: the agent must not be told
+ *  of a path that holds nothing. */
+export async function fetchRunAttachments(nodeId) {
+    const client = daemonClient();
+    const { attachments } = await client.listNodeAttachments(nodeId);
+    for (const file of attachments) {
+        if (existsSync(file.path))
+            continue;
+        const bytes = await client.readNodeAttachment(nodeId, file.sha256);
+        mkdirSync(dirname(file.path), { recursive: true });
+        const partial = `${file.path}.partial`;
+        writeFileSync(partial, bytes);
+        renameSync(partial, file.path);
+    }
+}

package/dist/core/runtime/broker/daemon-ops.d.ts

@@ -1,11 +1,16 @@
+import { CrtrClient } from '../../../api/client.js';
 import { type BrokerSignalCachedNode } from '../../../daemon/broker-signals/bus.js';
 import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerParkActivityResultDTO, BrokerParkCompleteRequest, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest, BrokerTelemetryRequest } from '../../../api/dto/broker-ops.js';
 import type { AcknowledgeMailResultDTO, ClaimMailResultDTO, MailReceiptDTO } from '../../../api/dto/mail.js';
 import type { BrokerFaultInputDTO, BrokerFaultRequest, BrokerFaultResultDTO, BrokerProviderRetryRequest, BrokerProviderRetryResultDTO, BrokerTurnRequest, BrokerTurnResultDTO, RecoveryStateDTO } from '../../../api/dto/recovery.js';
 import type { RelaunchRootResultDTO } from '../../../api/dto/lifecycle.js';
 import type { PushReportRequest } from '../../../api/dto/reports.js';
-import type { BackgroundedJobDTO, BackgroundedJobRequest, DeliveryRequest, DeliveryResponse } from '../../../api/dto/delivery.js';
+import type { BackgroundedJobDTO, BackgroundedJobRequest, JobReportRequest, DeliveryRequest, DeliveryResponse } from '../../../api/dto/delivery.js';
 import type { NodeLogAppendResultDTO, NodeMessageBodyDTO, NodePushedFinalResultDTO, NodeTelemetryRecordRequest } from '../../../api/dto/node-records.js';
+/** Where this broker reaches `/v1`: `CRTR_API_URL` when the launcher set one (an http(s) URL in a
+ *  sandbox), else the local API socket. */
+export declare function brokerApiUrl(): string | undefined;
+export declare function daemonClient(): CrtrClient;
 export declare function appendBrokerLog(nodeId: string, record: string): Promise<NodeLogAppendResultDTO>;
 export declare function putBrokerTelemetry(nodeId: string, telemetry: Omit<NodeTelemetryRecordRequest, 'expected_execution_id'>): Promise<void>;
 export declare function putBrokerRecap(nodeId: string, briefing: string): Promise<void>;
@@ -22,15 +27,19 @@ export declare function startBrokerBashJob(nodeId: string, request: {
 }>;
 /** Record a command the valve just backgrounded as this node's job object. */
 export declare function recordBackgroundedJob(nodeId: string, jobId: string, request: BackgroundedJobRequest): Promise<BackgroundedJobDTO>;
+/** Report on a job this broker runs: process identity, activity, output, exit. */
+export declare function reportBrokerJob(nodeId: string, jobId: string, request: Omit<JobReportRequest, 'expected_execution_id'>): Promise<void>;
 export declare function stopBrokerBashJob(nodeId: string, jobId: string): Promise<void>;
 export declare function brokerExecutionId(): string;
 export declare function bindBrokerSession(nodeId: string, request: Omit<BrokerSessionBoundRequest, 'executionId'>): Promise<BrokerSessionBoundResultDTO>;
 type BrokerInput<T> = T extends unknown ? Omit<T, 'expected_execution_id'> : never;
 export declare function settleBroker(nodeId: string, request: BrokerInput<BrokerSettleRequest>): Promise<BrokerSettleDirective>;
+export declare function postBrokerIdle(nodeId: string): Promise<void>;
 export declare function completeBrokerPark(nodeId: string, request: BrokerInput<BrokerParkCompleteRequest>): Promise<BrokerSettleDirective>;
 export declare function recordBrokerParkActivity(nodeId: string): Promise<BrokerParkActivityResultDTO>;
 export declare function recordBrokerTelemetry(nodeId: string, request: Omit<BrokerTelemetryRequest, 'expected_execution_id'>): Promise<void>;
 export declare function claimBrokerMail(nodeId: string, channel: 'wake' | 'passive' | 'deferred_run', reportBodies: Map<string, Promise<string>>): Promise<ClaimMailResultDTO>;
+/** Mail is settled only after the entries the turn wrote are durable: a failed flush rejects and nothing is acknowledged. */
 export declare function acknowledgeBrokerMail(nodeId: string, deliveries: MailReceiptDTO[]): Promise<AcknowledgeMailResultDTO>;
 export declare function recordBrokerTurn(nodeId: string, request: Omit<BrokerTurnRequest, 'expected_execution_id'>): Promise<BrokerTurnResultDTO>;
 export declare function mutateBrokerProviderRetry(nodeId: string, request: Omit<BrokerProviderRetryRequest, 'expected_execution_id'>): Promise<BrokerProviderRetryResultDTO>;

package/dist/core/runtime/broker/daemon-ops.js

@@ -1,14 +1,33 @@
 // Broker-to-daemon operation client. A broker is launched by crtrd, so a cold
 // daemon socket must fail loud — it must never use the CLI factory that can
 // autostart another daemon.
+import { CrtrClient } from '../../../api/client.js';
+import { currentNodeToken } from './node-token.js';
 import { localClient } from '../../../api/node-transport.js';
 import { ApiError } from '../../../api/errors.js';
 import { envExecutionId } from '../../../shared/env.js';
 import { brokerSignalClient } from './signal-stream.js';
 import { cachedBrokerNodeFields } from '../../../daemon/broker-signals/bus.js';
+import { fetchRunAttachments } from './attachments-fetch.js';
 import { reportRefNodeId } from '../../../shared/inbox-entry-body.js';
-function daemonClient() {
-    return localClient({ autostart: false });
+/** Where this broker reaches `/v1`: `CRTR_API_URL` when the launcher set one (an http(s) URL in a
+ *  sandbox), else the local API socket. */
+export function brokerApiUrl() {
+    const url = process.env['CRTR_API_URL'];
+    if (url === undefined || url === '')
+        return undefined;
+    if (!/^https?:\/\//.test(url))
+        throw new Error(`CRTR_API_URL must be an http(s) URL: ${url}`);
+    return url;
+}
+export function daemonClient() {
+    const url = brokerApiUrl();
+    if (url === undefined)
+        return localClient({ autostart: false });
+    const token = currentNodeToken();
+    if (token === undefined)
+        throw new Error('broker has no node token for CRTR_API_URL');
+    return new CrtrClient({ baseUrl: url, headers: { authorization: `Bearer ${token}` } });
 }
 export function appendBrokerLog(nodeId, record) {
     return daemonClient().appendNodeLog(nodeId, { record, expected_execution_id: brokerExecutionId() });
@@ -38,6 +57,10 @@ export function startBrokerBashJob(nodeId, request) {
 export function recordBackgroundedJob(nodeId, jobId, request) {
     return daemonClient().recordBackgroundedJob(nodeId, jobId, request);
 }
+/** Report on a job this broker runs: process identity, activity, output, exit. */
+export function reportBrokerJob(nodeId, jobId, request) {
+    return daemonClient().reportBashJob(nodeId, jobId, { ...request, expected_execution_id: brokerExecutionId() });
+}
 export function stopBrokerBashJob(nodeId, jobId) {
     return daemonClient().request('DELETE', `/v1/nodes/${encodeURIComponent(nodeId)}/jobs/${encodeURIComponent(jobId)}?foreground=1`, {
         expected_execution_id: brokerExecutionId(),
@@ -55,6 +78,9 @@ export function bindBrokerSession(nodeId, request) {
 export function settleBroker(nodeId, request) {
     return daemonClient().settleBroker(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
 }
+export function postBrokerIdle(nodeId) {
+    return daemonClient().postBrokerIdle(nodeId, { expected_execution_id: brokerExecutionId() });
+}
 export function completeBrokerPark(nodeId, request) {
     return daemonClient().completeBrokerPark(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
 }
@@ -64,12 +90,21 @@ export function recordBrokerParkActivity(nodeId) {
 export function recordBrokerTelemetry(nodeId, request) {
     return daemonClient().recordBrokerTelemetry(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
 }
+/** Entries whose run attachments this broker has already downloaded. */
+const attachmentsChecked = new Set();
 export async function claimBrokerMail(nodeId, channel, reportBodies) {
     const client = daemonClient();
     const executionId = brokerExecutionId();
     const result = await client.claimNodeMail(nodeId, { execution_id: executionId, channel });
     if (result.action === 'hold')
         return result;
+    // Mail the agent has not seen may name a file of this run's attachments (D98): have it on disk before the mail is handed over.
+    const fresh = result.deliveries.filter((delivery) => !attachmentsChecked.has(delivery.entry.entry_id));
+    if (fresh.length > 0) {
+        await fetchRunAttachments(nodeId);
+        for (const delivery of fresh)
+            attachmentsChecked.add(delivery.entry.entry_id);
+    }
     const deliveries = await Promise.all(result.deliveries.map(async (delivery) => {
         const ref = delivery.entry.ref;
         if (ref === undefined || reportRefNodeId(ref) === undefined)
@@ -103,7 +138,10 @@ export async function claimBrokerMail(nodeId, channel, reportBodies) {
     }
     return { ...result, deliveries };
 }
-export function acknowledgeBrokerMail(nodeId, deliveries) {
+/** Mail is settled only after the entries the turn wrote are durable: a failed flush rejects and nothing is acknowledged. */
+export async function acknowledgeBrokerMail(nodeId, deliveries) {
+    // Loaded on use: the store's index pulls in the pi engine, which a thin CLI leaf must not load.
+    await (await import('../../conversation-store/index.js')).flushConversation();
     return daemonClient().acknowledgeNodeMail(nodeId, { execution_id: brokerExecutionId(), deliveries });
 }
 export function recordBrokerTurn(nodeId, request) {

package/dist/core/runtime/broker/node-token.d.ts

@@ -0,0 +1,3 @@
+/** fd 3 is a one-shot pipe from the daemon, not a file or an environment value. */
+export declare function receiveNodeToken(): Promise<string>;
+export declare function currentNodeToken(): string | undefined;

package/dist/core/runtime/broker/node-token.js

@@ -0,0 +1,16 @@
+import { createReadStream } from 'node:fs';
+let token = null;
+/** fd 3 is a one-shot pipe from the daemon, not a file or an environment value. */
+export async function receiveNodeToken() {
+    if (token !== null)
+        throw new Error('node token was already received');
+    const chunks = [];
+    for await (const chunk of createReadStream('', { fd: 3, autoClose: true }))
+        chunks.push(Buffer.from(chunk));
+    const received = Buffer.concat(chunks).toString('utf8');
+    if (!/^[A-Za-z0-9_-]{43}$/.test(received))
+        throw new Error('broker received an invalid node token');
+    token = received;
+    return received;
+}
+export function currentNodeToken() { return token ?? undefined; }

package/dist/core/runtime/broker/signal-stream.js

@@ -1,6 +1,6 @@
 // Process-wide broker signal connection. Pi's Jiti loader evaluates extensions in
 // another module graph, so a module-local singleton would open duplicate streams.
-import { localClient } from '../../../api/node-transport.js';
+import { daemonClient } from './daemon-ops.js';
 import { ApiError } from '../../../api/errors.js';
 const KEY = Symbol.for('@crouton-kit/crtr:broker-signal-client');
 export class BrokerSignalClient {
@@ -84,7 +84,7 @@ export class BrokerSignalClient {
         this.controller = controller;
         void (async () => {
             try {
-                for await (const line of localClient({ autostart: false }).getBrokerSignals(this.nodeId, this.executionId, { signal: controller.signal, maxRetries: 0 })) {
+                for await (const line of daemonClient().getBrokerSignals(this.nodeId, this.executionId, { signal: controller.signal, maxRetries: 0 })) {
                     if (!this.running || this.controller !== controller)
                         return;
                     this.armHeartbeat(controller);

package/dist/core/scoped-state/materialized-plugins.d.ts

@@ -0,0 +1,18 @@
+/** One enabled plugin row of the person's user scope, with its marketplace's url and ref. */
+export interface PluginInstall {
+    name: string;
+    version: string | null;
+    sourcePath: string | null;
+    marketplace: {
+        name: string;
+        url: string | null;
+        ref: string | null;
+    } | null;
+}
+/** The directory holding this person's materialized plugins as `<dir>/<plugin name>`; undefined when none were materialized. */
+export declare function materializedPluginsDir(person: string): string | undefined;
+/** Install `installs` for `person` at `revision` into this process's plugin cache, once per (person, revision). When a plugin cannot
+ *  be installed — a source on another machine, a marketplace that does not list it, a failed clone — the failure is held for that person
+ *  and thrown by the next read of their plugins (`materializedPluginsDir`), so a request that never reads plugins, such as the one that
+ *  fixes the settings, still works; the next load retries. */
+export declare function materializePlugins(person: string, revision: number, installs: readonly PluginInstall[]): Promise<void>;