@north-light/crouter 0.3.220 → 0.3.222

package/dist/api/client.d.ts

@@ -12,11 +12,13 @@ import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js
 import type { DeleteProfileRequest, DeleteProfileResultDTO, EnsureProfileRequest, ProfileDTO } from './dto/profiles.js';
 import type { FilePeekDTO } from './dto/files.js';
 import type { MemoryDocRefDTO } from './dto/memory.js';
+import type { ChatInventoryDTO, ProspectiveChatInventoryDTO, ProspectiveChatInventoryQuery } from './dto/chat-inventory.js';
 import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, ModelAuthListDTO } from './dto/modelauth.js';
 import type { CreateHumanBridgeRequest, HumanBridgeResultDTO, HumanCancelRequest, HumanCancelResultDTO, HumanResolveRequest, HumanResolveResultDTO } from './dto/human.js';
 import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
 import type { CreateReviewCommentRequest, EditReviewCommentRequest, ListReviewCommentsQuery, ReadReviewCommentEventsQuery, ReviewCommentActionRequest, ReviewCommentDetailDTO, ReviewCommentEventsDTO, ReviewCommentListDTO, ReviewCommentMutationDTO, ReviewCommentRangeBatchRequest, ReviewCommentRangeBatchResultDTO } from './dto/review-comments.js';
 import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, InboxPageDTO, InboxPageHistoryDTO, InboxPageResponseDTO, InboxTicketIdDTO, PageFeedbackResolutionDTO, PageResponsesDTO, PageTicketResultDTO, RespondInboxPageRequest } from './dto/inbox.js';
+import type { CreateHumanRequestDTO, CreateHumanRequestRequest, HumanRequestDTO, HumanRequestIdDTO, ReplaceHumanRequestRequest, RespondHumanRequestRequest, SettleHumanRequestRequest } from './dto/human-requests.js';
 import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
 import type { CloseWorktreeResultDTO } from './dto/worktree.js';
 import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
