@teamscala/service-boot 0.23.284 → 0.23.286

package/src/fn-routers/proposal-send-router.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The proposal SEND router — the proposal twin of agreement-send-router. An
+ * authed portal caller POSTs {proposalId, baseUrl} to email the proposal's CRM
+ * contact a per-recipient magic-link (no email gate, no OTP — see
+ * attach-proposal-magic.ts) to view their proposal. Resend-backed.
+ */
+import * as v from "valibot";
+interface User {
+    id: string;
+    organisationId: string | null;
+}
+interface Context {
+    user: User | null | undefined;
+    headers: Headers;
+    resolveUser?: (headers: Headers, prisma: any) => Promise<User | null>;
+    prisma: any;
+}
+export declare const proposalSendRouter: {
+    send: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<User | null>;
+        prisma: any;
+        user: User;
+    }>, v.ObjectSchema<{
+        readonly proposalId: v.StringSchema<undefined>;
+        /** Public base URL of the proposals site, e.g. https://proposals-dev.scala.business (no trailing slash). */
+        readonly baseUrl: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        ok: false;
+        error: any;
+        sentAt?: undefined;
+        url?: undefined;
+        email?: undefined;
+    } | {
+        error?: undefined;
+        ok: true;
+        sentAt: string;
+        url: string;
+        email: string;
+    }, {
+        ok: false;
+        error: any;
+        sentAt?: undefined;
+        url?: undefined;
+        email?: undefined;
+    } | {
+        error?: undefined;
+        ok: true;
+        sentAt: string;
+        url: string;
+        email: string;
+    }>, Record<never, never>, Record<never, never>>;
+};
+export {};

package/src/fn-routers/public-agreement-router.d.ts

