@wardby/cli 0.5.3 → 0.7.0

package/dist/core/secrets.js

@@ -1,31 +1,120 @@
+/**
+ * Secrets: encrypted-at-rest values, attached to an agent by name, readable
+ * only inside the sandbox at point-of-use (never by any read/list tool).
+ * `Secret.name` is unique per owner (`@@unique([ownerId, name])`), so two
+ * owners can each have their own "API_KEY" without collision — attach/get
+ * always resolve a name within one owner's (or, at get-time, one agent's)
+ * scope, never globally.
+ */
+import { Prisma } from "#prisma";
 import { boundedString } from "../sandbox/bounded-json.js";
+import { assertBrokerableValue, brokerConfigHash, parseSecretBrokerConfig, SECRET_BROKER_CHANGED, } from "./secret-broker-config.js";
+function brokerOf(secret) {
+    return secret.broker === null || secret.broker === undefined ? null : parseSecretBrokerConfig(secret.broker);
+}
+const BROKERED_GET_MESSAGE = 'secret_brokered: this secret is brokered; send it with fetch(url, { secrets: ["NAME"] }) instead of reading it';
 /**
  * Encrypts and stores a secret value. Upserts on (ownerId, name) — calling
  * this again for a name the owner already has rotates its value in place
  * (same id) rather than failing on the unique constraint. The plaintext is
- * never logged or returned.
+ * never logged or returned. With `options.broker`, the config is validated
+ * against the value, saved, and audited in the same transaction.
  */
