@north-light/crouter-api 0.3.173 → 0.3.175

package/dist/__tests__/{client.test.js → serial/client.test.js}

@@ -14,8 +14,8 @@ import { createServer } from 'node:http';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { coldStartTimeoutMessage, CrtrClient, safeColdStartDiagnostic } from '../client.js';
-import { ApiError } from '../errors.js';
+import { coldStartTimeoutMessage, CrtrClient, safeColdStartDiagnostic } from '../../client.js';
+import { ApiError } from '../../errors.js';
 test('coldStartTimeoutMessage appends a present diagnostic to the base message', () => {
     const msg = coldStartTimeoutMessage('crtrd.err (tail):\nError: bind EADDRINUSE');
     assert.match(msg, /crtrd did not start/);
@@ -139,136 +139,3 @@ test('safeColdStartDiagnostic treats a THROWING hook as absent, not a propagated
         throw new Error('custom hook blew up');
     }), undefined);
 });
-/** Spin a loopback server on a temp unix socket that records every request and
- *  replies with `respond(req)`. `respond` returning `undefined` means "handler
- *  not reached for this call" and is never exercised by these tests. */
-async function startCapturingServer(respond) {
-    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-inbox-'));
-    const socketPath = join(dir, 'crtrd.sock');
-    const requests = [];
-    const server = createServer((req, res) => {
-        const chunks = [];
-        req.on('data', (chunk) => chunks.push(chunk));
-        req.on('end', () => {
-            const raw = Buffer.concat(chunks).toString('utf8');
-            const body = raw.trim() === '' ? undefined : JSON.parse(raw);
-            const captured = { method: req.method ?? '', path: req.url ?? '', body };
-            requests.push(captured);
-            const { status, body: resBody } = respond(captured);
-            res.writeHead(status, { 'content-type': 'application/json' });
-            res.end(JSON.stringify(resBody));
-        });
-    });
-    await new Promise((resolvePromise) => server.listen(socketPath, resolvePromise));
-    const client = new CrtrClient({ socketPath, autostart: false });
-    return {
-        client,
-        requests,
-        close: () => new Promise((resolvePromise, rejectPromise) => {
-            server.close((err) => (err ? rejectPromise(err) : resolvePromise()));
-        }).finally(() => rmSync(dir, { recursive: true, force: true })),
-    };
-}
-const SAMPLE_TICKET_ID = 'a'.repeat(64);
-test('listHumanInbox sends GET /v1/human/inbox with no body and returns the parsed list', async () => {
-    const inboxList = { tickets: [{ ticket_id: SAMPLE_TICKET_ID, kind: 'deck', title: 'Approve deploy', blocked_since: '2026-01-01T00:00:00Z', source: {} }] };
-    const srv = await startCapturingServer(() => ({ status: 200, body: inboxList }));
-    try {
-        const result = await srv.client.listHumanInbox();
-        assert.deepEqual(result, inboxList);
-        assert.equal(srv.requests.length, 1);
-        assert.equal(srv.requests[0]?.method, 'GET');
-        assert.equal(srv.requests[0]?.path, '/v1/human/inbox');
-        assert.equal(srv.requests[0]?.body, undefined);
-    }
-    finally {
-        await srv.close();
-    }
-});
-test('getHumanInboxDeck sends GET /v1/human/inbox/:ticket_id with no body and returns the parsed deck', async () => {
-    const deck = { ticket_id: SAMPLE_TICKET_ID, kind: 'deck', deck: { title: 'Approve deploy', interactions: [] } };
-    const srv = await startCapturingServer(() => ({ status: 200, body: deck }));
-    try {
-        const result = await srv.client.getHumanInboxDeck(SAMPLE_TICKET_ID);
-        assert.deepEqual(result, deck);
-        assert.equal(srv.requests[0]?.method, 'GET');
-        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}`);
-        assert.equal(srv.requests[0]?.body, undefined);
-    }
-    finally {
-        await srv.close();
-    }
-});
-test('respondHumanInboxDeck sends POST with the exact responses body and returns the canonical result unchanged', async () => {
-    const request = { responses: [{ id: 'notify', selectedOptionId: 'ok' }] };
-    const result = { schema: 'humanloop.response/v2', kind: 'deck', responses: request.responses, summary: 'Acknowledged', completedAt: '2026-01-01T00:00:00Z' };
-    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
-    try {
-        const got = await srv.client.respondHumanInboxDeck(SAMPLE_TICKET_ID, request);
-        assert.deepEqual(got, result);
-        assert.equal(srv.requests[0]?.method, 'POST');
-        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}/respond`);
-        assert.deepEqual(srv.requests[0]?.body, request);
-    }
-    finally {
-        await srv.close();
-    }
-});
-test('cancelHumanInboxTicket sends POST with the reason body when a request is passed', async () => {
-    const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: '2026-01-01T00:00:00Z', reason: 'no longer needed', actor: 'human' };
-    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
-    try {
-        const got = await srv.client.cancelHumanInboxTicket(SAMPLE_TICKET_ID, { reason: 'no longer needed' });
-        assert.deepEqual(got, result);
-        assert.equal(srv.requests[0]?.method, 'POST');
-        assert.equal(srv.requests[0]?.path, `/v1/human/inbox/${SAMPLE_TICKET_ID}/cancel`);
-        assert.deepEqual(srv.requests[0]?.body, { reason: 'no longer needed' });
-    }
-    finally {
-        await srv.close();
-    }
-});
-test('cancelHumanInboxTicket sends an empty object body when no request is passed', async () => {
-    const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: '2026-01-01T00:00:00Z' };
-    const srv = await startCapturingServer(() => ({ status: 200, body: result }));
-    try {
-        const got = await srv.client.cancelHumanInboxTicket(SAMPLE_TICKET_ID);
-        assert.deepEqual(got, result);
-        assert.deepEqual(srv.requests[0]?.body, {});
-    }
-    finally {
-        await srv.close();
-    }
-});
-test('a non-2xx inbox error body decodes to a typed ApiError (status/code/message)', async () => {
-    const srv = await startCapturingServer(() => ({
-        status: 409,
-        body: { error: { code: 'ticket_kind_unsupported', message: 'review tickets have no v1 response operation' } },
-    }));
-    try {
-        await assert.rejects(() => srv.client.respondHumanInboxDeck(SAMPLE_TICKET_ID, { responses: [] }), (err) => {
-            assert.ok(err instanceof ApiError);
-            assert.equal(err.status, 409);
-            assert.equal(err.code, 'ticket_kind_unsupported');
-            assert.match(err.message, /review tickets have no v1 response operation/);
-            return true;
-        });
-    }
-    finally {
-        await srv.close();
-    }
-});
-test('a malformed local ticket id throws a synchronous TypeError and never reaches the transport', async () => {
-    const srv = await startCapturingServer(() => {
-        throw new Error('handler must never be invoked for a locally-rejected ticket id');
-    });
-    try {
-        assert.throws(() => srv.client.getHumanInboxDeck('not-a-valid-hash'), TypeError);
-        assert.throws(() => srv.client.respondHumanInboxDeck('short', { responses: [] }), TypeError);
-        assert.throws(() => srv.client.cancelHumanInboxTicket('UPPERCASE'.repeat(7)), TypeError);
-        assert.equal(srv.requests.length, 0);
-    }
-    finally {
-        await srv.close();
-    }
-});

