@north-light/crouter-api 0.3.255 → 0.3.256

package/dist/api/client.d.ts

@@ -20,7 +20,7 @@ import type { CreateReviewCommentRequest, EditReviewCommentRequest, ListReviewCo
 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 { AbandonWorktreeRequest, AbandonWorktreeResultDTO, CloseWorktreeResultDTO } from './dto/worktree.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';
 export interface CrtrClientOptions {
     /** Unix socket path (default local transport). Exactly one of socketPath|baseUrl. */
@@ -55,6 +55,16 @@ export interface CrtrClientOptions {
      *  a slow-but-valid cold start cannot pass the authoritative verifier while
      *  this poll times out first. */
     coldStartPollWindowMs?: number;
+    /** Injected check for a STANDING reason the daemon will never come up — one
+     *  that the poll window cannot outlast because nothing about it changes with
+     *  time. Consulted on each `/healthz` poll; a returned string ends the wait
+     *  immediately and becomes the error message.
+     *
+     *  Without this the caller waits out the whole cold-start window to report
+     *  "not reachable", even when the reason it is unreachable — and the repair
+     *  for it — were both known before the first poll. Must be synchronous and
+     *  cheap; it runs on every poll tick. */
+    coldStartAbort?: () => string | null;
 }
 export declare class CrtrClient {
     private readonly socketPath?;
@@ -65,6 +75,7 @@ export declare class CrtrClient {
     private readonly onColdSocket?;
     private readonly coldStartDiagnostic?;
     private readonly coldStartPollWindowMs;
+    private readonly coldStartAbort?;
     /** Guards against re-entering the autostart path more than once per client. */
     private coldStartAttempted;
     constructor(opts: CrtrClientOptions);
@@ -114,6 +125,7 @@ export declare class CrtrClient {
      *  crtrd is the repo host (same principle as spawnChild's creation git). */
     closeWorktree(id: string): Promise<CloseWorktreeResultDTO>;
     abandonWorktree(id: string, req: AbandonWorktreeRequest): Promise<AbandonWorktreeResultDTO>;
+    listQuarantinedWorktrees(): Promise<QuarantinedWorktreeDTO[]>;
     subscribe(id: string, req: SubscribeRequest): Promise<SubscriptionDTO>;
     listFocuses(): Promise<FocusDTO[]>;
     focusOf(nodeId: string): Promise<FocusDTO | null>;

package/dist/api/client.js

@@ -48,6 +48,7 @@ export class CrtrClient {
     onColdSocket;
     coldStartDiagnostic;
     coldStartPollWindowMs;
+    coldStartAbort;
     /** Guards against re-entering the autostart path more than once per client. */
     coldStartAttempted = false;
     constructor(opts) {
@@ -67,6 +68,8 @@ export class CrtrClient {
             this.onColdSocket = opts.onColdSocket;
         if (opts.coldStartDiagnostic !== undefined)
             this.coldStartDiagnostic = opts.coldStartDiagnostic;
+        if (opts.coldStartAbort !== undefined)
+            this.coldStartAbort = opts.coldStartAbort;
         this.coldStartPollWindowMs = opts.coldStartPollWindowMs ?? HEALTHZ_POLL_WINDOW_MS;
     }
     /** Construct a client bound to the default local socket with autostart on. Pass
@@ -179,6 +182,9 @@ export class CrtrClient {
     abandonWorktree(id, req) {
         return this.request('POST', routes.nodeWorktreeAbandon(this.nodePath(id)), req);
     }
+    listQuarantinedWorktrees() {
+        return this.request('GET', routes.quarantinedWorktrees());
+    }
     subscribe(id, req) {
         return this.request('POST', routes.nodeSubscriptions(this.nodePath(id)), req);
     }
@@ -745,6 +751,17 @@ export class CrtrClient {
                 if (!this.isColdSocketError(err))
                     throw toTransportApiError(err);
             }
+            // Waiting cannot clear a standing block, and the repair is already known.
+            let standingBlock = null;
+            try {
+                standingBlock = this.coldStartAbort?.() ?? null;
+            }
+            catch {
+                standingBlock = null;
+            }
+            if (standingBlock !== null) {
+                throw new ApiError(503, 'daemon_unavailable', `crtrd cannot start: ${standingBlock}`);
+            }
             if (Date.now() >= deadline) {
                 const diagnostic = safeColdStartDiagnostic(this.coldStartDiagnostic);
                 throw new ApiError(503, 'daemon_unavailable', coldStartTimeoutMessage(diagnostic));

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

@@ -14,6 +14,10 @@ export interface CloseWorktreeResultDTO {
     /** False while the local branch remains checked out by the deferred cleanup. */
     branch_deleted: boolean;
     branch_delete_error?: string;
+    /** Present ONLY when landing had to stash local changes in the base checkout
+     *  and re-applying them conflicted: names the preserved stash and how to
+     *  re-apply it. Its absence means nothing local was left over. */
+    base_checkout_stash?: string;
 }
 export interface AbandonWorktreeRequest {
     by: string;
@@ -25,3 +29,16 @@ export interface AbandonWorktreeResultDTO {
     worktree_path: string;
     branch_deleted: boolean;
 }
+/** A daemon-cleanup refusal retained for human intervention. */
+export interface QuarantinedWorktreeDTO {
+    node_id: string;
+    path: string;
+    branch: string;
+    repo_root: string;
+    reason: string;
+    detail?: string;
+    attempts: number;
+    last_attempt: string;
+    /** Bytes occupied by the checkout, or null when it is gone or unmeasurable. */
+    size_bytes: number | null;
+}

package/dist/api/routes.d.ts

@@ -40,6 +40,7 @@ export declare const routes: {
     readonly nodeConfig: (id: string) => string;
     readonly nodeWorktreeClose: (id: string) => string;
     readonly nodeWorktreeAbandon: (id: string) => string;
+    readonly quarantinedWorktrees: () => string;
     readonly nodeAttach: (id: string) => string;
     readonly focuses: () => string;
     readonly focusByNode: () => string;

package/dist/api/routes.js

@@ -58,6 +58,7 @@ export const routes = {
     nodeConfig: (id) => `${V}/nodes/${id}/config`,
     nodeWorktreeClose: (id) => `${V}/nodes/${id}/worktree/close`,
     nodeWorktreeAbandon: (id) => `${V}/nodes/${id}/worktree/abandon`,
+    quarantinedWorktrees: () => `${V}/worktrees/quarantined`,
     nodeAttach: (id) => `${V}/nodes/${id}/attach`,
     // Focuses (viewer registry — the canvas.db `focuses` table)
     focuses: () => `${V}/focuses`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.255",
+  "version": "0.3.256",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",