ai-foreman 1.7.6 → 1.7.8

package/dist/statusReporter.d.ts

@@ -1,7 +1,8 @@
-import type { BuilderAdapter } from "./adapters/types.js";
+import type { ContextSample, SessionUsageSample } from "rafi-spec";
+import type { BuilderAdapter, BuilderEvent, CompactResult, ContextUsage, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "./adapters/types.js";
 export interface AgentStatusSnapshot {
-    role: string;
-    provider: string;
+    role: "builder" | "qa";
+    provider: "claude" | "codex";
     model: string;
     reasoning: string;
     fast: boolean;
@@ -11,12 +12,22 @@ export interface AgentStatusSnapshot {
     total: number;
     phase: string;
     qaCycle?: number;
+    /** Compatibility projection. New consumers should use contextSample. */
     context?: {
         used: number;
         maximum?: number;
         percentage?: number;
     };
+    contextSample: ContextSample;
+    sessionUsage?: SessionUsageSample;
     sessionTransition: string;
+    lifecycleState?: string;
+    configuredCeilingPercent?: number;
+    installedNativeTokenLimit?: number;
+    installedNativePercent?: number;
+    compactionCount?: number;
+    compactMaximum?: number;
+    settingsRevision?: number;
     at: string;
 }
 export interface StatusClock {
@@ -24,17 +35,82 @@ export interface StatusClock {
     setInterval(callback: () => void, milliseconds: number): unknown;
     clearInterval(handle: unknown): void;
 }
-/** Non-blocking five-minute status with provider-truthful context occupancy. */
+export interface AgentStatusReporterInput {
+    runId: string;
+    role: "builder" | "qa";
+    provider: "claude" | "codex";
+    model: string;
+    reasoning: string;
+    fast: boolean;
+    ticket?: string;
+    stack?: string;
+    step: number;
+    total: number;
+    phase: string;
+    qaCycle?: number;
+    sessionTransition: string;
+    settingsRevision: number;
+    displaySessionCost: boolean;
+    adapter: BuilderAdapter | (() => BuilderAdapter);
+    compactionCount?: number | (() => number);
+    handoffGeneration?: number | (() => number);
+    /** Shared enforcement snapshot. When supplied, status never polls occupancy independently. */
+    contextSnapshot?: () => {
+        role: "builder" | "qa";
+        provider: "claude" | "codex";
+        model: string;
+        lifecycleState: string;
+        contextSample: ContextSample;
+        configuredCeilingPercent: number;
+        installedNativeTokenLimit?: number;
+        installedNativePercent?: number;
+        compactionCount: number;
+        compactMaximum: number;
+        settingsRevision: number;
+    } | undefined;
+}
+/**
+ * A non-blocking ten-second reporter. It never invents occupancy or cost: an
+ * absent provider sample is rendered as measuring, stale, or unavailable.
+ */
 export declare class AgentStatusReporter {
     private readonly input;
     private readonly emit;
     private readonly clock;
     private readonly intervalMs;
     private handle?;
-    constructor(input: Omit<AgentStatusSnapshot, "context" | "at"> & {
-        adapter: BuilderAdapter | (() => BuilderAdapter);
-    }, emit: (line: string, snapshot: AgentStatusSnapshot) => void, clock?: StatusClock, intervalMs?: number);
+    private lastGoodContext?;
+    private readonly lastGoodByRole;
+    constructor(input: AgentStatusReporterInput, emit: (line: string, snapshot: AgentStatusSnapshot) => void, clock?: StatusClock, intervalMs?: number);
     start(): void;
     tick(): Promise<void>;
-    stop(): void;
+    stop(finalPhase?: string): void;
+    updateState(patch: Partial<Omit<AgentStatusReporterInput, "runId">>): void;
+    private emitSnapshot;
+    private measuringSample;
+    private contextSample;
+    private adapter;
+}
+/** Switches the shared live status to a role for the lifetime of its adapter. */
+export declare class RoleStatusAdapter implements BuilderAdapter {
+    private readonly adapter;
+    private readonly onActive;
+    private readonly onClose;
+    readonly agent: "claude" | "codex";
+    constructor(adapter: BuilderAdapter, onActive: (adapter: BuilderAdapter) => void, onClose: () => void);
+    sendTurn(text: string): Promise<TurnResult>;
+    sessionId(): string | undefined;
+    sessionRef(): import("rafi-spec").ProviderSessionRefV1 | undefined;
+    adoptSessionRef(ref: import("rafi-spec").ProviderSessionRefV1): void;
+    validateSession(): Promise<import("rafi-spec").SessionAvailabilityV1>;
+    compact(): Promise<CompactResult>;
+    prepareContextManagement(policy: import("./adapters/types.js").ContextManagementPolicy): Promise<import("./adapters/types.js").PreparedContextManagement>;
+    updateContextManagement(policy: import("./adapters/types.js").ContextManagementPolicy): Promise<import("./adapters/types.js").PreparedContextManagement>;
+    interruptTurnAtCompactionBoundary(providerEventId?: string): Promise<import("./adapters/types.js").InterruptResult>;
+    installManagedTurnDispatcher(dispatcher: import("./adapters/types.js").ManagedTurnDispatcher): void;
+    contextUsage(): Promise<ContextUsage | undefined>;
+    sessionUsage(): Promise<ProviderSessionUsage | undefined>;
+    switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
+    events(): AsyncIterable<BuilderEvent>;
+    close(): Promise<void>;
 }

package/dist/statusReporter.js

@@ -1,31 +1,287 @@
+import { providerSessionKey } from "./sessionIdentity.js";
 const systemClock = {
     now: () => new Date(),
-    setInterval: (callback, milliseconds) => { const handle = setInterval(callback, milliseconds); handle.unref(); return handle; },
+    setInterval: (callback, milliseconds) => {
+        const handle = setInterval(callback, milliseconds);
+        handle.unref();
+        return handle;
+    },
     clearInterval: (handle) => clearInterval(handle),
 };
-/** Non-blocking five-minute status with provider-truthful context occupancy. */
+/**
+ * A non-blocking ten-second reporter. It never invents occupancy or cost: an
+ * absent provider sample is rendered as measuring, stale, or unavailable.
+ */
 export class AgentStatusReporter {
     input;
     emit;
     clock;
     intervalMs;
     handle;
-    constructor(input, emit, clock = systemClock, intervalMs = 300_000) {
+    lastGoodContext;
+    lastGoodByRole = new Map();
+    constructor(input, emit, clock = systemClock, intervalMs = 10_000) {
         this.input = input;
         this.emit = emit;
         this.clock = clock;
         this.intervalMs = intervalMs;
     }
-    start() { if (this.handle !== undefined)
-        return; this.handle = this.clock.setInterval(() => void this.tick(), this.intervalMs); }
+    start() {
+        if (this.handle !== undefined)
+            return;
+        this.emitSnapshot(this.measuringSample(), undefined);
+        this.handle = this.clock.setInterval(() => void this.tick(), this.intervalMs);
+    }
     async tick() {
-        const adapter = typeof this.input.adapter === "function" ? this.input.adapter() : this.input.adapter;
-        const context = await adapter.contextUsage?.();
-        const { adapter: _adapter, ...base } = this.input;
-        const snapshot = { ...base, ...(context ? { context } : {}), at: this.clock.now().toISOString() };
-        const occupancy = context ? `context: ${context.used}/${context.maximum ?? "unknown"}${context.percentage === undefined ? "" : ` (${context.percentage.toFixed(1)}%)`}` : "context: unavailable";
-        this.emit(`[${snapshot.at}] ${snapshot.role} ${snapshot.provider}/${snapshot.model} reasoning=${snapshot.reasoning} fast=${snapshot.fast}; ${snapshot.ticket ? `ticket=${snapshot.ticket}; ` : ""}${snapshot.stack ? `stack=${snapshot.stack}; ` : ""}step=${snapshot.step}/${snapshot.total}; phase=${snapshot.phase}${snapshot.qaCycle ? `; qa_cycle=${snapshot.qaCycle}` : ""}; ${occupancy}; session=${snapshot.sessionTransition}`, snapshot);
-    }
-    stop() { if (this.handle !== undefined)
-        this.clock.clearInterval(this.handle); this.handle = undefined; }
+        const adapter = this.adapter();
+        const now = this.clock.now();
+        let contextSample;
+        const hasCoordinator = this.input.contextSnapshot !== undefined;
+        const coordinated = this.input.contextSnapshot?.();
+        if (coordinated && coordinated.role === this.input.role) {
+            contextSample = coordinated.contextSample;
+            this.input.provider = coordinated.provider;
+            this.input.model = coordinated.model;
+            this.input.settingsRevision = coordinated.settingsRevision;
+            this.input.compactionCount = coordinated.compactionCount;
+            if (contextSample.freshness === "fresh") {
+                this.lastGoodContext = contextSample;
+                this.lastGoodByRole.set(this.input.role, contextSample);
+            }
+        }
+        else if (!hasCoordinator) {
+            let observed;
+            try {
+                observed = await adapter.contextUsage?.();
+            }
+            catch {
+                observed = undefined;
+            }
+            if (observed && Number.isFinite(observed.used))
+                contextSample = this.contextSample(observed, now);
+            else if (this.lastGoodContext)
+                contextSample = { ...this.lastGoodContext, freshness: "stale" };
+            else
+                contextSample = { ...this.measuringSample(now), freshness: "unavailable" };
+        }
+        else {
+            const prior = this.lastGoodByRole.get(this.input.role);
+            contextSample = prior
+                ? { ...prior, freshness: "stale" }
+                : { ...this.measuringSample(now), freshness: "unavailable" };
+        }
+        if (contextSample.freshness === "fresh") {
+            this.lastGoodContext = contextSample;
+            this.lastGoodByRole.set(this.input.role, contextSample);
+        }
+        let sessionUsage;
+        if (this.input.displaySessionCost) {
+            try {
+                const usage = await adapter.sessionUsage?.();
+                const ref = adapter.sessionRef?.();
+                sessionUsage = usage ? {
+                    version: 1,
+                    runId: this.input.runId,
+                    role: this.input.role,
+                    provider: this.input.provider,
+                    providerSessionId: adapter.sessionId(),
+                    ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : {}),
+                    observedAt: usage.observedAt,
+                    source: usage.source,
+                    cumulativeInputTokens: usage.inputTokens,
+                    cumulativeOutputTokens: usage.outputTokens,
+                    cumulativeTotalTokens: usage.totalTokens,
+                    authoritativeCostUsd: usage.authoritativeCostUsd,
+                } : unavailableUsage(this.input, adapter, now);
+            }
+            catch {
+                sessionUsage = unavailableUsage(this.input, adapter, now);
+            }
+        }
+        this.emitSnapshot(contextSample, sessionUsage, now);
+    }
+    stop(finalPhase = "completed") {
+        if (this.handle === undefined)
+            return;
+        this.clock.clearInterval(this.handle);
+        this.handle = undefined;
+        this.input.phase = finalPhase;
+        this.emitSnapshot(this.lastGoodContext ?? { ...this.measuringSample(), freshness: "unavailable" }, undefined);
+    }
+    updateState(patch) {
+        const priorRole = this.input.role;
+        const priorAdapter = this.adapter();
+        const priorSessionId = priorAdapter.sessionId();
+        if (this.lastGoodContext)
+            this.lastGoodByRole.set(priorRole, this.lastGoodContext);
+        Object.assign(this.input, patch);
+        if (priorRole !== this.input.role
+            || priorAdapter !== this.adapter()
+            || priorSessionId !== this.adapter().sessionId()
+            || patch.sessionTransition !== undefined)
+            this.lastGoodContext = this.lastGoodByRole.get(this.input.role);
+        this.emitSnapshot(this.measuringSample(), undefined);
+    }
+    emitSnapshot(contextSample, sessionUsage, now = this.clock.now()) {
+        const coordinated = this.input.contextSnapshot?.();
+        const { adapter: _adapter, displaySessionCost: _display, compactionCount: _compactions, handoffGeneration: _handoffs, contextSnapshot: _contextSnapshot, ...base } = this.input;
+        const context = contextSample.used === undefined ? undefined : {
+            used: contextSample.used,
+            maximum: contextSample.maximum,
+            percentage: contextSample.percentage,
+        };
+        const snapshot = {
+            ...base,
+            ...(context ? { context } : {}),
+            contextSample,
+            ...(sessionUsage ? { sessionUsage } : {}),
+            ...(coordinated && coordinated.role === this.input.role ? {
+                lifecycleState: coordinated.lifecycleState,
+                configuredCeilingPercent: coordinated.configuredCeilingPercent,
+                installedNativeTokenLimit: coordinated.installedNativeTokenLimit,
+                installedNativePercent: coordinated.installedNativePercent,
+                compactionCount: coordinated.compactionCount,
+                compactMaximum: coordinated.compactMaximum,
+                settingsRevision: coordinated.settingsRevision,
+            } : {
+                compactionCount: contextSample.compactionCount,
+                settingsRevision: contextSample.settingsRevision,
+            }),
+            at: now.toISOString(),
+        };
+        const line = [
+            `${snapshot.role} ${snapshot.provider}/${snapshot.model}`,
+            `activity=${snapshot.phase}`,
+            formatContext(contextSample),
+            ...(snapshot.configuredCeilingPercent === undefined ? [] : [`ceiling=${snapshot.configuredCeilingPercent}%`]),
+            ...(snapshot.installedNativePercent === undefined ? [] : [`native=${snapshot.installedNativePercent.toFixed(1)}%${snapshot.installedNativeTokenLimit === undefined ? "" : `/${snapshot.installedNativeTokenLimit}`}`]),
+            ...(snapshot.lifecycleState ? [`state=${formatLifecycle(snapshot.lifecycleState)}`] : []),
+            `compactions=${snapshot.compactionCount ?? contextSample.compactionCount}${snapshot.compactMaximum === undefined ? "" : `/${snapshot.compactMaximum}`}`,
+            `revision=${snapshot.settingsRevision ?? contextSample.settingsRevision}`,
+            `handoff=${contextSample.handoffGeneration}`,
+            `session=${snapshot.sessionTransition}`,
+            ...(this.input.displaySessionCost ? [formatSessionUsage(sessionUsage)] : []),
+        ].join("; ");
+        this.emit(`[${snapshot.at}] ${line}`, snapshot);
+    }
+    measuringSample(now = this.clock.now()) {
+        const ref = this.adapter().sessionRef?.();
+        return {
+            version: 1,
+            runId: this.input.runId,
+            role: this.input.role,
+            provider: this.input.provider,
+            providerSessionId: this.adapter().sessionId(),
+            ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : {}),
+            model: this.input.model,
+            observedAt: now.toISOString(),
+            source: "provider-query",
+            freshness: "measuring",
+            settingsRevision: this.input.settingsRevision,
+            compactionCount: numeric(this.input.compactionCount),
+            handoffGeneration: numeric(this.input.handoffGeneration),
+        };
+    }
+    contextSample(usage, now) {
+        const ref = this.adapter().sessionRef?.();
+        return {
+            ...this.measuringSample(now),
+            providerSessionId: this.adapter().sessionId(),
+            ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : {}),
+            observedAt: usage.observedAt ?? now.toISOString(),
+            source: usage.source ?? "provider-query",
+            freshness: "fresh",
+            used: usage.used,
+            maximum: usage.maximum,
+            percentage: usage.percentage ?? (usage.maximum ? (usage.used / usage.maximum) * 100 : undefined),
+        };
+    }
+    adapter() {
+        return typeof this.input.adapter === "function" ? this.input.adapter() : this.input.adapter;
+    }
+}
+/** Switches the shared live status to a role for the lifetime of its adapter. */
+export class RoleStatusAdapter {
+    adapter;
+    onActive;
+    onClose;
+    agent;
+    constructor(adapter, onActive, onClose) {
+        this.adapter = adapter;
+        this.onActive = onActive;
+        this.onClose = onClose;
+        this.agent = adapter.agent;
+    }
+    async sendTurn(text) { this.onActive(this.adapter); return this.adapter.sendTurn(text); }
+    sessionId() { return this.adapter.sessionId(); }
+    sessionRef() { return this.adapter.sessionRef?.(); }
+    adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
+    validateSession() { return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped" }); }
+    compact() { this.onActive(this.adapter); return this.adapter.compact?.() ?? Promise.resolve({ ok: false, error: "native compaction unavailable" }); }
+    prepareContextManagement(policy) { this.onActive(this.adapter); if (!this.adapter.prepareContextManagement)
+        return Promise.reject(new Error("native context management unavailable")); return this.adapter.prepareContextManagement(policy); }
+    updateContextManagement(policy) { if (!this.adapter.updateContextManagement)
+        return Promise.reject(new Error("native context reconfiguration unavailable")); return this.adapter.updateContextManagement(policy); }
+    interruptTurnAtCompactionBoundary(providerEventId) { return this.adapter.interruptTurnAtCompactionBoundary?.(providerEventId) ?? Promise.resolve({ ok: false, error: "compaction-boundary interruption unavailable", providerEventId }); }
+    installManagedTurnDispatcher(dispatcher) { this.adapter.installManagedTurnDispatcher?.(dispatcher); }
+    contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
+    sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
+    switchSettings(settings) { return this.adapter.switchSettings?.(settings) ?? Promise.resolve({ ok: false, error: "settings switch unavailable" }); }
+    events() { return this.adapter.events(); }
+    async close() { try {
+        await this.adapter.close();
+    }
+    finally {
+        this.onClose();
+    } }
+}
+function unavailableUsage(input, adapter, now) {
+    const ref = adapter.sessionRef?.();
+    return {
+        version: 1,
+        runId: input.runId,
+        role: input.role,
+        provider: input.provider,
+        providerSessionId: adapter.sessionId(),
+        ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : {}),
+        observedAt: now.toISOString(),
+        source: "unavailable",
+    };
+}
+function numeric(value) {
+    const resolved = typeof value === "function" ? value() : value;
+    return Number.isSafeInteger(resolved) && (resolved ?? -1) >= 0 ? resolved : 0;
+}
+function formatContext(sample) {
+    if (sample.freshness === "measuring")
+        return "context measuring…";
+    if (sample.freshness === "unavailable")
+        return "context unavailable";
+    const occupancy = sample.percentage === undefined
+        ? `${sample.used ?? "unknown"}/${sample.maximum ?? "unknown"}`
+        : `${sample.percentage.toFixed(1)}% (${sample.used ?? "unknown"}/${sample.maximum ?? "unknown"})`;
+    return `context ${occupancy}${sample.freshness === "stale" ? " stale" : ""}`;
+}
+function formatLifecycle(state) {
+    if (state === "initializing")
+        return "measuring";
+    if (state === "threshold_pending")
+        return "pending";
+    if (state === "native_compacting" || state === "host_compacting")
+        return "compacting";
+    if (state === "compacted_unverified")
+        return "verifying";
+    if (state === "handoff_required" || state === "resuming")
+        return "handing off";
+    return state;
+}
+function formatSessionUsage(sample) {
+    if (!sample || sample.source === "unavailable")
+        return "session usage unavailable";
+    if (sample.authoritativeCostUsd !== undefined)
+        return `session cost $${sample.authoritativeCostUsd.toFixed(4)} (provider)`;
+    if (sample.cumulativeTotalTokens !== undefined)
+        return `session tokens ${sample.cumulativeTotalTokens}`;
+    const total = (sample.cumulativeInputTokens ?? 0) + (sample.cumulativeOutputTokens ?? 0);
+    return total > 0 ? `session tokens ${total}` : "session usage unavailable";
 }