@@ -0,0 +1,281 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Public ORPC procedures for DocuSign-style agreement signing, reached by the
+ * sign-in block's in-document signing blocks over the public HTTP transport
+ * (getOrpcClient().fn.publicAgreement.*). The unguessable agreement id plus an
+ * email that matches one of the agreement's parties IS the gate (no password).
+ *
+ * This is the off-the-shelf path per building-applications: server logic beyond
+ * CRUD is a typed ORPC procedure (the publicAssessment/publicGptSession shape),
+ * NOT a hand-written /api/data/* Hono handler and NOT a loopback fetch to the
+ * service's own ORPC. Writes go through context.prisma inside the handler — the
+ * sanctioned in-handler DB access (orpc-is-the-only-api) — so the audit trigger
+ * sees the ORPC caller context, the same proven path publicGptSession uses.
+ *
+ * Multi-party model: signature_data holds a parties roster (JSON) so one
+ * agreement can require signatures from several parties (e.g. Provider + Client)
+ * with no schema change. Each party is gated by its own email; the agreement
+ * completes (signed_at set) only when every party has signed. A single-signer
+ * agreement falls back to the original signer_email/signer_name columns.
+ */
+import * as v from "valibot";
+/** The Certificate of Completion display copy. DB-driven via the
+ *  `config/certificate-of-completion` registry row — mirrors the agreement gate's
+ *  `config/content-gate-agreement` pattern (same signing surface), so an operator
+ *  can rebrand/reword the certificate via `registry_edit` with no deploy; the
+ *  hardcoded defaults are the fallback. Generic structural data-column labels
+ *  (Signer/Role/Envelope ID/…) stay in the component, exactly as the gate keeps
+ *  its structural markup in code. */
+export interface CertificateCopy {
+    title: string;
+    signersHeading: string;
+    sealHeading: string;
+    sealNote: string;
+    footer: string;
+    badgeCompleted: string;
+    badgeInProgress: string;
+    /** Audit-table column labels — DB-driven so rewording is a registry_edit.
+     *  Each labels BOTH the <th> header AND the stacked-row data-label on mobile
+     *  (one source, kept in sync), never a second hardcoded copy. */
+    colSigner: string;
+    colRole: string;
+    colSigned: string;
+    colIp: string;
+    colAuth: string;
+}
+/** The Certificate of Completion data shape — the court-style audit certificate.
+ *  One home: {@link buildCertificateData} is consumed by both the
+ *  `publicAgreement.certificate` ORPC and the SSR agreement gate, so the signing
+ *  block receives identical data whether it reads the ORPC response or the
+ *  server-seeded prop. */
+export interface CertificateData {
+    ok: boolean;
+    envelopeId?: string;
+    documentName?: string | null;
+    issuedAt?: string;
+    complete?: boolean;
+    createdAt?: string | null;
+    sentAt?: string | null;
+    viewedAt?: string | null;
+    signedAt?: string | null;
+    documentHash?: string | null;
+    hashAlgo?: string | null;
+    hashedAt?: string | null;
+    parties?: {
+        role: string;
+        name: string | null;
+        email: string | null;
+        title: string | null;
+        company: string | null;
+        signedAt: string | null;
+        ip: string | null;
+        userAgent: string | null;
+        authMethod: string | null;
+    }[];
+    /** DB-driven display copy (config/certificate-of-completion); null when the
+     *  config row is missing/broken — the component falls back to FALLBACK_COPY. */
+    copy?: CertificateCopy | null;
+}
+/**
+ * Build the Certificate of Completion data for an agreement, gated to a party
+ * email — signer evidence (IP/device) is never exposed to a non-party. One data
+ * home: the `publicAgreement.certificate` ORPC and the SSR agreement gate
+ * (`buildSigningSession` in agreement-gate.ts) both call this. The read is
+ * intentionally RLS-unscoped via the raw registry prisma — the certificate is
+ * reached without a session (AG cookie only), which context.prisma's RLS would
+ * otherwise treat as no-org and hide. Accepts either the agreement record id or
+ * its page id (the UUID the signer sees in the URL is the page id).
+ */
+export declare function buildCertificateData(agreementId: string, email: string): Promise<CertificateData>;
+interface Context {
+    prisma: any;
+    headers: Headers;
+    resolveUser?: (headers: Headers, prisma: any) => Promise<any>;
+}
+export declare const publicAgreementRouter: {
+    verify: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly agreementId: v.StringSchema<undefined>;
+        readonly email: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        matched: false;
+        multiParty?: undefined;
+        role?: undefined;
+        partySignedAt?: undefined;
+        allSigned?: undefined;
+        parties?: undefined;
+        name?: undefined;
+        signerName?: undefined;
+        signedAt?: undefined;
+        accessToken?: undefined;
+    } | {
+        matched: boolean;
+        multiParty: boolean;
+        name: any;
+        role: any;
+        signerName: any;
+        partySignedAt: any;
+        allSigned: any;
+        parties: any;
+        accessToken: any;
+        signedAt?: undefined;
+    } | {
+        multiParty?: undefined;
+        role?: undefined;
+        partySignedAt?: undefined;
+        allSigned?: undefined;
+        parties?: undefined;
+        matched: boolean;
+        name: any;
+        signerName: any;
+        signedAt: any;
+        accessToken: any;
+    }, {
+        matched: false;
+        multiParty?: undefined;
+        role?: undefined;
+        partySignedAt?: undefined;
+        allSigned?: undefined;
+        parties?: undefined;
+        name?: undefined;
+        signerName?: undefined;
+        signedAt?: undefined;
+        accessToken?: undefined;
+    } | {
+        matched: boolean;
+        multiParty: boolean;
+        name: any;
+        role: any;
+        signerName: any;
+        partySignedAt: any;
+        allSigned: any;
+        parties: any;
+        accessToken: any;
+        signedAt?: undefined;
+    } | {
+        multiParty?: undefined;
+        role?: undefined;
+        partySignedAt?: undefined;
+        allSigned?: undefined;
+        parties?: undefined;
+        matched: boolean;
+        name: any;
+        signerName: any;
+        signedAt: any;
+        accessToken: any;
+    }>, Record<never, never>, Record<never, never>>;
+    sign: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly agreementId: v.StringSchema<undefined>;
+        readonly email: v.StringSchema<undefined>;
+        readonly signatureData: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly signerName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly title: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly company: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        signerName?: undefined;
+        signedAt?: undefined;
+        ok: false;
+        error: string;
+        alreadySigned?: undefined;
+        payUrl?: undefined;
+    } | {
+        ok: true;
+        role: any;
+        signedAt: any;
+        allSigned: any;
+        parties: any;
+        payUrl: string | null;
+    } | {
+        error?: undefined;
+        ok: true;
+        alreadySigned: boolean;
+        signedAt: any;
+        signerName: any;
+        payUrl?: undefined;
+    } | {
+        error?: undefined;
+        alreadySigned?: undefined;
+        ok: true;
+        signedAt: any;
+        signerName: any;
+        payUrl: string | null;
+    }, {
+        signerName?: undefined;
+        signedAt?: undefined;
+        ok: false;
+        error: string;
+        alreadySigned?: undefined;
+        payUrl?: undefined;
+    } | {
+        ok: true;
+        role: any;
+        signedAt: any;
+        allSigned: any;
+        parties: any;
+        payUrl: string | null;
+    } | {
+        error?: undefined;
+        ok: true;
+        alreadySigned: boolean;
+        signedAt: any;
+        signerName: any;
+        payUrl?: undefined;
+    } | {
+        error?: undefined;
+        alreadySigned?: undefined;
+        ok: true;
+        signedAt: any;
+        signerName: any;
+        payUrl: string | null;
+    }>, Record<never, never>, Record<never, never>>;
+    certificate: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly agreementId: v.StringSchema<undefined>;
+        readonly email: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<CertificateData, CertificateData>, Record<never, never>, Record<never, never>>;
+    verifyDocument: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly agreementId: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        parties?: undefined;
+        signedAt?: undefined;
+        ok: false;
+        envelopeId?: undefined;
+        documentName?: undefined;
+        complete?: undefined;
+        sealedHash?: undefined;
+        recomputedHash?: undefined;
+        valid?: undefined;
+    } | {
+        ok: true;
+        envelopeId: any;
+        documentName: any;
+        complete: any;
+        signedAt: any;
+        sealedHash: string | null;
+        recomputedHash: string | null;
+        valid: boolean;
+        parties: any;
+    }, {
+        parties?: undefined;
+        signedAt?: undefined;
+        ok: false;
+        envelopeId?: undefined;
+        documentName?: undefined;
+        complete?: undefined;
+        sealedHash?: undefined;
+        recomputedHash?: undefined;
+        valid?: undefined;
+    } | {
+        ok: true;
+        envelopeId: any;
+        documentName: any;
+        complete: any;
+        signedAt: any;
+        sealedHash: string | null;
+        recomputedHash: string | null;
+        valid: boolean;
+        parties: any;
+    }>, Record<never, never>, Record<never, never>>;
+};
+export {};

