@north-light/api 0.3.580 → 0.3.587

package/dist/api/client.d.ts

@@ -2,8 +2,8 @@ import { ApiError } from './errors.js';
 import type { GitCredentialDTO, GitCredentialRequest, StartBundleDTO } from './dto/execution-start.js';
 import type { ChargeListDTO, SpendLimitListDTO, SpendLimitRemovedDTO, SpendLimitSetRequest, LimitDTO } from './dto/charges.js';
 import type { AppLimitsChangeDTO, LimitsDTO, SetAppLimitsRequest } from './dto/limits.js';
-import type { DaemonAdmitDTO, DaemonRestartDTO, DueDTO, HealthDTO, ReadyDTO, MigrateStateDTO, MigrateStateRequest, StatusDTO } from './dto/health.js';
-import type { BashJobStatusDTO, BashJobStopResultDTO } from './dto/bash-jobs.js';
+import type { DaemonAdmitDTO, DaemonDrainDTO, DaemonDrainRequest, DaemonRestartDTO, DueDTO, HealthDTO, ReadyDTO, MigrateStateDTO, MigrateStateRequest, StatusDTO } from './dto/health.js';
+import type { BashJobOutputDTO, BashJobOutputQuery, BashJobStatusDTO, BashJobStopResultDTO } from './dto/bash-jobs.js';
 import type { ContextListDTO, CreateNodeRequest, ListNodesQuery, NodeDetailDTO, NodeMessagesPageDTO, NodeMessagesQuery, NodeSessionDTO, NodeSnapshotDTO, NodeSubjectDTO, NodeSummaryDTO, TranscriptDTO, TranscriptQuery } from './dto/nodes.js';
 import type { NodeOutcomeResponseDTO, OutcomeDeliveryDTO, RegisterOutcomeDeliveryRequest } from './dto/node-outcomes.js';
 import type { AnalyticsDTO, AnalyticsQuery, MemoryReadsRequestDTO } from './dto/analytics.js';
