@north-light/crouter-api 0.3.254 → 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/dist/shared/generated-context.d.ts

@@ -11,8 +11,8 @@ 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 goodbye that does not narrate
- *  the parking.
+ *  one update for subscribers and history, then a silent stop with no assistant
+ *  prose for an external channel to relay.
  *
  *  The durable inheritance shares a CONTRACT with `node yield`'s pre-invocation
  *  guide (roadmap current, short and shrinking; context dir for in-progress

package/dist/shared/generated-context.js

@@ -16,20 +16,20 @@ export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone a
 /** 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 goodbye that does not narrate
- *  the parking.
+ *  one update for subscribers and history, then a silent stop with no assistant
+ *  prose for an external channel to relay.
  *
  *  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'
-    + '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, say that plainly and keep every artifact minimal.\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 it for subscribers and history, not as a second roadmap. Its first line must stand alone as the current outcome, blocker, or decision that matters; then include only unfinished work, a needed decision, and concrete handles a subscriber may need. This concludes the conversation; it does not finish the mandate.\n\n'
-    + '6. End with a short, one-sentence sign-off to the reader in second person: say you are putting your notes in order and pausing here until they come back. If you saved any memories, describe what you did extremely briefly (i.e. "I noted your preference for XYZ" or "I updated my memories on ABC"). Keep all visible text this turn—including the update — about their work, not crouter\'s machinery: do not mention roadmap or context paths, filing a report, parking, idling, residency, or node ids. Then stop. A later message reopens you on a fresh context window grounded in your goal and roadmap, so the inheritance you leave now is what you get back.';
+    + '6. Keep this entire turn silent in the conversation: produce no assistant prose before, between, or after tool calls, and do not narrate the work. Once every required tool call has finished, end the response immediately without emitting any text, sign-off, summary, acknowledgement, or other visible content. The deferred update from step 5 is the only reader-facing conclusion. A later message reopens you on a fresh context window grounded in your goal and roadmap, so the inheritance you leave now is what you get back.';
 /** 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.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.254",
+  "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",