@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/mesh/live/flush.js

@@ -2,26 +2,43 @@
  * Flush spool + held session events (US-008).
  *
  * Claim-by-rename → group by sessionId → read work-context state →
- * drop untracked / hold unverified / strip local-only → POST batches of ≤100
- * with bounded full-jitter retries. Never touches sessions-bind.json.
+ * drop untracked / hold unverified / strip local-only → POST at most 25 events
+ * per session per flush. Throttles honor Retry-After and preserve the backlog.
  *
  * Orphan `*.claimed` files from a prior crash are recovered first.
  * 2xx responses are accounted per eventId (accepted / duplicates / rejected).
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { readSessionState } from "../../work-context/state.js";
+import { readMetaCompanySlug, resolveCompany } from "../../work-context/company.js";
+import { companyBindingChanged, reboundSessionProjection, } from "../../work-context/company-rebind.js";
+import { deriveRemoteOwnerSlug, deriveRepoIdentityKey, } from "../../work-context/repo-remote.js";
+import { rebindNeedsProjectOnPrompt } from "../../work-context/prompt-rebind.js";
+import { readSessionState, updateSessionState, writeSessionState } from "../../work-context/state.js";
+import { generateUlid } from "./ulid.js";
+import { repairAckedRegisterStates } from "../../work-context/outbox.js";
 import { workContextRoot } from "../../work-context/paths.js";
 import { defaultSleep, FLUSH_MAX_ATTEMPTS, fullJitterDelayMs, } from "./backoff.js";
 import { LOCAL_ONLY_FIELDS, stripLocalOnlyFields } from "./format-spool-line.js";
+import { enrichSessionEndEvent } from "./report-summary.js";
 import { SESSION_EVENTS_BATCH_MAX, WRITABLE_CONTEXT_STATUSES, parseSessionEventsBatchAck, } from "./session-events-client.js";
-import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendSpoolLine, claimHeld, claimSpool, countJsonlLines, ensureSpoolFile, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
+import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLinesIfAbsent, appendSpoolLine, claimHeld, claimSpool, countDistinctHeldEvents, countJsonlLines, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
 import { workMeshHeldPath, workMeshRoot } from "./paths.js";
+/** Bound a replayed session backlog so one flush cannot burst hundreds of events. */
+const SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH = 25;
+/** Never keep a flush blocked on a Retry-After value for more than five minutes. */
+const MAX_RETRY_AFTER_MS = 5 * 60 * 1000;
 export const HELD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 /** Re-attempt held events at most this often (spool still flushes every cycle). */
 export const HELD_RETRY_INTERVAL_MS = 5 * 60 * 1000;
-/** Cap held.jsonl size; oldest overflow is dead-lettered with HELD_OVERFLOW. */
+/** Cap distinct held events; oldest overflow is dead-lettered with HELD_OVERFLOW. */
 export const HELD_MAX_LINES = 20_000;
