@north-light/crouter-api 0.3.281 → 0.3.283

package/dist/api/client.d.ts

@@ -1,15 +1,16 @@
 import type { DaemonRestartDTO, HealthDTO, StatusDTO } from './dto/health.js';
 import type { BashJobStatusDTO, BashJobStopResultDTO } from './dto/bash-jobs.js';
 import type { ArtifactListDTO, ArtifactsQuery, 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 { InterruptResultDTO, MessageResultDTO, SendMessageRequest } from './dto/messages.js';
-import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery } from './dto/reports.js';
+import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery, SubmitResultDTO, SubmitResultRequest } from './dto/reports.js';
 import type { CloseRequest, CloseResultDTO, PromoteRequest, RelaunchRootResultDTO, ReviveRequest, ReviveResultDTO, WaitRequest, YieldRequest } from './dto/lifecycle.js';
 import type { SubscribeRequest, SubscriptionDTO } from './dto/subscriptions.js';
 import type { FocusDTO, RegisterFocusRequest, SetFocusPaneRequest } from './dto/focus.js';
 import { type ArmCronRequest, type CancelCronQuery, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery, type PokeCronsResult } from './dto/crons.js';
 import type { NodeConfigPatch } from './dto/config.js';
 import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js';
-import type { DeleteProfileRequest, DeleteProfileResultDTO, EnsureProfileRequest, ProfileDTO, UpdateProfileMetadataRequest } from './dto/profiles.js';
+import type { DeleteProfileRequest, DeleteProfileResultDTO, EnsureProfileRequest, ProfileDTO, ProfilePauseResultDTO, UpdateProfileMetadataRequest } 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';
@@ -21,7 +22,7 @@ import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, I
 import type { CreateHumanRequestDTO, CreateHumanRequestRequest, HumanRequestDTO, HumanRequestIdDTO, ReplaceHumanRequestRequest, RespondHumanRequestRequest, SettleHumanRequestRequest } from './dto/human-requests.js';
 import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryStatsQuery, HistoryStatsResultDTO, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
 import type { AbandonWorktreeRequest, AbandonWorktreeResultDTO, CloseWorktreeResultDTO, QuarantinedWorktreeDTO } from './dto/worktree.js';
