@north-light/api 0.3.561 → 0.3.563

package/dist/api/routes.d.ts

@@ -13,6 +13,8 @@ export declare const routes: {
     readonly reviveAll: () => string;
     readonly node: (id: string) => string;
     readonly nodeMemoryReads: (id: string) => string;
+    readonly executionStart: (id: string) => string;
+    readonly environmentGitCredential: (id: string) => string;
     readonly nodeOutcome: (id: string) => string;
     readonly nodeOutcomeDelivery: (id: string) => string;
     readonly nodeEvents: (id: string) => string;
@@ -27,6 +29,7 @@ export declare const routes: {
     readonly nodeResult: (id: string) => string;
     readonly nodeJobs: (id: string) => string;
     readonly nodeJob: (id: string, jobId: string) => string;
+    readonly nodeJobReport: (id: string, jobId: string) => string;
     readonly nodeJobBackground: (id: string, jobId: string) => string;
     readonly nodeDelivery: (id: string) => string;
     readonly deliveryDryRun: () => string;
@@ -38,10 +41,14 @@ export declare const routes: {
     readonly nodeRelaunchRoot: (id: string) => string;
     readonly nodeBrokerSessionBound: (id: string) => string;
     readonly nodeBrokerSettle: (id: string) => string;
+    readonly nodeBrokerIdle: (id: string) => string;
     readonly nodeBrokerParkComplete: (id: string) => string;
     readonly nodeBrokerParkActivity: (id: string) => string;
     readonly nodeBrokerTelemetry: (id: string) => string;
     readonly nodeLog: (id: string) => string;
+    readonly nodeSummaries: (id: string) => string;
+    readonly nodeAttachments: (id: string) => string;
+    readonly nodeAttachment: (id: string, sha256: string) => string;
     readonly nodeTelemetry: (id: string) => string;
     readonly nodeRecap: (id: string) => string;
     readonly nodeInboxReport: (id: string) => string;
@@ -52,6 +59,8 @@ export declare const routes: {
     readonly nodeBrokerModel: (id: string) => string;
     readonly nodeBrokerExtensionState: (id: string) => string;
     readonly nodeBrokerSignals: (id: string) => string;
+    readonly nodeBrokerStructuredRequest: (id: string) => string;
+    readonly nodeBrokerGoal: (id: string) => string;
     readonly nodeBrokerGeneratedName: (id: string) => string;
     readonly nodeBrokerPersonaAck: (id: string) => string;
     readonly brokerTurn: (id: string) => string;
@@ -140,9 +149,11 @@ export declare const routes: {
     readonly appEnvVar: (variable: string) => string;
     readonly profileEnv: (name: string) => string;
     readonly profileEnvVar: (name: string, variable: string) => string;
+    readonly settings: () => string;
     readonly modelAuths: () => string;
     readonly modelAuthReadiness: () => string;
     readonly modelAuth: (provider: string) => string;
+    readonly modelAuthAccount: (provider: string, label: string) => string;
     readonly modelAuthFlows: () => string;
     readonly modelAuthFlow: (flowId: string) => string;
     readonly modelAuthFlowComplete: (flowId: string) => string;

package/dist/api/routes.js

@@ -28,6 +28,8 @@ export const routes = {
     reviveAll: () => `${V}/nodes/revive-all`,
     node: (id) => `${V}/nodes/${id}`,
     nodeMemoryReads: (id) => `${V}/nodes/${id}/memory-reads`,
+    executionStart: (id) => `${V}/executions/${id}/start`,
+    environmentGitCredential: (id) => `${V}/environments/${id}/git-credential`,
     nodeOutcome: (id) => `${V}/nodes/${id}/outcome`,
     nodeOutcomeDelivery: (id) => `${V}/nodes/${id}/outcome-delivery`,
     nodeEvents: (id) => `${V}/nodes/${id}/events`,
@@ -43,6 +45,7 @@ export const routes = {
     nodeResult: (id) => `${V}/nodes/${id}/result`,
     nodeJobs: (id) => `${V}/nodes/${id}/jobs`,
     nodeJob: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}`,
+    nodeJobReport: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}/report`,
     nodeJobBackground: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}/background`,
     nodeDelivery: (id) => `${V}/nodes/${id}/delivery`,
     deliveryDryRun: () => `${V}/delivery/dry-run`,
@@ -56,10 +59,14 @@ export const routes = {
     nodeRelaunchRoot: (id) => `${V}/nodes/${id}/relaunch-root`,
     nodeBrokerSessionBound: (id) => `${V}/nodes/${id}/broker/session-bound`,
     nodeBrokerSettle: (id) => `${V}/nodes/${id}/broker/settle`,
+    nodeBrokerIdle: (id) => `${V}/nodes/${id}/broker/idle`,
     nodeBrokerParkComplete: (id) => `${V}/nodes/${id}/broker/park-complete`,
     nodeBrokerParkActivity: (id) => `${V}/nodes/${id}/broker/park-activity`,
     nodeBrokerTelemetry: (id) => `${V}/nodes/${id}/broker/telemetry`,
     nodeLog: (id) => `${V}/nodes/${id}/records/log`,
+    nodeSummaries: (id) => `${V}/nodes/${id}/records/summaries`,
+    nodeAttachments: (id) => `${V}/nodes/${id}/attachments`,
+    nodeAttachment: (id, sha256) => `${V}/nodes/${id}/attachments/${sha256}`,
     nodeTelemetry: (id) => `${V}/nodes/${id}/records/telemetry`,
     nodeRecap: (id) => `${V}/nodes/${id}/records/recap`,
     nodeInboxReport: (id) => `${V}/nodes/${id}/records/inbox`,
@@ -70,6 +77,8 @@ export const routes = {
     nodeBrokerModel: (id) => `${V}/nodes/${id}/broker/model`,
     nodeBrokerExtensionState: (id) => `${V}/nodes/${id}/broker/extension-state`,
     nodeBrokerSignals: (id) => `${V}/nodes/${id}/broker/signals`,
+    nodeBrokerStructuredRequest: (id) => `${V}/nodes/${id}/broker/structured-request`,
+    nodeBrokerGoal: (id) => `${V}/nodes/${id}/broker/goal`,
     nodeBrokerGeneratedName: (id) => `${V}/nodes/${id}/broker/generated-name`,
     nodeBrokerPersonaAck: (id) => `${V}/nodes/${id}/broker/persona-ack`,
     brokerTurn: (id) => `${V}/broker/${id}/turn`,
@@ -168,10 +177,13 @@ export const routes = {
     appEnvVar: (variable) => `${V}/apps/self/env/${encodeURIComponent(variable)}`,
     profileEnv: (name) => `${V}/profiles/${name}/env`,
     profileEnvVar: (name, variable) => `${V}/profiles/${name}/env/${variable}`,
+    // Person settings
+    settings: () => `${V}/settings`,
     // Model auth
     modelAuths: () => `${V}/model-auth`,
     modelAuthReadiness: () => `${V}/model-auth/readiness`,
     modelAuth: (provider) => `${V}/model-auth/${provider}`,
+    modelAuthAccount: (provider, label) => `${V}/model-auth/${provider}/accounts/${encodeURIComponent(label)}`,
     modelAuthFlows: () => `${V}/model-auth/flows`,
     modelAuthFlow: (flowId) => `${V}/model-auth/flows/${encodeURIComponent(flowId)}`,
     modelAuthFlowComplete: (flowId) => `${V}/model-auth/flows/${encodeURIComponent(flowId)}/complete`,

package/dist/core/canvas/paths.d.ts

@@ -71,7 +71,6 @@ export declare function inboxPath(nodeId: string): string;
 export declare function situationalContextPath(nodeId: string): string;
 export declare function passivePath(nodeId: string): string;
 export declare function transcriptPath(nodeId: string): string;
-export declare function sessionPtrPath(nodeId: string): string;
 /** Create the full directory skeleton for a node. Idempotent. The agent and
  *  run folders are app-writable, so their subfolders are made beneath them. */
 export declare function ensureNodeDirs(nodeId: string, grantee: string): void;

package/dist/core/canvas/paths.js

@@ -152,9 +152,6 @@ export function passivePath(nodeId) {
 export function transcriptPath(nodeId) {
     return join(nodeDir(nodeId), 'transcript.jsonl');
 }
-export function sessionPtrPath(nodeId) {
-    return join(nodeDir(nodeId), 'session.ptr');
-}
 /** Create the full directory skeleton for a node. Idempotent. The agent and
  *  run folders are app-writable, so their subfolders are made beneath them. */
 export function ensureNodeDirs(nodeId, grantee) {

package/dist/core/canvas/person-state.d.ts

@@ -0,0 +1,26 @@
+/** Thrown by `personId()` before the person is known (a hosted first boot, before its first grant snapshot). */
+export declare class PersonUnresolvedError extends Error {
+    readonly code = "person_unresolved";
+    constructor();
+}
+/** Thrown by `personId()` on a cloud role (`crtrd --role api|reconcile`) outside a request: the control plane serves many people and
+ *  has no install person to fall back to. A lane that works for a person takes the person from the row it claimed. */
+export declare class PersonOutsideRequestError extends Error {
+    readonly code = "person_outside_request";
+    constructor();
+}
+/** crtrd sets this once at boot; it wins unconditionally. */
+export declare function setPersonId(id: string): void;
+/** crtrd calls this at boot on a cloud role, instead of resolving a person: from then on a person read outside a request throws. */
+export declare function markCloudRole(): void;
+/** Whether this process is a cloud role (`markCloudRole` ran at boot). */
+export declare function isCloudRole(): boolean;
+/** Run `fn` as `person` (`user:<id>`, the request token's `sub`): every `personId()` inside it, across awaits, answers `person`. */
+export declare function runAsPerson<T>(person: string, fn: () => T): T;
+/** The request's person; else, on a Mac, the boot-set person. Throws `PersonOutsideRequestError` on a cloud role outside a request and
+ *  `PersonUnresolvedError` when a Mac's person is not bound. Tests and non-daemon processes use `personIdAsync()`. */
+export declare function personId(): string;
+/** The boot-set person, if any (for `personIdAsync`). */
+export declare function bootPersonId(): string | undefined;
+/** The request's person, if any (for `personIdAsync`). */
+export declare function requestPersonId(): string | undefined;

package/dist/core/canvas/person-state.js

@@ -0,0 +1,41 @@
+// person-state.ts — the process's person binding (boot-set person, cloud-role flag, per-request person). Pure: no database, so the
+// CLI-reachable settings cache can read the current person without reaching canvas state.
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Thrown by `personId()` before the person is known (a hosted first boot, before its first grant snapshot). */
+export class PersonUnresolvedError extends Error {
+    code = 'person_unresolved';
+    constructor() { super('the install\'s person is not resolved yet'); this.name = 'PersonUnresolvedError'; }
+}
+/** Thrown by `personId()` on a cloud role (`crtrd --role api|reconcile`) outside a request: the control plane serves many people and
+ *  has no install person to fall back to. A lane that works for a person takes the person from the row it claimed. */
+export class PersonOutsideRequestError extends Error {
+    code = 'person_outside_request';
+    constructor() { super('no person: a cloud role reads the person only inside a request, from its token'); this.name = 'PersonOutsideRequestError'; }
+}
+let daemonPersonId;
+let cloudRole = false;
+const requestPersons = new AsyncLocalStorage();
+/** crtrd sets this once at boot; it wins unconditionally. */
+export function setPersonId(id) { daemonPersonId = id; }
+/** crtrd calls this at boot on a cloud role, instead of resolving a person: from then on a person read outside a request throws. */
+export function markCloudRole() { cloudRole = true; }
+/** Whether this process is a cloud role (`markCloudRole` ran at boot). */
+export function isCloudRole() { return cloudRole; }
+/** Run `fn` as `person` (`user:<id>`, the request token's `sub`): every `personId()` inside it, across awaits, answers `person`. */
+export function runAsPerson(person, fn) { return requestPersons.run(person, fn); }
+/** The request's person; else, on a Mac, the boot-set person. Throws `PersonOutsideRequestError` on a cloud role outside a request and
+ *  `PersonUnresolvedError` when a Mac's person is not bound. Tests and non-daemon processes use `personIdAsync()`. */
+export function personId() {
+    const request = requestPersons.getStore();
+    if (request !== undefined)
+        return request;
+    if (cloudRole)
+        throw new PersonOutsideRequestError();
+    if (daemonPersonId === undefined)
+        throw new PersonUnresolvedError();
+    return daemonPersonId;
+}
+/** The boot-set person, if any (for `personIdAsync`). */
+export function bootPersonId() { return daemonPersonId; }
+/** The request's person, if any (for `personIdAsync`). */
+export function requestPersonId() { return requestPersons.getStore(); }

package/dist/core/command-plugins/bundle.d.ts

@@ -98,7 +98,7 @@ export declare function isInstalledGeneration(name: string, scope: Scope, root:
  *  are recorded either way, because both describe the bytes now at the root. */
 export declare function recordCheckedGeneration(scope: Scope, name: string, etag: string | undefined, options: {
     swapped: boolean;
-}): void;
+}): Promise<void>;
 /** Every file lands by temp file plus rename, fsynced, so a crash mid-write leaves the previous bytes or
  *  the whole new ones — never a 0-byte `plugin.json` or `commands.json` that crashes the next boot. */
 export declare function writeStagedBundle(stagingRoot: string, manifest: PluginManifest, bundle: ValidatedBundle): void;

package/dist/core/command-plugins/bundle.js

@@ -474,8 +474,8 @@ export function isInstalledGeneration(name, scope, root, version) {
 /** The ledger for a check that reached a served archive. `swapped` says whether
  *  that archive replaced the package on disk; the validator and the check time
  *  are recorded either way, because both describe the bytes now at the root. */
-export function recordCheckedGeneration(scope, name, etag, options) {
-    updateState(scope, (state) => {
+export async function recordCheckedGeneration(scope, name, etag, options) {
+    await updateState(scope, (state) => {
         if (state.plugins[name] === undefined)
             state.plugins[name] = {};
         if (options.swapped)
@@ -598,10 +598,10 @@ export async function installBundleArchive(name, raw, options) {
     // rewritten. The forbidden state — a validator for a generation the disk does
     // not have, and so a permanent 304 against a package that was never unpacked
     // — is unreachable from this order.
-    ensureScopeInitialized(scope, scopeRootPath);
-    updateConfig(scope, (cfg) => {
+    await ensureScopeInitialized(scope, scopeRootPath);
+    await updateConfig(scope, (cfg) => {
         cfg.plugins[name] = { enabled: options.enable ? true : (cfg.plugins[name]?.enabled ?? true), version };
     });
-    recordCheckedGeneration(scope, name, options.etag, { swapped: true });
+    await recordCheckedGeneration(scope, name, options.etag, { swapped: true });
     return { manifest, validated, version, root, staged };
 }

package/dist/core/config.d.ts

@@ -1,6 +1,6 @@
 import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig, ProviderOptionsConfig } from '../types.js';
 import { type BindingId } from './keybindings/catalog.js';
-import type { RotationConfig } from './subscription-state.js';
+import type { RotationConfig } from './managed-providers.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
 export interface BrokerConfigSnapshot {
@@ -26,16 +26,17 @@ 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): {
+export declare function replaceRawSettingsForTarget(target: RawSettingsTarget, next: Record<string, unknown>, ifRevision: string): Promise<{
     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;
-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;
+export declare function updateRawConfigAtomically(scope: Scope, mutate: (latest: RawConfig) => RawConfig): Promise<RawConfig>;
+export declare function writeConfig(scope: Scope, config: ScopeConfig): Promise<void>;
+export declare function writeRawConfig(scope: Scope, config: Partial<ScopeConfig>): Promise<void>;
+export declare function writeState(scope: Scope, state: ScopeState): Promise<void>;
+/** A project scope is a directory holding `config.json`; the user and profile scopes are the person's rows and need no directory setup. */
+export declare function ensureScopeInitialized(scope: Scope, root: string): Promise<void>;
 /** Normalize the user-owned list of attach actions allowed to bridge through an
  * occupied tmux root binding. Unknown and non-attach ids have no effect. */
 export declare function normalizeTmuxPassthrough(raw: unknown): BindingId[];
@@ -207,16 +208,16 @@ export declare function persistModelLadders(root: string, patch: {
     defaultProvider?: ModelProvider;
     anthropic?: Partial<Record<ModelStrength, string>>;
     openai?: Partial<Record<ModelStrength, string>>;
-}): void;
+}): Promise<void>;
 /** Persist one complete route at one exact config root. The route is the only
  * raw route entry touched; unrelated routes and local ladder defaults remain
  * absent. Pass `undefined` to remove this scope's entry, which resumes lower
  * scope inheritance rather than introducing a tombstone. */
-export declare function persistModelRoute(root: string, routeId: string, route: ModelRouteConfig | undefined): void;
+export declare function persistModelRoute(root: string, routeId: string, route: ModelRouteConfig | undefined): Promise<void>;
 /** Mutate one exact config root. Setup uses this for profile and explicit
  * project targets that cannot be represented by the user/project Scope enum. */
-export declare function updateConfigAtRoot(root: string, mutate: (cfg: ScopeConfig) => void): ScopeConfig;
-export declare function updateConfig(scope: Scope, mutate: (cfg: ScopeConfig) => void): ScopeConfig;
+export declare function updateConfigAtRoot(root: string, mutate: (cfg: ScopeConfig) => void): Promise<ScopeConfig>;
+export declare function updateConfig(scope: Scope, mutate: (cfg: ScopeConfig) => void): Promise<ScopeConfig>;
 /** Persist one sparse kind-model field at an exact config root. The sparse
  * patch keeps every unrelated kind and launch knob inherited from lower
  * scopes instead of freezing a materialized registry snapshot. */
@@ -225,9 +226,9 @@ export declare function persistDefaultKindModel(opts: {
     kind: string;
     model: string;
     orchestrator?: boolean;
-}): {
+}): Promise<{
     path: string;
     field: 'model' | 'orchestratorModel';
-};
-export declare function updateState(scope: Scope, mutate: (s: ScopeState) => void): ScopeState;
+}>;
+export declare function updateState(scope: Scope, mutate: (s: ScopeState) => void): Promise<ScopeState>;
 export {};

package/dist/core/config.js

@@ -10,9 +10,8 @@ import { atomicWriteJson, readJsonIfExists, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots, userScopeRoot } from './scope.js';
 import { listInstalledPluginsInRoot } from './installed-plugins.js';
 import { profileDir, listProfiles } from './profiles/manifest.js';
-import { canonicalRoot, projectStore, userStore } from './scoped-state/paths.js';
-import { convertLegacyScopedStore, initializeFreshScopedStore } from './scoped-state/migrate.js';
-import { mutateRawSettings, readBookkeeping, readRawSettings, readRawSettingsWithRevision, replaceRawSettings, writeBookkeeping, writeRawSettings } from './scoped-state/settings.js';
+import { canonicalRoot } from './scoped-state/paths.js';
+import { readCachedSettings, readCachedState, revisionOf, SettingsRevisionConflictError, writeSettings } from './scoped-state/person-store.js';
 import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
 import { normalizeWorkingGerunds } from '../shared/working-activity.js';
@@ -39,23 +38,18 @@ function settingsOwnerForRoot(root) {
     const canonical = canonicalRoot(root);
     const userRoot = canonicalRoot(userScopeRoot());
     if (canonical === userRoot)
-        return { store: userStore(userRoot), key: 'user', kind: 'user', root: userRoot };
-    // Project roots can be classified without opening the user store. This keeps a
-    // fresh project usable when an unrelated legacy user root still needs conversion.
-    if (basename(canonical) === '.crouter') {
-        convertLegacyScopedStore({ kind: 'project', root: canonical });
-        return { store: projectStore(canonical), key: 'project', kind: 'project', root: canonical };
-    }
+        return { key: 'user', kind: 'user', root: userRoot };
+    if (basename(canonical) === '.crouter')
+        return { key: 'project', kind: 'project', root: canonical };
     for (const profile of listProfiles()) {
         const profilePath = canonicalRoot(profileDir(profile.profileId));
         if (canonical === profilePath)
-            return { store: userStore(userRoot), key: `profile:${profile.profileId}`, kind: 'profile', root: profilePath, profileId: profile.profileId };
+            return { key: `profile:${profile.profileId}`, kind: 'profile', root: profilePath, profileId: profile.profileId };
     }
     throw new Error(`settings root is not a recognized owner: ${root}`);
 }
 function readRawAtRoot(root) {
-    // Project configuration is a file; reading it must not initialize SQL state
-    // (or its lock directory) after the project disappears.
+    // Project configuration is a file; reading it must not touch the person's rows (or its lock directory) after the project disappears.
     if (basename(root) === '.crouter') {
         let canonical;
         try {
@@ -69,21 +63,33 @@ function readRawAtRoot(root) {
         if (canonical !== canonicalRoot(userScopeRoot()))
             return readJsonIfExists(configPathFor(root));
     }
-    return readRawSettings(settingsOwnerForRoot(root));
+    return readCachedSettings(settingsOwnerForRoot(root).key).settings;
+}
+/** Replace a user or profile owner's settings through the one write algorithm: `compute` runs against the cached raw settings and
+ *  runs again if the rows changed underneath it. */
+async function mutatePersonSettings(key, mutate) {
+    let value;
+    await writeSettings((snapshot) => {
+        const current = snapshot.settings[key];
+        const result = mutate(structuredClone(current ?? {}));
+        value = result.value;
+        return [{ op: 'settings.replace', owner: key, raw: result.next, ifRevision: revisionOf(current) }];
+    });
+    return value;
 }
-function writeRawAtRoot(root, raw) {
+async function writeRawAtRoot(root, raw) {
     const owner = settingsOwnerForRoot(root);
     if (owner.kind === 'project') {
         withConfigPathLock(configPathFor(owner.root), (path) => atomicWriteJson(path, raw, { createParent: false }));
         return;
     }
-    writeRawSettings(owner, raw);
+    await mutatePersonSettings(owner.key, () => ({ value: undefined, next: raw }));
 }
-function mutateRawAtRoot(root, mutate) {
+async function mutateRawAtRoot(root, mutate) {
     const owner = settingsOwnerForRoot(root);
     if (owner.kind === 'project')
         return withConfigPathLock(configPathFor(owner.root), (path) => { const result = mutate(readJsonIfExists(path) ?? {}); atomicWriteJson(path, result.next, { createParent: false }); return result.value; });
-    return mutateRawSettings(owner, (raw) => mutate(raw));
+    return await mutatePersonSettings(owner.key, mutate);
 }
 const brokerSnapshotState = globalThis;
 const brokerSnapshotKey = Symbol.for('crtr.broker.config-snapshot');
@@ -104,18 +110,17 @@ export function readConfig(scope) {
     return root ? readConfigAtRoot(root) : defaultScopeConfig();
 }
 export function readConfigAtRoot(root) { const existing = readRawAtRoot(root); return existing ? mergeConfig(existing) : defaultScopeConfig(); }
+function readProjectState(root) {
+    const raw = readJsonIfExists(statePathFor(root));
+    return { marketplaces: raw?.marketplaces ?? {}, plugins: raw?.plugins ?? {}, activeCanvas: raw?.activeCanvas ?? null, ...(raw?.last_self_check === undefined ? {} : { last_self_check: raw.last_self_check }) };
+}
 export function readState(scope) {
     const root = scopeRoot(scope);
     if (!root)
         return defaultScopeState();
-    try {
-        return readBookkeeping(settingsOwnerForRoot(root));
-    }
-    catch (error) {
-        if (scope === 'project' && !existsSync(root))
-            return defaultScopeState();
-        throw error;
-    }
+    if (scope === 'project')
+        return existsSync(root) ? readProjectState(root) : defaultScopeState();
+    return readCachedState(settingsOwnerForRoot(root).key);
 }
 export class InvalidRawSettingsError extends Error {
     constructor(cause) {
@@ -123,53 +128,64 @@ export class InvalidRawSettingsError extends Error {
         this.name = 'InvalidRawSettingsError';
     }
 }
-function rawSettingsOwnerForTarget(target) {
+function rawSettingsKeyForTarget(target) {
     if (target.scope === 'user')
-        return settingsOwnerForRoot(userScopeRoot());
+        return 'user';
     if (!listProfiles().some((profile) => profile.profileId === target.profileId)) {
         throw notFound(`profile not found: ${target.profileId}`, { received: target.profileId, next: 'Run `crtr profile list` to see available profiles.' });
     }
-    return settingsOwnerForRoot(profileDir(target.profileId));
+    return `profile:${target.profileId}`;
 }
 export function readRawSettingsForTarget(target) {
-    return readRawSettingsWithRevision(rawSettingsOwnerForTarget(target));
-}
-export function replaceRawSettingsForTarget(target, next, ifRevision) {
-    return replaceRawSettings(rawSettingsOwnerForTarget(target), next, ifRevision, (settings) => {
-        try {
-            mergeConfig(settings);
-        }
-        catch (error) {
-            throw new InvalidRawSettingsError(error);
-        }
-    });
+    return readCachedSettings(rawSettingsKeyForTarget(target));
 }
-export function updateRawConfigAtomically(scope, mutate) { const root = requireScopeRoot(scope); return mutateRawAtRoot(root, (latest) => { const next = mutate(latest); return { value: next, next }; }); }
-export function writeConfig(scope, config) { writeRawAtRoot(requireScopeRoot(scope), config); }
-export function writeRawConfig(scope, config) { writeRawAtRoot(requireScopeRoot(scope), config); }
-export function writeState(scope, state) { const root = requireScopeRoot(scope); writeBookkeeping(settingsOwnerForRoot(root), state); }
-export function ensureScopeInitialized(scope, root) {
+export async function replaceRawSettingsForTarget(target, next, ifRevision) {
+    const key = rawSettingsKeyForTarget(target);
+    try {
+        mergeConfig(next);
+    }
+    catch (error) {
+        throw new InvalidRawSettingsError(error);
+    }
+    const before = readCachedSettings(key);
+    if (before.revision !== ifRevision)
+        throw new SettingsRevisionConflictError();
+    const after = await writeSettings((snapshot) => (revisionOf(snapshot.settings[key]) === ifRevision
+        ? [{ op: 'settings.replace', owner: key, raw: next, ifRevision }] : (() => { throw new SettingsRevisionConflictError(); })()));
+    const revision = revisionOf(after.settings[key]);
+    return { revision, changed: revision !== ifRevision };
+}
+export async function updateRawConfigAtomically(scope, mutate) { const root = requireScopeRoot(scope); return await mutateRawAtRoot(root, (latest) => { const next = mutate(latest); return { value: next, next }; }); }
+export async function writeConfig(scope, config) { await writeRawAtRoot(requireScopeRoot(scope), config); }
+export async function writeRawConfig(scope, config) { await writeRawAtRoot(requireScopeRoot(scope), config); }
+function writeProjectState(root, state) { withConfigPathLock(statePathFor(root), (path) => atomicWriteJson(path, state, { createParent: false })); }
+export async function writeState(scope, state) {
+    const root = requireScopeRoot(scope);
     if (scope === 'project') {
-        try {
-            mkdirSync(root);
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST' || !statSync(root).isDirectory())
-                throw error;
-        }
+        writeProjectState(root, state);
+        return;
     }
-    else
+    const key = settingsOwnerForRoot(root).key;
+    await writeSettings(() => [{ op: 'state.write', owner: key, state }]);
+}
+/** A project scope is a directory holding `config.json`; the user and profile scopes are the person's rows and need no directory setup. */
+export async function ensureScopeInitialized(scope, root) {
+    if (scope !== 'project') {
         ensureDir(root);
-    const owner = scope === 'user' ? settingsOwnerForRoot(userScopeRoot()) : settingsOwnerForRoot(root);
-    initializeFreshScopedStore({ kind: owner.kind === 'user' ? 'user' : 'project', root: owner.store.root });
-    if (owner.kind === 'project' && readJsonIfExists(configPathFor(owner.root)) === null) {
-        // A project config holds only what the project overrides. Seeding it with
-        // the full default document would make every default (kinds, display
-        // toggles, auto_update) a project-level override that silently shadows the
-        // user's own settings for every directory beneath it — reads default-fill
-        // missing keys from the running build, so a sparse file loses nothing.
-        writeRawAtRoot(owner.root, { schema_version: defaultScopeConfig().schema_version });
+        return;
+    }
+    try {
+        mkdirSync(root);
     }
+    catch (error) {
+        if (error.code !== 'EEXIST' || !statSync(root).isDirectory())
+            throw error;
+    }
+    // A project config holds only what the project overrides. Seeding it with the full default document would make every default
+    // (kinds, display toggles, auto_update) a project-level override that silently shadows the user's own settings for every
+    // directory beneath it — reads default-fill missing keys from the running build, so a sparse file loses nothing.
+    if (readJsonIfExists(configPathFor(root)) === null)
+        await writeRawAtRoot(root, { schema_version: defaultScopeConfig().schema_version });
 }
 function normalizeKeybindings(raw) {
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
@@ -854,6 +870,13 @@ function mergeConfig(partial) {
     if (ledger?.take_pct !== undefined && (typeof ledger.take_pct !== 'number' || !Number.isFinite(ledger.take_pct) || ledger.take_pct < 0 || ledger.take_pct > 100)) {
         throw new Error('ledger.take_pct must be a number from 0 to 100');
     }
+    for (const key of ['sandbox_usd_per_gb_hour', 'sandbox_standby_s', 'storage_usd_per_gb_month', 'sandbox_disk_usd_per_gb_month', 'infra_free_usd_per_month']) {
+        const value = ledger?.[key];
+        if (value !== undefined && (typeof value !== 'number' || !Number.isFinite(value) || value < 0))
+            throw new Error(`ledger.${key} must be a number of at least 0`);
+    }
+    if (ledger?.r2_move !== undefined && typeof ledger.r2_move !== 'boolean')
+        throw new Error('ledger.r2_move must be true or false');
     const store = partial.store;
     const runtime = partial.runtime;
     if (runtime?.person_uids !== undefined && (!Array.isArray(runtime.person_uids)
@@ -1052,8 +1075,8 @@ function sparseModelLaddersToPersist(rawLadders, baseline, mutated) {
  *  `sys config set` never freezes a full concrete `modelLadders` to disk,
  *  and a direct ladder-rung set still persists only the touched rung -- all
  *  through one lock-protected atomic update path. */
-function mutateConfigAtRoot(root, mutate) {
-    return mutateRawAtRoot(root, (raw) => {
+async function mutateConfigAtRoot(root, mutate) {
+    return await mutateRawAtRoot(root, (raw) => {
         const baseline = mergeConfig(raw);
         const cfg = mergeConfig(raw);
         mutate(cfg);
@@ -1080,8 +1103,8 @@ function mutateConfigAtRoot(root, mutate) {
  *  default produces an empty diff and silently persists nothing, so the choice
  *  evaporates as soon as the default moves. Explicit intent is recorded as
  *  written. Mirrors `persistDefaultKindModel`. */
-export function persistModelLadders(root, patch) {
-    mutateRawAtRoot(root, (raw) => { const current = (raw.modelLadders ?? {}); const next = { ...current }; if (patch.defaultProvider !== undefined)
+export async function persistModelLadders(root, patch) {
+    await mutateRawAtRoot(root, (raw) => { const current = (raw.modelLadders ?? {}); const next = { ...current }; if (patch.defaultProvider !== undefined)
         next.defaultProvider = patch.defaultProvider; for (const provider of ['anthropic', 'openai'])
         if (patch[provider] !== undefined)
             next[provider] = { ...(current[provider] ?? {}), ...patch[provider] }; return { value: undefined, next: { ...raw, modelLadders: next } }; });
@@ -1090,12 +1113,12 @@ export function persistModelLadders(root, patch) {
  * raw route entry touched; unrelated routes and local ladder defaults remain
  * absent. Pass `undefined` to remove this scope's entry, which resumes lower
  * scope inheritance rather than introducing a tombstone. */
-export function persistModelRoute(root, routeId, route) {
+export async function persistModelRoute(root, routeId, route) {
     if (route !== undefined)
         assertCompleteModelRoute(routeId, route);
     else if (routeId.trim() === '')
         throw new Error('model route id must be a non-empty string');
-    mutateRawAtRoot(root, (raw) => { const routes = copyRouteRecord((raw.modelRoutes ?? {})); if (route === undefined)
+    await mutateRawAtRoot(root, (raw) => { const routes = copyRouteRecord((raw.modelRoutes ?? {})); if (route === undefined)
         delete routes[routeId];
     else
         setRouteRecord(routes, routeId, { ...route, models: { ...route.models } }); const next = { ...raw }; if (Object.keys(routes).length === 0)
@@ -1105,23 +1128,23 @@ export function persistModelRoute(root, routeId, route) {
 }
 /** Mutate one exact config root. Setup uses this for profile and explicit
  * project targets that cannot be represented by the user/project Scope enum. */
-export function updateConfigAtRoot(root, mutate) {
-    return mutateConfigAtRoot(root, mutate);
+export async function updateConfigAtRoot(root, mutate) {
+    return await mutateConfigAtRoot(root, mutate);
 }
-export function updateConfig(scope, mutate) {
-    return updateConfigAtRoot(requireScopeRoot(scope), mutate);
+export async function updateConfig(scope, mutate) {
+    return await updateConfigAtRoot(requireScopeRoot(scope), mutate);
 }
 /** Persist one sparse kind-model field at an exact config root. The sparse
  * patch keeps every unrelated kind and launch knob inherited from lower
  * scopes instead of freezing a materialized registry snapshot. */
-export function persistDefaultKindModel(opts) {
+export async function persistDefaultKindModel(opts) {
     const field = opts.orchestrator === true ? 'orchestratorModel' : 'model';
-    mutateRawAtRoot(opts.root, (raw) => { const kinds = { ...(raw.kinds ?? {}), [opts.kind]: { ...(raw.kinds ?? {})[opts.kind], [field]: opts.model } }; return { value: undefined, next: { ...raw, kinds: kinds } }; });
+    await mutateRawAtRoot(opts.root, (raw) => { const kinds = { ...(raw.kinds ?? {}), [opts.kind]: { ...(raw.kinds ?? {})[opts.kind], [field]: opts.model } }; return { value: undefined, next: { ...raw, kinds: kinds } }; });
     return { path: configPathFor(opts.root), field };
 }
-export function updateState(scope, mutate) {
+export async function updateState(scope, mutate) {
     const s = readState(scope);
     mutate(s);
-    writeState(scope, s);
+    await writeState(scope, s);
     return s;
 }

package/dist/core/conversation-store/client.d.ts

@@ -0,0 +1,2 @@
+import type { ConversationStoreClient } from './index.js';
+export declare function createStoreClient(address: string, token?: string): ConversationStoreClient;