@onepointfour-packs/flaredeck-agent 0.2.209 → 0.2.211

package/dist/harness/handover.js

@@ -0,0 +1,63 @@
+/**
+ * When a card session ends, whether it writes a handover note to the card, and on which plan.
+ * Split out of serve.ts (docs/spec-harness-profiles.md, step 2).
+ */
+/** Tools that only look: reading files, searching, asking FlareDeck or a service what is there. */
+export function onlyLooks(tool) {
+    if (['Read', 'Grep', 'Glob', 'LS', 'ToolSearch', 'TodoWrite', 'TaskOutput', 'LSP', 'WebFetch', 'WebSearch', 'Monitor', 'Skill'].includes(tool))
+        return true;
+    const op = tool.startsWith('mcp__') ? tool.split('__').slice(2).join('__') : '';
+    return /^(get|find|list|read|search|health|hello|whats|check|describe|site_map|see_screen|browser_look|browser_screenshot|browser_events|pull_request_status|preview)/i.test(op);
+}
+/** Record a tool call against the session it ran in. */
+export function noteHandoverTool(logs, key, tool, at) {
+    const l = logs.get(key) ?? {};
+    if (/__set-card-notes$/.test(tool))
+        l.notesAt = at;
+    else if (!onlyLooks(tool))
+        l.changedAt = at;
+    logs.set(key, l);
+}
+/**
+ * Whether a session ending needs a handover note: it changed something, after its last notes.
+ * Unknown (no record) is treated as needed, as before.
+ */
+export function handoverNeeded(l) {
+    if (!l)
+        return true;
+    if (!l.changedAt)
+        return false;
+    return !l.notesAt || l.changedAt > l.notesAt;
+}
+/**
+ * Whether a worker's card has gone to someone else, so its notes are no longer the worker's to
+ * write. FlareDeck refuses them (set-card-notes: "not assigned to you"), and the handover turn
+ * reopened a whole session only to be told so — CASE on HR-1128, TARS on HR-1141 (20 Oct).
+ * Unknown (no card, no assignee, no id) is not "someone else": the handover runs as before.
+ */
+export function cardWentElsewhere(card, selfId) {
+    const holder = card?.assigned_to?.uid;
+    return !!selfId && !!holder && holder !== selfId;
+}
+/**
+ * Which Claude token a handover runs on: a fresh pick from FlareDeck, because the plan the turn
+ * used may have run out since; the turn's own plan when FlareDeck cannot be asked; 'none' when
+ * every plan is spent; null to fall back to this machine's own login (no subscriptions set up).
+ */
+export async function handoverSubscription(subs, lastUsed) {
+    try {
+        const s = await subs();
+        if (!s)
+            return lastUsed ?? null;
+        const pick = await s.choose([]);
+        if (pick.use === 'token' && pick.token)
+            return pick.token;
+        if (pick.use === 'none')
+            return 'none';
+        return lastUsed ?? null;
+    }
+    catch {
+        return lastUsed ?? null;
+    }
+}
+//# sourceMappingURL=handover.js.map