+/**
+ * Re-check an unbound session against the project catalog at most this often.
+ * The catalog itself is also cached inside bind-best.
+ */
+export const PROJECT_REBIND_INTERVAL_MS = 60_000;
+const lastProjectRebindAtMs = new Map();
 function parseLine(line) {
     try {
         const v = JSON.parse(line);
@@ -60,8 +77,43 @@ function unwrapHeld(obj) {
 function heldEnvelope(event, heldReason, heldAt) {
     return JSON.stringify({ event, heldReason, heldAt });
 }
-function deadLetterEnvelope(event, reason, responseCode, at) {
-    return JSON.stringify({ event, reason, responseCode, at });
+/**
+ * A seven-day retention rule must never beat local recovery. An event can
+ * still carry enough trusted/deterministic context (or have a configured
+ * device default) to reconcile its session on the next daemon startup.
+ */
+function isLocallyReconcilableHeldEvent(event, state, workContextRoot) {
+    const sessionId = sessionIdOf(event);
+    if (!sessionId || state?.companyUid)
+        return Boolean(sessionId && state?.companyUid);
+    const text = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
+    const cwd = text(event.cwd);
+    const hqRoot = text(event.hqRoot);
+    const remoteOwnerSlug = cwd
+        ? deriveRemoteOwnerSlug({ cwd, hqRoot }) ?? undefined
+        : undefined;
+    const repoIdentityKey = cwd ? deriveRepoIdentityKey({ cwd }) : null;
+    return (resolveCompany({
+        root: workContextRoot,
+        sessionId,
+        existingState: state,
+        trusted: text(event.companySlug)
+            ? { companySlug: text(event.companySlug) }
+            : undefined,
+        cwd,
+        hqRoot,
+        remoteOwnerSlug,
+        repoIdentityKey,
+    }).status === "resolved");
+}
+function deadLetterEnvelope(event, reason, responseCode, at, code) {
+    return JSON.stringify({
+        event,
+        reason,
+        responseCode,
+        at,
+        ...(code ? { code } : {}),
+    });
 }
 function groupBySession(events) {
     const map = new Map();
@@ -81,18 +133,32 @@ async function postBatchWithRetries(poster, body, deps) {
     let lastStatus = 0;
     let lastBody = {};
     for (let attempt = 0; attempt < deps.maxAttempts; attempt += 1) {
+        if (deps.signal?.aborted) {
+            return { ok: false, retryable: true, status: lastStatus, body: lastBody };
+        }
         const res = await poster(body);
         lastStatus = res.status;
         lastBody = res.body;
         if (res.ok)
             return { ok: true, body: res.body };
+        if (res.status === 429 || res.status === 503) {
+            const retryAfterMs = typeof res.retryAfterMs === "number" &&
+                Number.isFinite(res.retryAfterMs) &&
+                res.retryAfterMs >= 0
+                ? Math.min(res.retryAfterMs, MAX_RETRY_AFTER_MS)
+                : 0;
+            const jitterMs = fullJitterDelayMs(attempt, { random: deps.random });
+            await deps.sleep(Math.min(MAX_RETRY_AFTER_MS, Math.max(retryAfterMs, jitterMs)), deps.signal);
+            // A throttled batch stays queued for a later flush; do not hot-loop it.
+            return { ok: false, retryable: true, status: res.status, body: res.body };
+        }
         if (!res.retryable) {
             return { ok: false, retryable: false, status: res.status, body: res.body };
         }
         if (attempt + 1 >= deps.maxAttempts)
             break;
         const delay = fullJitterDelayMs(attempt, { random: deps.random });
-        await deps.sleep(delay);
+        await deps.sleep(delay, deps.signal);
     }
     return { ok: false, retryable: true, status: lastStatus, body: lastBody };
 }
@@ -157,10 +223,16 @@ export async function flushSessionEvents(deps) {
                     summary.deadLettered += 1;
                     continue;
                 }
-                // Expire held lines older than 7 days.
+                // Expire held lines older than 7 days only when local recovery cannot
+                // still resolve the session. The daemon backfill runs before startup
+                // flush, so retaining these lines gives that deterministic repair a
+                // chance rather than silently losing attributable work.
                 if (heldAt) {
                     const age = now().getTime() - Date.parse(heldAt);
-                    if (Number.isFinite(age) && age > HELD_TTL_MS) {
+                    const state = readSessionState(sessionIdOf(event), deps.workContextRoot);
+                    if (Number.isFinite(age) &&
+                        age > HELD_TTL_MS &&
+                        !isLocallyReconcilableHeldEvent(event, state, deps.workContextRoot)) {
                         appendDeadLetterLine(deadLetterEnvelope(event, "HELD_EXPIRED", "held_ttl", now().toISOString()), deps.workMeshRoot);
                         summary.deadLettered += 1;
                         continue;
@@ -171,39 +243,80 @@ export async function flushSessionEvents(deps) {
             }
         }
         const bySession = groupBySession(collected);
+        // Older clients acknowledged register operations without copying the
+        // authoritative company into the session projection. Repair those files
+        // before classification so a valid receipt cannot be held as NEEDS_COMPANY.
+        repairAckedRegisterStates(deps.workContextRoot, new Set(bySession.keys()), now);
         const markDisposed = (event) => {
             pendingRestore.delete(event);
         };
-        for (const [sessionId, items] of bySession) {
-            const state = readSessionState(sessionId, deps.workContextRoot);
+        const loggedProject404 = new Set();
+        sessionLoop: for (const [sessionId, items] of bySession) {
+            if (deps.signal?.aborted)
+                break sessionLoop;
+            let state = readSessionState(sessionId, deps.workContextRoot);
+            state = applySessionMetaCompanyRebind(sessionId, items, state, deps, now);
+            const leaveResult = await postPresenceLeaveIfNeeded({
+                sessionId,
+                items,
+                state,
+                deps,
+                now,
+                maxAttempts,
+                sleep,
+                random,
+                summary,
+                markDisposed,
+            });
+            state = leaveResult.state;
+            if (leaveResult.abort)
+                continue;
+            const remainingItems = leaveResult.items;
+            if (state?.companyConfidence === "device_default" &&
+                deps.authorizeDeviceDefaultTenant) {
+                const allowed = await deps.authorizeDeviceDefaultTenant(state);
+                // Authorization may restore a company the gate previously cleared.
+                state = readSessionState(sessionId, deps.workContextRoot) ?? state;
+                if (!allowed) {
+                    const heldAt = now().toISOString();
+                    summary.held += appendHeldLinesIfAbsent(remainingItems.map((item) => heldEnvelope(item.event, "NEEDS_COMPANY", item.heldAt ?? heldAt)), deps.workMeshRoot);
+                    for (const item of remainingItems)
+                        markDisposed(item.event);
+                    continue;
+                }
+            }
+            // After the company gate (which may restore a cleared company), try to
+            // bind a needs_project session to an existing Board before classifying.
+            state = rebindUnboundSession(sessionId, remainingItems, state, deps, nowMs);
             const decision = classifySession(state);
             if (decision.action === "drop") {
                 appendDroppedReceipt({
                     v: 1,
                     sessionId,
-                    dropped: items.length,
+                    dropped: remainingItems.length,
                     reason: "untracked",
                     at: now().toISOString(),
                 }, deps.workMeshRoot);
-                summary.dropped += items.length;
-                for (const item of items)
+                summary.dropped += remainingItems.length;
+                for (const item of remainingItems)
                     markDisposed(item.event);
                 continue;
             }
             if (decision.action === "hold") {
                 const heldAt = now().toISOString();
-                for (const item of items) {
-                    appendHeldLine(heldEnvelope(item.event, decision.heldReason, item.heldAt ?? heldAt), deps.workMeshRoot);
-                    summary.held += 1;
+                summary.held += appendHeldLinesIfAbsent(remainingItems.map((item) => heldEnvelope(item.event, decision.heldReason, item.heldAt ?? heldAt)), deps.workMeshRoot);
+                for (const item of remainingItems)
                     markDisposed(item.event);
-                }
                 continue;
             }
-            // Post path: strip local-only, batch ≤100, retry.
-            const stripped = items.map((item) => stripLocalOnlyFields(item.event));
+            // Post a bounded portion of this session's remaining backlog (after any
+            // presence-leave). Untouched events stay in pendingRestore and are put
+            // back on the spool below.
+            const flushItems = remainingItems.slice(0, SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH);
+            const stripped = flushItems.map((item) => stripLocalOnlyFields(enrichSessionEndEvent(item.event)));
             for (let i = 0; i < stripped.length; i += SESSION_EVENTS_BATCH_MAX) {
                 const chunk = stripped.slice(i, i + SESSION_EVENTS_BATCH_MAX);
-                const originalChunk = items.slice(i, i + SESSION_EVENTS_BATCH_MAX);
+                const originalChunk = flushItems.slice(i, i + SESSION_EVENTS_BATCH_MAX);
                 const body = {
                     contractVersion: 1,
                     companyUid: decision.companyUid,
@@ -222,11 +335,40 @@ export async function flushSessionEvents(deps) {
                     maxAttempts,
                     sleep,
                     random,
+                    signal: deps.signal,
                 });
                 if (result.ok) {
                     accountBatchSuccess(result.body, originalChunk, deps.workMeshRoot, now, summary, markDisposed);
                     continue;
                 }
+                if (!result.retryable && result.status === 404) {
+                    const rejectedProjectId = decision.projectId;
+                    updateSessionState(sessionId, deps.workContextRoot, (current) => {
+                        if (!current)
+                            return current;
+                        return {
+                            ...current,
+                            contextStatus: "needs_project",
+                            projectGate: "missing_board",
+                            projectBindReason: "server returned HTTP 404 for this session's project",
+                            projectCandidates: rejectedProjectId
+                                ? [{ projectId: rejectedProjectId }]
+                                : current.projectCandidates,
+                            projectId: undefined,
+                            taskId: undefined,
+                            updatedAt: now().toISOString(),
+                        };
+                    });
+                    if (!loggedProject404.has(sessionId)) {
+                        loggedProject404.add(sessionId);
+                        deps.log?.(`work-mesh: session ${sessionId} project missing (HTTP 404); downgraded to needs_project and held events`);
+                    }
+                    const heldAt = now().toISOString();
+                    summary.held += appendHeldLinesIfAbsent(originalChunk.map((item) => heldEnvelope(item.event, "NEEDS_PROJECT", item.heldAt ?? heldAt)), deps.workMeshRoot);
+                    for (const item of originalChunk)
+                        markDisposed(item.event);
+                    continue;
+                }
                 if (!result.retryable) {
                     const at = now().toISOString();
                     for (const item of originalChunk) {
@@ -243,6 +385,10 @@ export async function flushSessionEvents(deps) {
                     summary.restored += 1;
                     markDisposed(item.event);
                 }
+                if (result.status === 429 || result.status === 503)
+                    break;
+                if (deps.signal?.aborted)
+                    break sessionLoop;
             }
         }
     }
@@ -277,15 +423,17 @@ export async function flushSessionEvents(deps) {
  *   flusher (`hq mesh flush` beside the daemon) may have appended to a fresh
  *   held.jsonl after our claim renamed the old one away.
  * - The overflow claim file is removed only after every dead letter and every
- *   retained line is on disk. If anything throws, the claim stays behind and
- *   recoverOrphanClaims re-reads it on the next flush (duplicates are possible,
- *   loss is not).
+ *   retained line is on disk. Retained rows are idempotent by eventId, so a
+ *   retry after an interrupted append is safe; the claim stays until recovery
+ *   can finish, preserving the append-before-remove ordering.
  */
 function trimHeldOverflow(meshRoot, maxLines, now, summary) {
     if (maxLines <= 0)
         return 0;
     const heldPath = workMeshHeldPath(meshRoot);
-    if (countJsonlLines(heldPath) <= maxLines)
+    const lineCount = countJsonlLines(heldPath);
+    const distinctCount = countDistinctHeldEvents(heldPath);
+    if (lineCount <= maxLines && lineCount === distinctCount)
         return 0;
     const claim = claimHeld(meshRoot, `${now().getTime()}.overflow`);
     if (!claim.claimPath)
@@ -295,15 +443,26 @@ function trimHeldOverflow(meshRoot, maxLines, now, summary) {
         return 0;
     }
     try {
-        if (claim.lines.length <= maxLines) {
-            appendHeldLines(meshRoot, claim.lines);
+        const alreadyHeldIds = readHeldEventIds(heldPath);
+        const seenClaimIds = new Set();
+        const uniqueLines = claim.lines.filter((line) => {
+            const eventId = heldEventIdOfLine(line);
+            if (!eventId)
+                return true;
+            if (alreadyHeldIds.has(eventId) || seenClaimIds.has(eventId))
+                return false;
+            seenClaimIds.add(eventId);
+            return true;
+        });
+        if (uniqueLines.length <= maxLines) {
+            appendHeldLinesOnce(meshRoot, uniqueLines);
             removeClaimFile(claim.claimPath);
             return 0;
         }
-        const overflow = claim.lines.length - maxLines;
+        const overflow = uniqueLines.length - maxLines;
         // Oldest by heldAt: retries regroup held by session, so file order is not
         // chronological. Unparseable lines sort first (dead-lettered first).
-        const ordered = claim.lines
+        const ordered = uniqueLines
             .map((line, idx) => ({ line, idx, atMs: heldAtMs(line) }))
             .sort((a, b) => a.atMs - b.atMs || a.idx - b.idx);
         const toDead = ordered.slice(0, overflow);
@@ -323,7 +482,7 @@ function trimHeldOverflow(meshRoot, maxLines, now, summary) {
             }
             summary.deadLettered += 1;
         }
-        appendHeldLines(meshRoot, toKeep);
+        appendHeldLinesOnce(meshRoot, toKeep);
         summary.heldOverflow = overflow;
         removeClaimFile(claim.claimPath);
         return overflow;
@@ -344,12 +503,25 @@ function heldAtMs(line) {
     const ms = Date.parse(heldAt);
     return Number.isFinite(ms) ? ms : 0;
 }
-function appendHeldLines(meshRoot, lines) {
-    if (lines.length === 0)
-        return;
-    const heldPath = workMeshHeldPath(meshRoot);
-    ensureSpoolFile(heldPath);
-    fs.appendFileSync(heldPath, `${lines.join("\n")}\n`, { mode: 0o600 });
+function appendHeldLinesOnce(meshRoot, lines) {
+    appendHeldLinesIfAbsent(lines, meshRoot);
+}
+function heldEventIdOfLine(line) {
+    const parsed = parseLine(line);
+    return parsed ? eventIdOf(unwrapHeld(parsed).event) : null;
+}
+function readHeldEventIds(filePath) {
+    if (!fs.existsSync(filePath))
+        return new Set();
+    const ids = new Set();
+    for (const line of fs.readFileSync(filePath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        const id = heldEventIdOfLine(line);
+        if (id)
+            ids.add(id);
+    }
+    return ids;
 }
 /**
  * Account a 2xx batch: dead-letter rejected eventIds with their codes;
@@ -378,7 +550,7 @@ function accountBatchSuccess(body, originalChunk, meshRoot, now, summary, markDi
         const item = byId.get(row.eventId);
         if (!item)
             continue;
-        appendDeadLetterLine(deadLetterEnvelope(item.event, row.code, row.code, at), meshRoot);
+        appendDeadLetterLine(deadLetterEnvelope(item.event, row.code, row.code, at, row.code), meshRoot);
         summary.deadLettered += 1;
         rejectedIds.add(row.eventId);
         markDisposed(item.event);
@@ -412,6 +584,184 @@ function canonicalizeForRestore(event) {
     }
     return out;
 }
+function eventText(event, key) {
+    const value = event[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+const SESSION_EVENT_HARNESSES = new Set([
+    "claude-code",
+    "claude-desktop",
+    "codex",
+    "grok",
+    "hq-sessions",
+    "agent-box",
+    "agents-v2",
+]);
+function applySessionMetaCompanyRebind(sessionId, items, state, deps, now) {
+    if (!state)
+        return state;
+    const hqRoot = items.map((item) => eventText(item.event, "hqRoot")).find(Boolean);
+    if (!hqRoot)
+        return state;
+    const meta = readMetaCompanySlug(sessionId, hqRoot);
+    if (!meta)
+        return state;
+    if (!companyBindingChanged(state, { slug: meta }))
+        return state;
+    const next = reboundSessionProjection({
+        prior: state,
+        sessionId,
+        nextSlug: meta,
+        nowIso: now().toISOString(),
+    });
+    writeSessionState(next, deps.workContextRoot);
+    return readSessionState(sessionId, deps.workContextRoot) ?? next;
+}
+function leaveContextStatus(leave) {
+    if (leave.projectId && leave.taskId)
+        return "bound";
+    if (leave.projectId)
+        return "needs_task";
+    return "needs_project";
+}
+function synthesizeSessionEnd(sessionId, sample, seq, at) {
+    const harnessRaw = eventText(sample, "harness");
+    const harness = harnessRaw && SESSION_EVENT_HARNESSES.has(harnessRaw)
+        ? harnessRaw
+        : "claude-code";
+    return stripLocalOnlyFields(enrichSessionEndEvent({
+        v: 1,
+        eventId: generateUlid(),
+        kind: "session_end",
+        sessionId,
+        harness,
+        adapterVersion: eventText(sample, "adapterVersion") || "1.0.0",
+        at,
+        seq,
+        cwd: eventText(sample, "cwd"),
+    }));
+}
+async function postPresenceLeaveIfNeeded(input) {
+    const leave = input.state?.presenceLeave;
+    if (!leave?.companyUid) {
+        return { state: input.state, items: input.items, abort: false };
+    }
+    const oldSlug = leave.companySlug?.trim().toLowerCase();
+    const leaveItems = oldSlug
+        ? input.items.filter((item) => {
+            const slug = eventText(item.event, "companySlug")?.toLowerCase();
+            return slug === oldSlug;
+        })
+        : [];
+    const remaining = input.items.filter((item) => !leaveItems.includes(item));
+    const sample = leaveItems[0]?.event ?? input.items[0]?.event ?? {};
+    const maxSeq = input.items.reduce((max, item) => {
+        const seq = item.event.seq;
+        return typeof seq === "number" && Number.isFinite(seq) ? Math.max(max, seq) : max;
+    }, 0);
+    const sessionEnd = synthesizeSessionEnd(input.sessionId, sample, maxSeq + 1, input.now().toISOString());
+    const events = [
+        ...leaveItems.map((item) => stripLocalOnlyFields(item.event)),
+        sessionEnd,
+    ];
+    const body = {
+        contractVersion: 1,
+        companyUid: leave.companyUid,
+        sessionId: input.sessionId,
+        contextStatus: leaveContextStatus(leave),
+        events,
+    };
+    if (leave.bindingEpisodeId)
+        body.bindingEpisodeId = leave.bindingEpisodeId;
+    if (leave.projectId)
+        body.projectId = leave.projectId;
+    if (leave.taskId)
+        body.taskId = leave.taskId;
+    input.summary.batches += 1;
+    const result = await postBatchWithRetries(input.deps.poster, body, {
+        maxAttempts: input.maxAttempts,
+        sleep: input.sleep,
+        random: input.random,
+        signal: input.deps.signal,
+    });
+    if (!result.ok) {
+        const at = input.now().toISOString();
+        if (!result.retryable) {
+            for (const item of input.items) {
+                appendDeadLetterLine(deadLetterEnvelope(item.event, `HTTP_${result.status}`, result.status, at), input.deps.workMeshRoot);
+                input.summary.deadLettered += 1;
+                input.markDisposed(item.event);
+            }
+            return { state: input.state, items: [], abort: true };
+        }
+        for (const item of input.items) {
+            appendSpoolLine(JSON.stringify(canonicalizeForRestore(item.event)), input.deps.workMeshRoot);
+            input.summary.restored += 1;
+            input.markDisposed(item.event);
+        }
+        return { state: input.state, items: [], abort: true };
+    }
+    accountBatchSuccess({
+        accepted: events.length,
+        duplicates: 0,
+        rejected: [],
+    }, [...leaveItems, { event: sessionEnd }], input.deps.workMeshRoot, input.now, input.summary, input.markDisposed);
+    const cleared = updateSessionState(input.sessionId, input.deps.workContextRoot, (current) => {
+        if (!current)
+            return current;
+        const { presenceLeave: _leave, ...rest } = current;
+        return { ...rest, updatedAt: input.now().toISOString() };
+    });
+    return {
+        state: cleared ?? input.state,
+        items: remaining,
+        abort: false,
+    };
+}
+/**
+ * Before a needs_project (or unresolved-with-company) batch is classified,
+ * run the prompt-submit bind-best refinement. A bind updates the session
+ * file so the batch posts with that projectId. Ties stay unbound. At most
+ * one attempt per session per minute; failures stay on the existing state.
+ */
+function rebindUnboundSession(sessionId, items, state, deps, nowMs) {
+    if (!state?.companyUid)
+        return state;
+    if (state.contextStatus !== "needs_project" && state.contextStatus !== "unresolved") {
+        return state;
+    }
+    const key = `${deps.workContextRoot}\0${sessionId}`;
+    const previous = lastProjectRebindAtMs.get(key);
+    if (previous !== undefined && nowMs - previous < PROJECT_REBIND_INTERVAL_MS) {
+        return state;
+    }
+    lastProjectRebindAtMs.set(key, nowMs);
+    const sample = items[0]?.event ?? {};
+    const started = Date.now();
+    try {
+        rebindNeedsProjectOnPrompt({
+            sessionId,
+            root: deps.workContextRoot,
+            hqRoot: eventText(sample, "hqRoot"),
+            cwd: eventText(sample, "cwd"),
+            companySlug: state.companySlug ?? eventText(sample, "companySlug"),
+            companyUid: state.companyUid,
+            hint: eventText(sample, "project"),
+            env: deps.env,
+            home: deps.home,
+            nowMs,
+            now: deps.now,
+        });
+    }
+    catch (err) {
+        deps.log?.(`work-mesh: session ${sessionId} project rebind failed: ${err instanceof Error ? err.message : "unknown"}`);
+    }
+    const elapsed = Date.now() - started;
+    if (elapsed > 300) {
+        deps.log?.(`work-mesh: session ${sessionId} project rebind took ${elapsed}ms`);
+    }
+    return readSessionState(sessionId, deps.workContextRoot) ?? state;
+}
 function classifySession(state) {
     if (!state) {
         return { action: "hold", heldReason: "STATE_ABSENT" };
@@ -425,6 +775,9 @@ function classifySession(state) {
     if (state.contextStatus === "company_conflict") {
         return { action: "hold", heldReason: "COMPANY_CONFLICT" };
     }
+    if (state.projectGate === "choose" || state.projectGate === "missing_board") {
+        return { action: "hold", heldReason: "NEEDS_PROJECT" };
+    }
     if (!WRITABLE_CONTEXT_STATUSES.has(state.contextStatus)) {
         return { action: "hold", heldReason: "STATE_ABSENT" };
     }

package/dist/lib/mesh/live/format-spool-line.d.ts

@@ -5,7 +5,7 @@
 export declare const LOCAL_ONLY_FIELDS: readonly ["cwd", "hqRoot", "companySlug", "project", "task", "toolWrites"];
 export type LocalOnlyField = (typeof LOCAL_ONLY_FIELDS)[number];
 /** Network + local key order matching work-mesh-enqueue.sh. */
-export declare const SPOOL_KEY_ORDER: readonly ["v", "eventId", "kind", "sessionId", "harness", "adapterVersion", "runtimeVersion", "source", "at", "seq", "taskId", "status", "reason", "summary", "cwd", "hqRoot", "companySlug", "project", "task", "toolWrites"];
+export declare const SPOOL_KEY_ORDER: readonly ["v", "eventId", "kind", "sessionId", "harness", "adapterVersion", "runtimeVersion", "source", "at", "seq", "taskId", "status", "reason", "summary", "repo", "gitBranch", "prUrls", "cwd", "hqRoot", "companySlug", "project", "task", "toolWrites"];
 export type SessionEventKind = "session_start" | "turn_start" | "turn_end" | "session_end" | "task_status" | "blocked" | "note";
 export type SessionEventHarness = "claude-code" | "claude-desktop" | "codex" | "grok" | "hq-sessions" | "agent-box" | "agents-v2";
 export type SessionEventSource = "hooks" | "transcript";
@@ -24,6 +24,9 @@ export interface SpoolEventInput {
     status?: "queued" | "in_progress" | "review" | "done";
     reason?: string;
     summary?: string;
+    repo?: string;
+    gitBranch?: string;
+    prUrls?: string[];
     cwd?: string;
     hqRoot?: string;
     companySlug?: string;
@@ -35,7 +38,7 @@ export interface SpoolEventInput {
  * Build a compact JSON object in SPOOL_KEY_ORDER, omitting absent optional
  * strings. `toolWrites` is included when it is a finite number >= 0 (including 0).
  */
-export declare function buildOrderedSpoolObject(input: SpoolEventInput): Record<string, string | number>;
+export declare function buildOrderedSpoolObject(input: SpoolEventInput): Record<string, string | number | string[]>;
 /** Compact JSON line body (no trailing newline). */
 export declare function formatSpoolLine(input: SpoolEventInput): string;
 export declare function stripLocalOnlyFields(event: Record<string, unknown>): Record<string, unknown>;

package/dist/lib/mesh/live/format-spool-line.js

@@ -26,6 +26,9 @@ export const SPOOL_KEY_ORDER = [
     "status",
     "reason",
     "summary",
+    "repo",
+    "gitBranch",
+    "prUrls",
     "cwd",
     "hqRoot",
     "companySlug",
@@ -63,6 +66,13 @@ export function buildOrderedSpoolObject(input) {
         out.reason = input.reason;
     if (includeString(input.summary))
         out.summary = input.summary;
+    if (includeString(input.repo))
+        out.repo = input.repo;
+    if (includeString(input.gitBranch))
+        out.gitBranch = input.gitBranch;
+    if (Array.isArray(input.prUrls) && input.prUrls.length > 0) {
+        out.prUrls = input.prUrls.filter(includeString).slice(0, 5);
+    }
     if (includeString(input.cwd))
         out.cwd = input.cwd;
     if (includeString(input.hqRoot))

package/dist/lib/mesh/live/paths.d.ts

@@ -6,6 +6,8 @@ export declare const WORK_MESH_DIRNAME = "work-mesh";
 export declare function workMeshRoot(home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function workMeshSpoolPath(root?: string): string;
 export declare function workMeshHeldPath(root?: string): string;
+/** Rotating cursor for bounded daemon-start held-event recovery. */
+export declare function workMeshHeldBackfillCursorPath(root?: string): string;
 export declare function workMeshDeadLetterPath(root?: string): string;
 export declare function workMeshDroppedReceiptPath(root?: string): string;
 /** Claim path: spool.<ts>.claimed (never reuse spool.jsonl for claim). */

package/dist/lib/mesh/live/paths.js

@@ -17,6 +17,10 @@ export function workMeshSpoolPath(root) {
 export function workMeshHeldPath(root) {
     return path.join(root ?? workMeshRoot(), "held.jsonl");
 }
+/** Rotating cursor for bounded daemon-start held-event recovery. */
+export function workMeshHeldBackfillCursorPath(root) {
+    return path.join(root ?? workMeshRoot(), "held-backfill-cursor.json");
+}
 export function workMeshDeadLetterPath(root) {
     return path.join(root ?? workMeshRoot(), "dead-letter.jsonl");
 }