crewly 1.20.195 → 1.20.196

package/dist/backend/backend/src/services/project-tickets/ticket-autopilot.service.js

@@ -20,7 +20,7 @@
  * @module services/project-tickets/ticket-autopilot.service
  */
 import * as path from 'path';
-import { TICKET_AUTOPILOT_CONSTANTS, USAGE_CONSTANTS } from '../../constants.js';
+import { ORCHESTRATOR_SESSION_NAME, TICKET_AUTOPILOT_CONSTANTS, USAGE_CONSTANTS } from '../../constants.js';
 import { LoggerService } from '../core/logger.service.js';
 import { atomicWriteJson, safeReadJson } from '../../utils/file-io.utils.js';
 import { createWorkItem, MAX_BRIEF_MARKDOWN_BYTES } from '../../types/v2/work-item.types.js';
@@ -30,6 +30,20 @@ import { getTeamLeads } from '../../utils/team.utils.js';
 import { isTeamLead, } from './project-ticket-workflow.service.js';
 import { OPEN_TICKET_STATUSES, decideDigest, decideTriage, hasNeedsOwnerLabel, inFlightByAssignee, isMemberIdle, localDateKey, memberAvailability, memberResponsibility, localMidnight, selectTriageCandidates, } from './ticket-autopilot-decision.js';
 import { buildBudgetPausedMessage, buildDigestMessage, buildTriageBrief, } from './ticket-autopilot-messages.js';