package/dist/harness/handover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handover.js","sourceRoot":"","sources":["../../src/harness/handover.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,mGAAmG;AACnG,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5J,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,OAAO,gKAAgK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACnL,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,gBAAgB,CAAC,IAA8B,EAAE,GAAW,EAAE,IAAY,EAAE,EAAU;IACpG,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,CAAC,CAAC,OAAO,GAAG,EAAE,CAAC;SAC9C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAAE,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC;IAC5C,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,CAA0B;IACvD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,IAAI,CAAC,CAAC,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,OAAO,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAkE,EAAE,MAAc;IAClH,MAAM,MAAM,GAAG,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC;IACtC,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,IAAI,MAAM,KAAK,MAAM,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAqG,EACrG,QAA4B;IAE5B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC;YAAE,OAAO,QAAQ,IAAI,IAAI,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,GAAG,KAAK,OAAO,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QAC1D,IAAI,IAAI,CAAC,GAAG,KAAK,MAAM;YAAE,OAAO,MAAM,CAAC;QACvC,OAAO,QAAQ,IAAI,IAAI,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,IAAI,IAAI,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/harness/pause.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Paused: a wall this agent cannot get past by itself — GitHub refusing it, a required MCP server
+ * not connected, the disk full — so it does no work at all, no turns and no tokens, until it is
+ * resumed. See flaredeck-mcp/src/mcp/pause.ts for the why.
+ *
+ * Who resumes it: a wall that clears on its own (disk, MCP) is resumed by the agent the moment it
+ * clears; one that needs a person (GitHub) is reported fixed to the lead, once, and the lead
+ * resumes it — or, with no lead to ask, the agent resumes itself.
+ * Split out of serve.ts (docs/spec-harness-profiles.md, step 2).
+ */
+export type Wall = {
+    check: string;
+    reason: string;
+};
+/** FlareDeck's record of the pause (flaredeck.ts). */
+export type PauseRecord = {
+    pauseState: () => Promise<{
+        check: string;
+        reason: string;
+        since: string;
+        ready?: boolean;
+    } | null>;
+    pause: (check: string, reason: string) => Promise<{
+        already: boolean;
+        handedBack: string[];
+        lead: string | null;
+    }>;
+    resumeSelf: () => Promise<{
+        resumed: boolean;
+        why?: string;
+    }>;
+    ready: () => Promise<void>;
+};
+export type PauseDeps = {
+    /** Undefined when this harness has no FlareDeck REST access: nothing is recorded or asked. */
+    record: PauseRecord | undefined;
+    /** The walls, checked in code — never by asking the model. Null: none. */
+    walls: () => Promise<Wall | null>;
+    /** A wall that clears on its own, checked every minute: null while it stands, else what cleared it. */
+    cleared: (check: 'disk' | 'mcp') => Promise<string | null>;
+    hasLead: () => boolean;
+    /** Stop the turn running now, if any. */
+    stopRun: () => void;
+    /** What the pane shows: the reason while paused, undefined when not. */
+    show: (reason: string | undefined) => void;
+    /** Back to work: pick up the card in progress or the next one. */
+    resume: () => void;
+    log: (kind: 'warn' | 'event', text: string) => void;
+    now?: () => number;
+};
+/** The walls slower to check (they ask GitHub) are looked at again this often while paused. */
+export declare const WALL_RECHECK_MS: number;
+export declare function createPause(d: PauseDeps): {
+    paused: () => Wall | null;
+    enter: (wall: Wall) => Promise<void>;
+    /**
+     * At start, before any card is picked up. A restart while paused picks the pause back up from
+     * FlareDeck rather than re-announcing it — and checks the wall now, not in ten minutes: a
+     * restart is often BECAUSE somebody fixed it (C3PO, 16 Oct, sat paused for a lead it lacks).
+     */
+    start(): Promise<void>;
+    /**
+     * Every minute while paused: has the lead resumed it (one REST call, no model)? Has a wall that
+     * clears on its own cleared? Every ten minutes, are the other walls gone?
+     */
+    tick(): Promise<void>;
+};

package/dist/harness/pause.js