package/dist/client.d.ts

@@ -5,18 +5,19 @@ import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery }
 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 CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery } from './dto/crons.js';
+import { type ArmCronRequest, type CancelCronQuery, type CronDTO, type CronRunDTO, type CronScopeQuery, type CronShowDTO, type ListCronsQuery } from './dto/crons.js';
 import type { NodeConfigPatch } from './dto/config.js';
 import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js';
 import type { EnsureProfileRequest, ProfileDTO } from './dto/profiles.js';
 import type { FilePeekDTO } from './dto/files.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, ReviewOpenResultDTO, ReviewSubmitResultDTO } from './dto/reviews.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, DeckTicketResultDTO, InboxDeckDTO, InboxListDTO, InboxTicketIdDTO, RespondInboxDeckRequest } from './dto/inbox.js';
+import type { InboxListDTO } from './dto/inbox.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';
 export interface CrtrClientOptions {
     /** Unix socket path (default local transport). Exactly one of socketPath|baseUrl. */
     socketPath?: string;
@@ -86,6 +87,13 @@ export declare class CrtrClient {
     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>;
+    advanceBrokerInboxCursor(id: string, req: BrokerInboxCursorRequest): Promise<BrokerInboxCursorDirective>;
+    commitBrokerModel(id: string, req: BrokerModelCommitRequest): Promise<BrokerModelCommitResultDTO>;
+    brokerExtensionState(id: string): Promise<BrokerExtensionStateDTO>;
+    commitBrokerGeneratedName(id: string, req: BrokerGeneratedNameRequest): Promise<BrokerGeneratedNameResultDTO>;
+    commitBrokerPersonaAck(id: string, req: BrokerPersonaAckRequest): Promise<void>;
     closeNode(id: string, req?: CloseRequest): Promise<CloseResultDTO>;
     recycleNode(id: string): Promise<NodeDetailDTO>;
     demoteNode(id: string): Promise<NodeDetailDTO>;
@@ -122,7 +130,7 @@ export declare class CrtrClient {
      *  advance the schedule or consume a one-shot; never escalates. */
     runCron(cronId: string, q?: CronScopeQuery): Promise<CronRunDTO>;
     /** Cancel one cron (`DELETE /v1/crons/:cronId`, idempotent). */
-    cancelCron(cronId: string, q?: CronScopeQuery): Promise<void>;
+    cancelCron(cronId: string, q?: CancelCronQuery): Promise<void>;
     ensureAttach(id: string, req?: AttachEnsureRequest): Promise<AttachEnsureResultDTO>;
     getReports(id: string, q?: ReportsQuery): Promise<ReportDTO[]>;
     getTranscript(id: string, q?: TranscriptQuery): Promise<TranscriptDTO>;
@@ -159,7 +167,6 @@ export declare class CrtrClient {
     listReviews(query?: ListReviewsQuery): Promise<ReviewListDTO>;
     getReview(reviewId: string): Promise<ReviewDTO>;
     getReviewByBridge(bridgeNodeId: string): Promise<ReviewDTO>;
-    openReview(reviewId: string): Promise<ReviewOpenResultDTO>;
     submitReview(reviewId: string): Promise<ReviewSubmitResultDTO>;
     cancelReview(reviewId: string, req?: CancelReviewRequest): Promise<ReviewCancelResultDTO>;
     getReviewDocumentBase(reviewId: string): Promise<ReviewDocumentBaseDTO>;
@@ -172,17 +179,7 @@ export declare class CrtrClient {
     resolveReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
     reopenReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
     deleteReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
-    /** Pending deck/review tickets across every available crouter-owned
-     *  humanloop root. */
     listHumanInbox(): Promise<InboxListDTO>;
-    /** Read one pending deck by its opaque ticket id, with Markdown bodies
-     *  resolved inline. */
-    getHumanInboxDeck(ticketId: InboxTicketIdDTO): Promise<InboxDeckDTO>;
-    /** Submit ordered interaction responses for a pending deck. Single-assignment
-     *  server-side: a competing resolution races to `ticket_already_resolved`. */
-    respondHumanInboxDeck(ticketId: InboxTicketIdDTO, request: RespondInboxDeckRequest): Promise<DeckTicketResultDTO>;
-    /** Cancel a pending deck (terminal response, never deletion). */
-    cancelHumanInboxTicket(ticketId: InboxTicketIdDTO, request?: CancelInboxTicketRequest): Promise<CanceledTicketResultDTO>;
     /** Composed client-side from `GET /v1/nodes` + `GET /v1/status` (spec §6.3 —
      *  the dashboard is absorbed into those two reads; there is no single route).
      *  `generated_at` is the client-side capture instant of the composition. */
@@ -220,12 +217,6 @@ export declare class CrtrClient {
      *  it raw, so a value carrying `/`, whitespace or `?` would corrupt the
      *  request line rather than 404 cleanly. Mirrors `nodePath`. */
     private cronPath;
-    /** Validate an opaque inbox ticket id before route construction. A local
-     *  shape violation is a caller bug, not a server-rejectable request — throws
-     *  `TypeError` (matching the existing safe-segment discipline of a local
-     *  precondition, distinct from `nodePath`'s `ApiError` because that one IS a
-     *  request the server could plausibly receive and reject itself). */
-    private ticketId;
     /** Validate a review id before route construction (D-A6). Reviews are minted
      *  and addressed like node ids, but arrive from agent argv, so a malformed
      *  one is a plausible request the server would also reject — `ApiError`,

package/dist/client.js

@@ -118,6 +118,27 @@ export class CrtrClient {
     relaunchRoot(id) {
         return this.request('POST', routes.nodeRelaunchRoot(this.nodePath(id)), {});
     }
+    bindBrokerSession(id, req) {
+        return this.request('POST', routes.nodeBrokerSessionBound(this.nodePath(id)), req);
+    }
+    settleBroker(id, req) {
+        return this.request('POST', routes.nodeBrokerSettle(this.nodePath(id)), req);
+    }
+    advanceBrokerInboxCursor(id, req) {
+        return this.request('POST', routes.nodeBrokerInboxCursor(this.nodePath(id)), req);
+    }
+    commitBrokerModel(id, req) {
+        return this.request('POST', routes.nodeBrokerModel(this.nodePath(id)), req);
+    }
+    brokerExtensionState(id) {
+        return this.request('GET', routes.nodeBrokerExtensionState(this.nodePath(id)));
+    }
+    commitBrokerGeneratedName(id, req) {
+        return this.request('POST', routes.nodeBrokerGeneratedName(this.nodePath(id)), req);
+    }
+    commitBrokerPersonaAck(id, req) {
+        return this.request('POST', routes.nodeBrokerPersonaAck(this.nodePath(id)), req);
+    }
     closeNode(id, req) {
         return this.request('POST', routes.nodeClose(this.nodePath(id)), req ?? {});
     }
@@ -292,9 +313,6 @@ export class CrtrClient {
     getReviewByBridge(bridgeNodeId) {
         return this.request('GET', routes.humanReviewByBridge(this.nodePath(bridgeNodeId)));
     }
-    openReview(reviewId) {
-        return this.request('POST', routes.humanReviewOpen(this.reviewPath(reviewId)), {});
-    }
     submitReview(reviewId) {
         return this.request('POST', routes.humanReviewSubmit(this.reviewPath(reviewId)), {});
     }
@@ -333,26 +351,10 @@ export class CrtrClient {
     deleteReviewComment(commentId, req = {}) {
         return this.request('POST', routes.humanCommentDelete(this.commentPath(commentId)), req);
     }
-    // ---- Humanloop inbox (Northlight crouter-inbox v1, inbox-contract.md §A) --
-    /** Pending deck/review tickets across every available crouter-owned
-     *  humanloop root. */
+    // ---- Attached terminal viewer inbox -------------------------------------
     listHumanInbox() {
         return this.request('GET', routes.humanInbox());
     }
-    /** Read one pending deck by its opaque ticket id, with Markdown bodies
-     *  resolved inline. */
-    getHumanInboxDeck(ticketId) {
-        return this.request('GET', routes.humanInboxTicket(this.ticketId(ticketId)));
-    }
-    /** Submit ordered interaction responses for a pending deck. Single-assignment
-     *  server-side: a competing resolution races to `ticket_already_resolved`. */
-    respondHumanInboxDeck(ticketId, request) {
-        return this.request('POST', routes.humanInboxRespond(this.ticketId(ticketId)), request);
-    }
-    /** Cancel a pending deck (terminal response, never deletion). */
-    cancelHumanInboxTicket(ticketId, request) {
-        return this.request('POST', routes.humanInboxCancel(this.ticketId(ticketId)), request ?? {});
-    }
     // ---- Canvas reads / maintenance ---------------------------------------
     /** Composed client-side from `GET /v1/nodes` + `GET /v1/status` (spec §6.3 —
      *  the dashboard is absorbed into those two reads; there is no single route).
@@ -444,17 +446,6 @@ export class CrtrClient {
         }
         return id;
     }
-    /** Validate an opaque inbox ticket id before route construction. A local
-     *  shape violation is a caller bug, not a server-rejectable request — throws
-     *  `TypeError` (matching the existing safe-segment discipline of a local
-     *  precondition, distinct from `nodePath`'s `ApiError` because that one IS a
-     *  request the server could plausibly receive and reject itself). */
-    ticketId(id) {
-        if (!/^[a-f0-9]{64}$/.test(id)) {
-            throw new TypeError(`invalid inbox ticket id: ${JSON.stringify(id)}`);
-        }
-        return id;
-    }
     /** Validate a review id before route construction (D-A6). Reviews are minted
      *  and addressed like node ids, but arrive from agent argv, so a malformed
      *  one is a plausible request the server would also reject — `ApiError`,

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

@@ -0,0 +1,158 @@
+import type { ExitIntentDTO, NodeStatusDTO } from './common.js';
+/** `POST /v1/nodes/{id}/broker/session-bound` body. Pi's session-start reason
+ * distinguishes an ordinary boot/resume from `/new`, whose child-side session
+ * reset is a different durable operation. `reviewBoundaryIds` reports only the
+ * review markers visible in Pi's current branch; crtrd owns the node binding
+ * used to decide whether that branch is valid. */
+export interface BrokerSessionBoundRequest {
+    piSessionId: string;
+    sessionFile: string | null;
+    pid: number;
+    reason: string | null;
+    reviewBoundaryIds: string[];
+}
+/** Pi-side consequence selected by crtrd after binding the session. The
+ * handler itself never calls back into the broker while servicing the request. */
+export interface BrokerSessionBoundResultDTO {
+    action: 'none' | 'relaunch_root' | 'shutdown';
+}
+/** `POST /v1/nodes/{id}/broker/settle` body. These are the facts only Pi can
+ * know at its settlement boundary; crtrd reads all current canvas state and
+ * selects the durable consequence. */
+export interface BrokerSettleRequest {
+    stopReason: string;
+    backgroundJobsRunning: boolean;
+    pushedFinal: boolean;
+    askedHuman: boolean;
+}
+/** The only consequence a settle caller may enact. crtrd has already committed
+ * every canvas and placement effect before returning this directive. */
+export type BrokerSettleDirective = {
+    action: 'reprompt';
+    prompt: string;
+} | {
+    action: 'stay_dormant';
+} | {
+    action: 'shutdown';
+};
+/** `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. */
+export interface BrokerInboxCursorRequest {
+    throughEntryId: string;
+    brokerPid: number;
+}
+/** crtrd either commits the durable cursor or preserves it while a refresh
+ * discards the current Pi conversation, so the next broker replays the entry. */
+export type BrokerInboxCursorDirective = {
+    action: 'advanced';
+} | {
+    action: 'hold_refresh';
+};
+/** Durable model recipe selected by the live broker after Pi accepts a model or thinking change. */
+export interface BrokerModelCommitRequest {
+    spec: string;
+    pinnedOverride?: boolean;
+    userSelected: boolean;
+}
+export interface BrokerModelCommitResultDTO {
+    modelOverride: string;
+}
+/** The dependency-light identity/runtime projection broker extensions need to
+ * render their local Pi hooks without reading canvas.db themselves. */
+export interface BrokerExtensionNodeDTO {
+    node_id: string;
+    name: string;
+    description?: string;
+    icon?: string;
+    kind: string;
+    mode: 'base' | 'orchestrator';
+    lifecycle: 'terminal' | 'resident';
+    status: NodeStatusDTO;
+    cwd: string;
+    parent: string | null;
+    fork_from: string | null;
+    profile_id: string | null;
+    managed_worktree?: {
+        state: 'open' | 'closed';
+        path: string;
+        branch: string;
+        base_ref: string;
+        base_sha: string;
+    } | null;
+    review_binding?: {
+        review_id: string;
+        origin_node_id: string;
+        branch_file: string;
+        target_file: string;
+    } | null;
+    intent: ExitIntentDTO;
+    persona_ack?: {
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+    created: string;
+}
+export interface BrokerExtensionSubjectDTO {
+    kind: string;
+    mode: 'base' | 'orchestrator';
+    lifecycle: 'terminal' | 'resident';
+    hasManager: boolean;
+    cwd: string;
+    scope: 'user' | 'project';
+    orchestration: {
+        depth: number;
+    };
+    profile: string | null;
+}
+/** One resolved report sender. Report contents stay broker-local filesystem
+ * data; this daemon projection supplies only existence and display metadata. */
+export interface BrokerReportNodeDTO {
+    node_id: string;
+    name: string;
+    created: string;
+}
+/** `GET /v1/nodes/{id}/broker/extension-state`. This is deliberately a fixed
+ * extension rendering projection, not a generic node/state read API. */
+export interface BrokerExtensionStateDTO {
+    node: BrokerExtensionNodeDTO;
+    warm_spare: boolean;
+    ancestors: BrokerExtensionNodeDTO[];
+    children: BrokerExtensionNodeDTO[];
+    fork_source: BrokerExtensionNodeDTO | null;
+    subject: BrokerExtensionSubjectDTO;
+    report_nodes: BrokerReportNodeDTO[];
+}
+/** Guarded generated-label update. `initial` can only fill a blank generated
+ * description; `recap` additionally compares the exact automatic-name snapshot
+ * captured before the headless naming call. */
+export type BrokerGeneratedNameRequest = {
+    kind: 'initial';
+    description: string;
+    icon: string;
+} | {
+    kind: 'recap';
+    description: string;
+    icon: string;
+    expected: {
+        name: string;
+        description: string;
+        icon: string;
+        kind: string;
+    };
+};
+/** A daemon-selected Pi editor-label directive. No handler calls a broker. */
+export interface BrokerGeneratedNameResultDTO {
+    applied: boolean;
+    editorLabel?: string;
+}
+export interface BrokerPersonaAckRequest {
+    from: {
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+    to: {
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+}

package/dist/dto/broker-ops.js

@@ -0,0 +1,6 @@
+// Broker-to-daemon operation DTOs. These requests are emitted by a broker Pi
+// extension, but are handled exclusively by crtrd so canvas state keeps one
+// owner.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/dto/crons.d.ts

@@ -74,6 +74,12 @@ export interface ListCronsQuery {
 export interface CronScopeQuery {
     profile?: string | null;
 }
+/** Cancellation-only query. `run_id` is set automatically inside a cron run,
+ * letting crtrd distinguish a run ending itself from an external cancellation
+ * that must terminate an in-flight process. */
+export interface CancelCronQuery extends CronScopeQuery {
+    run_id?: string;
+}
 /** One settled run-log entry (`GET /v1/crons/:cronId`, `POST /v1/crons/:cronId/run`). */
 export interface CronRunDTO {
     run_id: string;

package/dist/dto/human.d.ts

@@ -1,5 +1,4 @@
 import type { NodeIdDTO } from './common.js';
-import type { InteractionResponseDTO } from './inbox.js';
 /** One anchored review comment, mirroring crouter's ticket-store shape as a
  *  plain structural wire type (no store import). */
 export interface FeedbackCommentDTO {
@@ -37,6 +36,13 @@ export interface FeedbackResultDTO {
     commentsTotal: number;
     commentsUnresolved: number;
 }
+export interface InteractionResponseDTO {
+    id: string;
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    optionComments?: Record<string, string>;
+}
 /** `POST /v1/human/tickets/{node_id}/resolve` body — a deck answer. */
 export interface HumanResolveRequest {
     responses: InteractionResponseDTO[];

package/dist/dto/inbox.d.ts

@@ -1,7 +1,6 @@
 import type { IsoTime } from './common.js';
 /** Opaque, stable, URL-safe ticket id: lowercase SHA-256 hex of
- *  `canonicalRoot + "\0" + ticketBasename`. Clients must treat it as opaque —
- *  it discloses no home filesystem path. */
+ *  `canonicalRoot + "\0" + ticketBasename`. */
 export type InboxTicketIdDTO = string;
 export type InteractionKindDTO = 'notify' | 'decision' | 'context' | 'error' | 'review';
 export interface DeckSourceDTO {
@@ -33,72 +32,3 @@ export type InboxTicketSummaryDTO = DeckTicketSummaryDTO | ReviewTicketSummaryDT
 export interface InboxListDTO {
     tickets: InboxTicketSummaryDTO[];
 }
-export interface InteractionOptionDTO {
-    id: string;
-    label: string;
-    description?: string;
-}
-export interface InteractionPreAnswerDTO {
-    selectedOptionId?: string;
-    selectedOptionIds?: string[];
-    freetext?: string;
-    label?: string;
-}
-export interface InteractionDTO {
-    id: string;
-    title: string;
-    subtitle: string;
-    /** Resolved source Markdown — `bodyPath` is deliberately impossible here. */
-    body?: string;
-    options: InteractionOptionDTO[];
-    multiSelect?: boolean;
-    allowFreetext?: boolean;
-    freetextLabel?: string;
-    kind?: InteractionKindDTO;
-    preAnswered?: InteractionPreAnswerDTO;
-}
-export interface DeckDTO {
-    title: string;
-    source?: DeckSourceDTO;
-    interactions: InteractionDTO[];
-}
-/** `GET /v1/human/inbox/:ticket_id` result for a pending deck. */
-export interface InboxDeckDTO {
-    ticket_id: InboxTicketIdDTO;
-    kind: 'deck';
-    deck: DeckDTO;
-}
-export interface InteractionResponseDTO {
-    id: string;
-    selectedOptionId?: string;
-    selectedOptionIds?: string[];
-    freetext?: string;
-    optionComments?: Record<string, string>;
-}
-/** `POST /v1/human/inbox/:ticket_id/respond` body. */
-export interface RespondInboxDeckRequest {
-    responses: InteractionResponseDTO[];
-}
-/** `POST /v1/human/inbox/:ticket_id/respond` result — the canonical humanloop
- *  `humanloop.response/v2` result, unchanged. */
-export interface DeckTicketResultDTO {
-    schema: 'humanloop.response/v2';
-    kind: 'deck';
-    responses: InteractionResponseDTO[];
-    summary: string;
-    completedAt: IsoTime;
-}
-/** `POST /v1/human/inbox/:ticket_id/cancel` body. `reason`, when present, must
- *  be nonempty after trim and at most 1000 characters. */
-export interface CancelInboxTicketRequest {
-    reason?: string;
-}
-/** `POST /v1/human/inbox/:ticket_id/cancel` result — the canonical humanloop
- *  `humanloop.cancel/v1` result, unchanged. `actor` is always `"human"`. */
-export interface CanceledTicketResultDTO {
-    schema: 'humanloop.cancel/v1';
-    kind: 'canceled';
-    canceledAt: IsoTime;
-    reason?: string;
-    actor?: string;
-}

package/dist/dto/inbox.js

@@ -1,10 +1,2 @@
-// Humanloop inbox DTOs — crtrd `/v1/human/inbox` (Northlight crouter-inbox v1,
-// inbox-contract.md §A). Crouter API envelope fields use the existing
-// snake_case convention; nested humanloop protocol objects retain their
-// canonical camelCase field names so they cross the wire without translation
-// or loss. Optional fields are omitted when absent, never serialized as
-// `null`. `bodyPath` is deliberately impossible on this wire — crtrd resolves
-// it server-side via humanloop's `parseDeck` and returns inline `body`.
-//
-// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+// Ticket summaries rendered by the attached terminal viewer.
 export {};

package/dist/dto/nodes.d.ts

@@ -45,6 +45,12 @@ export interface NodeSummaryDTO {
     intent: ExitIntentDTO;
     waiting_for: NodeIdDTO | null;
     pi_pid: number | null;
+    /** Launch-time process identity paired with `pi_pid`, or null when absent. */
+    pi_pid_identity: string | null;
+    /** Current tmux placement cache. Local tmux callers re-check the pane itself before acting. */
+    window: string | null;
+    tmux_session: string | null;
+    pane: string | null;
     final_report: string | null;
     finalized_at: IsoTime | null;
 }
@@ -103,13 +109,6 @@ export interface NodeDetailDTO extends NodeSummaryDTO {
      *  (never launched, or no token accounting yet). */
     context_tokens?: number | null;
     pi_session_id?: string | null;
-    /** Launch-time process-identity fingerprint captured alongside `pi_pid`
-     *  (`NodeMeta.pi_pid_identity`), or null. Surfaced so `revive --now`'s
-     *  client-side SIGTERM can pass the identity baseline to `recordedPidLiveness`
-     *  and refuse to signal a stranger process that reused a dead broker's pid.
-     *  Null when the node predates the field or its launch-time capture failed
-     *  (fail-open — no baseline means no guard, not a false mismatch). */
-    pi_pid_identity?: string | null;
     /** The node's durable model override (`NodeMeta.model_override`), or null when
      *  it runs on the kind/profile default. Surfaced so `node config --model`
      *  can report the resolved model after a patch. */

package/dist/dto/reviews.d.ts

@@ -1,4 +1,4 @@
-import type { IsoTime, NodeIdDTO, NodeStatusDTO } from './common.js';
+import type { IsoTime, NodeIdDTO } from './common.js';
 import type { FeedbackResultDTO } from './human.js';
 export type ReviewOriginKindDTO = 'ticket' | 'inline';
 /** `binding` is intentionally never exposed over the API. */
@@ -73,16 +73,6 @@ export interface ListReviewsQuery {
 export interface ReviewListDTO {
     reviews: ReviewDTO[];
 }
-/** Daemon-derived result of opening an active review or acknowledging a terminal one. */
-export type ReviewOpenResultDTO = {
-    review: ReviewDTO;
-    companion_node_id: NodeIdDTO;
-    companion_status: NodeStatusDTO;
-    disposition: 'open';
-} | {
-    review: ReviewDTO;
-    disposition: 'terminal';
-};
 /** Daemon-derived result of terminal review approval. */
 export interface ReviewSubmitResultDTO {
     review: ReviewDTO;

package/dist/routes.d.ts

@@ -19,6 +19,13 @@ export declare const routes: {
     readonly nodeFork: (id: string) => string;
     readonly nodeRevive: (id: string) => string;
     readonly nodeRelaunchRoot: (id: string) => string;
+    readonly nodeBrokerSessionBound: (id: string) => string;
+    readonly nodeBrokerSettle: (id: string) => string;
+    readonly nodeBrokerInboxCursor: (id: string) => string;
+    readonly nodeBrokerModel: (id: string) => string;
+    readonly nodeBrokerExtensionState: (id: string) => string;
+    readonly nodeBrokerGeneratedName: (id: string) => string;
+    readonly nodeBrokerPersonaAck: (id: string) => string;
     readonly nodeClose: (id: string) => string;
     readonly nodeRecycle: (id: string) => string;
     readonly nodeDemote: (id: string) => string;
@@ -54,7 +61,6 @@ export declare const routes: {
     readonly humanReviews: () => string;
     readonly humanReview: (reviewId: string) => string;
     readonly humanReviewByBridge: (bridgeNodeId: string) => string;
-    readonly humanReviewOpen: (reviewId: string) => string;
     readonly humanReviewSubmit: (reviewId: string) => string;
     readonly humanReviewCancel: (reviewId: string) => string;
     readonly humanReviewDocument: (reviewId: string) => string;
@@ -67,9 +73,6 @@ export declare const routes: {
     readonly humanCommentReopen: (commentId: string) => string;
     readonly humanCommentDelete: (commentId: string) => string;
     readonly humanInbox: () => string;
-    readonly humanInboxTicket: (ticketId: string) => string;
-    readonly humanInboxRespond: (ticketId: string) => string;
-    readonly humanInboxCancel: (ticketId: string) => string;
     readonly profiles: () => string;
     readonly profile: (name: string) => string;
     readonly modelAuths: () => string;

package/dist/routes.js

@@ -37,6 +37,13 @@ export const routes = {
     nodeFork: (id) => `${V}/nodes/${id}/fork`,
     nodeRevive: (id) => `${V}/nodes/${id}/revive`,
     nodeRelaunchRoot: (id) => `${V}/nodes/${id}/relaunch-root`,
+    nodeBrokerSessionBound: (id) => `${V}/nodes/${id}/broker/session-bound`,
+    nodeBrokerSettle: (id) => `${V}/nodes/${id}/broker/settle`,
+    nodeBrokerInboxCursor: (id) => `${V}/nodes/${id}/broker/inbox-cursor`,
+    nodeBrokerModel: (id) => `${V}/nodes/${id}/broker/model`,
+    nodeBrokerExtensionState: (id) => `${V}/nodes/${id}/broker/extension-state`,
+    nodeBrokerGeneratedName: (id) => `${V}/nodes/${id}/broker/generated-name`,
+    nodeBrokerPersonaAck: (id) => `${V}/nodes/${id}/broker/persona-ack`,
     nodeClose: (id) => `${V}/nodes/${id}/close`,
     nodeRecycle: (id) => `${V}/nodes/${id}/recycle`,
     nodeDemote: (id) => `${V}/nodes/${id}/demote`,
@@ -80,7 +87,6 @@ export const routes = {
     humanReviews: () => `${V}/human/reviews`,
     humanReview: (reviewId) => `${V}/human/reviews/${reviewId}`,
     humanReviewByBridge: (bridgeNodeId) => `${V}/human/reviews/by-bridge/${bridgeNodeId}`,
-    humanReviewOpen: (reviewId) => `${V}/human/reviews/${reviewId}/open`,
     humanReviewSubmit: (reviewId) => `${V}/human/reviews/${reviewId}/submit`,
     humanReviewCancel: (reviewId) => `${V}/human/reviews/${reviewId}/cancel`,
     humanReviewDocument: (reviewId) => `${V}/human/reviews/${reviewId}/document`,
@@ -92,11 +98,8 @@ export const routes = {
     humanCommentResolve: (commentId) => `${V}/human/comments/${commentId}/resolve`,
     humanCommentReopen: (commentId) => `${V}/human/comments/${commentId}/reopen`,
     humanCommentDelete: (commentId) => `${V}/human/comments/${commentId}/delete`,
-    // Humanloop inbox (Northlight crouter-inbox v1, inbox-contract.md §A)
+    // Attached terminal viewer inbox
     humanInbox: () => `${V}/human/inbox`,
-    humanInboxTicket: (ticketId) => `${V}/human/inbox/${ticketId}`,
-    humanInboxRespond: (ticketId) => `${V}/human/inbox/${ticketId}/respond`,
-    humanInboxCancel: (ticketId) => `${V}/human/inbox/${ticketId}/cancel`,
     // Profiles (server-side for P2 Core; CLI profile verbs stay fs-local)
     profiles: () => `${V}/profiles`,
     profile: (name) => `${V}/profiles/${name}`,

package/package.json

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