package/src/fn-routers/public-assessment-router.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Public ORPC procedure for submitting a public assessment (quiz) response.
+ * Mirrors public-gpt-session-router: a public, system-trusted write path for an
+ * anonymous/guest visitor — find-or-create the contact in client_database, score
+ * the answers, and persist an assessment_responses row. This is the submit path
+ * the deleted public-assessment wrapper used to provide via an injected onSubmit;
+ * recovering it here brings the quiz in line with the shared machinery (the GPT's
+ * publicGptSession is the sibling pattern) instead of a per-page bespoke handler.
+ *
+ * Scoring (recovered from live data, 2026-06-13): each scale answer contributes
+ * (scaleValue - 1) earned out of 4 max (1–5 scale → 0–4); choice answers
+ * contribute the selected option's points out of the question's max option
+ * points. A category's score is round(100 * earned / max) over that category's
+ * questions; the overall total is the same over all questions. Unanswered
+ * questions count toward the denominator (contribute 0) — matches the historical
+ * rows (e.g. Σ(v-1)=78 over 36 questions → 78/144 = 54).
+ */
+import * as v from "valibot";
+interface Context {
+    prisma: any;
+    headers: Headers;
+    resolveUser?: (headers: Headers, prisma: any) => Promise<any>;
+}
+export declare const publicAssessmentRouter: {
+    submit: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly assessmentId: v.StringSchema<undefined>;
+        readonly firstName: v.StringSchema<undefined>;
+        readonly email: v.StringSchema<undefined>;
+        readonly company: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly phone: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly website: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly industry: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly teamSize: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly revenueRange: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly answers: v.ArraySchema<v.ObjectSchema<{
+            readonly questionId: v.StringSchema<undefined>;
+            readonly scaleValue: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            readonly textValue: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly choiceValue: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly choiceValues: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        readonly error: "Assessment not found";
+    } | {
+        readonly error?: undefined;
+        success: true;
+        responseId: any;
+        reportUrl: string;
+        totalScore: number;
+        categoryScores: Record<string, number>;
+        band?: string | undefined;
+    }, {
+        readonly error: "Assessment not found";
+    } | {
+        readonly error?: undefined;
+        success: true;
+        responseId: any;
+        reportUrl: string;
+        totalScore: number;
+        categoryScores: Record<string, number>;
+        band?: string | undefined;
+    }>, Record<never, never>, Record<never, never>>;
+};
+export {};