@@ -0,0 +1,128 @@
+/**
+ * Paused: a wall this agent cannot get past by itself — GitHub refusing it, a required MCP server
+ * not connected, the disk full — so it does no work at all, no turns and no tokens, until it is
+ * resumed. See flaredeck-mcp/src/mcp/pause.ts for the why.
+ *
+ * Who resumes it: a wall that clears on its own (disk, MCP) is resumed by the agent the moment it
+ * clears; one that needs a person (GitHub) is reported fixed to the lead, once, and the lead
+ * resumes it — or, with no lead to ask, the agent resumes itself.
+ * Split out of serve.ts (docs/spec-harness-profiles.md, step 2).
+ */
+/** The walls slower to check (they ask GitHub) are looked at again this often while paused. */
+export const WALL_RECHECK_MS = 10 * 60 * 1000;
+export function createPause(d) {
+    const now = d.now ?? Date.now;
+    let paused = null;
+    let readyReported = false;
+    let lastWallCheck = 0;
+    const unpause = (why) => {
+        d.log('event', why);
+        paused = null;
+        readyReported = false;
+        d.show(undefined);
+        d.resume();
+    };
+    /** The wall is gone. No lead to ask: resume. Otherwise tell the lead, once, and wait. */
+    const fixed = async (check) => {
+        if (!d.hasLead()) {
+            const r = await d.record?.resumeSelf().catch(() => null);
+            if (r?.resumed) {
+                unpause(`${check} is fixed — resumed myself (no lead to ask)`);
+                return;
+            }
+        }
+        if (readyReported)
+            return;
+        readyReported = true;
+        d.log('event', `${check} is fixed — told the lead; waiting to be resumed`);
+        await d.record?.ready().catch(() => { });
+    };
+    const enter = async (wall) => {
+        if (paused?.check === wall.check)
+            return;
+        paused = wall;
+        readyReported = false;
+        d.show(wall.reason);
+        d.log('warn', `PAUSED (${wall.check}): ${wall.reason}`);
+        d.stopRun();
+        try {
+            const r = await d.record?.pause(wall.check, wall.reason);
+            /* A solo agent has no lead: its cards stay with it (each gets a comment) and nobody is
+               messaged. "told the lead, handed back …" would describe something that never happened. */
+            if (r && !r.already) {
+                d.log('event', r.lead
+                    ? `told the lead${r.handedBack.length ? `, handed back ${r.handedBack.join(', ')}` : ''} — doing nothing until resumed`
+                    : `no lead to tell — ${r.handedBack.length ? `left a note on ${r.handedBack.join(', ')}; they stay mine` : 'nothing handed back'}. ${wall.check === 'disk' ? 'I resume myself once the disk is clear.' : wall.check === 'mcp' ? 'I resume myself once it is connected.' : 'A person resumes me.'}`);
+            }
+        }
+        catch (e) {
+            d.log('warn', `could not tell FlareDeck I am paused: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    return {
+        paused: () => paused,
+        enter,
+        /**
+         * At start, before any card is picked up. A restart while paused picks the pause back up from
+         * FlareDeck rather than re-announcing it — and checks the wall now, not in ten minutes: a
+         * restart is often BECAUSE somebody fixed it (C3PO, 16 Oct, sat paused for a lead it lacks).
+         */
+        async start() {
+            const server = await d.record?.pauseState().catch(() => undefined);
+            if (server) {
+                paused = { check: server.check, reason: server.reason };
+                readyReported = !!server.ready;
+                d.show(server.reason);
+                d.log('warn', `PAUSED since ${server.since.slice(0, 16).replace('T', ' ')} (${server.check}) — doing nothing until the lead resumes me`);
+                if (!(await d.walls())) {
+                    lastWallCheck = now();
+                    await fixed(server.check);
+                }
+                return;
+            }
+            const wall = await d.walls();
+            if (wall)
+                await enter(wall);
+        },
+        /**
+         * Every minute while paused: has the lead resumed it (one REST call, no model)? Has a wall that
+         * clears on its own cleared? Every ten minutes, are the other walls gone?
+         */
+        async tick() {
+            if (!paused)
+                return;
+            const server = await d.record?.pauseState().catch(() => undefined);
+            if (server === null) {
+                const still = await d.walls();
+                if (still) {
+                    paused = null;
+                    await enter(still);
+                    return;
+                }
+                unpause('resumed by the lead — back to work');
+                return;
+            }
+            /* Disk is a statfs call, so it is checked every tick; MCP is one HTTP call. A wall that has
+               cleared resumes the agent at once — there is nothing for a lead to decide about a number,
+               and waiting for one left the agent idle for hours after the space had been freed. */
+            const selfClearing = paused.check === 'disk' || paused.check === 'mcp';
+            if (selfClearing) {
+                const cleared = await d.cleared(paused.check);
+                if (!cleared)
+                    return;
+                const r = await d.record?.resumeSelf().catch(() => null);
+                if (r?.resumed) {
+                    unpause(`${cleared} — resumed myself and told the lead`);
+                    return;
+                }
+                // An older server without self-resume: fall through to telling the lead, as before.
+            }
+            if ((!selfClearing && now() - lastWallCheck < WALL_RECHECK_MS) || readyReported)
+                return;
+            lastWallCheck = now();
+            if (!(await d.walls()))
+                await fixed(paused.check);
+        },
+    };
+}
+//# sourceMappingURL=pause.js.map

package/dist/harness/pause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pause.js","sourceRoot":"","sources":["../../src/harness/pause.ts"],"names":[],"mappings":"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"}

package/dist/harness/plan-usage.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A turn's Claude subscription: what it reports to FlareDeck's ledger while it runs, and whether
+ * the turn has to run again on another one when it is over.
+ * Split out of serve.ts (docs/spec-harness-profiles.md, step 2).
+ */
+import type { AgentEvent } from '../agent.js';
+import { CouldNotWork } from '../engine.js';
+import type { SubscriptionsClient } from '../subscriptions.js';
+/** The run failed on its Claude subscription — capped or token rejected — not on its work. */
+export declare class RetryOnAnotherPlan extends CouldNotWork {
+}
+/**
+ * How many plans one event may switch through. Each retry spends one plan, so the plans that exist
+ * bound it already; this is the backstop.
+ */
+export declare const MAX_PLAN_SWITCHES = 4;
+/** A rejected token, as the CLI words it — not capacity, so never filed as spent. */
+export declare const TOKEN_REJECTED: RegExp;
+export type PlanUsageDeps = {
+    /** The plan this turn runs on; null when it runs on this machine's own login. */
+    plan: {
+        id: string;
+        label: string;
+    } | null;
+    subs: Pick<SubscriptionsClient, 'spent' | 'seen'> | null;
+    /**
+     * Plans that failed on an event, by event id, so its retry is offered a different one. A plan
+     * that hit its cap or had its token rejected used to fail the card while the other plans sat
+     * unused; now the event goes straight back on the queue and `choose` is told what not to offer.
+     */
+    failed: Map<string, string[]>;
+    eventId: string;
+    /** What the turn was on, for the ledger's note. */
+    during: string;
+    log: (kind: 'warn', text: string) => void;
+    /** The run reported its plan's usage itself, so no separate read is needed after it. */
+    onSeen: () => void;
+};
+export declare function planUsage(d: PlanUsageDeps): {
+    /** Every event of the run. Reported, never interpreted here. */
+    observe(out: AgentEvent): void;
+    /**
+     * The run is over. The plan failed, not the work: throw RetryOnAnotherPlan so the event runs
+     * again now, on another plan. A spent window was filed above (awaited here, so `choose` sees
+     * it); a rejected token — a mis-pasted or revoked setup-token — is excluded for this event and
+     * said plainly. The retry resumes the same session, so work done in the turn is not lost.
+     */
+    settle(runError: unknown, doneText: string): Promise<void>;
+};

package/dist/harness/plan-usage.js

@@ -0,0 +1,69 @@
+import { CouldNotWork } from '../engine.js';
+/** The run failed on its Claude subscription — capped or token rejected — not on its work. */
+export class RetryOnAnotherPlan extends CouldNotWork {
+}
+/**
+ * How many plans one event may switch through. Each retry spends one plan, so the plans that exist
+ * bound it already; this is the backstop.
+ */
+export const MAX_PLAN_SWITCHES = 4;
+/** A rejected token, as the CLI words it — not capacity, so never filed as spent. */
+export const TOKEN_REJECTED = /API Error: 401|invalid bearer token|OAuth token has expired|OAuth token (was )?revoked/i;
+export function planUsage(d) {
+    /**
+     * One cap is usually seen two or three times in a run: the structured `rate_limit_event` (which
+     * knows the window and the reset), then the error on the assistant message and the result text
+     * (which know neither). Reporting all of them filed an `unknown` window with a guessed five-hour
+     * block on top of the real one — keeping a plan out hours past its reset. Once a named window is
+     * reported, the anonymous echoes are dropped.
+     */
+    let spentNamed = false;
+    let spentAny = false;
+    const reports = [];
+    return {
+        /** Every event of the run. Reported, never interpreted here. */
+        observe(out) {
+            if (out.kind !== 'limits' || !d.plan)
+                return;
+            /* 'allowed_warning' arrives while the plan still works — treating it as spent would retire
+               every subscription at about half capacity, with each account still having headroom. */
+            if (out.spent) {
+                const named = !!out.window && out.window !== 'unknown';
+                spentAny = true;
+                if (named || !spentNamed) {
+                    spentNamed ||= named;
+                    reports.push(d.subs?.spent(d.plan.id, out.window, out.resetsAt, out.why ?? `hit during ${d.during}`) ?? Promise.resolve());
+                    d.log('warn', `claude: ${d.plan.label} hit its ${out.window ?? 'usage'} limit (${out.source ?? 'unknown signal'})`);
+                }
+            }
+            else if (out.window && typeof out.utilization === 'number') {
+                d.onSeen();
+                void d.subs?.seen(d.plan.id, out.window, out.utilization, out.resetsAt);
+            }
+        },
+        /**
+         * The run is over. The plan failed, not the work: throw RetryOnAnotherPlan so the event runs
+         * again now, on another plan. A spent window was filed above (awaited here, so `choose` sees
+         * it); a rejected token — a mis-pasted or revoked setup-token — is excluded for this event and
+         * said plainly. The retry resumes the same session, so work done in the turn is not lost.
+         */
+        async settle(runError, doneText) {
+            if (d.plan) {
+                const said = `${runError instanceof Error ? runError.message : runError ?? ''} ${doneText}`;
+                const rejected = TOKEN_REJECTED.test(said);
+                if (rejected || spentAny) {
+                    await Promise.allSettled(reports);
+                    const tried = [...(d.failed.get(d.eventId) ?? []), d.plan.id];
+                    if (rejected)
+                        d.log('warn', `claude: ${d.plan.label} — its token was rejected. Replace it on Integrations → Secrets.`);
+                    if (tried.length <= MAX_PLAN_SWITCHES) {
+                        d.failed.set(d.eventId, tried);
+                        throw new RetryOnAnotherPlan(`${d.plan.label} ${rejected ? 'rejected its token' : 'is at its limit'} — switching subscription and trying again`);
+                    }
+                }
+            }
+            d.failed.delete(d.eventId);
+        },
+    };
+}
+//# sourceMappingURL=plan-usage.js.map

package/dist/harness/plan-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-usage.js","sourceRoot":"","sources":["../../src/harness/plan-usage.ts"],"names":[],"mappings":"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"}

package/dist/harness/prompt.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What a turn is told: the prompt for an event, and the standing briefs for a lead and a manager.
+ * Split out of serve.ts (docs/spec-harness-profiles.md, step 2).
+ */
+import type { StreamEvent } from '../stream.js';
+import type { Profile } from '../profile.js';
+import { type AssistantPerson } from '../assistant.js';
+/**
+ * What the agent is actually asked.
+ *
+ * The event's own one-line rendering is the instruction — it already says what happened and to
+ * whom — with only enough added to make clear that acting is expected and that stopping quietly
+ * is not an option.
+ */
+/** What a pull request should target — the repo's own default, not a guess. */
+/**
+ * A few words for the pane from a needs-human reason: its first sentence, without a leading
+ * "1." — a reason written as a numbered list was shown as "waiting on a person (1)".
+ */
+export declare function parkLabel(reason: string): string;
+export declare const LEAD_SWEEP_GOAL: string;
+/**
+ * What a manager is told on every turn, on top of its own description in FlareDeck.
+ *
+ * It says what this harness gives a manager TODAY and, as plainly, what it does not yet stop:
+ * the approval, heads-up and escalation steps of docs/spec-manager-role.md are not built, so the
+ * limits below are instructions rather than guards. They come out as each guard goes in.
+ */
+export declare const MANAGER_BRIEF: string;
+/** A manager's regular check is of its TEAMS, not of cards assigned to it. */
+export declare const MANAGER_SWEEP_BRIEF: string;
+/** For a lead handed a card in a folder with no code of its own. See leadWithoutCode. */
+/** For an agent whose profile does not change code (an analyst): what its work is instead. */
+export declare const READ_ONLY_BRIEF: string;
+export declare const LEAD_WITHOUT_CODE_BRIEF: string;
+/**
+ * An event that waited behind other work says so. Norm (15 Oct): "by the time I act, the thing has
+ * often already been done" — it re-checked everything before every action, not knowing which
+ * events were fresh. Only past a few minutes; a fresh one needs no warning.
+ */
+export declare function waitedNote(event: Pick<StreamEvent, 'receivedAt'>, now?: number): string;
+/** A card assigned to a lead in a lane where work has not started: the lead hands it out. */
+export declare function isLeadDispatch(event: Pick<StreamEvent, 'event' | 'laneName'>, isLead: boolean): boolean;
+export declare function prompt(event: StreamEvent, isLead?: boolean): string;
+/**
+ * The parts of a turn's brief that depend on what kind of agent this is, by feature: a lead's
+ * (a worker free, a card with no code here), a manager's, a chat with one person, and one that
+ * does not change code. In this order, after the card's own brief.
+ */
+export declare function roleBriefs(p: Profile, o: {
+    event: StreamEvent;
+    /** This turn is the conversation with the agent's person (not a card it works). */
+    chat: boolean;
+    person: AssistantPerson | null;
+    /** A lead handed a card to build, with no code here: its job is to pass it on. */
+    leadWithoutCode: boolean;
+    /** The card in progress this event waits behind, if any. */
+    queuedBehind: string;
+}): string;