@@ -139,6 +139,9 @@ export declare class CrtrClient {
      *  caller living inside a node the handover will tear down still gets a
      *  settled result. */
     restartDaemon(): Promise<DaemonRestartDTO>;
+    /** Pause the daemon for an import (see {@link DaemonDrainDTO}); with `settle_limit_ms` waits for turns to settle. */
+    drainDaemon(req?: DaemonDrainRequest): Promise<DaemonDrainDTO>;
+    endDaemonDrain(): Promise<DaemonDrainDTO>;
     admitDaemon(): Promise<DaemonAdmitDTO>;
     migrateState(req: MigrateStateRequest): Promise<MigrateStateDTO>;
     appendNodeLog(id: string, req: NodeLogAppendRequest): Promise<NodeLogAppendResultDTO>;
@@ -180,6 +183,8 @@ export declare class CrtrClient {
     /** Disarm an unsettled outcome-delivery registration. */
     disarmOutcomeDelivery(id: string): Promise<void>;
     listBashJobs(id: string): Promise<BashJobStatusDTO[]>;
+    /** The job's output from the blob store, last bytes or lines (see `BashJobOutputQuery`). */
+    readBashJobOutput(id: string, jobId: string, query?: BashJobOutputQuery): Promise<BashJobOutputDTO>;
     stopBashJob(id: string, jobId: string): Promise<BashJobStopResultDTO>;
     /** Claim, quiet or re-arm one running job (see `JobPatchRequest`). */
     patchBashJob(id: string, jobId: string, request: JobPatchRequest): Promise<void>;
@@ -215,6 +220,8 @@ export declare class CrtrClient {
     commitBrokerModel(id: string, req: BrokerModelCommitRequest): Promise<BrokerModelCommitResultDTO>;
     /** The sandbox's start bundle for an execution of the calling node. */
     executionStart(executionId: string): Promise<StartBundleDTO>;
+    /** The calling node's imported files are unpacked in its sandbox (sets `import_node_files.unpacked_at`). */
+    executionImportUnpacked(executionId: string): Promise<void>;
     /** A GitHub token limited to the environment's recipe repositories, for the calling node's environment. */
     gitCredential(environmentId: string, req: GitCredentialRequest): Promise<GitCredentialDTO>;
     brokerExtensionState(id: string): Promise<BrokerExtensionStateDTO>;

package/dist/api/client.js

@@ -137,6 +137,14 @@ export class CrtrClient {
     restartDaemon() {
         return this.request('POST', routes.daemonRestart());
     }
+    /** Pause the daemon for an import (see {@link DaemonDrainDTO}); with `settle_limit_ms` waits for turns to settle. */
+    drainDaemon(req = {}) {
+        const wait = req.settle_limit_ms ?? 0;
+        return this.request('POST', routes.daemonDrain(), req, { timeout: wait + this.timeoutMs });
+    }
+    endDaemonDrain() {
+        return this.request('DELETE', routes.daemonDrain());
+    }
     admitDaemon() {
         return this.request('POST', routes.daemonAdmit());
     }
@@ -276,6 +284,16 @@ export class CrtrClient {
     listBashJobs(id) {
         return this.request('GET', routes.nodeJobs(this.nodePath(id)));
     }
+    /** The job's output from the blob store, last bytes or lines (see `BashJobOutputQuery`). */
+    readBashJobOutput(id, jobId, query = {}) {
+        const params = new URLSearchParams();
+        if (query.tail_lines !== undefined)
+            params.set('tail_lines', String(query.tail_lines));
+        if (query.max_bytes !== undefined)
+            params.set('max_bytes', String(query.max_bytes));
+        const suffix = params.size === 0 ? '' : `?${params.toString()}`;
+        return this.request('GET', `${routes.nodeJobOutput(this.nodePath(id), this.jobPath(jobId))}${suffix}`);
+    }
     stopBashJob(id, jobId) {
         return this.request('DELETE', routes.nodeJob(this.nodePath(id), this.jobPath(jobId)));
     }
@@ -366,6 +384,10 @@ export class CrtrClient {
     executionStart(executionId) {
         return this.request('GET', routes.executionStart(executionId));
     }
+    /** The calling node's imported files are unpacked in its sandbox (sets `import_node_files.unpacked_at`). */
+    executionImportUnpacked(executionId) {
+        return this.request('POST', routes.executionImportUnpacked(executionId), {});
+    }
     /** A GitHub token limited to the environment's recipe repositories, for the calling node's environment. */
     gitCredential(environmentId, req) {
         return this.request('POST', routes.environmentGitCredential(environmentId), req);

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.40";
+export declare const CONTRACT_LEVEL = "1.43";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.40';
+export const CONTRACT_LEVEL = '1.43';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/dto/bash-jobs.d.ts

@@ -16,6 +16,23 @@ export interface BashJobStatusDTO {
     /** Whether the persisted process group currently exists. */
     pgid_alive: boolean;
 }
+/** Query bounds for reading a job's stored output. With neither set, the last `BASH_JOB_OUTPUT_DEFAULT_BYTES` bytes come back. */
+export interface BashJobOutputQuery {
+    /** Return at most this many trailing lines. */
+    tail_lines?: number;
+    /** Return at most this many trailing bytes (default `BASH_JOB_OUTPUT_DEFAULT_BYTES`, at most `BASH_JOB_OUTPUT_MAX_BYTES`). */
+    max_bytes?: number;
+}
+/** A job's output as stored in the blob store, read back from its end. */
+export interface BashJobOutputDTO {
+    job_id: string;
+    /** The output the job has written so far, empty when it has written nothing. */
+    output: string;
+    /** True when earlier output exists that the bounds left out. */
+    truncated: boolean;
+}
+export declare const BASH_JOB_OUTPUT_DEFAULT_BYTES: number;
+export declare const BASH_JOB_OUTPUT_MAX_BYTES: number;
 /** Result of stopping one background bash job. `signaled` is false when the
  * process group had already exited, but the job is still retired via its exit
  * sentinel. */

package/dist/api/dto/bash-jobs.js

@@ -1,5 +1,7 @@
 // Background bash job API shapes. The daemon projects the file-backed job
 // control plane into these dependency-light DTOs for remote presenters.
+export const BASH_JOB_OUTPUT_DEFAULT_BYTES = 256 * 1024;
+export const BASH_JOB_OUTPUT_MAX_BYTES = 4 * 1024 * 1024;
 /** Whether a job id is safe to interpolate as one API/filesystem segment. */
 export function isSafeBashJobId(jobId) {
     return typeof jobId === 'string'

package/dist/api/dto/execution-start.d.ts

@@ -21,6 +21,16 @@ export interface StartBundlePluginDTO {
     };
     version: string | null;
 }
+/** A hosted node's imported files, not yet unpacked (design-import, "Sandbox import step"). */
+export interface StartBundleImportFilesDTO {
+    /** Signed GET URL of `import_node_files.blob_key` (a `tar.zst`). */
+    url: string;
+    /** The run's path map. Archive entries are named `<source prefix without its leading slash>/<path relative to the prefix>`; each is unpacked under that prefix's `to`. */
+    path_map: Array<{
+        from: string;
+        to: string;
+    }>;
+}
 /** `GET /v1/executions/{execution_id}/start`. Read-only; safe to repeat. */
 export interface StartBundleDTO {
     /** The execution row's `launch_json`, parsed. */
@@ -43,6 +53,10 @@ export interface StartBundleDTO {
     } | null;
     plugins_revision: number;
     plugins: StartBundlePluginDTO[];
+    /** Null when the node has no `import_node_files` row, or its archive was deleted (30 days after the first unpack). Named on every start while the archive exists: a sandbox unpacks it only when it holds no marker of its own. */
+    import_node_files: StartBundleImportFilesDTO | null;
+    /** Present only for an execution on a machine environment (the Mac, which holds no database): the node's profile metadata (`CRTR_PROFILE_META_*`) and the secrets of its environment (the app's rows, the owning profile's rows, the deployment rows), merged in the process runner's order. Secret values: read with the execution's node token, never carried in a link frame. */
+    machine_env?: Record<string, string>;
 }
 /** `POST /v1/environments/{id}/git-credential` body: what git asked for. */
 export interface GitCredentialRequest {

package/dist/api/dto/health.d.ts

@@ -8,6 +8,10 @@ export interface HealthDTO {
     daemon_up: boolean;
     store_accessible: boolean;
     brokers_reconciled: boolean;
+    /** Present on a machine-role daemon only: whether its link to the control plane is up. That daemon reports `startup_phase: 'recovering'` while it is down. */
+    link_connected?: boolean;
+    /** Present on a machine-role daemon only: false when this computer has no person sign-in, so it opens no link and runs no agent or cron. */
+    signed_in?: boolean;
     /** Present while corpus migration or normal daemon startup is incomplete. */
     startup_blocked?: string;
     /** Always present; only `ready` admits normal daemon work. */
@@ -108,6 +112,24 @@ export interface MigrateStateDTO {
     resumed: boolean;
     resume_error?: string;
 }
+/** `POST /v1/daemon/drain` and `DELETE /v1/daemon/drain`: the import's pause of this daemon. Drained means no new wake, no cron
+ *  fire, no warm-pool fill and no push-receiver delivery; turns in flight settle. */
+export interface DaemonDrainRequest {
+    /** Wait for turns in flight to settle for at most this long (ms, default 10 minutes), then stop each remaining broker as a
+     *  dormant exit. Absent: return at once with the busy list. */
+    settle_limit_ms?: number;
+}
+export interface DaemonDrainDTO {
+    drained: boolean;
+    /** When the drain began (ISO); null when not drained. */
+    since: string | null;
+    /** Nodes with a turn in flight and a live broker at the time of the answer. */
+    busy_nodes: string[];
+    /** Brokers this call stopped because their turn outlived the settle limit. */
+    stopped_nodes: string[];
+    /** `DELETE` only: whether the daemon was drained before this call ended the drain. */
+    was_drained?: boolean;
+}
 /** `POST /v1/daemon/admit` — opens normal daemon work after preparation. */
 export interface DaemonAdmitDTO {
     /** True only for the request that began admission. */

package/dist/api/dto/imports.d.ts

@@ -0,0 +1,142 @@
+export type ImportSourceKindDTO = 'machine' | 'hosted';
+export type ImportStateDTO = 'uploading' | 'loading' | 'committed' | 'done' | 'failed' | 'rolled_back';
+/** `POST /v1/imports`. The run's person is the token's `sub`; hosting's service credential names it in `person`. */
+export interface ImportStartRequest {
+    source_install_id: string;
+    source_kind: ImportSourceKindDTO;
+    /** The source's release; must equal the control plane's accepted release (`release_mismatch`). */
+    release: string;
+    /** `user:<id>`: required with hosting's service credential (`source_kind` hosted), absent with a person token. */
+    person?: string;
+}
+export interface ImportStartedDTO {
+    run_id: string;
+    upload: {
+        /** `imports/<run>/` — the row files, `source.json` and node-file archives go under it. */
+        rows_prefix: string;
+        /** Signed R2 PUT URL for a key, requested per key through `POST /v1/imports/<run>/upload-urls`. */
+        url_template: string;
+    };
+    /** Only for the service credential: a token for this run's `upload-urls`, `stores`, `load` and `get`, while it is uploading or loading. */
+    import_token?: string;
+}
+/** `POST /v1/imports/<run>/upload-urls` `{keys}`: signed PUT URLs for keys under `imports/<run>/` only (source blobs go to `imports/<run>/blobs/<key>`). */
+export interface ImportUploadUrlsDTO {
+    urls: Record<string, string>;
+    expires_at: string;
+}
+/** The file stores, uploaded over TLS through `PUT /v1/imports/<run>/stores/<name>` (never to R2). Each body is the file's JSON. */
+export type ImportStoreNameDTO = 'auth' | 'credentials' | 'env' | 'settings' | 'plugins';
+export interface ImportCountsDTO {
+    staged: number;
+    inserted: number;
+    mapped: number;
+    dropped: number;
+}
+export interface ImportVerifyDTO {
+    ok: boolean;
+    /** Per table: rows that differ from their rewritten staged row (first 10 keys). */
+    differences: Record<string, {
+        count: number;
+        keys: string[];
+    }>;
+    invariants: Record<string, boolean>;
+}
+export interface ImportFailureDTO {
+    step: string;
+    code: string;
+    message: string;
+    detail?: Record<string, unknown>;
+}
+/** `GET /v1/imports/<run>`. */
+export interface ImportRunDTO {
+    run_id: string;
+    source_install_id: string;
+    source_kind: ImportSourceKindDTO;
+    person: string;
+    release: string;
+    state: ImportStateDTO;
+    step: string | null;
+    counts: Record<string, ImportCountsDTO>;
+    verify: ImportVerifyDTO | null;
+    failure: ImportFailureDTO | null;
+    unresolved_plugins: string[];
+    created: string;
+    loaded: string | null;
+    finished: string | null;
+}
+/** `crtr sys import rollback <run>` result (the lane's preflight, I20). */
+export interface ImportRollbackDTO {
+    run_id: string;
+    rolled_back: boolean;
+    /** Per table: later rows referencing the run's rows; non-empty means refused `rollback_has_dependents`. */
+    dependents: Record<string, number>;
+    deleted: Record<string, number>;
+}
+export interface ImportAuthStoreDTO {
+    apiKeys: Record<string, unknown>;
+}
+export interface ImportCredentialAccountDTO {
+    provider: string;
+    id: string;
+    label: string;
+    labelKey: string;
+    position: number;
+    lastAttemptAt: number;
+    lastRateLimitedAt: number;
+    rateLimitedUntil: number;
+    authFailure?: 'invalid_grant';
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+    clientId?: string;
+    cooldowns: Array<{
+        family: string;
+        until: number;
+        at: number;
+    }>;
+}
+export interface ImportCredentialsStoreDTO {
+    accounts: ImportCredentialAccountDTO[];
+    rotation?: {
+        defaultFallbackStrength: string | null;
+        revertWhenAvailable: boolean | null;
+    };
+    openaiDeviceId?: string;
+}
+/** Profile env vars by the source's profile id. */
+export interface ImportEnvStoreDTO {
+    profiles: Record<string, Record<string, string>>;
+}
+/** Settings by owner key (`user`, `profile:<source profile id>`), without their `plugins` and `marketplaces` blocks. */
+export interface ImportSettingsStoreDTO {
+    settings: Record<string, Record<string, unknown>>;
+    state: Record<string, {
+        last_self_check?: string | null;
+        activeCanvas?: string | null;
+    }>;
+    profileProjects: Record<string, string[]>;
+    defaults: Record<string, string>;
+}
+export interface ImportPluginsStoreDTO {
+    marketplaces: Array<{
+        owner: string;
+        name: string;
+        url?: string | null;
+        ref?: string | null;
+        installed_at?: string | null;
+        last_updated?: string | null;
+    }>;
+    plugins: Array<{
+        owner: string;
+        name: string;
+        enabled: boolean;
+        source_marketplace?: string | null;
+        version?: string | null;
+        source_path?: string | null;
+        last_updated?: string | null;
+        etag?: string | null;
+        checked_at?: string | null;
+    }>;
+}

package/dist/api/dto/imports.js

@@ -0,0 +1,2 @@
+// `/v1/imports`: one source's import into the shared database. Design: design-import, "Interfaces & contracts".
+export {};

package/dist/api/error-codes.d.ts

@@ -224,6 +224,11 @@ export declare const errorCodes: {
         readonly status: 429;
         readonly retryable: true;
     };
+    readonly northlight_unreachable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
     readonly runtime_unreachable: {
         readonly type: "server_error";
         readonly status: 503;

package/dist/api/error-codes.js

@@ -62,6 +62,8 @@ export const errorCodes = {
     rate_limited: { type: 'rate_limit_error', status: 429, retryable: true },
     // `exec`: the app already has 4 live exec processes on this runtime.
     busy: { type: 'rate_limit_error', status: 429, retryable: true },
+    // This computer could not reach Northlight (a fetch that threw); never an HTTP answer. The CLI relay inside a node answers it.
+    northlight_unreachable: { type: 'server_error', status: 503, retryable: true },
     runtime_unreachable: { type: 'server_error', status: 503, retryable: true },
     isolated_unavailable: { type: 'server_error', status: 503, retryable: true },
     // `exec` on a runtime without a root launcher: it cannot sandbox the app's process, so it refuses to run it.

package/dist/api/errors.js

@@ -51,7 +51,8 @@ export function isDaemonTransportApiError(error) {
         return false;
     return (error.status === 503 && (error.code === 'daemon_unavailable'
         || error.code === 'transport_error'
-        || error.code === 'daemon_request_interrupted')) || (error.status === 504 && (error.code === 'request_timeout' || error.code === 'deadline_exceeded'))
+        || error.code === 'daemon_request_interrupted'
+        || error.code === 'northlight_unreachable')) || (error.status === 504 && (error.code === 'request_timeout' || error.code === 'deadline_exceeded'))
         || (error.status >= 500 && error.code === 'daemon_health_unavailable');
 }
 /** The daemon refused the caller's node token. A teardown revokes the broker's token before its process stops, so a broker

package/dist/api/index.d.ts

@@ -18,6 +18,7 @@ export * from './dto/limits.js';
 export * from './dto/grants.js';
 export * from './dto/usage.js';
 export * from './dto/charges.js';
+export * from './dto/imports.js';
 export * from './dto/execution-start.js';
 export * from './dto/nodes.js';
 export * from './dto/node-outcomes.js';

package/dist/api/index.js

@@ -15,6 +15,7 @@ export * from './dto/limits.js';
 export * from './dto/grants.js';
 export * from './dto/usage.js';
 export * from './dto/charges.js';
+export * from './dto/imports.js';
 export * from './dto/execution-start.js';
 export * from './dto/nodes.js';
 export * from './dto/node-outcomes.js';

package/dist/api/routes.d.ts

@@ -8,12 +8,14 @@ export declare const routes: {
     readonly due: () => string;
     readonly daemonRestart: () => string;
     readonly daemonMigrate: () => string;
+    readonly daemonDrain: () => string;
     readonly daemonAdmit: () => string;
     readonly nodes: () => string;
     readonly reviveAll: () => string;
     readonly node: (id: string) => string;
     readonly nodeMemoryReads: (id: string) => string;
     readonly executionStart: (id: string) => string;
+    readonly executionImportUnpacked: (id: string) => string;
     readonly environmentGitCredential: (id: string) => string;
     readonly nodeOutcome: (id: string) => string;
     readonly nodeOutcomeDelivery: (id: string) => string;
@@ -30,6 +32,7 @@ export declare const routes: {
     readonly nodeJobs: (id: string) => string;
     readonly nodeJob: (id: string, jobId: string) => string;
     readonly nodeJobReport: (id: string, jobId: string) => string;
+    readonly nodeJobOutput: (id: string, jobId: string) => string;
     readonly nodeJobBackground: (id: string, jobId: string) => string;
     readonly nodeDelivery: (id: string) => string;
     readonly deliveryDryRun: () => string;

package/dist/api/routes.js

@@ -22,6 +22,7 @@ export const routes = {
     due: () => `${V}/due`,
     daemonRestart: () => `${V}/daemon/restart`,
     daemonMigrate: () => `${V}/daemon/migrate`,
+    daemonDrain: () => `${V}/daemon/drain`,
     daemonAdmit: () => `${V}/daemon/admit`,
     // Nodes — collection + item
     nodes: () => `${V}/nodes`,
@@ -29,6 +30,7 @@ export const routes = {
     node: (id) => `${V}/nodes/${id}`,
     nodeMemoryReads: (id) => `${V}/nodes/${id}/memory-reads`,
     executionStart: (id) => `${V}/executions/${id}/start`,
+    executionImportUnpacked: (id) => `${V}/executions/${id}/import-unpacked`,
     environmentGitCredential: (id) => `${V}/environments/${id}/git-credential`,
     nodeOutcome: (id) => `${V}/nodes/${id}/outcome`,
     nodeOutcomeDelivery: (id) => `${V}/nodes/${id}/outcome-delivery`,
@@ -46,6 +48,7 @@ export const routes = {
     nodeJobs: (id) => `${V}/nodes/${id}/jobs`,
     nodeJob: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}`,
     nodeJobReport: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}/report`,
+    nodeJobOutput: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}/output`,
     nodeJobBackground: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}/background`,
     nodeDelivery: (id) => `${V}/nodes/${id}/delivery`,
     deliveryDryRun: () => `${V}/delivery/dry-run`,

package/dist/build-root.d.ts

@@ -0,0 +1,66 @@
+import type { RootDef } from './core/command.js';
+import { type CoreHookCatalog } from './core/command-hooks/catalog.js';
+/** Every shipped subtree name. Cheap (no module loading) — the front-door
+ *  recursion guard and the dispatcher's first-token routing need only names. */
+export declare const SUBTREE_NAMES: readonly string[];
+export declare function coreHookCatalog(): Promise<CoreHookCatalog>;
+export declare function coreCommandPaths(): Promise<ReadonlySet<string>>;
+/** Core command paths covering `asked`: answers membership for every asked
+ *  path exactly as `coreCommandPaths()` would (paths are partitioned by their
+ *  subtree's name), while loading only the subtrees those paths name. */
+export declare function coreCommandPathsCovering(asked: readonly string[]): Promise<ReadonlySet<string>>;
+/** Every core branch marked `extensible: true`, space-joined. Declared
+ *  statically so leaf dispatch can decide whether plugin core mounts can reach
+ *  its subtree without importing every subtree to find out; a test pins it to
+ *  the markers the loaded tree actually carries. */
+export declare const EXTENSIBLE_CORE_BRANCHES: readonly string[];
+export declare function extensibleCoreBranches(): Promise<ReadonlySet<string>>;
+/** The extensible branch paths the loaded tree declares — the source of truth
+ *  `EXTENSIBLE_CORE_BRANCHES` must match. */
+export declare function declaredExtensibleCoreBranches(): Promise<ReadonlySet<string>>;
+/** The person-only command path `argv` dispatches into, or null. */
+export declare function personOnlyInvocation(argv: readonly string[]): string | null;
+/** Select a smaller canonical tree; `runCli` still parses, renders help, and reports errors. */
+export declare function isDaemonControlInvocation(argv: readonly string[]): boolean;
+/** `sys signin` and `sys signout` run when the stored sign-in is gone or a move is unfinished, the states in which the settings load would refuse. */
+export declare function isSignInInvocation(argv: readonly string[]): boolean;
+export declare function isJoinInvocation(argv: readonly string[]): boolean;
+export declare function isLayoutMigrationInvocation(argv: readonly string[]): boolean;
+/** Assemble the canonical daemon-control definitions without loading settings or plugin discovery. This path exists so `crtr sys daemon restart` can start the new generation that converts pre-SQL user state. */
+export declare function resolveDaemonControlRoot(): Promise<RootDef>;
+/** Migration runs offline before command plugins can read or initialize scoped state. */
+export declare function resolveLayoutMigrationRoot(): Promise<RootDef>;
+/** Build a root that contains only the subtree `first` dispatches into.
+ *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
+ *  `-h`/`--help`, `--version`, and any unknown leading token all need the
+ *  complete tree (root -h lists every subtree; the unknown-path error names
+ *  every valid child). This keeps every help/error surface byte-identical while
+ *  the common leaf-dispatch path loads exactly one subtree. */
+export declare function resolveRoot(first: string | undefined): Promise<RootDef>;
+/** The root holding only core subtree `first` (with its plugin mounts and
+ *  hooks), or null when `first` is not a core subtree or this caller's scopes
+ *  hide it. Never composes external command sources, so it never fetches a
+ *  sandboxed node's provider catalog. */
+export declare function resolveCoreRoot(first: string): Promise<RootDef | null>;
+/** Assemble the full crtr command tree: every core subtree plus every top-level
+ *  branch contributed by an external command source — enabled command plugins
+ *  AND registered HTTP-transport plugins, folded together through ONE unified,
+ *  collision-resolved snapshot (`buildExternalCommandSnapshot`). Used for root
+ *  -h, the unknown-path error, bare-root boot, front-door recognition, and the
+ *  listing-completeness test — i.e. only the FALLTHROUGH path, never the core
+ *  fast path (`resolveRoot` short-circuits a recognized core first token with
+ *  zero plugin transport I/O). Root owns only the tagline; every subtree (core or
+ *  external) declares its own root representation via its rootEntry.
+ *
+ *  Order is deterministic: core subtrees in declared order first, then accepted
+ *  external branches sorted by contributor name (from the unified snapshot).
+ *  Composition is invocation-local — no cache, no persistence — and reads only
+ *  stored manifest bytes, so a plugin enable/update/remove or an HTTP-transport
+ *  plugin manifest replacement takes effect on the next invocation automatically.
+ *  The one network read is the granted provider catalog (`GET /v1/providers/tools`)
+ *  that a sandboxed node, a fleet node and a moved computer ask their control plane
+ *  or daemon for. On a moved computer a failed read does not abort the tree: the
+ *  tree is built from what is known locally and the failure rides on the root
+ *  (`providerCatalogFailure`), which the dispatcher raises in place of
+ *  `unknown_path` when the person types a top-level name the tree lacks. */
+export declare function buildRoot(): Promise<RootDef>;