agl 40.6.0 → 41.0.0

package/ts/driver/functions.drivertools.ts

@@ -125,7 +125,7 @@ export const driverToolDefinitions: readonly IDriverToolDefinition[] = [
   ...directReportToolDefinitions,
   {
     name: 'driver_notes_read',
-    description: 'Read your driver notes and their revision. The notes are also shown to you at the start of every run.',
+    description: 'Read your driver notes and their revision. Your context also shows them as the pinned context "driver-notes" whenever they changed and after a compaction; its latest revision is current.',
     inputSchema: plugins.z.object({}).strict(),
     readOnly: true,
     route: { kind: 'notes', operation: 'read' },
@@ -147,10 +147,24 @@ export const driverToolsByName: ReadonlyMap<string, IDriverToolDefinition> = new
   driverToolDefinitions.map((definitionArg) => [definitionArg.name, definitionArg]),
 );
 
-/** The section the driver's system prompt ends with: its instructions, then its notes. */
-export const composeDriverSystem = (instructionsArg: string, notesArg: string): string => [
-  instructionsArg.trim(),
-  notesArg.trim()
-    ? `## Your driver notes\n\nAs you last saved them with driver_notes_update:\n\n${notesArg.trim()}`
-    : '## Your driver notes\n\nEmpty. Save your working state with driver_notes_update.',
-].join('\n\n');
+/** The id of the pinned context that carries the driver's notes. */
+export const driverNotesContextId = 'driver-notes';
+
+/**
+ * The driver's notes as a FlexHarness pinned context, outside its system prompt: the model sees a
+ * revision once, when it is new and again after a compaction, and a new revision leaves the system
+ * prompt, the tools and the history in front of it as they were, so the cached prefix survives it.
+ * `revisionArg` is the revision of the session scratchpad that holds the notes, which every saved
+ * text moves; never the FlexHarness project revision. Empty notes are pinned too, so a cleared
+ * text replaces the one saved before it.
+ */
+export const driverNotesContext = (
+  notesArg: string,
+  revisionArg: number,
+): plugins.flexharness.IFlexPinnedContext => ({
+  id: driverNotesContextId,
+  revision: revisionArg,
+  text: notesArg.trim()
+    ? `Your driver notes, as you last saved them with driver_notes_update:\n\n${notesArg.trim()}`
+    : 'Your driver notes are empty. Save your working state with driver_notes_update.',
+});

package/ts/fleet/classes.boardpump.ts

@@ -1,5 +1,6 @@
 import * as plugins from '../plugins.js';
-import type { ITicket, ITicketActivity, ITicketActor, ITicketComment, ITicketPerson, ITicketQuestion, TTicketColumn, TTicketResponse } from '../../ts_interfaces/tickets.js';
+import type { ITicket, ITicketActivity, ITicketActor, ITicketComment, ITicketPerson, ITicketQuestion, TTicketColumn } from '../../ts_interfaces/tickets.js';
+import type { ITicketHistory } from '../classes.ticketstore.js';
 import type { IFleetBoardPumpConfiguration, IFleetUnboundDriver } from '../../ts_interfaces/fleet.js';
 import type { IFleetEvent } from '../../ts_interfaces/fleetworkers.js';
 import type { IControllerFleetWorkerView } from '../../ts_interfaces/index.js';
@@ -17,7 +18,8 @@ export interface IBoardPumpHost {
   /** The fleet owner the pump acts for and its configuration; undefined while the configuration authority is unavailable. */
   scope(): Promise<{ owner: string; configuration?: IFleetBoardPumpConfiguration } | undefined>;
   tickets(): Promise<ITicket[]>;
-  ticket(ticketKeyArg: string): Promise<TTicketResponse<'get'>>;
+  /** One ticket with its whole history and questions; the pump asks only when the ticket's revision moved. */
+  history(ticketKeyArg: string): Promise<ITicketHistory>;
   workers(ownerArg: string): Promise<IControllerFleetWorkerView[]>;
   /** Steers the live worker bound to the native session `harness:nativeId`; rejects when the harness did not admit the text. */
   steer(sessionIdArg: string, ticketKeyArg: string, textArg: string): Promise<unknown>;
@@ -44,6 +46,18 @@ interface IBoardPumpStall {
   namesUnboundDrivers?: true;
 }
 
+/**
+ * What the pump decides on from one ticket revision: when the ticket entered its column, its questions, and the comment
+ * nobody followed. Every change to a ticket, its history or its questions moves its revision, so these hold while it does.
+ */
+interface IBoardPumpTicketFacts {
+  ticket: ITicket;
+  entered: { id: string; at: string };
+  questions: ITicketQuestion[];
+  /** The newest discussion entry when it is a comment by someone not in the driver role that nothing by the driver role or the assignee followed. */
+  unfollowed?: { actor: ITicketActor; comment: ITicketComment };
+}
+
 const watchedColumns = new Set<TTicketColumn>(['ready', 'in_progress', 'needs_input', 'landed']);
 /** The activity a ticket's discussion consists of: its comments and its questions. */
 const discussionActions = new Set<ITicketActivity['action']>(['commented', 'asked', 'answered']);
@@ -74,6 +88,16 @@ const clip = (textArg: string, maximumArg = 32 * 1024): string => {
   const characters = [...textArg];
   return characters.length > maximumArg ? `${characters.slice(0, maximumArg - 1).join('').trimEnd()}…` : textArg;
 };
+/** The facts of one history; see `IBoardPumpTicketFacts`. */
+const ticketFacts = ({ ticket, activity, questions }: ITicketHistory): IBoardPumpTicketFacts => {
+  const own = (entryArg: ITicketActivity) => entryArg.actor.id === boardPumpActor.id;
+  const index = activity.findLastIndex((entryArg) => discussionActions.has(entryArg.action) && !own(entryArg));
+  const entry = activity[index];
+  const comment = entry && entry.action === 'commented' && entry.actor.role !== 'driver' ? entry.changes.comment?.after as ITicketComment | undefined : undefined;
+  const followed = activity.slice(index + 1).some((laterArg) => !own(laterArg) && (laterArg.actor.role === 'driver' || isPerson(laterArg.actor, ticket.assignee)));
+  return { ticket, entered: enteredColumn(ticket, activity), questions,
+    ...(entry && comment && !followed ? { unfollowed: { actor: entry.actor, comment } } : {}) };
+};
 const answerText = (questionArg: ITicketQuestion): string => {
   const answer = questionArg.answer!;
   const chosen = answer.choices.map((choiceArg) => questionArg.options.find((optionArg) => optionArg.id === choiceArg)?.label ?? choiceArg);
@@ -100,6 +124,8 @@ export class BoardPump {
   private running?: Promise<void>;
   /** The configuration changed during a pass, so another pass follows at once with it. */
   private changed = false;
+  /** The facts of each ticket at the revision they were read at; a ticket gone from the board is forgotten. */
+  private readonly facts = new Map<string, IBoardPumpTicketFacts>();
 
   constructor(private readonly host: IBoardPumpHost, options: IBoardPumpOptions = {}) {
     this.now = options.now ?? Date.now;
@@ -140,6 +166,8 @@ export class BoardPump {
     const now = this.now();
     const tickets = (await this.host.tickets()).filter((ticketArg) => ticketArg.columnId !== 'released');
     const workers = tickets.length ? await this.host.workers(scope.owner) : [];
+    const listed = new Set(tickets.map((ticketArg) => ticketArg.key));
+    for (const key of this.facts.keys()) if (!listed.has(key)) this.facts.delete(key);
     const seen = new Set<string>();
     for (const ticket of tickets) {
       this.abort.signal.throwIfAborted();
@@ -174,16 +202,25 @@ export class BoardPump {
     const watched = watchedColumns.has(column) && !(column === 'in_progress' && (ticketArg.labels.includes(boardPumpWaitingLabel) || live.length > 0));
     const comments = column !== 'released' && !live.length;
     if (!watched && !comments) return [];
-    const detail = await this.host.ticket(ticketArg.key);
-    if (detail.ticket.columnId !== column) return [];
+    const facts = await this.factsOf(ticketArg);
+    if (facts.ticket.columnId !== column) return [];
     const stalls: IBoardPumpStall[] = [];
-    const stall = watched ? this.columnStall(detail, bound, live, landedAfterHoursArg, nowArg) : undefined;
+    const stall = watched ? this.columnStall(facts, bound, live, landedAfterHoursArg, nowArg) : undefined;
     if (stall) stalls.push(stall);
-    const comment = comments ? this.commentStall(detail, bound) : undefined;
+    const comment = comments ? this.commentStall(facts, bound) : undefined;
     if (comment) stalls.push(comment);
     return stalls;
   }
 
+  /** The ticket's facts, read again only when its revision is not the one they were read at. */
+  private async factsOf(ticketArg: ITicket): Promise<IBoardPumpTicketFacts> {
+    const known = this.facts.get(ticketArg.key);
+    if (known && known.ticket.revision === ticketArg.revision) return known;
+    const facts = ticketFacts(await this.host.history(ticketArg.key));
+    this.facts.set(ticketArg.key, facts);
+    return facts;
+  }
+
   private header(ticketArg: ITicket): string {
     return `${ticketArg.key} ${quoted(ticketArg.title)} (${ticketArg.project}${ticketArg.assignee ? `, assigned to ${quoted(ticketArg.assignee.name)}` : ', unassigned'})`;
   }
@@ -193,18 +230,13 @@ export class BoardPump {
    * by someone not in the driver role, nothing by the driver role or the assignee followed it, and no live fleet worker
    * holds the ticket. Its notice names the Claude Code jobs that look like drivers and that no worker binds.
    */
-  private commentStall({ ticket, activity }: TTicketResponse<'get'>, boundArg: IControllerFleetWorkerView[]): IBoardPumpStall | undefined {
-    const own = (entryArg: ITicketActivity) => entryArg.actor.id === boardPumpActor.id;
-    const index = activity.findLastIndex((entryArg) => discussionActions.has(entryArg.action) && !own(entryArg));
-    const entry = activity[index];
-    if (!entry || entry.action !== 'commented' || entry.actor.role === 'driver') return undefined;
-    const comment = entry.changes.comment?.after as ITicketComment | undefined;
-    if (!comment) return undefined;
-    if (activity.slice(index + 1).some((laterArg) => !own(laterArg) && (laterArg.actor.role === 'driver' || isPerson(laterArg.actor, ticket.assignee)))) return undefined;
+  private commentStall({ ticket, unfollowed }: IBoardPumpTicketFacts, boundArg: IControllerFleetWorkerView[]): IBoardPumpStall | undefined {
+    if (!unfollowed) return undefined;
+    const { actor, comment } = unfollowed;
     const text = comment.body.map((partArg) => partArg.type === 'text' ? partArg.text : `@${partArg.label}`).join('').trim();
     const last = boundArg.at(-1);
     return { ticket, column: ticket.columnId, key: `board-pump:${ticket.key}:comment:${comment.id}`, namesUnboundDrivers: true,
-      notice: `${this.header(ticket)} has a comment by ${quoted(entry.actor.name)} (${entry.actor.role}) from ${comment.createdAt} that nothing `
+      notice: `${this.header(ticket)} has a comment by ${quoted(actor.name)} (${actor.role}) from ${comment.createdAt} that nothing `
         + `by the driver role or the assignee followed, and no live fleet worker holds the ticket, so no session was told:\n\n`
         + `  ${clip(text, 2000).replaceAll(/\r?\n/gu, '\n  ')}\n\n`
         + (last ? `Its last worker is ${workerText(last)}; resume it with fleet_worker_steer (name ${quoted(last.worker.name)}, ticketKey ${ticket.key}). `
@@ -212,11 +244,10 @@ export class BoardPump {
         + 'Claude Code background jobs that look like drivers and that no fleet worker binds:' };
   }
 
-  private columnStall({ ticket, activity, questions }: TTicketResponse<'get'>, bound: IControllerFleetWorkerView[], live: IControllerFleetWorkerView[],
+  private columnStall({ ticket, entered, questions }: IBoardPumpTicketFacts, bound: IControllerFleetWorkerView[], live: IControllerFleetWorkerView[],
     landedAfterHoursArg: number, nowArg: number): IBoardPumpStall | undefined {
     const column = ticket.columnId;
     const assigned = ticket.assignee?.sessionId;
-    const entered = enteredColumn(ticket, activity);
     const header = this.header(ticket);
     const key = (stateArg: unknown[]) => `board-pump:${ticket.key}:${column}:${plugins.crypto.createHash('sha256')
       .update(JSON.stringify([entered.id, ...stateArg])).digest('hex').slice(0, 32)}`;
@@ -292,10 +323,11 @@ export class BoardPump {
   private async apply(ownerArg: string, docArg: IFleetTicketEffectDocument, kindArg: 'ticket.notified' | 'ticket.stalled',
     stallArg: IBoardPumpStall): Promise<boolean> {
     if (docArg.state === 'applied') return true;
-    const effect = await this.host.effects.dispatch(docArg, this.abort.signal);
+    const { effect, commentId } = await this.host.effects.dispatch(docArg, this.abort.signal);
     if (effect.state !== 'applied') return false;
     const text = docArg.request.kind === 'comment' && typeof docArg.request.body === 'string' ? docArg.request.body : stallArg.notice;
-    this.host.publish({ kind: kindArg, ticketKey: stallArg.ticket.key, status: stallArg.column, text,
+    // The notice is its comment, so the event names it: the driver reads it whole with ticket_get and commentId.
+    this.host.publish({ kind: kindArg, ticketKey: stallArg.ticket.key, status: stallArg.column, text, ...(commentId ? { commentId } : {}),
       ...(kindArg === 'ticket.notified' && stallArg.delivery ? { sessionId: stallArg.delivery.sessionId, workerName: stallArg.delivery.worker.worker.name } : {}) },
     ownerArg);
     return true;

package/ts/fleet/classes.ticketeffects.ts

@@ -32,6 +32,14 @@ export class FleetTicketEffectModel extends plugins.nosqldb.SmartDataDbDoc<Fleet
   @plugins.nosqldb.svDb() public origin?: string;
 }
 
+/**
+ * A dispatched effect and, when the board wrote or replayed a comment for it, that comment's id. The id is a return
+ * value only: neither the effect record nor `IFleetTicketSync` stores it.
+ */
+export interface IFleetTicketDispatch { effect: IFleetTicketEffect; commentId?: string }
+/** A report's ticket sync and the id of the comment that holds the report, when the board wrote it. */
+export interface IFleetTicketReport { sync: IFleetTicketSync; commentId?: string }
+
 /** Owns exact requests; the ticket board owns effects and atomic idempotency receipts. */
 export class FleetTicketEffects {
   constructor(private readonly apply: (event: TTicketFleetEvent, signal?: AbortSignal, origin?: string) => Promise<ITicketFleetEventResult>) {}
@@ -93,16 +101,20 @@ export class FleetTicketEffects {
     if (observed && (observed.updateId === updateId || observed.state === 'applied')) return this.publicEffect(FleetTicketEffectModel.exact.toPersisted(observed));
     throw new Error('Fleet ticket confirmation outcome is unresolved; reconcile its saved request/key.');
   }
-  public async dispatch(doc: IFleetTicketEffectDocument, signal?: AbortSignal): Promise<IFleetTicketEffect> {
+  /** Applies the saved request; a comment the board returned (a replay returns the stored one) is named by its id. */
+  public async dispatch(doc: IFleetTicketEffectDocument, signal?: AbortSignal): Promise<IFleetTicketDispatch> {
+    let commentId: string | undefined;
+    const named = (effect: IFleetTicketEffect): IFleetTicketDispatch => ({ effect, ...(commentId ? { commentId } : {}) });
     try {
       // Even confirmed replays use the durable board receipt, never a local dedupe cache.
       const result = await this.apply(structuredClone(doc.request), signal, doc.origin);
-      return await this.mark(doc, 'applied', result.revision);
+      commentId = result.comment?.id;
+      return named(await this.mark(doc, 'applied', result.revision));
     } catch (error) {
       const state = error instanceof TicketError && error.code !== 'outcome_unknown' ? 'failed' : 'unknown';
       const message = error instanceof Error ? error.message.slice(0, 4096) : 'Fleet ticket application outcome is unknown.';
-      try { return await this.mark(doc, state, undefined, message); }
-      catch { return { eventKey: doc.id, ticketKey: doc.request.ticketKey, state: 'unknown', error: 'Fleet ticket confirmation was not saved; reconcile the exact event key.' }; }
+      try { return named(await this.mark(doc, state, undefined, message)); }
+      catch { return named({ eventKey: doc.id, ticketKey: doc.request.ticketKey, state: 'unknown', error: 'Fleet ticket confirmation was not saved; reconcile the exact event key.' }); }
     }
   }
   public summary(effects: IFleetTicketEffect[]): IFleetTicketSync {
@@ -117,7 +129,7 @@ export class FleetTicketEffects {
     if (records.length > 512) throw new Error('Too many fleet ticket effects; reconcile an exact event key.');
     if (eventKey && !records.length) throw new Error('Fleet event is unavailable for this owner and ticket.');
     const effects: IFleetTicketEffect[] = [];
-    for (const record of records) effects.push(await this.dispatch(FleetTicketEffectModel.exact.toPersisted(record), signal));
+    for (const record of records) effects.push((await this.dispatch(FleetTicketEffectModel.exact.toPersisted(record), signal)).effect);
     return this.summary(effects);
   }
   public async operation(owner: string, ticketKey: string, actor: ITicketActor, operationId: string, result: IFleetLandResult | IFleetReleaseResult | IFleetToolingResult, signal?: AbortSignal): Promise<IFleetTicketSync> {
@@ -133,22 +145,24 @@ export class FleetTicketEffects {
     // Save the entire release set before any ticket application.
     for (const event of events) prepared.push(await this.prepare(owner, event));
     const effects: IFleetTicketEffect[] = [];
-    for (const event of prepared) effects.push(await this.dispatch(event, signal));
+    for (const event of prepared) effects.push((await this.dispatch(event, signal)).effect);
     return this.summary(effects);
   }
-  public async report(owner: string, ticketKey: string, actor: ITicketActor, worker: { name: string; harness: string; nativeId?: string }, report: { reportId?: string; text: string; truncated: boolean }, signal?: AbortSignal): Promise<IFleetTicketSync> {
+  /** Comments a worker's report on its ticket; the result names the comment that holds it. */
+  public async report(owner: string, ticketKey: string, actor: ITicketActor, worker: { name: string; harness: string; nativeId?: string }, report: { reportId?: string; text: string; truncated: boolean }, signal?: AbortSignal): Promise<IFleetTicketReport> {
     if (!worker.nativeId || !report.reportId || !report.text.trim()) throw new Error('A report comment requires proven native session and report identities.');
     const body = `Fleet report from ${worker.name} (${worker.harness}:${worker.nativeId}), report ${report.reportId}${report.truncated ? ' (truncated)' : ''}:\n\n${report.text}`;
     const identity = plugins.crypto.createHash('sha256').update(JSON.stringify([owner, ticketKey, worker.harness, worker.nativeId, report.reportId, body])).digest('hex');
     const event: TTicketFleetEvent = { ticketKey, actor: this.actor(actor), kind: 'comment', body, idempotencyKey: `fleet:report:${identity}` };
-    return this.summary([await this.dispatch(await this.prepare(owner, event, `${worker.harness}:${worker.nativeId}`), signal)]);
+    const { effect, commentId } = await this.dispatch(await this.prepare(owner, event, `${worker.harness}:${worker.nativeId}`), signal);
+    return { sync: this.summary([effect]), ...(commentId ? { commentId } : {}) };
   }
   public async lostDispatch(owner: string, worker: IFleetWorker, signal?: AbortSignal): Promise<IFleetTicketSync> {
     const lost = worker.lostDispatch;
     if (!lost || !worker.ticketKey) throw new Error('Lost dispatch comment requires a durable attributed resolution and ticket.');
     const body = `Fleet worker ${worker.name} (${worker.harness}${worker.nativeId ? `:${worker.nativeId}` : ', no native identity'}): dispatch ${lost.dispatch?.id ?? 'unfenced native session'} (${lost.dispatch?.action ?? 'observation'}) resolved as lost at ${lost.resolvedAt}.\nReason: ${lost.reason}\nAbsence proof: ${JSON.stringify(lost.proof)}\nOriginal fence: ${JSON.stringify(lost.dispatch ?? null)}\nNo prompt or message was resent. Stop/archive are permitted.`;
     const event: TTicketFleetEvent = { ticketKey: worker.ticketKey, actor: this.actor(lost.actor), kind: 'comment', body, idempotencyKey: `fleet:lost:${lost.id}` };
-    return this.summary([await this.dispatch(await this.prepare(owner, event, worker.nativeId ? `${worker.harness}:${worker.nativeId}` : undefined), signal)]);
+    return this.summary([(await this.dispatch(await this.prepare(owner, event, worker.nativeId ? `${worker.harness}:${worker.nativeId}` : undefined), signal)).effect]);
   }
   public async reconfirmedDispatch(owner: string, worker: IFleetWorker, signal?: AbortSignal): Promise<IFleetTicketSync> {
     const reconfirmed = worker.reconfirmedDispatch;
@@ -159,7 +173,7 @@ export class FleetTicketEffects {
       : `cannot prove whether the message arrived${proof.firstMessageAt ? ` (its first message since the fence arrived at ${proof.firstMessageAt})` : ''}`;
     const body = `Fleet worker ${worker.name} (${worker.harness}:${worker.nativeId}): steer ${reconfirmed.dispatch.id} reconfirmed at ${reconfirmed.resolvedAt}. The native session is ${proof.status} and its transcript ${delivery}.\nReason: ${reconfirmed.reason}\nSession proof: ${JSON.stringify(proof)}\nOriginal fence: ${JSON.stringify(reconfirmed.dispatch)}\nNo prompt or message was resent.`;
     const event: TTicketFleetEvent = { ticketKey: worker.ticketKey, actor: this.actor(reconfirmed.actor), kind: 'comment', body, idempotencyKey: `fleet:reconfirmed:${reconfirmed.id}` };
-    return this.summary([await this.dispatch(await this.prepare(owner, event, `${worker.harness}:${worker.nativeId}`), signal)]);
+    return this.summary([(await this.dispatch(await this.prepare(owner, event, `${worker.harness}:${worker.nativeId}`), signal)).effect]);
   }
   /** The ticket comment of the worker's saved re-bind; a replay rebuilds the same comment from the saved record alone. */
   public async reboundSession(owner: string, worker: IFleetWorker, signal?: AbortSignal): Promise<IFleetTicketSync> {
@@ -170,6 +184,6 @@ export class FleetTicketEffects {
       : `the inventory lists it under the worker's name in ${proof.cwd}; its transcript does not show that it continues ${proof.previous.nativeId}`;
     const body = `Fleet worker ${worker.name} (${worker.harness}) re-bound from native session ${proof.previous.nativeId} (${proof.previous.status}) to ${proof.nativeId} (${proof.status}) at ${rebound.resolvedAt}: ${relation}.\nReason: ${rebound.reason}\nRe-bind proof: ${JSON.stringify(proof)}\nNothing was sent or resumed; the next steer wakes ${proof.nativeId} with its saved options.`;
     const event: TTicketFleetEvent = { ticketKey: worker.ticketKey, actor: this.actor(rebound.actor), kind: 'comment', body, idempotencyKey: `fleet:rebound:${rebound.id}` };
-    return this.summary([await this.dispatch(await this.prepare(owner, event, `${worker.harness}:${worker.nativeId}`), signal)]);
+    return this.summary([(await this.dispatch(await this.prepare(owner, event, `${worker.harness}:${worker.nativeId}`), signal)).effect]);
   }
 }

package/ts/fleet/classes.workers.ts

@@ -1,9 +1,9 @@
 import * as plugins from '../plugins.js';
 import { controllerRuntimeIdKey, type IWorkerClaudeJobRequest, type TWorkerClaudeJobObservation } from '../../ts_interfaces/index.js';
-import type { IFleetWorker, IFleetWorkerProfile, IFleetWorkerJob, IFleetNativeMessageReceipt, TFleetEventKind, TFleetWorkerAction, TFleetWorkerRequest, TFleetWorkerResponse, TFleetWorkerJobAction, IFleetWorkerReport, IFleetWorkerDispatchHolder } from '../../ts_interfaces/fleetworkers.js';
+import type { IFleetEvent, IFleetWorker, IFleetWorkerProfile, IFleetWorkerJob, IFleetNativeMessageReceipt, TFleetEventKind, TFleetWorkerAction, TFleetWorkerRequest, TFleetWorkerResponse, TFleetWorkerJobAction, IFleetWorkerReport, IFleetWorkerDispatchHolder } from '../../ts_interfaces/fleetworkers.js';
 import type { IFleetConfiguration, IFleetOperation, IFleetTicketSync } from '../../ts_interfaces/fleet.js';
 import type { ITicketActor } from '../../ts_interfaces/tickets.js';
-import type { FleetTicketEffects } from './classes.ticketeffects.js';
+import type { FleetTicketEffects, IFleetTicketReport } from './classes.ticketeffects.js';
 import type { IControllerSystemMetrics, IControllerFleetWorkerView, IReq_ControllerFleetWorkerRead, IControllerPermission, IControllerQuestion, TControllerPermissionReply } from '../../ts_interfaces/index.js';
 import { FleetWorkerStore, type IFleetWorkerStore, type IFleetWorkerDocument } from './classes.workerstore.js';
 import { FleetEvents } from './classes.events.js';
@@ -115,15 +115,21 @@ export class FleetWorkers {
       try {
         const backend = this.backends[worker.harness], observed = backend.observed?.(worker), excerpt = backend.observedExcerpt?.(worker);
         const events = await this.backends[worker.harness].poll(worker, worker.profile);
+        const ticketed = this.options.ticketEffects && worker.ticketKey && worker.ticketActor;
         for (const { nativeId: _nativeId, ...event } of events) {
-          this.events.publish({ ...event, workerId: worker.id, workerName: worker.name, ...(worker.ticketKey ? { ticketKey: worker.ticketKey } : {}) }, owner);
-          if (this.options.ticketEffects && worker.ticketKey && worker.ticketActor) {
-            if (event.kind === 'worker.report.mid_turn' && event.text && event.reportId) await this.reportTicket(owner, worker, { reportId: event.reportId, text: event.text, truncated: event.truncated ?? false });
-            else if (event.kind === 'worker.turn.ended') {
-              const report = await this.backends[worker.harness].observe(worker, worker.profile);
-              if (report.reportId && report.text.trim()) await this.reportTicket(owner, worker, report);
-            }
+          const published = { ...event, workerId: worker.id, workerName: worker.name, ...(worker.ticketKey ? { ticketKey: worker.ticketKey } : {}) };
+          if (ticketed && event.kind === 'worker.report.mid_turn' && event.text && event.reportId) {
+            await this.reportTicket(owner, worker, { reportId: event.reportId, text: event.text, truncated: event.truncated ?? false }, published);
+            continue;
+          }
+          if (ticketed && event.kind === 'worker.turn.ended') {
+            let report: IFleetWorkerReport;
+            // The turn's end is published whether or not its report can be observed.
+            try { report = await this.backends[worker.harness].observe(worker, worker.profile); }
+            catch (error) { this.events.publish(published, owner); throw error; }
+            if (report.reportId && report.text.trim()) { await this.reportTicket(owner, worker, report, published); continue; }
           }
+          this.events.publish(published, owner);
         }
         if (this.options.ticketEffects && worker.ticketKey && worker.ticketActor) {
           const baseline = `${worker.id}:${worker.nativeId}:${worker.ticketKey}`;
@@ -162,8 +168,9 @@ export class FleetWorkers {
     let report: IFleetWorkerReport;
     try { report = await backend.observe(worker, worker.profile); } catch { return; }
     if (!report.reportId || !report.text.trim() || !fleetReportMarker.test(report.text)) return;
-    this.events.publish({ kind: 'worker.report.mid_turn', workerId: worker.id, workerName: worker.name, ...ticket, reportId: report.reportId, text: report.text, truncated: report.truncated, status: report.status }, owner);
-    if (this.options.ticketEffects && worker.ticketKey && worker.ticketActor) await this.reportTicket(owner, worker, report);
+    const event: Omit<IFleetEvent, 'id' | 'occurredAt'> = { kind: 'worker.report.mid_turn', workerId: worker.id, workerName: worker.name, ...ticket, reportId: report.reportId, text: report.text, truncated: report.truncated, status: report.status };
+    if (this.options.ticketEffects && worker.ticketKey && worker.ticketActor) await this.reportTicket(owner, worker, report, event);
+    else this.events.publish(event, owner);
   }
   public releaseEvent(operation: IFleetOperation, owner: string, repo?: string): void {
     if (operation.operation !== 'release' || !['succeeded', 'failed'].includes(operation.state)) return;
@@ -175,11 +182,16 @@ export class FleetWorkers {
     this.events.publish({ kind: ticketSync.state === 'applied' ? 'ticket.applied' : ticketSync.state === 'failed' ? 'ticket.failed' : 'ticket.unknown',
       ticketKey, ticketSync, ...(workerId ? { workerId } : {}), ...(operationId ? { operationId } : {}) }, owner);
   }
-  private async reportTicket(owner: string, worker: IFleetWorker, report: { reportId?: string; text: string; truncated: boolean }): Promise<IFleetTicketSync> {
-    let sync: IFleetTicketSync;
-    try { sync = await this.options.ticketEffects!.report(owner, worker.ticketKey!, worker.ticketActor!, worker, report, this.abort.signal); }
-    catch (error) { sync = { state: 'unknown', effects: [], error: this.error(error) }; }
-    this.ticketEvent(owner, worker.ticketKey!, sync, worker.id); return sync;
+  /**
+   * Comments the report on the worker's ticket first, then publishes `event`, naming the comment that holds its whole
+   * text when the board wrote it, and then the comment's ticket event.
+   */
+  private async reportTicket(owner: string, worker: IFleetWorker, report: { reportId?: string; text: string; truncated: boolean }, event?: Omit<IFleetEvent, 'id' | 'occurredAt'>): Promise<IFleetTicketSync> {
+    let written: IFleetTicketReport;
+    try { written = await this.options.ticketEffects!.report(owner, worker.ticketKey!, worker.ticketActor!, worker, report, this.abort.signal); }
+    catch (error) { written = { sync: { state: 'unknown', effects: [], error: this.error(error) } }; }
+    if (event) this.events.publish({ ...event, ...(written.commentId ? { commentId: written.commentId } : {}) }, owner);
+    this.ticketEvent(owner, worker.ticketKey!, written.sync, worker.id); return written.sync;
   }
   /** `reportsTo` names the direct report whose session asks; a worker it starts or adopts reports to it. */
   public async execute<T extends TFleetWorkerAction>(action: T, request: TFleetWorkerRequest<T>, configuration: IFleetConfiguration, owner: string, signal?: AbortSignal, actor?: ITicketActor, reportsTo?: string): Promise<TFleetWorkerResponse<T>> {

package/ts/fleet/functions.workervalidation.ts

@@ -117,7 +117,7 @@ const job = plugins.z.object({ id: text, action: plugins.z.enum(['start', 'adopt
 const event = plugins.z.object({ id: plugins.z.number().int().positive(),
   kind: plugins.z.enum(['worker.changed', 'worker.turn.ended', 'worker.report.mid_turn', 'worker.reaped', 'worker.credential.failed', 'worker.observation.failed', 'release.finished', 'release.failed', 'ticket.applied', 'ticket.failed', 'ticket.unknown',
     'ticket.changed', 'ticket.notified', 'ticket.notification.failed', 'ticket.stalled', 'harness.release.discovered', 'host.load']),
-  occurredAt: text, workerId: text.optional(), workerName: name.optional(), sessionId: text.optional(), reportId: text.optional(), turnId: text.optional(), status: text.optional(),
+  occurredAt: text, workerId: text.optional(), workerName: name.optional(), sessionId: text.optional(), reportId: text.optional(), commentId: text.optional(), turnId: text.optional(), status: text.optional(),
   ticketKey: ticketKey.optional(),
   ticketSync: ticketSync.optional(),
   text: plugins.z.string().max(64 * 1024).optional(), truncated: plugins.z.boolean().optional(), error: plugins.z.string().max(4096).optional(),