package/src/fn-routers/public-gpt-session-router.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for public GPT session management.
+ * Creates/restores conversations and messages for public-facing GPT pages.
+ */
+import * as v from "valibot";
+interface Context {
+    prisma: any;
+    headers: Headers;
+    resolveUser?: (headers: Headers, prisma: any) => Promise<any>;
+}
+export declare const publicGptSessionRouter: {
+    createOrRestore: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly contactName: v.StringSchema<undefined>;
+        readonly email: v.StringSchema<undefined>;
+        readonly phone: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly gptId: v.StringSchema<undefined>;
+        readonly orgId: v.StringSchema<undefined>;
+        readonly sourceUrl: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        conversationId: any;
+        contactName: any;
+        contactPhone: any;
+        messages: any;
+        tokenTotals: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }, {
+        conversationId: any;
+        contactName: any;
+        contactPhone: any;
+        messages: any;
+        tokenTotals: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }>, Record<never, never>, Record<never, never>>;
+    load: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly conversationId: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        conversationId: any;
+        contactName: string;
+        contactEmail: string;
+        messages: any;
+        tokenTotals: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    } | null, {
+        conversationId: any;
+        contactName: string;
+        contactEmail: string;
+        messages: any;
+        tokenTotals: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    } | null>, Record<never, never>, Record<never, never>>;
+    saveMessages: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly conversationId: v.StringSchema<undefined>;
+        readonly messages: v.ArraySchema<v.ObjectSchema<{
+            readonly id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly role: v.StringSchema<undefined>;
+            readonly content: v.StringSchema<undefined>;
+            readonly parts: v.OptionalSchema<v.ArraySchema<v.AnySchema, undefined>, undefined>;
+            readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.AnySchema, undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, import("@orpc/contract").Schema<void, void>, Record<never, never>, Record<never, never>>;
+    clear: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly conversationId: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        conversationId: any;
+        contactName: string;
+        contactPhone: string | undefined;
+        messages: Array<{
+            role: string;
+            content: string;
+            parts?: unknown[];
+        }>;
+        tokenTotals: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }, {
+        conversationId: any;
+        contactName: string;
+        contactPhone: string | undefined;
+        messages: Array<{
+            role: string;
+            content: string;
+            parts?: unknown[];
+        }>;
+        tokenTotals: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }>, Record<never, never>, Record<never, never>>;
+    checkIdentity: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly email: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        isPlatformUser: boolean;
+    }, {
+        isPlatformUser: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+    upload: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, v.ObjectSchema<{
+        readonly conversationId: v.StringSchema<undefined>;
+        readonly fileData: v.StringSchema<undefined>;
+        readonly fileName: v.StringSchema<undefined>;
+        readonly fileType: v.StringSchema<undefined>;
+        readonly fileSize: v.NumberSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        success: true;
+        url: string;
+        type: string;
+    }, {
+        success: true;
+        url: string;
+        type: string;
+    }>, Record<never, never>, Record<never, never>>;
+};
+export {};

package/src/fn-routers/sign-in-flow-router.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * `fn.signInFlow` — typed ORPC procedures for the sign-in flow's client-facing
+ * reads (flow config, session check, portal list). Replaces the former
+ * `/api/data/{sign-in-flow-config,check-session,portals}` HANDLER_MAP entries
+ * from the deleted register-data-routes.ts (orpc-is-the-only-api: every API surface is a
+ * typed ORPC procedure, never a hand-written Hono route). Logic ported
+ * verbatim from those handlers — these are anonymous-allowed reads (they
+ * return an empty result for an unauthenticated caller, never throw), so they
+ * use a public base procedure reading `context.headers` for the session, NOT
+ * the `authed` middleware (which throws UNAUTHORIZED).
+ *
+ * EXPAND phase: this router is ADDITIVE — registered into the `fn` namespace
+ * but not yet retargeted by @teamscala/auth's use-sign-in-flow client (which
+ * still hits the /api/data/* routes). The HANDLER_MAP entries stay until the
+ * client retarget + round-trip verify land (post-incident, when the auth-flow
+ * test harness can run), then are removed (CONTRACT).
+ */
+import type { Context } from "./auth-router.ts";
+export declare const signInFlowRouter: {
+    getSignInFlowConfig: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<any, any>, Record<never, never>, Record<never, never>>;
+    checkSession: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        user?: undefined;
+        redirectUrl?: undefined;
+        portalCount?: undefined;
+    } | {
+        user: any;
+        redirectUrl: any;
+        portalCount: number;
+    }, {
+        user?: undefined;
+        redirectUrl?: undefined;
+        portalCount?: undefined;
+    } | {
+        user: any;
+        redirectUrl: any;
+        portalCount: number;
+    }>, Record<never, never>, Record<never, never>>;
+    listPortals: import("@orpc/server").DecoratedProcedure<Context & Record<never, never>, Context, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        portals: never[];
+        userOrgId: null;
+        userName: any;
+    } | {
+        portals: {
+            id: unknown;
+            name: {};
+            slug: {} | null;
+            status: {} | null;
+            website_type: {} | null;
+            organisation_id: {} | null;
+            portal_type: {} | null;
+        }[];
+        userOrgId: string;
+        userName: any;
+    }, {
+        portals: never[];
+        userOrgId: null;
+        userName: any;
+    } | {
+        portals: {
+            id: unknown;
+            name: {};
+            slug: {} | null;
+            status: {} | null;
+            website_type: {} | null;
+            organisation_id: {} | null;
+            portal_type: {} | null;
+        }[];
+        userOrgId: string;
+        userName: any;
+    }>, Record<never, never>, Record<never, never>>;
+};