@@ -151,6 +153,12 @@ export declare class CrtrClient {
     /** The node's conversation exactly as it ran — raw `.jsonl` bytes plus the
      *  assembled system prompt. For exports; `getSnapshot` is for renderers. */
     getSession(id: string): Promise<NodeSessionDTO>;
+    /** What a non-terminal chat surface may offer for this node: the chat-capable
+     *  slash commands its live engine registered, and the memory documents an
+     *  inline `/name` token resolves to. Never revives — a node whose broker is
+     *  not live answers `broker_live: false` with empty arrays. */
+    getChatInventory(id: string): Promise<ChatInventoryDTO>;
+    getProspectiveChatInventory(q?: ProspectiveChatInventoryQuery): Promise<ProspectiveChatInventoryDTO>;
     getArtifacts(id: string, q?: ArtifactsQuery): Promise<ArtifactListDTO>;
     getContext(id: string): Promise<ContextListDTO>;
     /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for
@@ -160,6 +168,9 @@ export declare class CrtrClient {
      *  node would read — the node's own precedence chain, not this process's.
      *  Pair with `peekFile` to render the document. */
     resolveMemoryDoc(name: string, nodeId: string): Promise<MemoryDocRefDTO>;
+    /** Create-or-return by name. Supplied `projects` are shape-checked even when
+     *  the profile already exists; their directories are only required to exist
+     *  when this call creates the profile. */
     ensureProfile(name: string, req?: EnsureProfileRequest): Promise<ProfileDTO>;
     listProfiles(): Promise<ProfileDTO[]>;
     getProfile(name: string): Promise<ProfileDTO>;
@@ -211,6 +222,24 @@ export declare class CrtrClient {
     getInboxResponse(ticketId: InboxTicketIdDTO): Promise<InboxPageResponseDTO>;
     /** Cancel a ticket (terminal response, never deletion). */
     cancelHumanInboxTicket(ticketId: InboxTicketIdDTO, request?: CancelInboxTicketRequest): Promise<CanceledTicketResultDTO>;
+    /** Create one durable human request. Its `request_id` is the same opaque id
+     *  the inbox routes address, so the request and the inbox ticket are one
+     *  record. An unresolvable `action.name` is rejected before the page is
+     *  published, leaving no inbox row behind. */
+    createHumanRequest(request: CreateHumanRequestRequest): Promise<CreateHumanRequestDTO>;
+    /** Read one request: its current state, its answer when answered, and the
+     *  delivery state of its completion action when it bound one. */
+    getHumanRequest(requestId: HumanRequestIdDTO): Promise<HumanRequestDTO>;
+    /** Revise a pending request's page in place. Identity, provenance, and the
+     *  frozen action binding are preserved; a settled request refuses. */
+    replaceHumanRequest(requestId: HumanRequestIdDTO, request: ReplaceHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** Settle a request `answered` programmatically. Races a human answer to the
+     *  same first-writer-wins result. */
+    respondHumanRequest(requestId: HumanRequestIdDTO, request: RespondHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** The recipient surface closing a request without answering. */
+    dismissHumanRequest(requestId: HumanRequestIdDTO, request?: SettleHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** The requester withdrawing its own request. */
+    cancelHumanRequest(requestId: HumanRequestIdDTO, request?: SettleHumanRequestRequest): Promise<HumanRequestDTO>;
     /** Resolve one page feedback comment — the bound companion's report that it
      *  has been dealt with. `nodeId` names the caller; the daemon refuses any
      *  node but the ticket's companion. Terminal for the comment; appends no

package/dist/api/client.js

@@ -267,6 +267,16 @@ export class CrtrClient {
     getSession(id) {
         return this.request('GET', routes.nodeSession(this.nodePath(id)));
     }
+    /** What a non-terminal chat surface may offer for this node: the chat-capable
+     *  slash commands its live engine registered, and the memory documents an
+     *  inline `/name` token resolves to. Never revives — a node whose broker is
+     *  not live answers `broker_live: false` with empty arrays. */
+    getChatInventory(id) {
+        return this.request('GET', routes.nodeChatInventory(this.nodePath(id)));
+    }
+    getProspectiveChatInventory(q) {
+        return this.request('GET', withQuery(routes.prospectiveChatInventory(), q));
+    }
     getArtifacts(id, q) {
         return this.request('GET', withQuery(routes.nodeArtifacts(this.nodePath(id)), q));
     }
@@ -287,6 +297,9 @@ export class CrtrClient {
         return this.request('GET', withQuery(routes.memoryResolve(), { name, node: nodeId }));
     }
     // ---- Profiles ----------------------------------------------------------
+    /** Create-or-return by name. Supplied `projects` are shape-checked even when
+     *  the profile already exists; their directories are only required to exist
+     *  when this call creates the profile. */
     ensureProfile(name, req) {
         return this.request('PUT', routes.profile(name), req ?? {});
     }
@@ -416,6 +429,37 @@ export class CrtrClient {
     cancelHumanInboxTicket(ticketId, request) {
         return this.request('POST', routes.humanInboxCancel(this.ticketId(ticketId)), request ?? {});
     }
+    // ---- Durable programmatic human requests -------------------------------
+    /** Create one durable human request. Its `request_id` is the same opaque id
+     *  the inbox routes address, so the request and the inbox ticket are one
+     *  record. An unresolvable `action.name` is rejected before the page is
+     *  published, leaving no inbox row behind. */
+    createHumanRequest(request) {
+        return this.request('POST', routes.humanRequests(), request);
+    }
+    /** Read one request: its current state, its answer when answered, and the
+     *  delivery state of its completion action when it bound one. */
+    getHumanRequest(requestId) {
+        return this.request('GET', routes.humanRequest(this.ticketId(requestId)));
+    }
+    /** Revise a pending request's page in place. Identity, provenance, and the
+     *  frozen action binding are preserved; a settled request refuses. */
+    replaceHumanRequest(requestId, request) {
+        return this.request('POST', routes.humanRequestReplace(this.ticketId(requestId)), request);
+    }
+    /** Settle a request `answered` programmatically. Races a human answer to the
+     *  same first-writer-wins result. */
+    respondHumanRequest(requestId, request) {
+        return this.request('POST', routes.humanRequestRespond(this.ticketId(requestId)), request);
+    }
+    /** The recipient surface closing a request without answering. */
+    dismissHumanRequest(requestId, request = {}) {
+        return this.request('POST', routes.humanRequestDismiss(this.ticketId(requestId)), request);
+    }
+    /** The requester withdrawing its own request. */
+    cancelHumanRequest(requestId, request = {}) {
+        return this.request('POST', routes.humanRequestCancel(this.ticketId(requestId)), request);
+    }
     /** Resolve one page feedback comment — the bound companion's report that it
      *  has been dealt with. `nodeId` names the caller; the daemon refuses any
      *  node but the ticket's companion. Terminal for the comment; appends no

package/dist/api/dto/chat-inventory.d.ts

@@ -0,0 +1,56 @@
+/** One command a chat surface may advertise. Builtin and non-opted-in rows are
+ *  dropped before this DTO exists, so `source` never carries `'builtin'`. */
+export interface ChatInventoryCommandDTO {
+    /** No leading slash, exactly as the engine dispatches it. */
+    name: string;
+    description: string;
+    source: 'command' | 'template';
+    /** Argument shape to display beside the name, when the command supplies one. */
+    argument_hint?: string;
+    /** Deterministic expansion metadata for a memory-slash command — the same
+     *  material the terminal preview uses, so a chat preview cannot drift from
+     *  what submission sends. */
+    expansion?: {
+        kind: 'memory-slash';
+        commandName: string;
+        body: string;
+    };
+    /** Raw prompt-template content (frontmatter stripped), for `source: 'template'`. */
+    template?: string;
+}
+/** One resolvable inline memory reference. Metadata only — never the document
+ *  body or its source path. `shortForm` stays camelCase to mirror the broker's
+ *  own `RefMeta`, which is where these rows come from. */
+export interface ChatInventoryMemoryRefDTO {
+    /** Canonical `/`-joined name, e.g. `taste/writing`. */
+    name: string;
+    kind: 'knowledge' | 'preference';
+    scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+    shortForm: string;
+}
+/** `GET /v1/nodes/{id}/chat-inventory` result.
+ *
+ *  `broker_live` reports whether the node's engine was reachable at all. There
+ *  is no per-part error flag: a part that failed and a part that is genuinely
+ *  empty both arrive as an empty array, and a client's behavior is identical
+ *  for both. A dormant node answers 200 with `broker_live: false` — this read
+ *  never revives an engine. */
+export interface ChatInventoryDTO {
+    node_id: string;
+    broker_live: boolean;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+/** Session-less inventory for the launch target a create would resolve. */
+export interface ProspectiveChatInventoryDTO {
+    profile_id: string | null;
+    cwd: string;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+export interface ProspectiveChatInventoryQuery {
+    profile?: string;
+    cwd?: string;
+    /** Same optional kind operand as POST /v1/nodes. */
+    kind?: string;
+}

package/dist/api/dto/chat-inventory.js

@@ -0,0 +1,11 @@
+// Chat-inventory DTO. Backs `GET /v1/nodes/{id}/chat-inventory` — the one read
+// a non-terminal chat surface makes to learn what the node's live engine will
+// accept: the slash commands that can complete their outcome from a chat
+// conversation, and the memory documents an inline `/name` token resolves to.
+//
+// Eligibility is decided in crouter and disclosed here. A client never filters
+// by name, infers capability, or invents a row: what is absent from these
+// arrays is not offered.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/api/dto/human-requests.d.ts

@@ -0,0 +1,88 @@
+import type { IsoTime } from './common.js';
+import type { InboxTicketIdDTO, PageResponsesDTO, TicketSourceDTO } from './inbox.js';
+/** A request id IS an opaque inbox ticket id: lowercase 64-hex. */
+export type HumanRequestIdDTO = InboxTicketIdDTO;
+/** The complete authored page text, inline — never a path. */
+export interface HumanRequestPageDTO {
+    dialect: 'jsx' | 'html';
+    source: string;
+}
+export interface HumanRequestDeliveryDTO {
+    placement: 'inline' | 'panel';
+    inbox: boolean;
+    reply: boolean;
+}
+/** Frozen at creation: the action name and its opaque payload. An omitted
+ *  `payload` is frozen as JSON null, so the completion document always carries it. */
+export interface HumanRequestActionDTO {
+    name: string;
+    payload?: unknown;
+}
+export interface CreateHumanRequestRequest {
+    page: HumanRequestPageDTO;
+    delivery?: HumanRequestDeliveryDTO;
+    source?: TicketSourceDTO;
+    creator_cwd: string;
+    action?: HumanRequestActionDTO;
+}
+export type HumanRequestState = 'pending' | 'answered' | 'dismissed' | 'canceled';
+export type HumanRequestDeliveryState = 'none' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
+export interface CreateHumanRequestDTO {
+    request_id: HumanRequestIdDTO;
+    state: 'pending';
+    /** Omitted entirely when the request carries no action binding. */
+    action?: {
+        name: string;
+    };
+    delivery_state: HumanRequestDeliveryState;
+}
+export interface HumanRequestDeliveryFailureDTO {
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    exit_code?: number;
+    signal?: string;
+    message?: string;
+    /** A bounded tail, not full output. */
+    stderr?: string;
+}
+export interface HumanRequestDeliveryDetailDTO {
+    state: HumanRequestDeliveryState;
+    /** Attempts started. */
+    attempt: number;
+    /** Present only while pending after a retryable failure. */
+    next_attempt_at?: IsoTime;
+    accepted_at?: IsoTime;
+    permanent_failed_at?: IsoTime;
+    last_failure?: HumanRequestDeliveryFailureDTO;
+}
+export interface HumanRequestDTO {
+    request_id: HumanRequestIdDTO;
+    state: HumanRequestState;
+    title: string;
+    subtitle?: string;
+    source: TicketSourceDTO;
+    emitted_at: IsoTime;
+    /** Present unless pending. */
+    settled_at?: IsoTime;
+    /** Present only when `state` is `answered`. */
+    responses?: PageResponsesDTO;
+    reason?: string;
+    actor?: string;
+    /** `action` and `delivery` are both omitted when no action is bound. */
+    action?: {
+        name: string;
+        payload: unknown;
+    };
+    delivery?: HumanRequestDeliveryDetailDTO;
+}
+export interface ReplaceHumanRequestRequest {
+    page: HumanRequestPageDTO;
+    delivery?: HumanRequestDeliveryDTO;
+}
+export interface RespondHumanRequestRequest {
+    responses: PageResponsesDTO;
+    actor?: string;
+}
+export interface SettleHumanRequestRequest {
+    reason?: string;
+    actor?: string;
+}

package/dist/api/dto/human-requests.js

@@ -0,0 +1,4 @@
+// Durable programmatic human-request DTOs — crtrd `/v1/human/requests`. The
+// envelope is snake_case; nested page-protocol objects keep their canonical
+// camelCase names, matching the inbox DTOs.
+export {};

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

@@ -44,6 +44,9 @@ export interface HumanResolveRequest {
 export interface HumanCancelRequest {
     reason?: string;
     actor?: string;
+    /** The recipient surface closing it sends `dismissed`; a requester retracting
+     * it sends `canceled` or omits the field. */
+    disposition?: 'canceled' | 'dismissed';
 }
 /** `POST /v1/human/tickets/{ticket_id}/resolve` result. */
 export interface HumanResolveResultDTO {

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

@@ -1,8 +1,22 @@
+/** The disclosure ladder, lowest to highest. Index order is the ordering. */
+export declare const PROFILE_PROJECT_MEMORY_VALUES: readonly ["none", "name", "preview", "content"];
+/** How much of a project's memory stores the profile relationship lets an
+ *  automatic delivery disclose. */
+export type ProfileProjectMemory = (typeof PROFILE_PROJECT_MEMORY_VALUES)[number];
+/** One project directory in a profile's purview. */
+export interface ProfileProject {
+    /** Absolute, real-path-resolved directory. */
+    path: string;
+    /** Maximum rung automatic boot and workspace-open delivery may reach from
+     *  this project's memory stores, regardless of the node's working directory.
+     *  An authored lower rung stays lower; targeted reads are never capped. */
+    memory: ProfileProjectMemory;
+}
 /** `PUT /v1/profiles/{name}` body — idempotent ensure. Every field applies
  *  only at create; an existing same-named profile is returned untouched. */
 export interface EnsureProfileRequest {
-    /** Absolute project directories in the profile's purview. */
-    projects?: string[];
+    /** Project directories in the profile's purview, each with its memory cap. */
+    projects?: ProfileProject[];
     /** Persona kind for node creates under the profile that omit kind. */
     default_kind?: string;
     /** Profile facts (identity, role); each entry reaches every broker
@@ -37,9 +51,9 @@ export interface ProfileDTO {
     /** Stable profile-directory id (`<slug>-<id>`). */
     id: string;
     name: string;
-    projects: string[];
-    /** Where nodes under this profile run — one of `projects` (the first unless
-     *  re-pointed), or null when the profile owns none. */
+    projects: ProfileProject[];
+    /** Where nodes under this profile run — one of `projects[].path` (the first
+     *  unless re-pointed), or null when the profile owns none. */
     home: string | null;
     /** ISO timestamp when the profile was paused, or null while active. */
     paused_at: string | null;

package/dist/api/dto/profiles.js

@@ -1,3 +1,4 @@
 // Profile DTOs (spec §6.6). Profile deletion crosses profile, canvas, cron,
 // inbox, and review state, so every consumer routes it through crtrd.
-export {};
+/** The disclosure ladder, lowest to highest. Index order is the ordering. */
+export const PROFILE_PROJECT_MEMORY_VALUES = ['none', 'name', 'preview', 'content'];

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

@@ -93,6 +93,8 @@ export interface ReviewCancelResultDTO {
 export interface CancelReviewRequest {
     reason?: string;
     actor?: string;
+    /** Recipient surfaces send `dismissed`; a requester withdrawal defaults to `canceled`. */
+    disposition?: 'canceled' | 'dismissed';
 }
 /** Daemon-derived coordinate base for the terminal review surface. */
 export interface ReviewDocumentBaseDTO {

package/dist/api/index.d.ts

@@ -25,5 +25,7 @@ export * from './dto/human.js';
 export * from './dto/files.js';
 export * from './dto/memory.js';
 export * from './dto/inbox.js';
+export * from './dto/human-requests.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';
+export * from './dto/chat-inventory.js';

package/dist/api/index.js

@@ -26,5 +26,7 @@ export * from './dto/human.js';
 export * from './dto/files.js';
 export * from './dto/memory.js';
 export * from './dto/inbox.js';
+export * from './dto/human-requests.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';
+export * from './dto/chat-inventory.js';

package/dist/api/routes.d.ts

@@ -11,6 +11,8 @@ export declare const routes: {
     readonly nodeSnapshot: (id: string) => string;
     readonly nodeSubject: (id: string) => string;
     readonly nodeSession: (id: string) => string;
+    readonly nodeChatInventory: (id: string) => string;
+    readonly prospectiveChatInventory: () => string;
     readonly nodeTranscript: (id: string) => string;
     readonly nodeContext: (id: string) => string;
     readonly nodeArtifacts: (id: string) => string;
@@ -83,6 +85,12 @@ export declare const routes: {
     readonly humanInboxResponse: (ticketId: string) => string;
     readonly humanInboxCancel: (ticketId: string) => string;
     readonly humanInboxFeedbackResolve: (ticketId: string, commentId: string) => string;
+    readonly humanRequests: () => string;
+    readonly humanRequest: (requestId: string) => string;
+    readonly humanRequestReplace: (requestId: string) => string;
+    readonly humanRequestRespond: (requestId: string) => string;
+    readonly humanRequestDismiss: (requestId: string) => string;
+    readonly humanRequestCancel: (requestId: string) => string;
     readonly profiles: () => string;
     readonly profile: (name: string) => string;
     readonly modelAuths: () => string;

package/dist/api/routes.js

@@ -27,6 +27,8 @@ export const routes = {
     nodeSnapshot: (id) => `${V}/nodes/${id}/snapshot`,
     nodeSubject: (id) => `${V}/nodes/${id}/subject`,
     nodeSession: (id) => `${V}/nodes/${id}/session`,
+    nodeChatInventory: (id) => `${V}/nodes/${id}/chat-inventory`,
+    prospectiveChatInventory: () => `${V}/prospective-chat-inventory`,
     nodeTranscript: (id) => `${V}/nodes/${id}/transcript`,
     nodeContext: (id) => `${V}/nodes/${id}/context`,
     nodeArtifacts: (id) => `${V}/nodes/${id}/artifacts`,
@@ -110,6 +112,15 @@ export const routes = {
     humanInboxResponse: (ticketId) => `${V}/human/inbox/${ticketId}/response`,
     humanInboxCancel: (ticketId) => `${V}/human/inbox/${ticketId}/cancel`,
     humanInboxFeedbackResolve: (ticketId, commentId) => `${V}/human/inbox/${ticketId}/feedback-comments/${commentId}/resolve`,
+    // Durable programmatic human requests. `request_id` is the same opaque
+    // inbox ticket id the `/v1/human/inbox` routes address, so one request is one
+    // record across both surfaces.
+    humanRequests: () => `${V}/human/requests`,
+    humanRequest: (requestId) => `${V}/human/requests/${requestId}`,
+    humanRequestReplace: (requestId) => `${V}/human/requests/${requestId}/replace`,
+    humanRequestRespond: (requestId) => `${V}/human/requests/${requestId}/respond`,
+    humanRequestDismiss: (requestId) => `${V}/human/requests/${requestId}/dismiss`,
+    humanRequestCancel: (requestId) => `${V}/human/requests/${requestId}/cancel`,
     // Profiles (deletion is daemon-owned because it crosses canvas state)
     profiles: () => `${V}/profiles`,
     profile: (name) => `${V}/profiles/${name}`,

package/dist/build-root.d.ts

@@ -1,13 +1,9 @@
 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[];
-/** Every core command path, space-joined ("cron", "cron add", …) — the set
- *  plugin `helpAddenda` keys are validated against at the strict gates
- *  (install, bundle parse, doctor/inspect reports). Loads every core subtree,
- *  so call it only from those gates, never on a dispatch path. Passthrough
- *  branches are excluded: crtr never renders their help, so an addendum
- *  targeting one could never appear. */
+export declare function coreHookCatalog(): Promise<CoreHookCatalog>;
 export declare function coreCommandPaths(): Promise<ReadonlySet<string>>;
 /** Build a root that contains only the subtree `first` dispatches into.
  *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,

package/dist/build-root.js

@@ -1,4 +1,7 @@
 import { defineRoot } from './core/command.js';
+import { createCoreHookCatalog } from './core/command-hooks/catalog.js';
+import { composeCoreHooks } from './core/command-hooks/compose.js';
+import { mark } from './core/timing.js';
 const TAGLINE = 'crtr: agentic runtime.';
 /** Flags handled before dispatch, so they belong to no leaf schema and are
  *  stated once at root (help.ts renders them as the Globals footer). */
@@ -43,8 +46,51 @@ export const SUBTREE_NAMES = Object.freeze(Object.keys(SUBTREE_LOADERS));
  *  so call it only from those gates, never on a dispatch path. Passthrough
  *  branches are excluded: crtr never renders their help, so an addendum
  *  targeting one could never appear. */
+/** Every core subtree, built once per process. The hook catalog and the full
+ *  root both need the complete set; a recognized core first token still loads
+ *  only its own subtree until something actually demands the whole tree. */
+let coreSubtrees;
+function loadCoreSubtrees() {
+    coreSubtrees ??= Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    return coreSubtrees;
+}
+/** Complete static catalog of hook-eligible core leaves. Lifecycle and recovery
+ *  inspection share the same memoized subtree load as root composition. */
+let hookCatalog;
+export function coreHookCatalog() {
+    mark('cli.hooks.catalog');
+    hookCatalog ??= loadCoreSubtrees().then(createCoreHookCatalog);
+    return hookCatalog;
+}
+/** A loader for the effective hook registry, compiled over the COMPLETE core
+ *  catalog so a hook targeting any other subtree is never mistaken for a stale
+ *  target. Loading is lazy — only eligible leaf help or dispatch reaches it,
+ *  and static help discovery never runs a plugin executable. The memoization
+ *  is per composed root, never process-global: discovery reads
+ *  stored plugin bytes and the caller's scope stack, so a plugin install,
+ *  update, or disable (and a cwd change in a long-lived host) must govern the
+ *  next root instead of being pinned by the first one. */
+function hookRegistryLoader() {
+    let registry;
+    return () => {
+        // Dynamic import keeps hook discovery (manifest/artifact validation, plugin
+        // resolution) off the module graph of an invocation that neither renders
+        // eligible leaf help nor dispatches one, matching this file's lazy rationale.
+        registry ??= (async () => {
+            const { compileHookRegistry, effectiveHookPlugins } = await import('./core/command-hooks/discovery.js');
+            const plugins = effectiveHookPlugins();
+            mark('cli.hooks.effective_plugins', { count: plugins.length });
+            if (plugins.length === 0) {
+                mark('cli.hooks.empty_registry');
+                return compileHookRegistry(createCoreHookCatalog([]), []);
+            }
+            return compileHookRegistry(await coreHookCatalog(), plugins);
+        })();
+        return registry;
+    };
+}
 export async function coreCommandPaths() {
-    const core = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    const core = await loadCoreSubtrees();
     const paths = new Set();
     const visit = (node, prefix) => {
         if (node.kind === 'branch' && node.passthrough !== undefined)
@@ -67,7 +113,7 @@ export async function coreCommandPaths() {
 export async function resolveRoot(first) {
     const loader = first !== undefined ? SUBTREE_LOADERS[first] : undefined;
     if (loader !== undefined) {
-        return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [await loader()] });
+        return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: composeCoreHooks([await loader()], hookRegistryLoader()) });
     }
     return buildRoot();
 }
@@ -88,7 +134,7 @@ export async function resolveRoot(first) {
  *  HTTP-transport plugin manifest replacement takes effect on the next invocation
  *  automatically. Composition performs no network I/O. */
 export async function buildRoot() {
-    const core = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    const core = await loadCoreSubtrees();
     // Dynamic import keeps external command discovery/compose (plugin +
     // HTTP-transport plugin, and their resolver/manifest/HTTP deps) OFF the hot leaf
     // path's module graph — they load only here, on the fallthrough, matching
@@ -102,5 +148,6 @@ export async function buildRoot() {
     // sys doctor). Reads only stored manifests — zero network.
     const snapshot = buildExternalCommandSnapshot(new Set(SUBTREE_NAMES));
     const external = composeExternalSubtrees(snapshot);
-    return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [...core, ...external] });
+    // Only core leaves are hookable, so external contributions compose unwrapped.
+    return defineRoot({ tagline: TAGLINE, globals: GLOBALS, subtrees: [...composeCoreHooks(core, hookRegistryLoader()), ...external] });
 }

package/dist/builtin-memory/00-runtime-base/00-authoring.md

@@ -0,0 +1,31 @@
+---
+kind: preference
+when-and-why-to-read: When a node writes an artifact, report, or decision for another reader, this preference should be read because current, concrete records let the next action proceed without reconstructing stale context or invented terminology.
+rationale: >-
+  The living-document paragraph ("Living documents") exists because agents default to appending — plans kept old+new versions side by side, answered Q&A sections stayed behind after the answer was folded in, findings docs grew contradicted layers (observed by Silas, 2026-07-08). The stale trail isn't neutral history; it keeps steering the next reader (the pink-elephant effect), measurably dulling the agent that consumes the doc. Orchestrators already had this discipline in the kernel; base workers, who author most artifacts, had nothing.
+
+  "Say what actually happens" exists because an approval request called a root a person had created an "attended root" — an invented category with no referent in the product, which forced Silas to halt the decision and ask what the term meant (2026-07-28). Agents coin taxonomies to compress a distinction; the reader pays by decoding a word that names nothing real.
+
+  The Mermaid line exists because the viewer's inline diagram affordance is otherwise invisible to an agent working from ordinary Markdown defaults.
+
+  An "Identity" section is deliberately absent, and the artifacts section carries no paths. The bearings message already states the node id, the context dir's absolute path, the `$CRTR_CONTEXT_DIR` env var, the address-by-absolute-path rule, the bare-`context/` trap, and the cwd — so a layer copy was pure duplication. It was also the only per-node text in the whole system-prompt block: the preference render interpolates `$CRTR_NODE_ID`/`$CRTR_CONTEXT_DIR`, which made every node's cached prompt prefix globally unique. Keep node-specific values out of this layer; bearings is where they belong.
+lint-ignore: length
+surfaces:
+  - on: boot
+    at: content
+---
+
+## Working in the canvas
+You are a **node** in a live agent graph (the crtr canvas). This section is your operating protocol — it is true for every node regardless of role.
+
+## Artifacts
+An artifact you write to your context dir is shared by pointer: whatever carries it — a report, a reply, an ask — names its absolute path, never the full substance pasted in.
+
+## Living documents
+Every doc you keep — artifact, plan, findings, memory — is a living statement of what is true *now*, never a log of how it got that way. When something changes, rewrite the doc in place as if writing it fresh: fold an answer into the section it settles and delete the question, replace superseded findings, and never leave an old version beside the new one. Superseded text keeps steering whoever reads it — an audit trail in a working doc costs the next reader the very attention the doc exists to save.
+
+## Say what actually happens
+Everything you write — replies, reports, approval requests, artifacts, memory docs, comments — describes systems in concrete, existing product terms: the real command, the real event, the actual cause. When you need shorthand for a distinction, spell it out ("a root created by a person" vs "a root created by a cron job") instead of coining a label ("attended root"); an invented term makes the reader stop and decode a category the system does not actually have.
+
+## Mermaid diagrams
+When visual structure would land faster than prose, use a Mermaid fence; the user's terminal viewer renders it inline.

package/dist/builtin-memory/00-runtime-base/01-escalation.md

@@ -0,0 +1,14 @@
+---
+kind: preference
+when-and-why-to-read: When progress depends on a person deciding, reviewing, or responding, or when a crtr command fails unexpectedly, this preference should be read because the runtime can deliver the needed signal to its actual recipient instead of leaving work stranded in conversation prose.
+rationale: The human inbox and system-feedback commands are delivery paths whose effects are otherwise invisible in ordinary conversation.
+surfaces:
+  - on: boot
+    at: content
+---
+
+## When blocked, want feedback, or need the user
+Don't guess at a decision a person should make. Run `crtr human send -h` and put the question to the user through the crouter human inbox, because a question posed as prose in a reply or report pings nobody while an ask lands on their screen and pushes the answer back to your inbox. An ask blocks on a person, so spend them well: resolve what the code, a tool, or a delegate can settle, and engage when intent is genuinely ambiguous, when approaches carry real tradeoffs, when scope or direction changes, when an action is irreversible or high-risk, or when finished work needs sign-off — a whole goal costs a handful of asks, not a stream.
+
+## When crtr itself misbehaves
+A `crtr` command that errors unexpectedly, hangs, churns, double-spawns, or contradicts its own `-h` is a harness bug — don't silently work around it. Run `crtr sys feedback` to report it (`-h` for how), then continue.

package/dist/builtin-memory/{insights/listen.md → 00-runtime-base/02-insight-capture.md}

@@ -7,4 +7,5 @@ surfaces:
     at: content
 ---
 
+## When user knowledge should persist
 When directly received user-supplied or user-validated material may contain a coherent reusable principle, follow [[insights/capture]]. Use an active domain listener's boundary when one matches; otherwise use the higher bar: the episode must justify a permanent reusable principle future agents should be routed to, and a new domain needs that principle as its first approved truth. Do not treat approval of an insight review as a fresh candidate, because user knowledge unavailable from model weights should not disappear with the episode.

package/dist/builtin-memory/02-turn-lifecycle/00-ending-a-turn.md

@@ -0,0 +1,27 @@
+---
+kind: preference
+when-and-why-to-read: When a node has no immediate action because it awaits an event, a person, or a fresh context window, this preference should be read because ending the turn through the matching runtime path preserves wakeability without wasting a live window or losing an unanswered decision.
+rationale: >-
+  "Waiting is a way to end a turn" lived in its own ungated all-node doc until 2026-07-28. Same gate, same audience, never independently readable — so the split bought no routing and cost a stub cross-reference in runtime-base pointing at a section spliced a few hundred tokens later. It now has its own sort position as the turn-lifecycle preamble; split it again only when a section needs its own sort position, incident rationale, or independent deletion/re-gate decision.
+
+  Yield applies to every node regardless of mode; promotion does not, because only the mode layers own that boundary — 04-base-worker for when a base node should promote, the kernel for how an orchestrator uses promotion — so restating it in the universal layer duplicated the base-worker text for an audience that includes nodes it does not apply to.
+lint-ignore: length
+surfaces:
+  - on: boot
+    at: content
+---
+
+## Waiting is a way to end a turn
+
+When your goal is sound but your next step is blocked on something that has not happened yet — a child's report, the user, a CI run, tomorrow morning — you are **waiting**. Waiting is free: you end your turn, hold no window, and burn no compute, and the runtime brings you back the instant the thing you wait on happens.
+
+- **Never busy-wait.** Do not hold your window open to re-poll a URL or watch a clock. A wait that costs a live window is a defect — just stop: end your turn and go dormant.
+- **For waits the runtime already knows — a child's report or the reply to your own human page — just stop.** Go dormant; the runtime wakes you when it lands. There is nothing to poll or verify, and a deadline set to "check in" on a delegate is unnecessary — children auto-wake you when they push.
+- **Schedule a wake yourself only when nothing can push to you** — recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). Run `crtr cron -h` to schedule the matching bash action, or `crtr node wait deadline -h` when the desired contract is an inbox-versus-deadline race.
+
+## Yield for a fresh window
+When your context is filling but the mandate isn't done, yield: you revive fresh as the same node with the same mandate, carrying a note to your future self.
+
+    crtr node yield                     # `crtr node yield -h` — refresh into a clean window, carrying a note forward
+
+Never yield carrying an unasked question: put anything you're still wondering for the user through `crtr human send` BEFORE you yield — an in-flight ask survives the refresh, and its answer wakes your fresh window like any child's report.

package/dist/builtin-memory/{02-lifecycle/01-resident.md → 02-turn-lifecycle/02-resident.md}

@@ -7,5 +7,10 @@ surfaces:
     at: content
 ---
 
+## Communicating with the user
+- Respond to what was actually said—don’t invent questions, concerns, or agreement.
+- Lead with substance—skip praise, validation, and conversational throat-clearing.
+- Use plain, proportionate language—cut clichés, metaphors, faux urgency, and repetition.
+
 ## How you end
 You are **resident** and interactable: you are never forced to submit a final result. Stopping is legitimate — the runtime keeps live waits wakeable and completes an unattended conversation after nothing remains to wake it. Do **not** `crtr push final` to "finish" (it would close you mid-conversation); you end by yielding or by being closed. End your turn whenever you have nothing in hand — the runtime owns what happens next.