package/dist/ticketPlanning.js

@@ -203,6 +203,7 @@ export function applyApprovedTicketPlan(projectDir, proposal, opts) {
         try {
             const now = new Date().toISOString();
             db.transaction(() => {
+                db.ensureSyntheticLegacyGroup(existing, opts.now ?? new Date());
                 const existingNext = [...db.getAllStates().values()].filter((state) => state.status === "next").map((state) => state.ticket_id);
                 if (proposal.next.replace_existing)
                     for (const id of existingNext)
@@ -227,6 +228,10 @@ export function applyApprovedTicketPlan(projectDir, proposal, opts) {
                         throw new Error(`future work item ${disposition.id} does not exist`);
                     db.updateFutureWorkDisposition(disposition.id, disposition.disposition);
                 }
+                if (proposal.additions.length) {
+                    const operationDigest = createHash("sha256").update(JSON.stringify(proposal.additions)).digest("hex");
+                    db.createTicketGroup({ origin: "ticket-plan", operationId: `ticket-plan:${operationDigest}`, createdAt: now, members: proposal.additions.map((ticket) => ({ ticketId: ticket.id, definition: ticket, validatedAt: now })) });
+                }
             });
             const states = db.getAllStates();
             renderAndWrite({ config, projectDir: root, ticketDefs: staged, states, db });
@@ -234,6 +239,9 @@ export function applyApprovedTicketPlan(projectDir, proposal, opts) {
             const errors = validation.filter((issue) => issue.severity === "error");
             if (errors.length)
                 throw new Error(`post-apply tracker validation failed:\n${errors.map((issue) => `- ${issue.message}`).join("\n")}`);
+            for (const ticket of staged)
+                if (db.getTicketGroupForTicket(ticket.id))
+                    db.updateTicketDefinitionSnapshot(ticket.id, ticket, now);
         }
         finally {
             db.close();

package/dist/ticketPopulation.js

@@ -2,9 +2,9 @@ import { createHash, randomUUID } from "node:crypto";
 import { closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { stringify } from "yaml";
-import { WorkflowDb } from "./workflowDb.js";
+import { WorkflowDb, WORKFLOW_DB_FILE } from "./workflowDb.js";
 import { cmdRender, cmdValidate } from "./tickets/commands.js";
-import { validateTicketDefs } from "./tickets/ticketLoader.js";
+import { loadTickets, validateTicketDefs } from "./tickets/ticketLoader.js";
 import { normalizeDeliveryConfig, validateDeliveryConfig } from "./tickets/delivery.js";
 import { loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
 import { StateDb } from "./tickets/stateDb.js";
@@ -106,6 +106,12 @@ export function applyTicketPopulation(projectDir, materialized, runId, now = new
     const root = resolve(projectDir);
     const config = loadTicketsConfig(root);
     const paths = resolveTicketPaths(config, root);
+    // Finish any older two-phase publication before resolving a new batch. This
+    // makes direct API use as safe as the CLI pre-action hook.
+    recoverTicketPublications(root);
+    const previousTickets = loadTickets(paths.tickets);
+    const previousIds = new Set(previousTickets.map((ticket) => ticket.id));
+    const createdTickets = materialized.tickets.filter((ticket) => !previousIds.has(ticket.id));
     const workflow = new WorkflowDb(root);
     let actualRunId = runId;
     let lease;
@@ -113,12 +119,17 @@ export function applyTicketPopulation(projectDir, materialized, runId, now = new
         if (!actualRunId)
             actualRunId = workflow.createRun({ kind: "ticket-populate", originalWork: { tickets: materialized.tickets.map((ticket) => ticket.id) }, state: {} }, now).runId;
         lease = workflow.acquireLease(actualRunId, undefined, now);
+        const operationId = `ticket-populate-publication:${actualRunId}`;
         const deliveryPath = join(root, ".tickets", "delivery.yaml");
         const stage = join(root, ".rafi", "staging", randomUUID());
         mkdirSync(stage, { recursive: true });
         const stagedTickets = join(stage, "tickets.yaml");
         const stagedDelivery = join(stage, "delivery.yaml");
-        const tx = workflow.beginPublication(actualRunId, { files: [{ staged: stagedTickets, target: paths.tickets }, { staged: stagedDelivery, target: deliveryPath }], stage }, {
+        const tx = workflow.beginPublication(actualRunId, {
+            operation: "ticket-populate", operationId,
+            files: [{ staged: stagedTickets, target: paths.tickets }, { staged: stagedDelivery, target: deliveryPath }],
+            stage, managedTicketIds: materialized.tickets.map((ticket) => ticket.id),
+        }, {
             [paths.tickets]: fileDigest(paths.tickets), [deliveryPath]: fileDigest(deliveryPath),
         }, now);
         fsyncWrite(stagedTickets, stringify({ tickets: materialized.tickets }, { lineWidth: 120 }));
@@ -128,6 +139,7 @@ export function applyTicketPopulation(projectDir, materialized, runId, now = new
         try {
             db.transaction(() => {
                 const at = now.toISOString();
+                db.ensureSyntheticLegacyGroup(previousTickets, now);
                 for (const ticket of materialized.tickets)
                     if (!db.getState(ticket.id))
                         db.upsertState(ticket.id, { status: "planned", updated_by: "rafi tickets populate" }, at);
@@ -138,6 +150,16 @@ export function applyTicketPopulation(projectDir, materialized, runId, now = new
                     db.upsertState(id, { status: "obsolete", completed_at: at, updated_by: "rafi tickets populate" }, at);
                     db.insertEvent({ timestamp: at, actor: "rafi tickets populate", ticket_id: id, event_type: "obsolete", old_status: prior?.status ?? "planned", new_status: "obsolete", summary: "Removed by approved plan revision", validation: null, evidence: null, payload_json: JSON.stringify({ runId: actualRunId }) });
                 }
+                if (createdTickets.length)
+                    db.createTicketGroup({ origin: "ticket-populate", operationId: `ticket-populate:${actualRunId}`, createdAt: at, members: createdTickets.map((ticket) => ({ ticketId: ticket.id, definition: ticket, validatedAt: at })) });
+                db.recordOperationReceipt({
+                    operation_id: operationId,
+                    operation_type: "ticket-populate-publication",
+                    ticket_id: null,
+                    run_id: actualRunId,
+                    completed_at: at,
+                    payload_json: JSON.stringify({ transactionId: tx.transactionId, tickets: materialized.tickets.map((ticket) => ticket.id) }),
+                });
             });
         }
         finally {
@@ -151,6 +173,15 @@ export function applyTicketPopulation(projectDir, materialized, runId, now = new
         const validation = cmdValidate(root);
         if (!validation.clean)
             throw new Error(`published ticket population failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`);
+        const snapshotDb = new StateDb(paths.stateDb);
+        try {
+            for (const ticket of materialized.tickets)
+                if (snapshotDb.getTicketGroupForTicket(ticket.id))
+                    snapshotDb.updateTicketDefinitionSnapshot(ticket.id, ticket, now.toISOString());
+        }
+        finally {
+            snapshotDb.close();
+        }
         workflow.updatePublication(tx.transactionId, "committed", now);
         workflow.transition(actualRunId, { status: "completed", checkpoint: "population-committed", remainingWork: {}, state: { transactionId: tx.transactionId } }, now);
         rmSync(stage, { recursive: true, force: true });
@@ -164,25 +195,70 @@ export function applyTicketPopulation(projectDir, materialized, runId, now = new
 }
 /** Startup recovery deterministically finishes publications after tracker commit. */
 export function recoverTicketPublications(projectDir) {
+    if (!existsSync(join(resolve(projectDir), WORKFLOW_DB_FILE)))
+        return [];
     const workflow = new WorkflowDb(projectDir);
     const recovered = [];
     try {
         for (const tx of workflow.incompletePublications()) {
             const intent = tx.intent;
-            if (["tracker_committed", "published"].includes(tx.status)) {
-                if (tx.status === "tracker_committed")
-                    for (const file of intent.files)
-                        if (existsSync(file.staged))
-                            publishStaged(file.staged, file.target);
-                workflow.updatePublication(tx.transactionId, "committed");
-                recovered.push(tx.transactionId);
-                rmSync(intent.stage, { recursive: true, force: true });
+            const run = workflow.getRun(tx.runId);
+            const isLegacyPopulation = !intent.operation && Array.isArray(intent.files) && run?.kind === "ticket-populate";
+            if (intent.operation !== "ticket-populate" && !isLegacyPopulation)
+                continue;
+            if (!intent.files || !intent.stage)
+                throw new Error(`ticket population ${tx.transactionId} has an invalid durable publication intent`);
+            const root = resolve(projectDir);
+            const config = loadTicketsConfig(root);
+            const paths = resolveTicketPaths(config, root);
+            let trackerCommitted = ["tracker_committed", "published"].includes(tx.status);
+            if (!trackerCommitted && intent.operationId) {
+                const receiptDb = new StateDb(paths.stateDb);
+                try {
+                    trackerCommitted = Boolean(receiptDb.getOperationReceipt(intent.operationId));
+                }
+                finally {
+                    receiptDb.close();
+                }
             }
-            else {
+            if (!trackerCommitted) {
                 rmSync(intent.stage, { recursive: true, force: true });
                 workflow.updatePublication(tx.transactionId, "rolled_back");
+                if (run && run.status !== "failed")
+                    workflow.transition(run.runId, { status: "failed", checkpoint: "population-rolled-back-before-tracker-commit", state: { ...run.state, recoveredPublication: tx.transactionId } });
                 recovered.push(tx.transactionId);
+                continue;
+            }
+            if (tx.status !== "published") {
+                for (const file of intent.files) {
+                    if (!existsSync(file.staged))
+                        throw new Error(`ticket population ${tx.transactionId} cannot recover because staged file is missing: ${file.staged}`);
+                    publishStaged(file.staged, file.target);
+                }
+                workflow.updatePublication(tx.transactionId, "published");
+            }
+            cmdRender(root);
+            const validation = cmdValidate(root);
+            if (!validation.clean)
+                throw new Error(`recovered ticket population failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`);
+            const definitions = loadTickets(paths.tickets);
+            const managedIds = new Set(intent.managedTicketIds ?? definitions.map((ticket) => ticket.id));
+            const snapshotDb = new StateDb(paths.stateDb);
+            try {
+                snapshotDb.transaction(() => {
+                    for (const ticket of definitions)
+                        if (managedIds.has(ticket.id) && snapshotDb.getTicketGroupForTicket(ticket.id))
+                            snapshotDb.updateTicketDefinitionSnapshot(ticket.id, ticket);
+                });
+            }
+            finally {
+                snapshotDb.close();
             }
+            workflow.updatePublication(tx.transactionId, "committed");
+            if (run && run.status !== "completed")
+                workflow.transition(run.runId, { status: "completed", checkpoint: "population-recovered", remainingWork: {}, state: { ...run.state, recoveredPublication: tx.transactionId } });
+            recovered.push(tx.transactionId);
+            rmSync(intent.stage, { recursive: true, force: true });
         }
         return recovered;
     }

package/dist/tickets/commands.js

@@ -385,19 +385,27 @@ export function cmdAcceptFutureWork(projectDir, futureWorkId, opts) {
             rollback: null,
             notes: fw.rationale ?? null,
         };
-        ctx.db.transaction(() => {
-            ctx.db.updateFutureWorkDisposition(futureWorkId, "accepted");
-            logEvent(ctx.db, {
-                timestamp: now,
-                actor: opts.actor ?? null,
-                ticketId: opts.ticketId,
-                eventType: "accept-future-work",
-                oldStatus: null,
-                newStatus: "planned",
-                summary: `Accepted future work ${futureWorkId} as ticket ${opts.ticketId}`,
-            });
-        });
+        ctx.db.ensureSyntheticLegacyGroup(ctx.tickets);
         saveTickets(ctx.paths.tickets, [...ctx.tickets, newTicket]);
+        try {
+            ctx.db.transaction(() => {
+                ctx.db.updateFutureWorkDisposition(futureWorkId, "accepted");
+                logEvent(ctx.db, {
+                    timestamp: now,
+                    actor: opts.actor ?? null,
+                    ticketId: opts.ticketId,
+                    eventType: "accept-future-work",
+                    oldStatus: null,
+                    newStatus: "planned",
+                    summary: `Accepted future work ${futureWorkId} as ticket ${opts.ticketId}`,
+                });
+                ctx.db.createTicketGroup({ origin: "future-work", operationId: `future-work:${futureWorkId}`, members: [{ ticketId: newTicket.id, definition: newTicket, validatedAt: now }] });
+            });
+        }
+        catch (error) {
+            saveTickets(ctx.paths.tickets, ctx.tickets);
+            throw error;
+        }
         // Re-open context to pick up new ticket list
         const newCtx = openContext(projectDir);
         try {