package/src/fn-routers/task-sync-dispatch.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * DB→AGENT dispatch for task-sync — notifies a lane's live pane that its
+ * work_items task list changed out-of-band (operator toggled a subtask in the
+ * projects UI, another lane edited a shared task). The pane's adapter then
+ * re-reads (fn.taskSync.readTaskList) and updates its native list.
+ *
+ * MECHANISM — reuses the existing CLI-agnostic channel delivery, no new
+ * transport: a POST to scala-channel's fleet-events publish entry
+ * (POST /api/fleet/events — @teamscala/channel/fleet-events-publish) carrying an
+ * `orchestrator.message` FleetEvent with slotName "cross-pane". That slot is
+ * the watchEvents bypass for events NOT tied to a fleet_agent_runs row
+ * (FleetEventOrchestratorMessageSchema comment) — exactly the system-originated
+ * case. scala-channel re-emits onto its eventBus and streamFleetEvents delivers
+ * to the subscriber filtered by orchestratorSessionId (the target lane pane).
+ * Both the Claude Code relay and the OpenCode scala-hooks plugin subscribe to
+ * that SSE stream for their own pane identity and inject each event natively —
+ * so ONE publish reaches every CLI that has a live projection, no per-CLI
+ * dispatch code here.
+ *
+ * NOT the dispatch entry (POST /api/channel/send): that path requires a real
+ * sender pane identity (channel-sender-identity-validated anti-spoof) and so
+ * cannot carry a system-originated notification. The publish path is
+ * internal-trusted (localhost super-admin) and accepts a synthetic
+ * fromOrchestratorId — the correct path for a system→pane message.
+ *
+ * scala-channel's address is resolved from its service_routing row (local_port)
+ * — never hardcoded (service-ports-from-registry). Fire-and-forget: a dispatch
+ * failure (scala-channel down, port unresolvable) is logged and swallowed; it
+ * must never block the work_items write that triggered it, and the lane's
+ * SessionStart/UserPromptSubmit backstop picks up the change on its next turn
+ * regardless.
+ */
+/**
+ * The `orchestrator.message` FleetEvent payload that notifies a lane its task
+ * list changed. Pure (no I/O) so it is unit-testable; notifyLaneOfTaskChange
+ * posts it. slotName "cross-pane" is REQUIRED — it is the watchEvents bypass for
+ * events not tied to a fleet_agent_runs row. orchestratorSessionId is the TARGET
+ * lane pane (the SSE subscriber filter). The message is single-line (the
+ * <channel> tag renders it inline).
+ */
+export interface TaskChangedEvent {
+    type: "orchestrator.message";
+    message: string;
+    fromOrchestratorId: string;
+    runId: string;
+    slotName: "cross-pane";
+    ts: number;
+    orchestratorSessionId: string;
+}
+export declare function buildTaskChangedEvent(lanePane: string, taskId: string, now?: number): TaskChangedEvent;
+/**
+ * Publish a "your task list changed" notification to the owning lane's pane.
+ * The pane identity is the stable tmux id ("tmux:%42") every CLI relay/plugin
+ * receives for. `taskId` is carried in the message so the recipient can re-read
+ * just that task. Fire-and-forget.
+ */
+export declare function notifyLaneOfTaskChange(lanePane: string, taskId: string): Promise<void>;