-export async function createSecret(name, value, ownerId, cipher, db) {
+export async function createSecret(name, value, ownerId, cipher, db, options = {}) {
     boundedString(name, 1024);
     boundedString(value, 65_536);
+    const broker = options.broker ? parseSecretBrokerConfig(options.broker) : undefined;
+    if (broker)
+        assertBrokerableValue(broker, value);
     const ciphertext = await cipher.encrypt(value);
     const keyId = cipher.keyId();
-    return db.secret.upsert({
-        where: { ownerId_name: { ownerId, name } },
-        create: { name, ciphertext, keyId, ownerId },
-        update: { ciphertext, keyId },
+    if (!broker) {
+        // A rotation that omits `broker` keeps the stored config, so the new value must still be brokerable.
+        const existing = await db.secret.findUnique({
+            where: { ownerId_name: { ownerId, name } },
+            select: { broker: true },
+        });
+        if (existing?.broker)
+            assertBrokerableValue(brokerOf(existing), value);
+        return db.secret.upsert({
+            where: { ownerId_name: { ownerId, name } },
+            create: { name, ciphertext, keyId, ownerId },
+            update: { ciphertext, keyId },
+        });
+    }
+    return db.$transaction(async (tx) => {
+        const existing = await tx.secret.findUnique({ where: { ownerId_name: { ownerId, name } } });
+        const before = existing ? brokerOf(existing) : null;
+        const secret = await tx.secret.upsert({
+            where: { ownerId_name: { ownerId, name } },
+            create: { name, ciphertext, keyId, ownerId, broker },
+            update: { ciphertext, keyId, broker },
+        });
+        if (JSON.stringify(before) !== JSON.stringify(broker)) {
+            await tx.secretBrokerChange.create({
+                data: {
+                    secretId: secret.id,
+                    ownerId,
+                    secretName: name,
+                    actorId: ownerId,
+                    before: before ?? Prisma.JsonNull,
+                    after: broker,
+                    via: options.via ?? "mcp",
+                },
+            });
+        }
+        return secret;
+    });
+}
+/**
+ * Sets, changes, or (broker: null) removes a secret's broker config, with one audit
+ * row per actual change. `expectedBrokerHash` (brokerConfigHash of the config the
+ * caller confirmed) makes the change conditional, checked inside the transaction:
+ * if the secret is no longer brokered with exactly that config, it throws
+ * secret_broker_changed and changes nothing.
+ */
+export async function setSecretBroker(db, cipher, input) {
+    const after = input.broker === null ? null : parseSecretBrokerConfig(input.broker);
+    return db.$transaction(async (tx) => {
+        const secret = await tx.secret.findUnique({
+            where: { ownerId_name: { ownerId: input.ownerId, name: input.name } },
+        });
+        if (!secret)
+            throw new Error(`secret_not_found: no secret named "${input.name}"`);
+        const before = brokerOf(secret);
+        if (input.expectedBrokerHash !== undefined && (!before || brokerConfigHash(before) !== input.expectedBrokerHash)) {
+            throw new Error(SECRET_BROKER_CHANGED);
+        }
+        if (JSON.stringify(before) === JSON.stringify(after))
+            return { before, after };
+        if (after)
+            assertBrokerableValue(after, await cipher.decrypt(secret.ciphertext));
+        await tx.secret.update({ where: { id: secret.id }, data: { broker: after ?? Prisma.DbNull } });
+        await tx.secretBrokerChange.create({
+            data: {
+                secretId: secret.id,
+                ownerId: input.ownerId,
+                secretName: secret.name,
+                actorId: input.actorId,
+                before: before ?? Prisma.JsonNull,
+                after: after ?? Prisma.JsonNull,
+                via: input.via,
+            },
+        });
+        return { before, after };
     });
 }
 /** Names/metadata only — never a value or ciphertext. */
 export async function listSecrets(ownerId, db) {
     const secrets = await db.secret.findMany({ where: { ownerId } });
-    return secrets.map(({ id, name, keyId, ownerId: owner, createdAt, updatedAt }) => ({
-        id,
-        name,
-        keyId,
-        ownerId: owner,
-        createdAt,
-        updatedAt,
+    return secrets.map((s) => ({
+        id: s.id,
+        name: s.name,
+        keyId: s.keyId,
+        ownerId: s.ownerId,
+        createdAt: s.createdAt,
+        updatedAt: s.updatedAt,
+        broker: brokerOf(s),
     }));
 }
 async function findOwnedSecretByName(db, ownerId, name) {
@@ -66,37 +155,53 @@ export async function deleteSecret(secretId, db) {
  * binding written before that rule, left behind by make_owner, or on an
  * owner-less agent behaves exactly like an unattached name, so one owner's
  * secret never reaches another owner's agent (A2/S2-2, R2-1).
+ *
+ * A brokered secret's `get` throws `secret_brokered`; only the privileged host's `resolve` sees its value.
  */
 export function buildSecretsAccessor(agentId, cipher, db) {
+    async function resolve(name) {
+        boundedString(name, 1024);
+        if (db.$queryRaw) {
+            // NULL-safe: "=" is never true when either owner is NULL.
+            const rows = await db.$queryRaw `
+        SELECT CASE WHEN octet_length(s."ciphertext") <= 262144 THEN s."ciphertext" ELSE NULL END AS "ciphertext",
+               s."broker" AS "broker"
+        FROM "Secret" s
+        JOIN "AgentSecret" a ON a."secretId" = s."id"
+        JOIN "Agent" g ON g."id" = a."agentId"
+        WHERE a."agentId" = ${agentId} AND a."boundName" = ${name} AND s."ownerId" = g."ownerId" LIMIT 1`;
+            if (!rows.length)
+                return undefined;
+            if (rows[0].ciphertext === null)
+                throw new Error("secret_value_limit");
+            return {
+                value: await cipher.decrypt(rows[0].ciphertext),
+                broker: brokerOf({ broker: rows[0].broker }),
+            };
+        }
+        // Lightweight provider doubles use the same post-read bound; production Prisma filters in SQL.
+        const attachment = await db.agentSecret.findFirst({
+            where: { agentId, boundName: name },
+            include: { secret: true, agent: { select: { ownerId: true } } },
+        });
+        if (!attachment)
+            return undefined;
+        const owner = attachment.agent.ownerId;
+        if (owner === null || attachment.secret.ownerId !== owner)
+            return undefined;
+        boundedString(attachment.secret.ciphertext, 256 * 1024);
+        return {
+            value: await cipher.decrypt(attachment.secret.ciphertext),
+            broker: brokerOf({ broker: attachment.secret.broker ?? null }),
+        };
+    }
     return {
+        resolve,
         async get(name) {
-            boundedString(name, 1024);
-            if (db.$queryRaw) {
-                // NULL-safe: "=" is never true when either owner is NULL.
-                const rows = await db.$queryRaw `
-          SELECT CASE WHEN octet_length(s."ciphertext") <= 262144 THEN s."ciphertext" ELSE NULL END AS "ciphertext"
-          FROM "Secret" s
-          JOIN "AgentSecret" a ON a."secretId" = s."id"
-          JOIN "Agent" g ON g."id" = a."agentId"
-          WHERE a."agentId" = ${agentId} AND a."boundName" = ${name} AND s."ownerId" = g."ownerId" LIMIT 1`;
-                if (!rows.length)
-                    return undefined;
-                if (rows[0].ciphertext === null)
-                    throw new Error("secret_value_limit");
-                return cipher.decrypt(rows[0].ciphertext);
-            }
-            // Lightweight provider doubles use the same post-read bound; production Prisma filters in SQL.
-            const attachment = await db.agentSecret.findFirst({
-                where: { agentId, boundName: name },
-                include: { secret: true, agent: { select: { ownerId: true } } },
-            });
-            if (!attachment)
-                return undefined;
-            const owner = attachment.agent.ownerId;
-            if (owner === null || attachment.secret.ownerId !== owner)
-                return undefined;
-            boundedString(attachment.secret.ciphertext, 256 * 1024);
-            return cipher.decrypt(attachment.secret.ciphertext);
+            const entry = await resolve(name);
+            if (entry?.broker)
+                throw new Error(BROKERED_GET_MESSAGE);
+            return entry?.value;
         },
     };
 }
@@ -115,5 +220,8 @@ export function scopeSecretsAccessor(accessor, allowedNames) {
                 return undefined;
             return accessor.get(name);
         },
+        ...(accessor.resolve && {
+            resolve: async (name) => (allowed.has(name) ? accessor.resolve(name) : undefined),
+        }),
     };
 }

package/dist/core/stop-run.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Stopping a run on request (the stop_run MCP tool). Every executor already owns the stop of the
+ * runs it executes (`Executor.stop`), and each makes the terminal write itself, conditional on the
+ * run still being pending or running, so the first terminal write wins and a finished run is never
+ * rewritten:
+ *
+ * - a native run in the control plane is recorded `cancelled` and stops at its next step boundary
+ *   (InProcessExecutor/DbosExecutor; a run that has not started never does);
+ * - a native run in the sandbox is recorded `cancelled`, its gateway session ends so the worker's
+ *   next call is refused, and after a short grace its worker is killed and removed
+ *   (NativeSandboxExecutor);
+ * - a coding run, queued for a slot or running, is recorded `cancelled` first (the fence that keeps
+ *   a finishing run from pushing or opening a pull request), then its proxy session is cancelled and
+ *   its job stopped and removed (ContainerExecutor).
+ *
+ * This module adds what a caller asks for on top: the run's in-flight delegated child runs are
+ * stopped too (depth-first, so nothing keeps spending for a parent that stopped), who stopped it
+ * and why is kept on the row (Run.stopRequestReason) and logged, and a run already finished is
+ * returned unchanged.
+ */
+import type { PrismaClient, RunStatus } from "#prisma";
+import type { Executor } from "../providers/executor/types.js";
+export type StopRunDb = Pick<PrismaClient, "run">;
+export interface StopRunOptions {
+    db: StopRunDb;
+    executor: Pick<Executor, "stop">;
+    runId: string;
+    /** Who asked (a principal id), recorded with the reason. */
+    stoppedBy: string;
+    /** The caller's own words, if any. */
+    reason?: string;
+}
+export interface StopRunResult {
+    runId: string;
+    /** The run's status before this call. */
+    previousStatus: RunStatus;
+    /** The run's status after it: `cancelled` once stopped, or whatever it had already ended as. */
+    status: RunStatus;
+    /** False when the run had already finished: nothing was changed. */
+    stopRequested: boolean;
+    /** In-flight delegated child runs this call stopped as well. */
+    stoppedChildRunIds: string[];
+}
+/** The text recorded on a stopped run: who stopped it and why. */
+export declare function stopRunReason(stoppedBy: string, reason?: string): string;
+export declare function stopRun(options: StopRunOptions): Promise<StopRunResult>;

package/dist/core/stop-run.js

@@ -0,0 +1,61 @@
+import { logger } from "./logger.js";
+const stopLog = logger.child({ module: "stop-run" });
+const DRIVABLE = ["pending", "running"];
+/** Delegation trees are shallow; this only bounds a malformed one. */
+const MAX_CHILD_DEPTH = 16;
+/** The text recorded on a stopped run: who stopped it and why. */
+export function stopRunReason(stoppedBy, reason) {
+    const why = reason?.trim();
+    return `Stopped by ${stoppedBy} with stop_run${why ? `: ${why}` : "."}`;
+}
+export async function stopRun(options) {
+    const { db, runId } = options;
+    const row = await db.run.findUnique({ where: { id: runId }, select: { status: true } });
+    if (!row)
+        throw new Error(`Unknown run "${runId}".`);
+    const previousStatus = row.status;
+    if (!DRIVABLE.includes(previousStatus)) {
+        return { runId, previousStatus, status: previousStatus, stopRequested: false, stoppedChildRunIds: [] };
+    }
+    const reason = stopRunReason(options.stoppedBy, options.reason);
+    stopLog.info({ runId, stoppedBy: options.stoppedBy, previousStatus, reason }, "stopping run");
+    const stoppedChildRunIds = [];
+    await stopOne(options, runId, reason, stoppedChildRunIds, 0, new Set());
+    const after = await db.run.findUniqueOrThrow({ where: { id: runId }, select: { status: true } });
+    return { runId, previousStatus, status: after.status, stopRequested: true, stoppedChildRunIds };
+}
+async function stopOne(options, runId, reason, stoppedChildRunIds, depth, visited) {
+    const { db, executor } = options;
+    visited.add(runId);
+    try {
+        await executor.stop(runId, reason);
+    }
+    catch (err) {
+        // Still stop the children and record the request: a failed stop is retried by calling again.
+        stopLog.warn({ err, runId }, "the executor failed to stop the run");
+    }
+    // A run that never started has nothing to interrupt: end it here if no executor did.
+    await db.run.updateMany({
+        where: { id: runId, status: "pending" },
+        data: { status: "cancelled", error: reason, finishedAt: new Date() },
+    });
+    // Kept for get_run; written only on a run this stop (or another) cancelled, never on one that
+    // finished some other way meanwhile. stopRequestedAt stays null: it is the native sandbox
+    // gateway's deferred-stop marker, which the scheduler leader drains.
+    await db.run.updateMany({
+        where: { id: runId, status: "cancelled", stopRequestReason: null },
+        data: { stopRequestReason: reason },
+    });
+    if (depth >= MAX_CHILD_DEPTH)
+        return;
+    const children = await db.run.findMany({
+        where: { parentRunId: runId, status: { in: [...DRIVABLE] } },
+        select: { id: true },
+    });
+    for (const child of children) {
+        if (visited.has(child.id))
+            continue;
+        stoppedChildRunIds.push(child.id);
+        await stopOne(options, child.id, `Parent run ${runId} was stopped. ${reason}`, stoppedChildRunIds, depth + 1, visited);
+    }
+}

package/dist/core/workflow-event-recorder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Turns an emitted workflow event into outbox rows: resolves the event's work
+ * item (given, else the run's attribution, else the PR's issue link), finds
+ * the channel links that match (project links by the item's project, agent
+ * links by the event's agent), filters each link's event kinds, de-duplicates
+ * by channel, and writes one WorkflowEvent plus one NotificationDelivery per
+ * channel in a transaction. A dedupeKey that already exists is a no-op, so
+ * redeliveries and repeated finalizers record a fact once. Writes nothing
+ * when no link matches.
+ */
+import { type PrismaClient } from "#prisma";
+import { type WorkflowEventSink } from "./workflow-events.js";
+export type RecorderDb = Pick<PrismaClient, "notificationChannel" | "workflowEvent" | "notificationDelivery" | "runAttribution" | "issuePullRequest" | "$transaction">;
+export declare function createWorkflowEventRecorder(db: RecorderDb, enabledProviders: readonly string[]): WorkflowEventSink;

package/dist/core/workflow-event-recorder.js

@@ -0,0 +1,120 @@
+/**
+ * Turns an emitted workflow event into outbox rows: resolves the event's work
+ * item (given, else the run's attribution, else the PR's issue link), finds
+ * the channel links that match (project links by the item's project, agent
+ * links by the event's agent), filters each link's event kinds, de-duplicates
+ * by channel, and writes one WorkflowEvent plus one NotificationDelivery per
+ * channel in a transaction. A dedupeKey that already exists is a no-op, so
+ * redeliveries and repeated finalizers record a fact once. Writes nothing
+ * when no link matches.
+ */
+import { Prisma } from "#prisma";
+import { projectOf } from "../providers/issue-tracker/types.js";
+import { threadKeys } from "./workflow-events.js";
+async function resolveWorkItem(db, input) {
+    if (input.workItem)
+        return input.workItem;
+    if (input.runId) {
+        const attribution = await db.runAttribution.findUnique({
+            where: { runId: input.runId },
+            select: { workItem: { select: { provider: true, key: true } } },
+        });
+        if (attribution)
+            return attribution.workItem;
+    }
+    if (input.pullRequest) {
+        const pr = await db.issuePullRequest.findFirst({
+            where: {
+                codeProvider: input.pullRequest.codeProvider,
+                repository: input.pullRequest.repository,
+                number: input.pullRequest.number,
+            },
+            orderBy: { createdAt: "asc" },
+            select: { issueProvider: true, issueKey: true },
+        });
+        if (pr)
+            return { provider: pr.issueProvider, key: pr.issueKey };
+    }
+    return null;
+}
+export function createWorkflowEventRecorder(db, enabledProviders) {
+    return async (input) => {
+        if (enabledProviders.length === 0)
+            return;
+        const existing = await db.workflowEvent.findUnique({
+            where: { dedupeKey: input.dedupeKey },
+            select: { id: true },
+        });
+        if (existing)
+            return;
+        const item = await resolveWorkItem(db, input);
+        const or = [];
+        if (item)
+            or.push({ issueProvider: item.provider, projectKey: projectOf(item.key) });
+        if (input.agentId)
+            or.push({ agentId: input.agentId });
+        if (or.length === 0)
+            return;
+        const links = await db.notificationChannel.findMany({
+            where: { provider: { in: [...enabledProviders] }, OR: or },
+            select: { provider: true, channelId: true, events: true, includeCost: true },
+        });
+        const kind = input.payload.kind;
+        const byChannel = new Map();
+        for (const link of links) {
+            if (link.events.length > 0 && !link.events.includes(kind))
+                continue;
+            const key = `${link.provider}\u0000${link.channelId}`;
+            const prev = byChannel.get(key);
+            byChannel.set(key, {
+                provider: link.provider,
+                channelId: link.channelId,
+                includeCost: (prev?.includeCost ?? false) || link.includeCost,
+            });
+        }
+        if (byChannel.size === 0)
+            return;
+        const threadKey = item
+            ? threadKeys.issue(item.provider, item.key)
+            : input.pullRequest
+                ? threadKeys.pr(input.pullRequest.codeProvider, input.pullRequest.repository, input.pullRequest.number)
+                : input.runId
+                    ? threadKeys.run(input.runId)
+                    : null;
+        if (!threadKey)
+            return;
+        try {
+            await db.$transaction(async (tx) => {
+                const event = await tx.workflowEvent.create({
+                    data: {
+                        kind,
+                        dedupeKey: input.dedupeKey,
+                        runId: input.runId ?? null,
+                        agentId: input.agentId ?? null,
+                        workItemProvider: item?.provider ?? null,
+                        workItemKey: item?.key ?? null,
+                        codeProvider: input.pullRequest?.codeProvider ?? null,
+                        repository: input.pullRequest?.repository ?? null,
+                        prNumber: input.pullRequest?.number ?? null,
+                        payload: input.payload,
+                    },
+                });
+                await tx.notificationDelivery.createMany({
+                    data: [...byChannel.values()].map((c) => ({
+                        eventId: event.id,
+                        provider: c.provider,
+                        channelId: c.channelId,
+                        threadKey,
+                        includeCost: c.includeCost,
+                    })),
+                });
+            });
+        }
+        catch (err) {
+            // A concurrent recording of the same fact won the dedupeKey: nothing to do.
+            if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === "P2002")
+                return;
+            throw err;
+        }
+    };
+}

package/dist/core/workflow-events.d.ts

@@ -0,0 +1,94 @@
+import type { PackageAuditDigest, PackageAuditMode } from "../coding/registry/audit-mode.js";
+import type { RegistryRefusalSummary } from "../coding/registry/report.js";
+export declare const WORKFLOW_EVENT_KINDS: readonly ["issue_picked_up", "run_failed", "run_blocked", "pr_opened", "review_posted", "review_fix", "pr_closed", "packages_audited"];
+export type WorkflowEventKind = (typeof WORKFLOW_EVENT_KINDS)[number];
+/** Template inputs per kind. Every string here may be shown in Slack (escaped). */
+export type WorkflowPayload = {
+    kind: "run_blocked";
+    agentName: string;
+    packageRefusals: RegistryRefusalSummary[];
+} | {
+    kind: "issue_picked_up";
+    agentName: string;
+    trigger: string;
+} | {
+    kind: "run_failed";
+    agentName: string;
+    status: "failed" | "budget_exhausted" | "cancelled" | "lost" | "refused";
+    reason: string | null;
+} | {
+    kind: "pr_opened";
+    prLabel: string;
+    prUrl: string;
+    movedTo: string | null;
+} | {
+    kind: "review_posted";
+    agentName: string;
+    verdict: "APPROVE" | "CHANGES_REQUESTED" | "COMMENT";
+    prLabel: string;
+    prUrl: string | null;
+    ciPending: boolean;
+} | {
+    kind: "review_fix";
+    prLabel: string;
+    round: number;
+    maxRounds: number;
+    state: "started" | "capped";
+} | {
+    kind: "pr_closed";
+    prLabel: string;
+    prUrl: string;
+    merged: boolean;
+    movedTo: string | null;
+} | ({
+    kind: "packages_audited";
+    agentName: string;
+    mode: PackageAuditMode;
+} & PackageAuditDigest);
+/** What a thread's parent message shows about its subject. */
+export interface ThreadSubject {
+    /** "PAY-241" or "org/repo#212" or "run abc123". */
+    label: string;
+    title: string | null;
+    url: string | null;
+}
+export declare const dedupeKeys: {
+    issuePickedUp: (runId: string) => string;
+    runBlocked: (runId: string) => string;
+    runFailed: (runId: string) => string;
+    prOpened: (codeProvider: string, repository: string, n: number) => string;
+    reviewPosted: (runId: string) => string;
+    reviewFix: (repository: string, n: number, round: number, state: "started" | "capped") => string;
+    prClosed: (codeProvider: string, repository: string, n: number) => string;
+    packagesAudited: (runId: string) => string;
+};
+export declare const threadKeys: {
+    issue: (provider: string, key: string) => string;
+    pr: (codeProvider: string, repository: string, n: number) => string;
+    run: (runId: string) => string;
+};
+/** First line of an error, at most 200 characters; null for empty. */
+export declare function shortReason(error: string | null | undefined): string | null;
+export interface WorkflowEventInput {
+    dedupeKey: string;
+    payload: WorkflowPayload;
+    /** The run the event is about (its attribution names the work item). */
+    runId?: string;
+    /** The agent the event is about (agent links match on it). */
+    agentId?: string;
+    /** Known work item; otherwise resolved from runId's RunAttribution, then the PR's IssuePullRequest. */
+    workItem?: {
+        provider: string;
+        key: string;
+    };
+    pullRequest?: {
+        codeProvider: string;
+        repository: string;
+        number: number;
+    };
+}
+export type WorkflowEventSink = (input: WorkflowEventInput) => Promise<void>;
+/** Installed once per process by startNotifications; null uninstalls (tests). */
+export declare function setWorkflowEventSink(next: WorkflowEventSink | null): void;
+/** Never throws; a no-op until a sink is installed. */
+export declare function emitWorkflowEvent(input: WorkflowEventInput): Promise<void>;

package/dist/core/workflow-events.js

@@ -0,0 +1,48 @@
+import { logger } from "./logger.js";
+export const WORKFLOW_EVENT_KINDS = [
+    "issue_picked_up",
+    "run_failed",
+    "run_blocked",
+    "pr_opened",
+    "review_posted",
+    "review_fix",
+    "pr_closed",
+    "packages_audited",
+];
+export const dedupeKeys = {
+    issuePickedUp: (runId) => `issue_picked_up:${runId}`,
+    runBlocked: (runId) => `run_blocked:${runId}`,
+    runFailed: (runId) => `run_failed:${runId}`,
+    prOpened: (codeProvider, repository, n) => `pr_opened:${codeProvider}:${repository}#${n}`,
+    reviewPosted: (runId) => `review_posted:${runId}`,
+    reviewFix: (repository, n, round, state) => `review_fix:${repository}#${n}:${round}:${state}`,
+    prClosed: (codeProvider, repository, n) => `pr_closed:${codeProvider}:${repository}#${n}`,
+    packagesAudited: (runId) => `packages_audited:${runId}`,
+};
+export const threadKeys = {
+    issue: (provider, key) => `issue:${provider}:${key}`,
+    pr: (codeProvider, repository, n) => `pr:${codeProvider}:${repository}#${n}`,
+    run: (runId) => `run:${runId}`,
+};
+/** First line of an error, at most 200 characters; null for empty. */
+export function shortReason(error) {
+    const first = (error ?? "").split("\n", 1)[0].trim();
+    return first ? first.slice(0, 200) : null;
+}
+const log = logger.child({ module: "workflow-events" });
+let sink = null;
+/** Installed once per process by startNotifications; null uninstalls (tests). */
+export function setWorkflowEventSink(next) {
+    sink = next;
+}
+/** Never throws; a no-op until a sink is installed. */
+export async function emitWorkflowEvent(input) {
+    if (!sink)
+        return;
+    try {
+        await sink(input);
+    }
+    catch (err) {
+        log.warn({ err, dedupeKey: input.dedupeKey }, "workflow event record failed");
+    }
+}

package/dist/core/workflow-run-events.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Workflow notifications a run's finalizer emits: run_failed for a top-level
+ * run that did not succeed, run_blocked for package refusals without changes
+ * (children are summarized by their parent), packages_audited when its coding
+ * children installed anything under package audit mode, and
+ * review_posted when the run published a verdict on its own check. Called
+ * only by the finalizer that made the run terminal. Never throws.
+ */
+import type { PrismaClient } from "#prisma";
+export type RunEventsDb = Pick<PrismaClient, "agent" | "runHostCheck" | "run" | "runBudgetEvent" | "registryFetch" | "registryAuditRecord">;
+/** Emits top-level run outcomes and published review verdicts. Never throws. */
+export declare function emitRunFinishedEvents(db: RunEventsDb, run: {
+    id: string;
+    agentId: string;
+    status: string;
+    error: string | null;
+    parentRunId: string | null;
+}): Promise<void>;