+import { autopilotRunTrace, startTriageTrace, traceAutopilotAction, createAutopilotTicketListener } from './ticket-autopilot-trace.js';
+import { computeAutopilotStats, dayEndMs, daysBetween, dayStartMs, rangeDays, } from './ticket-autopilot-stats.js';
+import { buildRetroBrief, duplicateOf, renderRetroMarkdown, RetroInputError, validateRetroInput, } from './ticket-autopilot-retro.js';
+import { getTraceStore } from '../trace/trace-store.js';
+import { clampStallMinutes, defaultStallMinutes } from '../trace/trace-metrics.js';
+/** Skip reasons in words (run trace). */
+const SKIP_WORDS = {
+    no_driver: 'no team lead to drive it',
+    budget_reached: 'daily budget reached',
+    triage_in_flight: 'a triage is still open',
+    nothing_to_triage: 'nothing to triage',
+    nobody_idle: 'nobody on the team is idle',
+    too_soon: 'too soon after the last triage',
+};
 /** WorkItem statuses that keep a triage "live" (one per project). */
 const LIVE_STATUSES = new Set([
     'queued',
@@ -59,6 +73,10 @@ export class TicketAutopilotService {
     timer = null;
     /** Serialises evaluations so an idle event and the tick never create two triages */
     chain = Promise.resolve();
+    /** Unsubscribe of the ticket-change tracing listener */
+    unlisten = null;
+    /** Serialises retro submissions */
+    retroChain = Promise.resolve();
     /**
      * @param deps - Stores, pool, ledger, owner notifier, state file, clock
      */
@@ -93,6 +111,11 @@ export class TicketAutopilotService {
      */
     start(intervalMs = TICKET_AUTOPILOT_CONSTANTS.TICK_INTERVAL_MS) {
         this.deps.workflow.setAutopilotPolicy?.(this.policy());
+        // Ticket status / label changes go into the ticket's autopilot trace
+        // (specs/2026-10-03-autopilot-experiments.md §1).
+        if (!this.unlisten && this.deps.tickets.onChange) {
+            this.unlisten = this.deps.tickets.onChange(createAutopilotTicketListener(() => this.deps.directory.getProjects(), this.now));
+        }
         if (intervalMs > 0 && !this.timer) {
             this.timer = setInterval(() => {
                 void this.tick().catch((err) => this.logger.warn('Ticket autopilot tick failed (non-fatal)', { error: err instanceof Error ? err.message : String(err) }));
@@ -106,6 +129,8 @@ export class TicketAutopilotService {
             clearInterval(this.timer);
         this.timer = null;
         this.deps.workflow.setAutopilotPolicy?.(null);
+        this.unlisten?.();
+        this.unlisten = null;
     }
     /**
      * The brakes the ticket workflow asks about.
@@ -198,6 +223,7 @@ export class TicketAutopilotService {
             }
             if (projects.length > 0) {
                 await this.processDigest(projects).catch((err) => this.logger.warn('Ticket digest pass failed', { error: err instanceof Error ? err.message : String(err) }));
+                await this.processRetros(projects).catch((err) => this.logger.warn('Autopilot retro pass failed', { error: err instanceof Error ? err.message : String(err) }));
             }
             return out;
         });
@@ -255,6 +281,7 @@ export class TicketAutopilotService {
         const budget = this.budgetToday(settings, teams).tokens;
         if (settings.enabled && spent >= budget)
             await this.noticeBudgetPaused(project, ps, spent, budget, now, teams[0]?.name);
+        this.traceBudgetState(project, ps, settings.enabled && spent >= budget, spent, budget, now);
         const { tickets } = await this.deps.tickets.list(project.path);
         const live = await this.liveTriageItem(project, nowMs);
         const selection = selectTriageCandidates({ tickets, teams, now: nowMs, listed: ps.listed });
@@ -274,6 +301,8 @@ export class TicketAutopilotService {
         });
         if (decision.action === 'skip' || !driver) {
             this.logger.debug('Ticket autopilot: no triage', { projectId: project.id, trigger, decision });
+            if (decision.action === 'skip')
+                this.traceSkip(project, ps, decision.reason, trigger, selection.candidates.length, now);
             await this.saveState();
             return { projectId: project.id, decision };
         }
@@ -332,7 +361,14 @@ export class TicketAutopilotService {
         });
         workItem.createdAt = now.toISOString();
         workItem.targetSource = 'assigned';
+        // The triage turn runs in its own trace (tagged with the project and day),
+        // so its calls and usage never eat the run trace's event budget.
+        autopilotRunTrace(project, now);
+        const triageTrace = startTriageTrace(project, n, now);
+        if (triageTrace)
+            workItem.traceId = triageTrace;
         await this.deps.pool.addToPool(workItem);
+        this.traceTriage(project, ps, workItem, driver.session, trigger, selection.candidates.map((c) => c.ticket), now);
         ps.lastTriageAt = nowMs;
         ps.lastTriageWorkItemId = workItem.id;
         const listed = {};
@@ -454,6 +490,679 @@ export class TicketAutopilotService {
         }
     }
     // ---------------------------------------------------------------------------
+    // Tracing (specs/2026-10-03-autopilot-experiments.md §1)
+    // ---------------------------------------------------------------------------
+    /**
+     * Trace the budget brake turning on or off. A pause from an earlier day
+     * ends at that day's rollover (the budget resets at midnight).
+     *
+     * @param project - Project
+     * @param ps - Its bookkeeping
+     * @param paused - Over the budget now
+     * @param spent - Tokens used today
+     * @param budget - Today's budget
+     * @param now - Clock
+     */
+    traceBudgetState(project, ps, paused, spent, budget, now) {
+        const today = localDateKey(now);
+        if (ps.budgetPausedAt !== undefined) {
+            const fromEarlierDay = localDateKey(new Date(ps.budgetPausedAt)) !== today;
+            if (!paused || fromEarlierDay) {
+                traceAutopilotAction(project, 'budget_resumed', {
+                    summary: fromEarlierDay ? `${project.name}: the daily budget reset at midnight; the autopilot runs again` : `${project.name}: under the daily budget again (boost); the autopilot runs again`,
+                    outcome: 'ok',
+                    data: { reason: fromEarlierDay ? 'new_day' : 'boost', pausedSince: new Date(ps.budgetPausedAt).toISOString(), spentTokens: spent, budgetTokens: Number.isFinite(budget) ? budget : -1 },
+                    now,
+                });
+                delete ps.budgetPausedAt;
+            }
+        }
+        if (paused && ps.budgetPausedAt === undefined) {
+            ps.budgetPausedAt = now.getTime();
+            traceAutopilotAction(project, 'budget_paused', {
+                summary: `${project.name}: daily budget reached (${spent} of ${budget} tokens); no triage or auto-claim until it resets`,
+                outcome: 'blocked',
+                data: { spentTokens: spent, budgetTokens: budget },
+                now,
+            });
+        }
+    }
+    /**
+     * Trace a skipped evaluation, once per reason change per day (the tick
+     * runs every few minutes and must not flood the run trace).
+     *
+     * @param project - Project
+     * @param ps - Its bookkeeping
+     * @param reason - Why no triage
+     * @param trigger - Tick or idle member
+     * @param candidates - Tickets that would be triaged
+     * @param now - Clock
+     */
+    traceSkip(project, ps, reason, trigger, candidates, now) {
+        if (reason === 'off')
+            return;
+        const day = localDateKey(now);
+        const seen = ps.skips?.day === day ? ps.skips.reasons : [];
+        if (seen.includes(reason))
+            return;
+        // A skip alone never starts the day's run trace: a day with nothing but
+        // skips is not an autopilot run (and gets no retro).
+        const run = traceAutopilotAction(project, 'skip', {
+            summary: `${project.name}: no triage — ${SKIP_WORDS[reason] ?? reason}`,
+            outcome: 'skipped',
+            data: { reason, trigger, candidates },
+            create: false,
+            now,
+        });
+        if (run)
+            ps.skips = { day, reasons: [...seen, reason] };
+    }
+    /**
+     * Trace a triage: the step, and each ticket listed for the first time today.
+     *
+     * @param project - Project
+     * @param ps - Its bookkeeping
+     * @param workItem - The triage item
+     * @param driver - Who triages
+     * @param trigger - Tick or idle member
+     * @param tickets - Tickets listed
+     * @param now - Clock
+     */
+    traceTriage(project, ps, workItem, driver, trigger, tickets, now) {
+        traceAutopilotAction(project, 'triage', {
+            summary: `${project.name}: ${driver} woken to triage ${tickets.length} ticket${tickets.length === 1 ? '' : 's'}`,
+            outcome: 'queued',
+            workItemId: workItem.id,
+            session: driver,
+            data: { trigger, count: tickets.length, tickets: tickets.map((t) => t.id).join(',') },
+            alsoTraceId: workItem.traceId ?? null,
+            now,
+        });
+        const day = localDateKey(now);
+        const seen = new Set(ps.triaged?.day === day ? ps.triaged.ids : []);
+        for (const t of tickets) {
+            if (seen.has(t.id))
+                continue;
+            seen.add(t.id);
+            traceAutopilotAction(project, 'triage_ticket', {
+                summary: `${t.id} listed for triage: ${t.title}`,
+                ticketId: t.id,
+                session: driver,
+                data: { status: t.status, priority: t.priority, labels: t.labels.join(',') },
+                now,
+            });
+        }
+        ps.triaged = { day, ids: [...seen] };
+    }
+    // ---------------------------------------------------------------------------
+    // Stats and runs (specs/2026-10-03-autopilot-experiments.md §2)
+    // ---------------------------------------------------------------------------
+    /**
+     * Stats of a project over the last `days` days (today included).
+     *
+     * @param ref - Project id, name or path
+     * @param caller - Owner, orchestrator or a lead of a project team
+     * @param opts - days (1..STATS_MAX_DAYS), label, stallMinutes
+     * @returns Stats, with the project and its settings
+     * @throws ProjectTicketError(400/403/404)
+     */
+    async getStats(ref, caller, opts = {}) {
+        const project = await this.deps.workflow.resolveProject(ref);
+        await this.requireReader(caller, project);
+        const days = this.daysParam(opts.days);
+        const range = rangeDays(this.now(), days);
+        const stats = await this.statsFor(project, range[0], range[range.length - 1], opts.label ?? null, opts.stallMinutes);
+        const status = await this.statusOf(project);
+        return { ...stats, project: { id: project.id, name: project.name }, settings: status.settings, pausedForToday: status.pausedForToday };
+    }
+    /**
+     * Stats of a project between two local days (no access check: experiments
+     * and the retro call it).
+     *
+     * @param projectRef - Project id, name or path
+     * @param start - First day (YYYY-MM-DD)
+     * @param end - Last day (YYYY-MM-DD)
+     * @param label - Only tickets with this label
+     * @param stallMinutes - Stall threshold
+     * @returns Stats
+     */
+    async statsBetween(projectRef, start, end, label = null, stallMinutes) {
+        const project = await this.deps.workflow.resolveProject(projectRef);
+        return this.statsFor(project, start, end, label, stallMinutes);
+    }
+    /**
+     * Stats of a project over a range of days.
+     *
+     * @param project - Project
+     * @param start - First day
+     * @param end - Last day
+     * @param label - Label filter
+     * @param stallMinutes - Stall threshold
+     * @returns Stats
+     */
+    async statsFor(project, start, end, label, stallMinutes) {
+        const reader = this.traceReader();
+        const minutes = clampStallMinutes(stallMinutes ?? defaultStallMinutes());
+        const days = daysBetween(start, end);
+        const since = new Date(dayStartMs(start));
+        const until = dayEndMs(end);
+        // listTagged throws when the index cannot be read: a read failure is
+        // never reported as a range without autopilot work.
+        const entries = reader.listTagged({ autopilotProjectId: project.id, since }).filter((e) => Date.parse(e.root.createdAt) < until);
+        const traces = [];
+        let unreadable = 0;
+        for (const entry of entries) {
+            try {
+                const full = await reader.readAll(entry.traceId);
+                if (!full) {
+                    unreadable += 1;
+                    continue;
+                }
+                // Metrics are computed per day by the stats (event times, every stall).
+                traces.push({ entry: { ...entry, root: full.root ?? entry.root }, events: full.events });
+            }
+            catch {
+                unreadable += 1;
+            }
+        }
+        const settings = resolveTicketAutopilotSettings(project.ticketAutopilot);
+        const teams = await this.projectTeams(project);
+        return computeAutopilotStats({
+            projectId: project.id,
+            label,
+            days,
+            traces,
+            ledger: this.ledgerByDay(teams, days),
+            dailyBudgetTokens: settings.dailyBudgetTokens,
+            stallMinutes: minutes,
+            now: this.now(),
+            unreadable,
+        });
+    }
+    /**
+     * Run traces and ticket traces of the last `days` days, newest day first.
+     *
+     * @param ref - Project id, name or path
+     * @param caller - Owner, orchestrator or a lead of a project team
+     * @param opts - days, label
+     * @returns Days with their traces
+     */
+    async getRuns(ref, caller, opts = {}) {
+        const project = await this.deps.workflow.resolveProject(ref);
+        await this.requireReader(caller, project);
+        const range = rangeDays(this.now(), this.daysParam(opts.days));
+        const wanted = new Set(range);
+        const entries = this.traceReader().listTagged({ autopilotProjectId: project.id, since: new Date(dayStartMs(range[0])) });
+        const label = opts.label?.trim().toLowerCase();
+        const byDay = new Map(range.map((d) => [d, { day: d, runTraceId: null, traces: [] }]));
+        for (const e of entries) {
+            const day = e.tags?.autopilot?.day;
+            if (!day || !wanted.has(day))
+                continue;
+            const row = byDay.get(day);
+            if (e.root.kind === 'autopilot') {
+                row.runTraceId = e.traceId;
+                continue;
+            }
+            const labels = e.tags?.labels ?? [];
+            if (label && !labels.some((l) => l.toLowerCase() === label))
+                continue;
+            row.traces.push({
+                traceId: e.traceId,
+                kind: e.root.kind,
+                summary: e.root.summary,
+                ...(e.root.refs.ticketId ? { ticketId: e.root.refs.ticketId } : {}),
+                labels,
+                updatedAt: e.updatedAt,
+            });
+        }
+        return { project: { id: project.id, name: project.name }, days: [...byDay.values()].reverse() };
+    }
+    /**
+     * `?days=` within bounds.
+     *
+     * @param days - Requested
+     * @returns 1..STATS_MAX_DAYS (default STATS_DEFAULT_DAYS)
+     */
+    daysParam(days) {
+        const C = TICKET_AUTOPILOT_CONSTANTS;
+        if (days === undefined || !Number.isFinite(days))
+            return C.STATS_DEFAULT_DAYS;
+        const n = Math.floor(days);
+        if (n < 1 || n > C.STATS_MAX_DAYS)
+            throw new ProjectTicketError(400, `days must be 1 to ${C.STATS_MAX_DAYS}`);
+        return n;
+    }
+    /**
+     * The ledger of the project's team sessions per day (what the budget counts).
+     *
+     * @param teams - Project teams
+     * @param days - Day keys
+     * @returns Tokens and USD per day
+     */
+    ledgerByDay(teams, days) {
+        const sessions = new Set(teams.flatMap((t) => (t.members ?? []).map(sessionOf)).filter((x) => !!x));
+        const out = {};
+        for (const day of days) {
+            const since = new Date(dayStartMs(day));
+            const until = new Date(dayEndMs(day) - 1);
+            let tokens = 0;
+            let costUsd = 0;
+            for (const s of sessions) {
+                try {
+                    const u = this.deps.ledger.getSessionUsageSince(s, since, until);
+                    tokens += u.totalTokens;
+                    costUsd += u.cost ?? 0;
+                }
+                catch {
+                    // A ledger read failure leaves the day's number short, never fails the stats.
+                }
+            }
+            out[day] = { tokens, costUsd };
+        }
+        return out;
+    }
+    /**
+     * The trace reader (injected, else the process store + analysis).
+     *
+     * @returns Reader
+     */
+    traceReader() {
+        if (this.deps.traces)
+            return this.deps.traces;
+        return {
+            listTagged: (filter) => getTraceStore().listTagged(filter),
+            readAll: (id) => getTraceStore().readAll(id),
+        };
+    }
+    /**
+     * Whether an agent may read a project's autopilot traces: anyone on a team
+     * that works on the project (the rule decision cards use for tickets).
+     * The owner and the orchestrator are let through without a lookup.
+     *
+     * @param projectRef - Project id, name or path
+     * @param caller - Caller
+     * @returns True when allowed (false for an unknown project)
+     */
+    async canReadProjectTraces(projectRef, caller) {
+        if (!caller.session || caller.session === ORCHESTRATOR_SESSION_NAME)
+            return true;
+        let project;
+        try {
+            project = await this.deps.workflow.resolveProject(projectRef);
+        }
+        catch {
+            return false;
+        }
+        const { access } = await this.deps.workflow.accessOf(caller, project);
+        return access !== 'outsider';
+    }
+    /**
+     * Owner, orchestrator, or a lead of a project team (the driver).
+     *
+     * @param caller - Caller
+     * @param project - Project
+     * @throws ProjectTicketError(403)
+     */
+    async requireReader(caller, project) {
+        const { access } = await this.deps.workflow.accessOf(caller, project);
+        if (access !== 'owner' && access !== 'orchestrator' && access !== 'lead') {
+            throw new ProjectTicketError(403, 'Only the owner, the orchestrator or a team lead of the project can read its autopilot stats');
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Daily retro (specs/2026-10-03-autopilot-experiments.md §4)
+    // ---------------------------------------------------------------------------
+    /**
+     * Whether the daily retro runs for a project: its setting, else on while
+     * an autopilot experiment on the project is running.
+     *
+     * @param project - Project
+     * @returns True when on
+     */
+    async retroOn(project) {
+        const setting = resolveTicketAutopilotSettings(project.ticketAutopilot).retro;
+        if (setting !== null)
+            return setting;
+        if (!this.deps.runningExperiment)
+            return false;
+        return this.deps.runningExperiment(project.id).catch(() => false);
+    }
+    /**
+     * Schedule yesterday's retro for every enabled project that wants one
+     * (once per project per day, at or after RETRO_HOUR_LOCAL).
+     *
+     * @param projects - Enabled projects
+     * @returns WorkItems created
+     */
+    async processRetros(projects) {
+        if (!this.deps.retro)
+            return [];
+        const now = this.now();
+        if (now.getHours() < TICKET_AUTOPILOT_CONSTANTS.RETRO_HOUR_LOCAL)
+            return [];
+        const yesterday = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1, 12);
+        const day = localDateKey(yesterday);
+        const state = await this.loadState();
+        const out = [];
+        let items = null;
+        for (const project of projects) {
+            const ps = (state.projects[project.id] ??= {});
+            if (ps.retroScheduledFor === day)
+                continue;
+            if (ps.retroRetryAt && now.getTime() < ps.retroRetryAt)
+                continue;
+            if (!(await this.retroOn(project)))
+                continue;
+            const runTrace = autopilotRunTrace(project, yesterday, false);
+            if (!runTrace) {
+                // The autopilot did nothing that day: nothing to review.
+                ps.retroScheduledFor = day;
+                continue;
+            }
+            const teams = await this.projectTeams(project);
+            const driver = this.resolveDriver(resolveTicketAutopilotSettings(project.ticketAutopilot), teams);
+            if (!driver)
+                continue;
+            // Unreadable traces: try again on a later tick rather than judge the day.
+            const stats = await this.statsFor(project, day, day, null).catch(() => null);
+            const dayStats = stats?.days[0];
+            if (!stats || !dayStats || stats.incomplete) {
+                // Back off while the reads keep failing (doubling, capped).
+                ps.retroFailures = (ps.retroFailures ?? 0) + 1;
+                ps.retroRetryAt = now.getTime() + retryBackoffMs(ps.retroFailures);
+                continue;
+            }
+            delete ps.retroFailures;
+            delete ps.retroRetryAt;
+            ps.retroScheduledFor = day;
+            // Only a day with real autopilot work gets a retro (skips and budget
+            // notices alone are not a run).
+            if (dayStats.triaged + dayStats.started + dayStats.done + dayStats.verified === 0) {
+                this.logger.debug('Autopilot retro skipped: no autopilot work that day', { projectId: project.id, day });
+                continue;
+            }
+            items ??= await this.deps.pool.getAllItems();
+            const live = items.some((wi) => wi.metadata?.kind === TICKET_AUTOPILOT_CONSTANTS.RETRO_METADATA_KIND && wi.metadata?.projectId === project.id && LIVE_STATUSES.has(wi.status));
+            if (live) {
+                this.logger.info('Autopilot retro skipped: the previous one is still open', { projectId: project.id, day });
+                continue;
+            }
+            const runs = this.traceReader()
+                .listTagged({ autopilotProjectId: project.id, day })
+                .filter((e) => e.root.kind !== 'autopilot' && e.root.kind !== 'triage')
+                .slice(0, 25)
+                .map((e) => ({ traceId: e.traceId, title: e.root.summary }));
+            const brief = buildRetroBrief({ project: { id: project.id, name: project.name }, day, stats: dayStats, traces: [{ traceId: runTrace, title: `Run trace ${day}` }, ...runs] });
+            const workItem = createWorkItem({
+                type: TICKET_AUTOPILOT_CONSTANTS.RETRO_WORK_ITEM_TYPE,
+                owner: 'team_lead',
+                target: driver.session,
+                title: `Autopilot retro: ${project.name} ${day}`,
+                description: `Review the ${day} autopilot run of ${project.name}: what shipped, where it stalled and why; classify each problem and submit the retro.`,
+                briefMarkdown: capBrief(brief),
+                metadata: {
+                    kind: TICKET_AUTOPILOT_CONSTANTS.RETRO_METADATA_KIND,
+                    projectId: project.id,
+                    projectPath: project.path,
+                    teamId: driver.teamId,
+                    day,
+                    requiresVerification: false,
+                },
+            });
+            workItem.createdAt = now.toISOString();
+            workItem.targetSource = 'assigned';
+            workItem.traceId = runTrace;
+            await this.deps.pool.addToPool(workItem);
+            ps.retroWorkItemId = workItem.id;
+            traceAutopilotAction(project, 'retro_scheduled', {
+                summary: `${driver.session} asked for the ${day} retro of ${project.name}`,
+                outcome: 'queued',
+                workItemId: workItem.id,
+                session: driver.session,
+                data: { day },
+                // Recorded in the reviewed day's run only: scheduling never starts today's run trace.
+                runTraceId: runTrace,
+                now,
+            });
+            this.logger.info('Autopilot retro scheduled', { projectId: project.id, day, driver: driver.session, workItemId: workItem.id });
+            out.push(workItem);
+        }
+        await this.saveState();
+        return out;
+    }
+    /**
+     * A retro came in: write it to the project wiki, file the harness gaps on
+     * the Crewly project (deduped, capped) and ask the owner ONE card for them.
+     *
+     * @param ref - Project id, name or path
+     * @param body - `{day, summary, problems}`
+     * @param caller - Owner, orchestrator or a lead of a project team
+     * @returns What was written and filed
+     * @throws ProjectTicketError(400/403/404/503)
+     */
+    async submitRetro(ref, body, caller) {
+        // One retro at a time: the gap dedupe and the daily cap read and write the same state.
+        const run = this.retroChain.then(() => this.submitRetroNow(ref, body, caller), () => this.submitRetroNow(ref, body, caller));
+        this.retroChain = run.catch(() => undefined);
+        return run;
+    }
+    /**
+     * {@link submitRetro}, serialised.
+     *
+     * @param ref - Project
+     * @param body - Retro
+     * @param caller - Caller
+     * @returns What was written and filed
+     */
+    async submitRetroNow(ref, body, caller) {
+        const project = await this.deps.workflow.resolveProject(ref);
+        await this.requireReader(caller, project);
+        const retroDeps = this.deps.retro;
+        if (!retroDeps)
+            throw new ProjectTicketError(503, 'Retros are not available (the autopilot is not fully started)');
+        let retro;
+        try {
+            retro = validateRetroInput(body);
+        }
+        catch (err) {
+            if (err instanceof RetroInputError)
+                throw new ProjectTicketError(400, err.message);
+            throw err;
+        }
+        const by = caller.session ?? 'owner';
+        const now = this.now();
+        if (retro.day > localDateKey(now))
+            throw new ProjectTicketError(400, `day ${retro.day} is in the future`);
+        const stats = await this.statsFor(project, retro.day, retro.day, null).catch(() => null);
+        const runTrace = autopilotRunTrace(project, new Date(dayStartMs(retro.day) + 12 * 3_600_000), false);
+        const filed = await this.fileHarnessGaps(project, retro, retroDeps, now);
+        const wikiPath = `${TICKET_AUTOPILOT_CONSTANTS.RETRO_WIKI_DIR}/${retro.day}.md`;
+        const markdown = renderRetroMarkdown({ project, retro, stats: stats?.days[0] ?? null, by, filed: filed.filed, runTraceId: runTrace });
+        const written = await retroDeps.writeWiki(project.path, wikiPath, markdown, by).catch((err) => {
+            this.logger.warn('Could not write the autopilot retro to the wiki', { projectId: project.id, error: err instanceof Error ? err.message : String(err) });
+            return false;
+        });
+        const counts = {};
+        for (const p of retro.problems)
+            counts[p.class] = (counts[p.class] ?? 0) + 1;
+        traceAutopilotAction(project, 'retro_filed', {
+            summary: `${by} filed the ${retro.day} retro of ${project.name}: ${retro.problems.length} problem${retro.problems.length === 1 ? '' : 's'}, ${filed.filed.length} harness-gap ticket${filed.filed.length === 1 ? '' : 's'}`,
+            outcome: 'ok',
+            ...(caller.session ? { session: caller.session, actor: { kind: 'agent', session: caller.session } } : { actor: { kind: 'owner' } }),
+            data: { day: retro.day, wiki: written ? wikiPath : 'not written', ...counts, filed: filed.filed.length, duplicates: filed.duplicates.length, overCap: filed.overCap.length },
+            alsoTraceId: runTrace,
+            now,
+        });
+        this.logger.info('Autopilot retro filed', { projectId: project.id, day: retro.day, by, written, filed: filed.filed.map((t) => t.id) });
+        return { day: retro.day, wikiPath, written, ...filed };
+    }
+    /**
+     * File the retro's harness gaps on the Crewly project and ask the owner
+     * one card for them.
+     *
+     * @param project - The reviewed project
+     * @param retro - The retro
+     * @param retroDeps - Side effects
+     * @param now - Clock
+     * @returns Filed, duplicate and over-cap gaps, and the card
+     */
+    async fileHarnessGaps(project, retro, retroDeps, now) {
+        const C = TICKET_AUTOPILOT_CONSTANTS;
+        const gaps = retro.problems.filter((p) => p.class === 'harness_gap');
+        const out = { filed: [], duplicates: [], overCap: [], decisionId: null };
+        if (gaps.length === 0)
+            return out;
+        const target = await retroDeps.harnessProject();
+        if (!target) {
+            this.logger.warn('No harness project to file retro gaps on', { name: C.RETRO_HARNESS_PROJECT });
+            out.overCap = gaps.map((g) => g.title);
+            return out;
+        }
+        const state = await this.loadState();
+        const today = localDateKey(now);
+        const memory = now.getTime() - C.RETRO_GAP_MEMORY_DAYS * 24 * 3_600_000;
+        state.retro.gaps = state.retro.gaps.filter((g) => g.at >= memory);
+        const { tickets } = await this.deps.tickets.list(target.path);
+        const known = [...tickets.filter((t) => t.status !== 'done' && t.status !== 'cancelled').map((t) => t.title), ...state.retro.gaps.map((g) => g.title)];
+        for (const gap of gaps) {
+            const dup = duplicateOf(gap.title, known);
+            if (dup) {
+                out.duplicates.push({ title: gap.title, duplicateOf: dup });
+                continue;
+            }
+            if ((state.retro.gapDays[today] ?? 0) >= C.RETRO_MAX_GAPS_PER_DAY) {
+                out.overCap.push(gap.title);
+                continue;
+            }
+            const description = [
+                `Found by the ${retro.day} autopilot retro of ${project.name}.`,
+                '',
+                gap.detail ?? '',
+                '',
+                gap.evidence ? `Evidence: ${gap.evidence}` : '',
+                `Retro: ${project.name} wiki, ${C.RETRO_WIKI_DIR}/${retro.day}.md`,
+            ]
+                .filter((l, i, all) => l !== '' || (i > 0 && all[i - 1] !== ''))
+                .join('\n')
+                .trim();
+            const ticket = await retroDeps.createTicket(target, {
+                title: gap.title,
+                description,
+                // Held until the owner approves: triage skips retro-pending tickets,
+                // and nothing but this retro's card lifts the hold.
+                labels: [...C.RETRO_GAP_LABELS, C.RETRO_PENDING_LABEL],
+                source: `retro:${project.name}:${retro.day}`,
+            });
+            out.filed.push({ id: ticket.id, title: ticket.title });
+            known.push(gap.title);
+            state.retro.gaps.push({ title: gap.title, at: now.getTime() });
+            state.retro.gapDays[today] = (state.retro.gapDays[today] ?? 0) + 1;
+            traceAutopilotAction(project, 'retro_gap_ticket', {
+                summary: `Harness gap filed on ${target.name} as ${ticket.id}: ${gap.title}`,
+                outcome: 'queued',
+                ticketId: ticket.id,
+                data: { day: retro.day, harnessProject: target.name },
+                now,
+            });
+        }
+        for (const d of Object.keys(state.retro.gapDays))
+            if (d < localDateKey(new Date(memory)))
+                delete state.retro.gapDays[d];
+        if (out.filed.length > 0) {
+            const n = out.filed.length;
+            try {
+                const decision = await retroDeps.askOwner({
+                    key: `retro:${project.id}:${retro.day}`,
+                    title: `Harness gaps from the ${project.name} retro (${retro.day})`,
+                    question: `File ${n === 1 ? 'this harness gap' : `these ${n} harness gaps`} for the ${target.name} team?`,
+                    body: out.filed.map((t) => `• *${t.id}* ${t.title}`),
+                    approveLabel: C.RETRO_APPROVE_LABEL,
+                    skipLabel: C.RETRO_SKIP_LABEL,
+                    deadline: new Date(now.getTime() + C.RETRO_DECISION_DEADLINE_MS),
+                });
+                out.decisionId = decision.id;
+                state.retro.decisions[decision.id] = { projectId: project.id, projectPath: target.path, ticketIds: out.filed.map((t) => t.id) };
+            }
+            catch (err) {
+                // No card, no approval: the tickets must not wait on a question nobody asked.
+                this.logger.warn('Could not ask the owner about the retro gaps; the tickets are cancelled', { error: err instanceof Error ? err.message : String(err) });
+                for (const t of out.filed) {
+                    await retroDeps
+                        .applyGapDecision(target.path, t.id, false, `the owner could not be asked (${err instanceof Error ? err.message : String(err)})`)
+                        .catch(() => 'left');
+                }
+                out.unasked = out.filed.map((t) => t.id);
+            }
+        }
+        await this.saveState();
+        return out;
+    }
+    /**
+     * Tell the lead of the harness project that the owner skipped a gap
+     * ticket someone already started (a `notify` WorkItem: the normal
+     * dispatch path, which also wakes a stopped lead).
+     *
+     * @param projectPath - Harness project root
+     * @param ticketId - The started ticket
+     * @param decisionId - The card
+     */
+    async tellGapLead(projectPath, ticketId, decisionId) {
+        const wanted = path.resolve(projectPath);
+        const project = (await this.deps.directory.getProjects()).find((p) => !!p.path && path.resolve(p.path) === wanted);
+        if (!project)
+            return;
+        const lead = this.resolveDriver(resolveTicketAutopilotSettings(project.ticketAutopilot), await this.projectTeams(project));
+        if (!lead)
+            return;
+        const wi = createWorkItem({
+            type: 'notify',
+            owner: 'team_lead',
+            target: lead.session,
+            title: `Owner skipped harness gap ${ticketId}`,
+            description: `The owner skipped harness-gap ticket ${ticketId} (decision ${decisionId}), but work on it has already started. Decide whether to stop it (cancel the ticket) or finish it, and note why on the ticket.`,
+            metadata: { projectId: project.id, projectPath: project.path, teamId: lead.teamId, ticketId, requiresVerification: false },
+        });
+        wi.createdAt = this.now().toISOString();
+        wi.targetSource = 'assigned';
+        await this.deps.pool.addToPool(wi);
+        this.logger.info('Told the lead about a skipped gap ticket already in progress', { ticketId, lead: lead.session });
+    }
+    /**
+     * The owner answered a retro-gaps card: Approve releases its tickets
+     * (needs-owner hold removed, `ready`); anything else (Skip, the default at
+     * the deadline, a withdrawn card) cancels those that have not started.
+     *
+     * @param decision - The settled decision
+     * @returns Nothing for an agent (no agent asked it)
+     */
+    async onRetroDecision(decision) {
+        if (!this.deps.retro)
+            return null;
+        const state = await this.loadState();
+        const entry = state.retro.decisions[decision.id];
+        if (!entry)
+            return null;
+        const approved = (decision.status === 'resolved' || decision.status === 'defaulted') &&
+            decision.options.find((o) => o.key === decision.chosenKey)?.label === TICKET_AUTOPILOT_CONSTANTS.RETRO_APPROVE_LABEL;
+        for (const id of entry.ticketIds) {
+            const note = approved ? `owner approved (decision ${decision.id})` : `owner did not approve (decision ${decision.id}, ${decision.status})`;
+            const outcome = await this.deps.retro
+                .applyGapDecision(entry.projectPath, id, approved, note)
+                .catch((err) => {
+                this.logger.warn('Could not apply the retro decision to a ticket', { id, error: err instanceof Error ? err.message : String(err) });
+                return null;
+            });
+            // Skipped, but someone already works on it: its lead decides what to do.
+            if (!approved && outcome === 'left')
+                await this.tellGapLead(entry.projectPath, id, decision.id).catch(() => undefined);
+        }
+        delete state.retro.decisions[decision.id];
+        await this.saveState();
+        this.logger.info('Retro harness gaps decided', { decisionId: decision.id, approved, tickets: entry.ticketIds });
+        return null;
+    }
+    // ---------------------------------------------------------------------------
     // Helpers
     // ---------------------------------------------------------------------------
     /**
@@ -480,6 +1189,7 @@ export class TicketAutopilotService {
             pausedForToday: settings.enabled && spent >= budget.tokens,
             triageInFlight: live,
             lastTriageAt: ps?.lastTriageAt ? new Date(ps.lastTriageAt).toISOString() : null,
+            retroOn: await this.retroOn(project),
         };
     }
     /**
@@ -648,6 +1358,11 @@ export class TicketAutopilotService {
             projects: raw.projects && typeof raw.projects === 'object' ? raw.projects : {},
             questions: { lastSentAt: raw.questions?.lastSentAt, sentKeys: Array.isArray(sentKeys) ? sentKeys : [] },
             digest: raw.digest && typeof raw.digest === 'object' ? raw.digest : {},
+            retro: {
+                gapDays: raw.retro?.gapDays && typeof raw.retro.gapDays === 'object' ? raw.retro.gapDays : {},
+                gaps: Array.isArray(raw.retro?.gaps) ? raw.retro.gaps : [],
+                decisions: raw.retro?.decisions && typeof raw.retro.decisions === 'object' ? raw.retro.decisions : {},
+            },
         };
         return this.state;
     }
@@ -663,6 +1378,16 @@ export class TicketAutopilotService {
         }
     }
 }
+/**
+ * Backoff after `failures` failed tries: RETRY_BACKOFF_MIN_MS doubling up to RETRY_BACKOFF_MAX_MS.
+ *
+ * @param failures - Failed tries so far (≥ 1)
+ * @returns Milliseconds
+ */
+export function retryBackoffMs(failures) {
+    const C = TICKET_AUTOPILOT_CONSTANTS;
+    return Math.min(C.RETRY_BACKOFF_MAX_MS, C.RETRY_BACKOFF_MIN_MS * 2 ** Math.max(0, failures - 1));
+}
 /**
  * Keep a brief within the WorkItem brief budget.
  *