-import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerParkActivityResultDTO, BrokerParkCompleteRequest, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
 export interface CrtrClientOptions {
     /** Unix socket path (default local transport). Exactly one of socketPath|baseUrl. */
     socketPath?: string;
@@ -95,6 +96,16 @@ export declare class CrtrClient {
      * latest/canonical reports and pending-human counts in the same response. */
     listNodes(q?: ListNodesQuery): Promise<NodeSummaryDTO[]>;
     getNode(id: string): Promise<NodeDetailDTO>;
+    /** Read a node outcome, optionally awaiting it for at most 25 seconds. This
+     * is a GET so the client can safely replay it across daemon handover. */
+    getNodeOutcome(id: string, { waitSeconds }?: {
+        waitSeconds?: number;
+    }): Promise<NodeOutcomeResponseDTO>;
+    /** Register or replace an armed target for terminal-outcome delivery. */
+    registerOutcomeDelivery(id: string, req: RegisterOutcomeDeliveryRequest): Promise<OutcomeDeliveryDTO>;
+    getOutcomeDelivery(id: string): Promise<OutcomeDeliveryDTO>;
+    /** Disarm an unsettled outcome-delivery registration. */
+    disarmOutcomeDelivery(id: string): Promise<void>;
     listBashJobs(id: string): Promise<BashJobStatusDTO[]>;
     stopBashJob(id: string, jobId: string): Promise<BashJobStopResultDTO>;
     sendMessage(id: string, req: SendMessageRequest): Promise<MessageResultDTO>;
@@ -103,11 +114,14 @@ export declare class CrtrClient {
      *  revives a dormant target. */
     interruptNode(id: string): Promise<InterruptResultDTO>;
     pushReport(id: string, req: PushReportRequest): Promise<PushReportResultDTO>;
+    submitResult(id: string, req: SubmitResultRequest): Promise<SubmitResultDTO>;
     forkNode(id: string): Promise<NodeDetailDTO>;
     reviveNode(id: string, req?: ReviveRequest): Promise<ReviveResultDTO>;
     relaunchRoot(id: string): Promise<RelaunchRootResultDTO>;
     bindBrokerSession(id: string, req: BrokerSessionBoundRequest): Promise<BrokerSessionBoundResultDTO>;
     settleBroker(id: string, req: BrokerSettleRequest): Promise<BrokerSettleDirective>;
+    completeBrokerPark(id: string, req: BrokerParkCompleteRequest): Promise<BrokerSettleDirective>;
+    recordBrokerParkActivity(id: string): Promise<BrokerParkActivityResultDTO>;
     advanceBrokerInboxCursor(id: string, req: BrokerInboxCursorRequest): Promise<BrokerInboxCursorDirective>;
     commitBrokerModel(id: string, req: BrokerModelCommitRequest): Promise<BrokerModelCommitResultDTO>;
     brokerExtensionState(id: string): Promise<BrokerExtensionStateDTO>;
@@ -187,6 +201,8 @@ export declare class CrtrClient {
     ensureProfile(name: string, req?: EnsureProfileRequest): Promise<ProfileDTO>;
     listProfiles(): Promise<ProfileDTO[]>;
     getProfile(name: string): Promise<ProfileDTO>;
+    pauseProfile(name: string): Promise<ProfilePauseResultDTO>;
+    resumeProfile(name: string): Promise<ProfilePauseResultDTO>;
     /** Merge and remove entries in a profile's metadata map. */
     updateProfileMetadata(name: string, req: UpdateProfileMetadataRequest): Promise<ProfileDTO>;
     /** Force-delete or detach one profile by exact id or unique name. */

package/dist/api/client.js

@@ -104,6 +104,25 @@ export class CrtrClient {
     getNode(id) {
         return this.request('GET', routes.node(this.nodePath(id)));
     }
+    /** Read a node outcome, optionally awaiting it for at most 25 seconds. This
+     * is a GET so the client can safely replay it across daemon handover. */
+    getNodeOutcome(id, { waitSeconds } = {}) {
+        if (waitSeconds !== undefined && (!Number.isInteger(waitSeconds) || waitSeconds < 0 || waitSeconds > 25)) {
+            throw new RangeError('waitSeconds must be an integer between 0 and 25');
+        }
+        return this.request('GET', withQuery(routes.nodeOutcome(this.nodePath(id)), { wait: waitSeconds }));
+    }
+    /** Register or replace an armed target for terminal-outcome delivery. */
+    registerOutcomeDelivery(id, req) {
+        return this.request('PUT', routes.nodeOutcomeDelivery(this.nodePath(id)), req);
+    }
+    getOutcomeDelivery(id) {
+        return this.request('GET', routes.nodeOutcomeDelivery(this.nodePath(id)));
+    }
+    /** Disarm an unsettled outcome-delivery registration. */
+    async disarmOutcomeDelivery(id) {
+        await this.request('DELETE', routes.nodeOutcomeDelivery(this.nodePath(id)));
+    }
     listBashJobs(id) {
         return this.request('GET', routes.nodeJobs(this.nodePath(id)));
     }
@@ -122,6 +141,9 @@ export class CrtrClient {
     pushReport(id, req) {
         return this.request('POST', routes.nodeReports(this.nodePath(id)), req);
     }
+    submitResult(id, req) {
+        return this.request('POST', routes.nodeResult(this.nodePath(id)), req);
+    }
     forkNode(id) {
         return this.request('POST', routes.nodeFork(this.nodePath(id)), {});
     }
@@ -137,6 +159,12 @@ export class CrtrClient {
     settleBroker(id, req) {
         return this.request('POST', routes.nodeBrokerSettle(this.nodePath(id)), req);
     }
+    completeBrokerPark(id, req) {
+        return this.request('POST', routes.nodeBrokerParkComplete(this.nodePath(id)), req);
+    }
+    recordBrokerParkActivity(id) {
+        return this.request('POST', routes.nodeBrokerParkActivity(this.nodePath(id)), {});
+    }
     advanceBrokerInboxCursor(id, req) {
         return this.request('POST', routes.nodeBrokerInboxCursor(this.nodePath(id)), req);
     }
@@ -319,6 +347,12 @@ export class CrtrClient {
     getProfile(name) {
         return this.request('GET', routes.profile(name));
     }
+    pauseProfile(name) {
+        return this.request('POST', routes.profilePause(name), {});
+    }
+    resumeProfile(name) {
+        return this.request('POST', routes.profileResume(name), {});
+    }
     /** Merge and remove entries in a profile's metadata map. */
     updateProfileMetadata(name, req) {
         return this.request('PATCH', routes.profileMetadata(name), req);

package/dist/api/dto/broker-ops.d.ts

@@ -36,6 +36,17 @@ export type BrokerSettleDirective = {
 } | {
     action: 'shutdown';
 };
+/** A main-engine input has won broker admission while a parking summary may be
+ * in flight. crtrd records it against the process-local pending marker before
+ * Pi begins the input, making parking completion and input admission atomic. */
+export interface BrokerParkActivityResultDTO {
+    activity: 'recorded' | 'none';
+}
+/** `POST /v1/nodes/{id}/broker/park-complete` body. The isolated parking turn
+ * has ended; crtrd alone decides whether its pending park still applies. */
+export interface BrokerParkCompleteRequest {
+    outcome: 'completed' | 'failed';
+}
 /** `POST /v1/nodes/{id}/broker/inbox-cursor` body. The watcher advances this
  * only after Pi has settled every handoff through the supplied physical entry.
  * `brokerPid` binds the commit to the broker generation crtrd currently owns. */

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

@@ -46,11 +46,6 @@ export interface BrokerWelcomeFrame<M = unknown> {
     type: 'welcome';
     snapshot?: BrokerWelcomeSnapshot<M>;
 }
-/** The presentation classification of the run whose native events follow. */
-export interface BrokerTurnVisibilityFrame {
-    type: 'turn_visibility';
-    visibility: 'visible' | 'internal';
-}
 /**
  * The crtrd broker `node_named` control frame — the node's generated name at the
  * instant crtrd committed it.
@@ -76,12 +71,12 @@ export interface BrokerNodeNamedFrame {
     editorLabel: string;
 }
 /**
- * The broker-control frames a relay consumer reads: `welcome` (catch-up snapshot),
- * `turn_visibility`, `error`, and `node_named`. The broker interleaves others (display_*, ack, …)
+ * The broker-control frames a relay consumer reads: `welcome`, `error`, and
+ * `node_named`. The broker interleaves others (display_*, ack, …)
  * under non-colliding `type` discriminants; a relay mapper drops those through its
  * `default` arm untyped, so they are not enumerated here.
  */
-export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerTurnVisibilityFrame | BrokerErrorFrame | BrokerNodeNamedFrame;
+export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerErrorFrame | BrokerNodeNamedFrame;
 /**
  * What the crtrd broker attach delivers to a relay consumer: the live engine
  * event stream (`E` — pi's `AgentSessionEvent`, relayed verbatim) unioned with the

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

@@ -20,7 +20,7 @@ export type ModeDTO = 'base' | 'orchestrator';
 /** Why a node last stopped (mirrors the runtime `ExitIntent` union). */
 export type ExitIntentDTO = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
 /** Why a terminal node ended (mirrors the runtime `TerminalReason` union). */
-export type TerminalReasonDTO = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded';
+export type TerminalReasonDTO = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined';
 /** Inbox urgency tier for a delivered message (mirrors feed/inbox `InboxTier`). */
 export type InboxTierDTO = 'critical' | 'urgent' | 'normal' | 'deferred';
 /** Whether a node id is a safe single filesystem path segment. Re-declared here

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

@@ -36,8 +36,8 @@ export interface SendMessageRequest {
     /** One-shot runtime cards for this turn only — never persisted. Delivered in
      *  array order, after `situational_card` and ahead of the body. */
     context_cards?: RuntimeCardRequest[];
-    /** Raw JSON-schema string granting a one-off `submit` tool before delivery
-     *  (`--output-schema`). Immediate only. */
+    /** Raw JSON-schema string installing a one-off output schema before delivery
+     *  (`--output-schema`); the target answers with `crtr push result`. Immediate only. */
     output_schema?: string;
     /** `'interactive'`: deliver via the target's LIVE broker engine (prompt/steer
      *  on its one serialized frame loop — the same ordering a tmux viewer gets)

package/dist/api/dto/node-outcomes.d.ts

@@ -0,0 +1,80 @@
+import type { IsoTime, NodeIdDTO, NodeStatusDTO, TerminalReasonDTO } from './common.js';
+import type { DeclinedResultDTO } from './reports.js';
+export type OutcomeKindDTO = 'result' | 'failure';
+/** Bounded diagnostics recorded for a failed node outcome. */
+export interface NodeOutcomeDetailV1 {
+    schema: 'crtr.node-outcome-detail/v1';
+    message?: string;
+    fault_kind?: 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
+    error_class?: 'rate_limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context_overflow' | 'wedged' | 'model_not_found' | 'unknown';
+    respawn_failures?: number;
+    deadline?: {
+        deadline_at: string;
+        elapsed_ms: number;
+    };
+    /** Present only for reason `declined`: what the node gave `crtr push result --decline`. */
+    declined?: DeclinedResultDTO;
+    truncated?: true;
+}
+interface NodeOutcomeBaseDTO {
+    node_id: NodeIdDTO;
+    revision: number;
+    settled_at: IsoTime;
+    /** Canonical final report basename; set for kind='result' and for a declined structured result (kind='failure', reason='declined'); else null. */
+    final_report: string | null;
+    /** Absolute path of the canonical final report; null whenever `final_report` is. */
+    final_report_path: string | null;
+    /** Parsed context/result.json when the node ran under --output-schema; else null. */
+    structured_result: unknown | null;
+    /** Bounded diagnostics; null for kind='result'. */
+    detail: NodeOutcomeDetailV1 | null;
+}
+/** A settled outcome. Narrowing on `kind` then `reason` makes a declined
+ *  structured result (`failure`/`declined`) a case a consumer must handle:
+ *  only that case carries `declined`; every other outcome has it null. */
+export type NodeOutcomeDTO = (NodeOutcomeBaseDTO & {
+    kind: 'result';
+    reason: TerminalReasonDTO;
+    declined: null;
+}) | (NodeOutcomeBaseDTO & {
+    kind: 'failure';
+    reason: 'declined';
+    declined: DeclinedResultDTO;
+}) | (NodeOutcomeBaseDTO & {
+    kind: 'failure';
+    reason: Exclude<TerminalReasonDTO, 'declined'>;
+    declined: null;
+});
+export interface NodeOutcomeResponseDTO {
+    node_id: NodeIdDTO;
+    state: 'pending' | 'settled';
+    outcome: NodeOutcomeDTO | null;
+    node_status: NodeStatusDTO;
+    deadline_at: IsoTime | null;
+}
+export interface RegisterOutcomeDeliveryRequest {
+    /** A name declared in the humanActions map of scope config. */
+    action: string;
+    /** Opaque, frozen at registration, echoed verbatim in the document. */
+    payload?: unknown;
+}
+export type OutcomeDeliveryStateDTO = 'armed' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
+export interface OutcomeDeliveryDTO {
+    node_id: NodeIdDTO;
+    state: OutcomeDeliveryStateDTO;
+    action: string;
+    attempt: number;
+    /** ISO-8601 time of the next retry, or null before the row is scheduled. */
+    next_attempt_at: IsoTime | null;
+    accepted_at: IsoTime | null;
+    permanent_failed_at: IsoTime | null;
+    last_failure: {
+        kind: string;
+        exit_code?: number;
+        signal?: string;
+        message?: string;
+    } | null;
+    created_at: IsoTime;
+    updated_at: IsoTime;
+}
+export {};

package/dist/api/dto/node-outcomes.js

@@ -0,0 +1,2 @@
+// Node terminal-outcome and outcome-delivery DTOs.
+export {};

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

@@ -1,5 +1,6 @@
 import type { Cursor, ExitIntentDTO, IsoTime, LifecycleDTO, ModeDTO, NodeIdDTO, NodeStatusDTO, TerminalReasonDTO } from './common.js';
 import type { ReportDTO } from './reports.js';
+import type { NodeOutcomeDTO, RegisterOutcomeDeliveryRequest } from './node-outcomes.js';
 /** `GET /v1/nodes/{id}/subject` — the node-config subject substrate gate
  *  predicates evaluate against. Mirrors `NodeConfigSubject`; this narrow
  *  endpoint exists so a CLI process (the `memory read` leaf) can gate-check
@@ -51,6 +52,10 @@ export interface CreateNodeRequest {
     situational_context?: string;
     no_kickoff?: boolean;
     output_schema?: string;
+    /** Wall-clock bound from spawn, e.g. "45m", "2h", "1h30m". Expiry cancels the node and synthesizes a failure outcome with reason 'deadline_exceeded'. */
+    deadline?: string;
+    /** Arm outcome delivery atomically with node birth. */
+    outcome_delivery?: RegisterOutcomeDeliveryRequest;
     /** Spawn AT this exact node id instead of a runtime-minted one — format-
      *  validated and duplicate-rejected server-side (`NodeIdConflictError` →
      *  HTTP 409 `node_id_exists`). See `crtr node new --node-id`. */
@@ -80,6 +85,8 @@ export interface NodeSummaryDTO {
     cwd: string;
     host_kind: 'tmux' | 'broker' | null;
     profile_id: string | null;
+    /** Whether the node's profile is currently paused. */
+    profile_paused: boolean;
     parent: NodeIdDTO | null;
     created: IsoTime;
     intent: ExitIntentDTO;
@@ -96,6 +103,8 @@ export interface NodeSummaryDTO {
     /** Basename of the canonical final report, or null when this node has not finalized. */
     final_report: string | null;
     finalized_at: IsoTime | null;
+    deadline_at: IsoTime | null;
+    outcome: NodeOutcomeDTO | null;
     /** Present only when requested with `include=activity`. */
     activity?: NodeActivityDTO;
 }

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

@@ -28,6 +28,11 @@ export interface UpdateProfileMetadataRequest {
     set?: Record<string, string>;
     unset?: string[];
 }
+/** The daemon-owned result of pausing or resuming one profile. */
+export interface ProfilePauseResultDTO {
+    profile_id: string;
+    paused_at: string | null;
+}
 /** `DELETE /v1/profiles/{name}` body. Destructive deletion is never implicit. */
 export interface DeleteProfileRequest {
     force: boolean;

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

@@ -31,6 +31,51 @@ export interface PushReportResultDTO {
     /** Present only alongside `worktree_auto_dropped`: the checkout path dropped. */
     worktree_auto_dropped_path?: string;
 }
+/** Why a node declined a structured result. `reason` is one plain sentence
+ *  for a reader; `code` is an opaque token the requester classifies on and
+ *  validates itself — crouter only carries it; `retryable` is the node's
+ *  claim that the same request could succeed later. */
+export interface DeclinedResultDTO {
+    reason: string;
+    code: string;
+    retryable: boolean;
+}
+/** `POST /v1/nodes/{id}/result` body ({id} = the submitting node). Either the
+ *  structured result to validate against the node's pending output schema —
+ *  `value` must be present; any JSON value (including null) is legal input to
+ *  validation — or a decline: `decline` is the reason sentence, `code` the
+ *  requester-classified token, `retryable` the node's retry claim. A decline
+ *  records a `failure` outcome with reason `declined` carrying all three and
+ *  clears the request without validating anything. */
+export type SubmitResultRequest = {
+    value: unknown;
+} | {
+    decline: string;
+    code: string;
+    retryable: boolean;
+};
+/** Result of a structured-result submission (`crtr push result`). Terminal
+ *  mode reuses the final-push machinery, so `transitioned` and the worktree
+ *  auto-drop fields carry the same meaning as on PushReportResultDTO. */
+export interface SubmitResultDTO {
+    /** Which request this answered: `terminal` finished the node; `oneoff` left it working. */
+    mode: 'terminal' | 'oneoff';
+    /** Absolute path of the recorded artifact: context/result.json for an
+     *  answered request, context/declined.json for a declined one. */
+    result_path: string;
+    /** Present only when the request was declined. */
+    declined?: DeclinedResultDTO;
+    /** Absolute path of the report pushed alongside the result. */
+    report_path: string;
+    /** Subscriber node ids that received an inbox entry. */
+    notified: NodeIdDTO[];
+    transitioned?: {
+        from: string;
+        to: string;
+    };
+    worktree_auto_dropped?: boolean;
+    worktree_auto_dropped_path?: string;
+}
 /** `GET /v1/nodes/{id}/reports` query filters. */
 export interface ReportsQuery {
     tier?: ReportTierDTO;

package/dist/api/index.d.ts

@@ -7,6 +7,7 @@ export * from '../shared/generated-context.js';
 export * from './dto/common.js';
 export * from './dto/health.js';
 export * from './dto/nodes.js';
+export * from './dto/node-outcomes.js';
 export * from './dto/bash-jobs.js';
 export * from './dto/messages.js';
 export * from './dto/reports.js';

package/dist/api/index.js

@@ -8,6 +8,7 @@ export * from '../shared/generated-context.js';
 export * from './dto/common.js';
 export * from './dto/health.js';
 export * from './dto/nodes.js';
+export * from './dto/node-outcomes.js';
 export * from './dto/bash-jobs.js';
 export * from './dto/messages.js';
 export * from './dto/reports.js';

package/dist/api/plugin-manifest-schema.d.ts

@@ -0,0 +1,208 @@
+/** How prominently a node surfaces in ancestor `-h` listings. Default 'normal'. */
+export type ManifestTier = 'normal' | 'common' | 'important';
+/** Root-entry prose for a top-level branch — what every agent reads before it
+ *  has engaged the command at all. Required on a plugin's top-level branch. */
+export interface ManifestRootEntry {
+    concept: string;
+    description: string;
+    whenToUse: string;
+}
+/** One declared output field of a leaf's result. */
+export interface ManifestField {
+    name: string;
+    type: string;
+    required: boolean;
+    /** Inline semantic constraint — bounds, enum, token caps. */
+    constraint: string;
+}
+/** How a local file named by a `path` param is encoded into the request: 'text'
+ *  as UTF-8, 'base64' as the base64 of its raw bytes. The path string itself
+ *  never crosses the wire. */
+export type ManifestFileEncoding = 'text' | 'base64';
+export interface ManifestPositionalParam {
+    kind: 'positional';
+    name: string;
+    /** Display hint only; always parsed as string. */
+    type?: 'string' | 'path';
+    required: boolean;
+    constraint: string;
+    /** Collect every remaining positional token into an array, in argv order.
+     *  Only an `in: 'body'` REST mapping can carry an array. */
+    repeatable?: boolean;
+    /** Valid only on a `path` param. */
+    encoding?: ManifestFileEncoding;
+    /** See {@link ManifestFlagParam.defaultFromEnv}. */
+    defaultFromEnv?: string;
+}
+export interface ManifestFlagParam {
+    kind: 'flag';
+    name: string;
+    /** 'bool' flags take no value — presence is true. */
+    type: 'string' | 'int' | 'bool' | 'path' | 'enum';
+    /** Required, and only valid, when type is 'enum'. */
+    choices?: string[];
+    required: boolean;
+    constraint: string;
+    default?: string | number | boolean;
+    /** Repeat the flag to accumulate an array value. Valid only on string/int/enum,
+     *  only with an `in: 'body'` REST mapping, and never alongside `default`. */
+    repeatable?: boolean;
+    /** Valid only on a `path` flag. */
+    encoding?: ManifestFileEncoding;
+    /** UPPER_SNAKE_CASE environment variable on the CALLING machine whose value
+     *  fills this param when the caller omits it. An env-sourced value counts as
+     *  SUPPLIED — it satisfies `required` and ships on the wire — unlike a static
+     *  `default`, which does neither. Valid only on string/path params, never
+     *  alongside `default` or `repeatable`. */
+    defaultFromEnv?: string;
+}
+/** Raw stdin content blob — piped text, not parsed as JSON. */
+export interface ManifestStdinParam {
+    kind: 'stdin';
+    name: string;
+    required: boolean;
+    constraint: string;
+}
+/** `--context-file PATH`: reads and JSON-parses the file at PATH. */
+export interface ManifestContextFileParam {
+    kind: 'context-file';
+    name: string;
+    required: boolean;
+    constraint: string;
+    /** Description of the expected JSON shape. */
+    shape?: string;
+}
+export type ManifestInputParam = ManifestPositionalParam | ManifestFlagParam | ManifestStdinParam | ManifestContextFileParam;
+export type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type RestParamPlacement = 'path' | 'query' | 'body' | 'header';
+export interface RestParamMapping {
+    in: RestParamPlacement;
+    /** Rename for query/body; required for header; forbidden for path. */
+    as?: string;
+}
+export interface RestMapping {
+    method: RestMethod;
+    /** Absolute path template; each `{param}` placeholder names an `in: 'path'` param. */
+    path: string;
+    /** Default false. true means the response is an NDJSON stream relayed verbatim. */
+    streaming?: boolean;
+    /** Constant body fields merged into the request body verbatim (e.g. the `op`
+     *  discriminator on a single-endpoint invoke surface) — never sourced from a
+     *  declared param, and forbidden on GET. */
+    body?: Record<string, string | number | boolean>;
+    /** When set, every `in: 'body'` param value nests under this key instead of
+     *  sitting top-level (`bodyRoot: 'args'` → `{ args: { name, url } }`);
+     *  `body` constants stay top-level regardless. Forbidden on GET. */
+    bodyRoot?: string;
+    /** Keyed by declared param name; every declared param appears exactly once. */
+    params: Record<string, RestParamMapping>;
+}
+export interface ManifestTimeouts {
+    connectMs?: number;
+    requestMs?: number;
+    streamIdleMs?: number;
+}
+/** Exec transport only: forward every argv token after this branch to an
+ *  external binary instead of parsing children. A passthrough branch is
+ *  childless by construction; an HTTP manifest rejects it, because an HTTP
+ *  transport must not name a local binary to execute. */
+export interface ManifestPassthrough {
+    bin: string;
+    installHint: string;
+}
+export interface ManifestLeafBase {
+    kind: 'leaf';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: ManifestTier;
+    summary: string;
+    params: ManifestInputParam[];
+    output: ManifestField[];
+    /** Non-empty; `["None. Read-only."]` for a read-only leaf. Read-only, so a
+     *  server assembling a manifest may hand over a frozen or `as const` list. */
+    effects: readonly string[];
+}
+/** Exec-transport leaf. */
+export interface ManifestExecLeaf extends ManifestLeafBase {
+    outputKind: 'object';
+}
+/** HTTP-transport leaf; `outputKind` derives from `rest.streaming`. */
+export interface ManifestHttpLeaf extends ManifestLeafBase {
+    rest: RestMapping;
+}
+export type ManifestLeaf = ManifestExecLeaf | ManifestHttpLeaf;
+export interface ManifestBranch<L extends ManifestLeafBase = ManifestLeaf> {
+    kind: 'branch';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: ManifestTier;
+    /** Required on a top-level branch, forbidden on a nested one. */
+    rootEntry?: ManifestRootEntry;
+    /** Allows the nearest repository fragment to contribute children below this
+     *  top-level branch. */
+    extensible?: true;
+    summary: string;
+    model?: string;
+    /** Exec dialect only, and the type says so rather than leaving it to the
+     *  runtime validator: an HTTP-transport manifest naming a local binary to run
+     *  is the one shape a served manifest must never be able to express. `never`
+     *  on the HTTP leaf dialect makes `passthrough: {...}` a compile error in a
+     *  `ManifestBranch<ManifestHttpLeaf>`, and the conditional distributes over
+     *  the default union so a plain `ManifestBranch` still accepts it. */
+    passthrough?: L extends ManifestExecLeaf ? ManifestPassthrough : never;
+    children: ManifestNode<L>[];
+}
+/** A branch or a leaf. The parameter fixes which leaf dialect the whole subtree
+ *  may use, so an HTTP manifest cannot smuggle an exec leaf into a child slot. */
+export type ManifestNode<L extends ManifestLeafBase = ManifestLeaf> = ManifestBranch<L> | L;
+/** One mount point in the manifest's self-contained forest. */
+export interface ManifestMount<L extends ManifestLeafBase = ManifestLeaf> {
+    /** `[]` mounts `node` as a new top-level command; a non-empty path names a
+     *  branch this SAME manifest already contributes. */
+    parent: string[];
+    node: ManifestNode<L>;
+}
+/**
+ * A whole `commands.json` for an HTTP-transport plugin whose endpoint and auth
+ * live in the bundle's `bundle.json` rather than the manifest.
+ */
+export interface HttpPluginCommandManifest {
+    schemaVersion: 1;
+    /** Overrides the registration endpoint as the base for every leaf's REST path. */
+    baseUrl?: string;
+    timeouts?: ManifestTimeouts;
+    mounts: ManifestMount<ManifestHttpLeaf>[];
+    /** Core command path (space-joined, e.g. "cron add") → product addendum
+     *  appended to that command's help, rendered by crtr as an attributed
+     *  `<plugin-help plugin="...">` block after the core body. Append-only by
+     *  contract: an addendum adds product meaning beneath substrate help, never
+     *  replaces it. A key naming no core command path fails validation at guest
+     *  install. */
+    helpAddenda?: Record<string, string>;
+}
+/**
+ * The one field a plugin's HTTP backend adds to an error envelope to say the
+ * client parsed this call from an out-of-date description of its commands.
+ *
+ * crtr acts on it by refetching that plugin's bundle and re-running the
+ * caller's ORIGINAL argv against the refreshed command tree, exactly once. Two
+ * preconditions follow from that, and a server that cannot meet both must not
+ * set the field:
+ *
+ *  1. The manifest the server serves at its bundle endpoint must already
+ *     describe the operation it is complaining about. A refetch that hands back
+ *     the same description turns the retry into a second identical failure.
+ *  2. The original call must be safe to send again. crtr replays the argv, not
+ *     the request, but a leaf that already committed a side effect before the
+ *     backend rejected the op would commit it twice.
+ *
+ * Declared here, in the format both sides compile against, so the field name
+ * has one owner: rename it and every reader and writer fails to build. A type
+ * rather than a value — a const would force a CJS consumer to `require()` an
+ * ESM module.
+ */
+export interface ManifestStaleEnvelope {
+    manifest_stale?: true;
+}

package/dist/api/plugin-manifest-schema.js

@@ -0,0 +1,23 @@
+// The command-plugin manifest wire format — the exact JSON shape crtr's manifest
+// validator accepts in a plugin bundle's `commands.json`.
+//
+// This is the canonical, cross-repo declaration of that format. It is published
+// as `@north-light/crouter-api/plugin-manifest` so a server that SERVES a plugin
+// bundle (Northlight Core serves the `northlight` plugin over an authenticated
+// endpoint) compiles its manifest against the same types crtr validates it with,
+// instead of hand-mirroring them and discovering drift at guest install time.
+//
+// Types only. This file imports nothing — not even Node built-ins — so consuming
+// it costs a dependent nothing at runtime.
+//
+// Relationship to `src/core/help.ts`: these param and output types are the
+// JSON-expressible SUBSET of that module's `InputParam` and `Field`. A validated
+// manifest node's params flow straight into `defineLeaf`'s help descriptor
+// (`src/core/command-plugins/compose.ts`), so that assignment is what keeps the
+// two in step — widen a type here beyond what `help.ts` accepts and the build
+// fails at that site. Fields that cannot survive a JSON round trip (a flag's
+// `focusedHelp`, whose `dynamicState` is a function) are deliberately absent.
+//
+// Validators for this format live in `src/core/command-manifests/`, which imports
+// these types rather than redeclaring them.
+export {};

package/dist/api/routes.d.ts

@@ -8,6 +8,8 @@ export declare const routes: {
     readonly nodes: () => string;
     readonly reviveAll: () => string;
     readonly node: (id: string) => string;
+    readonly nodeOutcome: (id: string) => string;
+    readonly nodeOutcomeDelivery: (id: string) => string;
     readonly nodeSnapshot: (id: string) => string;
     readonly nodeSubject: (id: string) => string;
     readonly nodeSession: (id: string) => string;
@@ -17,6 +19,7 @@ export declare const routes: {
     readonly nodeContext: (id: string) => string;
     readonly nodeArtifacts: (id: string) => string;
     readonly nodeReports: (id: string) => string;
+    readonly nodeResult: (id: string) => string;
     readonly nodeJobs: (id: string) => string;
     readonly nodeJob: (id: string, jobId: string) => string;
     readonly nodeMessages: (id: string) => string;
@@ -26,6 +29,8 @@ export declare const routes: {
     readonly nodeRelaunchRoot: (id: string) => string;
     readonly nodeBrokerSessionBound: (id: string) => string;
     readonly nodeBrokerSettle: (id: string) => string;
+    readonly nodeBrokerParkComplete: (id: string) => string;
+    readonly nodeBrokerParkActivity: (id: string) => string;
     readonly nodeBrokerInboxCursor: (id: string) => string;
     readonly nodeBrokerModel: (id: string) => string;
     readonly nodeBrokerExtensionState: (id: string) => string;
@@ -96,6 +101,8 @@ export declare const routes: {
     readonly humanRequestCancel: (requestId: string) => string;
     readonly profiles: () => string;
     readonly profile: (name: string) => string;
+    readonly profilePause: (name: string) => string;
+    readonly profileResume: (name: string) => string;
     readonly profileMetadata: (name: string) => string;
     readonly modelAuths: () => string;
     readonly modelAuth: (provider: string) => string;

package/dist/api/routes.js

@@ -23,6 +23,8 @@ export const routes = {
     nodes: () => `${V}/nodes`,
     reviveAll: () => `${V}/nodes/revive-all`,
     node: (id) => `${V}/nodes/${id}`,
+    nodeOutcome: (id) => `${V}/nodes/${id}/outcome`,
+    nodeOutcomeDelivery: (id) => `${V}/nodes/${id}/outcome-delivery`,
     // Node reads
     nodeSnapshot: (id) => `${V}/nodes/${id}/snapshot`,
     nodeSubject: (id) => `${V}/nodes/${id}/subject`,
@@ -33,6 +35,7 @@ export const routes = {
     nodeContext: (id) => `${V}/nodes/${id}/context`,
     nodeArtifacts: (id) => `${V}/nodes/${id}/artifacts`,
     nodeReports: (id) => `${V}/nodes/${id}/reports`,
+    nodeResult: (id) => `${V}/nodes/${id}/result`,
     nodeJobs: (id) => `${V}/nodes/${id}/jobs`,
     nodeJob: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}`,
     // Node messages / feed
@@ -44,6 +47,8 @@ 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`,
+    nodeBrokerParkComplete: (id) => `${V}/nodes/${id}/broker/park-complete`,
+    nodeBrokerParkActivity: (id) => `${V}/nodes/${id}/broker/park-activity`,
     nodeBrokerInboxCursor: (id) => `${V}/nodes/${id}/broker/inbox-cursor`,
     nodeBrokerModel: (id) => `${V}/nodes/${id}/broker/model`,
     nodeBrokerExtensionState: (id) => `${V}/nodes/${id}/broker/extension-state`,
@@ -127,6 +132,8 @@ export const routes = {
     // Profiles (deletion is daemon-owned because it crosses canvas state)
     profiles: () => `${V}/profiles`,
     profile: (name) => `${V}/profiles/${name}`,
+    profilePause: (name) => `${V}/profiles/${name}/pause`,
+    profileResume: (name) => `${V}/profiles/${name}/resume`,
     profileMetadata: (name) => `${V}/profiles/${name}/metadata`,
     // Model auth
     modelAuths: () => `${V}/model-auth`,

package/dist/shared/env.d.ts

@@ -82,3 +82,6 @@ export declare function envUnattendedParkMs(): number | undefined;
 /** Test-only park-summary grace-period override
  *  (`CRTR_TEST_PARK_SUMMARY_GRACE_MS`); no production default. */
 export declare function envTestParkSummaryGraceMs(): number | undefined;
+/** The bounded lifetime shared by the daemon's pending-park sweep and its
+ * in-broker isolated turn. */
+export declare function parkSummaryGraceMs(): number;

package/dist/shared/env.js

@@ -195,3 +195,9 @@ export function envUnattendedParkMs() {
 export function envTestParkSummaryGraceMs() {
     return parsePositiveMsNoDefault(process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS']);
 }
+const DEFAULT_PARK_SUMMARY_GRACE_MS = 5 * 60_000;
+/** The bounded lifetime shared by the daemon's pending-park sweep and its
+ * in-broker isolated turn. */
+export function parkSummaryGraceMs() {
+    return envTestParkSummaryGraceMs() ?? DEFAULT_PARK_SUMMARY_GRACE_MS;
+}

package/dist/shared/generated-context.d.ts

@@ -8,15 +8,9 @@ export declare const CONTEXT_NUDGE_CUSTOM_TYPE = "crtr-context-nudge";
 export declare const REVIEW_BOUNDARY_CUSTOM_TYPE = "crtr-review-boundary";
 /** Generic completion mandate issued by the terminal-node stop guard. */
 export declare const STALL_REPROMPT: string;
-/** The daemon's parking mandate: the last turn of a conversation the unattended
- *  clock is concluding. Delivered live, wrapped in a `park` runtime card. It
- *  governs both the node's durable inheritance and reader-facing output:
- *  one update for subscribers and history, then a brief completion reply.
- *
- *  The durable inheritance shares a CONTRACT with `node yield`'s pre-invocation
- *  guide (roadmap current, short and shrinking; context dir for in-progress
- *  material; memory only for gated permanent lessons) but not a string: yield is
- *  read by an agent choosing to refresh, this by an agent being told to conclude. */
+/** The daemon's parking mandate for an isolated turn. It leaves current truth,
+ * supporting material when needed, lasting lessons, and one deferred update;
+ * the main conversation remains untouched and resumes without a fresh cycle. */
 export declare const PARK_SUMMARY_PROMPT: string;
 /** Static recovery prompts shared by the broker producer and display classifier. */
 export declare const AUTH_FAULT_RECOVERY_BODY = "Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.";

package/dist/shared/generated-context.js

@@ -13,22 +13,14 @@ export const REVIEW_BOUNDARY_CUSTOM_TYPE = 'crtr-review-boundary';
 /** Generic completion mandate issued by the terminal-node stop guard. */
 export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
     "Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human send` if you are blocked or need the user.";
-/** The daemon's parking mandate: the last turn of a conversation the unattended
- *  clock is concluding. Delivered live, wrapped in a `park` runtime card. It
- *  governs both the node's durable inheritance and reader-facing output:
- *  one update for subscribers and history, then a brief completion reply.
- *
- *  The durable inheritance shares a CONTRACT with `node yield`'s pre-invocation
- *  guide (roadmap current, short and shrinking; context dir for in-progress
- *  material; memory only for gated permanent lessons) but not a string: yield is
- *  read by an agent choosing to refresh, this by an agent being told to conclude. */
-export const PARK_SUMMARY_PROMPT = 'This conversation has been idle with nothing left to wake it, so it is being concluded. This is your last turn. Use it to leave a trustworthy inheritance, not to restart or broaden the work. Do these six things now, then stop.\n\n'
+/** The daemon's parking mandate for an isolated turn. It leaves current truth,
+ * supporting material when needed, lasting lessons, and one deferred update;
+ * the main conversation remains untouched and resumes without a fresh cycle. */
+export const PARK_SUMMARY_PROMPT = 'This conversation has been idle with nothing left to wake it, so it is being concluded. This is your last turn. Use it to leave a trustworthy inheritance, not to restart or broaden the work. Do these four things now, then stop.\n\n'
     + '1. Establish current truth. Check only state that may have changed outside the transcript and matters to resuming—such as the working tree, a remote run, or an external decision. Do not start new work; perform only a quick check needed to avoid recording an unverified claim. If no mandate or work ever began, record that plainly in the inheritance and keep every artifact minimal.\n\n'
-    + '2. Rewrite `$CRTR_CONTEXT_DIR/roadmap.md` for a fresh context window. This is the only handoff document a later fresh cycle receives in full. Preserve the current goal and exit criteria when they still apply, then state the present outcome; what remains or is blocked; decisions or questions still open; exact recovery handles for in-flight state; and the first safe move on return. Keep strategy and present state, not a transcript recap. Delete stale and completed steps instead of marking them done; the roadmap should stay short and shrink. Write a minimal one now if none exists.\n\n'
-    + '3. Put supporting material in your context directory only when the roadmap would become bulky without it. Rewrite existing living documents rather than leave superseded versions. Name every supporting file the next cycle must read from the roadmap and say what it is for—the revive shows filenames but does not inject their contents. Task state, identifiers, and recovery detail belong here, not in memory.\n\n'
-    + '4. Use memory only for a non-obvious, reusable lesson that should survive this task and is not already recorded. Read `crtr memory write -h`, find before writing, and choose the narrowest scope that will reach the next agent who needs it. Do not put a conversation recap, task status, recovery handles, or facts already captured in code or docs into memory.\n\n'
-    + '5. Push exactly one regular update with `crtr push update --tier deferred`, never `crtr push final`. Write for someone who has not seen this conversation: name the work in plain terms, say where it stands, and say what remains or is blocked. Put the current outcome in the first line; include only needed decisions and recovery handles. This concludes the conversation, not the mandate.\n\n'
-    + '6. When finished, reply with exactly `done`.';
+    + '2. Put supporting material in your context directory only when it is needed to keep the inheritance concise. Rewrite existing living documents rather than leave superseded versions. Task state, identifiers, and recovery detail belong here, not in memory.\n\n'
+    + '3. Use memory only for a non-obvious, reusable lesson that should survive this task and is not already recorded. Read `crtr memory write -h`, find before writing, and choose the narrowest scope that will reach the next agent who needs it. Do not put a conversation recap, task status, recovery handles, or facts already captured in code or docs into memory.\n\n'
+    + '4. Push exactly one regular update with `crtr push update --tier deferred`, never `crtr push final`. Write for someone who has not seen this conversation: name the work in plain terms, say where it stands, and say what remains or is blocked. Put the current outcome in the first line; include only needed decisions and recovery handles, then stop.';
 /** Static recovery prompts shared by the broker producer and display classifier. */
 export const AUTH_FAULT_RECOVERY_BODY = 'Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.';
 export const CONNECTION_FAULT_RECOVERY_BODY = 'The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.';
@@ -37,7 +29,7 @@ const REVIEW_APPROVAL_OPEN = '<crtr-review-approval>';
 const REVIEW_APPROVAL_CLOSE = '</crtr-review-approval>';
 const MODEL_FALLBACK_RECOVERY_OPEN = '<model-fallback-recovery>';
 const MODEL_FALLBACK_RECOVERY_CLOSE = '</model-fallback-recovery>';
-const STRUCTURED_OUTPUT_REPROMPT_PREFIX = 'You must call the `submit` tool with a result matching the required schema before you can stop. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n```json\n';
+const STRUCTURED_OUTPUT_REPROMPT_PREFIX = 'You must submit a result matching the required schema with `crtr push result` before you can stop, or decline it with `crtr push result --decline "<reason>" --code <token>` when the schema cannot be honestly satisfied. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n```json\n';
 const STRUCTURED_OUTPUT_REPROMPT_SUFFIX = '\n```';
 /** Format the stop guard's dynamic structured-output mandate. */
 export function formatStructuredOutputReprompt(schema) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.281",
-  "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
+  "version": "0.3.283",
+  "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",
   "types": "./dist/api/index.d.ts",
@@ -12,6 +12,12 @@
       "require": "./dist/api/index.js",
       "default": "./dist/api/index.js"
     },
+    "./plugin-manifest": {
+      "types": "./dist/api/plugin-manifest-schema.d.ts",
+      "import": "./dist/api/plugin-manifest-schema.js",
+      "require": "./dist/api/plugin-manifest-schema.js",
+      "default": "./dist/api/plugin-manifest-schema.js"
+    },
     "./cards": {
       "types": "./dist/shared/generated-context.d.ts",
       "import": "./dist/shared/generated-context.js",