@indigoai-us/hq-cli 5.345.62 → 5.345.64

package/dist/lib/lanes/loop.js

@@ -305,6 +305,9 @@ function fileEnvelope(file) {
     if (!isRecord(value) || value.schema_version !== LOOP_SCHEMA || !nonEmpty(value.envelope_id) || !nonEmpty(value.queued_at)) {
         throw new Error(`Invalid queued loop envelope record: ${file}`);
     }
+    if (value.stall_attempts !== undefined && (!Number.isSafeInteger(value.stall_attempts) || Number(value.stall_attempts) < 0)) {
+        throw new Error(`Invalid stall_attempts in queued loop envelope record: ${file}`);
+    }
     return { ...value, envelope: validateLoopEnvelope(value.envelope) };
 }
 /** Queue depth and FIFO ordering are based on the timestamp-prefixed filename. */
@@ -329,34 +332,41 @@ export function enqueueLoopEnvelope(input) {
     fs.mkdirSync(dir, { recursive: true });
     const release = acquireEnqueueLock(input.runDir);
     try {
-        const records = [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir), path.join(input.runDir, "loop", "stalled"), path.join(input.runDir, "loop", "withdrawn")]
-            .flatMap(envelopeFiles)
-            .map((file) => {
+        const withdrawnDir = path.join(input.runDir, "loop", "withdrawn");
+        const stalledDir = path.join(input.runDir, "loop", "stalled");
+        const records = [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir), stalledDir, withdrawnDir]
+            .flatMap((dir) => envelopeFiles(dir).map((file) => ({ file, dir })))
+            .map(({ file, dir }) => {
             try {
-                return fileEnvelope(file);
+                return { file, dir, record: fileEnvelope(file) };
             }
             catch (error) {
                 process.stderr.write(`hq lanes: ignored unreadable loop record ${file}: ${error instanceof Error ? error.message : String(error)}\n`);
                 return undefined;
             }
         })
-            .filter((record) => record !== undefined);
-        const withdrawnDir = path.join(input.runDir, "loop", "withdrawn");
-        const stalledDir = path.join(input.runDir, "loop", "stalled");
-        const reusableRecords = records.filter((record) => record.envelope_id === envelopeId);
+            .filter((entry) => entry !== undefined);
+        const reusableRecords = records.filter(({ record }) => record.envelope_id === envelopeId);
         const terminalResult = fs.existsSync(path.join(resultsDir(input.runDir), resultName(envelopeId)))
             ? readJson(path.join(resultsDir(input.runDir), resultName(envelopeId))) : undefined;
-        const reusable = reusableRecords.length > 0 && reusableRecords.every((record) => [stalledDir, withdrawnDir].some((dir) => envelopeFiles(dir).some((file) => {
+        const reusable = reusableRecords.length > 0 && reusableRecords.every(({ dir }) => dir === stalledDir || dir === withdrawnDir) &&
+            !reusableRecords.some(({ dir }) => dir === pendingDir(input.runDir) || dir === activeDir(input.runDir) || dir === claimedDir(input.runDir)) &&
+            (!isRecord(terminalResult) || terminalResult.status === "stalled");
+        if ((reusableRecords.length > 0 && !reusable) ||
+            (terminalResult !== undefined && (!reusable || !isRecord(terminalResult) || terminalResult.status !== "stalled"))) {
+            throw new Error(`envelope id ${envelopeId} was already used in this loop lane`);
+        }
+        const incomingStop = envelope.kind === "stop";
+        const blockingStop = [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir)].some((scanDir) => envelopeFiles(scanDir).some((file) => {
             try {
-                return fileEnvelope(file).envelope_id === record.envelope_id;
+                return fileEnvelope(file).envelope.kind === "stop";
             }
             catch {
                 return false;
             }
-        }))) && (!isRecord(terminalResult) || terminalResult.status === "stalled");
-        if ((records.some((record) => record.envelope_id === envelopeId) && !reusable) ||
-            (terminalResult !== undefined && (!reusable || !isRecord(terminalResult) || terminalResult.status !== "stalled"))) {
-            throw new Error(`envelope id ${envelopeId} was already used in this loop lane`);
+        }));
+        if (blockingStop) {
+            throw new Error(incomingStop ? "a stop envelope is already queued or active" : "cannot enqueue a phase after a stop envelope");
         }
         if (reusable) {
             for (const file of envelopeFiles(withdrawnDir).concat(envelopeFiles(stalledDir))) {
@@ -374,23 +384,11 @@ export function enqueueLoopEnvelope(input) {
                 fs.renameSync(resultFile, asidePath(resultFile, "stalled"));
             }
         }
-        const incomingStop = envelope.kind === "stop";
-        const blockingStop = [pendingDir(input.runDir), activeDir(input.runDir)].some((scanDir) => envelopeFiles(scanDir).some((file) => {
-            try {
-                return fileEnvelope(file).envelope.kind === "stop";
-            }
-            catch {
-                return false;
-            }
-        }));
-        if (blockingStop) {
-            throw new Error(incomingStop ? "a stop envelope is already queued or active" : "cannot enqueue a phase after a stop envelope");
-        }
         const sequence = nextQueueSequence(input.runDir);
         const prefix = `${String(sequence).padStart(16, "0")}-${String(now.getTime()).padStart(13, "0")}-${randomUUID()}`;
         const destination = path.join(dir, `${prefix}-${envelopeId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
         const temporary = `${destination}.${process.pid}.tmp`;
-        const record = { schema_version: LOOP_SCHEMA, envelope_id: envelopeId, queued_at: queuedAt, envelope };
+        const record = { schema_version: LOOP_SCHEMA, envelope_id: envelopeId, queued_at: queuedAt, stall_attempts: 0, envelope };
         try {
             fs.writeFileSync(temporary, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
             fs.renameSync(temporary, destination);
@@ -417,6 +415,12 @@ export function enqueueLoopEnvelope(input) {
 export function claimNextLoopEnvelope(runDir) {
     fs.mkdirSync(activeDir(runDir), { recursive: true });
     fs.mkdirSync(claimedDir(runDir), { recursive: true });
+    // A previous controller may have written a stop result but failed before moving the active record to claimed.
+    for (const active of envelopeFiles(activeDir(runDir))) {
+        const record = fileEnvelope(active);
+        if (record.envelope.kind === "stop")
+            return { file: active, record };
+    }
     for (const pending of envelopeFiles(pendingDir(runDir))) {
         const active = path.join(activeDir(runDir), path.basename(pending));
         try {
@@ -453,7 +457,7 @@ export function interruptLoopQueue(runDir) {
     }
     return { withdrawn, already_picked_up: alreadyPickedUp };
 }
-export function interruptLoopQueueForStory(runDir, storyId, phase) {
+export function interruptLoopQueueForStory(runDir, storyId, phase, hooks = {}) {
     const withdrawn = [];
     const alreadyPickedUp = [];
     const matches = (record) => {
@@ -461,28 +465,51 @@ export function interruptLoopQueueForStory(runDir, storyId, phase) {
         return envelope.story_id === storyId && (phase === undefined || envelope.phase === phase);
     };
     for (const file of envelopeFiles(pendingDir(runDir))) {
-        const record = fileEnvelope(file);
+        let record;
+        hooks.beforePendingRead?.(file);
+        try {
+            record = fileEnvelope(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
         if (!matches(record))
             continue;
         const destination = path.join(runDir, "loop", "withdrawn", path.basename(file));
         fs.mkdirSync(path.dirname(destination), { recursive: true });
-        fs.renameSync(file, destination);
-        withdrawn.push(record.envelope_id);
+        hooks.beforePendingRename?.(file);
+        try {
+            fs.renameSync(file, destination);
+            withdrawn.push(record.envelope_id);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            alreadyPickedUp.push(record.envelope_id);
+        }
     }
     for (const file of envelopeFiles(activeDir(runDir))) {
         const record = fileEnvelope(file);
         if (matches(record))
             alreadyPickedUp.push(record.envelope_id);
     }
-    return { withdrawn, already_picked_up: alreadyPickedUp };
+    return { withdrawn, already_picked_up: [...new Set(alreadyPickedUp)] };
 }
-export function applyLoopStallAnswer(input) {
-    const results = fs.existsSync(resultsDir(input.runDir))
-        ? fs.readdirSync(resultsDir(input.runDir)).filter((name) => name.endsWith(".json")) : [];
-    const resultPath = results.map((name) => path.join(resultsDir(input.runDir), name)).find((file) => {
+function stalledResultArchives(runDir) {
+    return fs.existsSync(resultsDir(runDir))
+        ? fs.readdirSync(resultsDir(runDir)).filter((name) => /\.stalled\.\d+\.json$/.test(name))
+        : [];
+}
+export function findLoopStallResult(runDir, questionId) {
+    const archivedNames = new Set(stalledResultArchives(runDir));
+    const results = fs.existsSync(resultsDir(runDir))
+        ? fs.readdirSync(resultsDir(runDir)).filter((name) => name.endsWith(".json") && !archivedNames.has(name)) : [];
+    const resultPath = results.map((name) => path.join(resultsDir(runDir), name)).find((file) => {
         try {
             const result = readJson(file);
-            return isRecord(result) && result.status === "stalled" && result.question_id === input.questionId;
+            return isRecord(result) && result.status === "stalled" && result.question_id === questionId;
         }
         catch (error) {
             if (error instanceof SyntaxError)
@@ -490,9 +517,35 @@ export function applyLoopStallAnswer(input) {
             throw error;
         }
     });
-    if (!resultPath)
+    return resultPath ? readJson(resultPath) : undefined;
+}
+export function applyLoopStallAnswer(input) {
+    const result = findLoopStallResult(input.runDir, input.questionId);
+    if (!result) {
+        for (const name of stalledResultArchives(input.runDir)) {
+            try {
+                const archived = readJson(path.join(resultsDir(input.runDir), name));
+                if (!isRecord(archived) || archived.status !== "stalled" || archived.question_id !== input.questionId)
+                    continue;
+                const envelopeId = String(archived.envelope_id);
+                for (const dir of [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir)]) {
+                    const match = envelopeFiles(dir).find((file) => fileEnvelope(file).envelope_id === envelopeId);
+                    if (!match)
+                        continue;
+                    const isAnswer = path.basename(match).startsWith("0000000000000-answer-");
+                    return { lane_id: path.basename(input.runDir), envelope_id: envelopeId, action: isAnswer && dir === pendingDir(input.runDir) ? "requeued" : "already_applied" };
+                }
+                return { lane_id: path.basename(input.runDir), envelope_id: envelopeId, action: "already_applied" };
+            }
+            catch (error) {
+                if (error instanceof SyntaxError || error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+        }
         return undefined;
-    const result = readJson(resultPath);
+    }
+    const resultPath = path.join(resultsDir(input.runDir), resultName(result.envelope_id));
     const envelopeFile = envelopeFiles(path.join(input.runDir, "loop", "stalled")).find((file) => {
         try {
             return fileEnvelope(file).envelope_id === result.envelope_id;
@@ -506,15 +559,17 @@ export function applyLoopStallAnswer(input) {
     const record = fileEnvelope(envelopeFile);
     const action = input.choice === "Retry with a longer deadline" ? "requeued" : "parked";
     if (action === "requeued") {
-        record.deadline_budget_seconds = Math.max(1, record.deadline_budget_seconds ?? phaseDeadlineBudget(record.envelope, 3600)) * 2;
+        record.deadline_budget_seconds = (record.deadline_budget_seconds ?? phaseDeadlineBudget(record.envelope, 3600)) * 2;
+        record.stall_attempts = 0;
         const head = path.join(pendingDir(input.runDir), `0000000000000-answer-${path.basename(envelopeFile)}`);
         fs.mkdirSync(pendingDir(input.runDir), { recursive: true });
         fs.renameSync(envelopeFile, head);
         fs.renameSync(resultPath, asidePath(resultPath, "stalled"));
         const pending = fileEnvelope(head);
         pending.deadline_budget_seconds = record.deadline_budget_seconds;
+        pending.stall_attempts = 0;
         atomicJson(head, pending);
-        persistStatus(input.runDir, path.basename(input.runDir), { stall_counts: { [record.envelope_id]: 0 } });
+        persistStallCount(input.runDir, path.basename(input.runDir), record.envelope_id, 0);
     }
     else {
         atomicJson(resultPath, {
@@ -613,6 +668,15 @@ function phaseDeadlineBudget(envelope, defaultSeconds) {
     const configured = Number(process.env.HQ_LANE_LOOP_PHASE_DEADLINE_SECS);
     return Number.isFinite(configured) && configured > 0 ? configured : defaultSeconds;
 }
+function persistStallCount(runDir, laneId, envelopeId, count) {
+    const status = loopStatus(runDir, laneId);
+    persistStatus(runDir, laneId, { stall_counts: { ...status.stall_counts, [envelopeId]: count } });
+}
+function clearPersistedStallCount(runDir, laneId, envelopeId) {
+    const counts = loopStatus(runDir, laneId).stall_counts;
+    delete counts[envelopeId];
+    persistStatus(runDir, laneId, { stall_counts: counts });
+}
 function persistStatus(runDir, laneId, patch) {
     let current = {};
     try {
@@ -658,7 +722,7 @@ export async function runLoopLane(options) {
     const stalls = new Map();
     let completed = 0;
     fs.mkdirSync(options.runDir, { recursive: true });
-    const releaseRunner = acquireRunnerLease(options.runDir);
+    let releaseRunner = acquireRunnerLease(options.runDir);
     persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid });
     try {
         const previous = readJson(loopPath(options.runDir));
@@ -673,7 +737,7 @@ export async function runLoopLane(options) {
         if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
             throw error;
     }
-    persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: {} });
+    persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
     while (!options.signal?.aborted) {
         const claimed = claimNextLoopEnvelope(options.runDir);
         if (!claimed) {
@@ -685,8 +749,29 @@ export async function runLoopLane(options) {
         const envelope = record.envelope;
         if (envelope.kind === "stop") {
             const stopped = { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "stopped", started_at: record.queued_at, finished_at: now().toISOString() };
-            writeResultAt(options.runDir, file, record, stopped);
-            persistStatus(options.runDir, options.lane.lane_id, { state: "stopped", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+            try {
+                writeResultAt(options.runDir, file, record, stopped);
+                persistStatus(options.runDir, options.lane.lane_id, { state: "stopped", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
+            }
+            catch (error) {
+                const cleanupErrors = [];
+                try {
+                    releaseRunner();
+                }
+                catch (cleanupError) {
+                    cleanupErrors.push(cleanupError);
+                }
+                releaseRunner = () => { };
+                try {
+                    clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+                }
+                catch (cleanupError) {
+                    cleanupErrors.push(cleanupError);
+                }
+                if (cleanupErrors.length)
+                    throw new AggregateError([error, ...cleanupErrors], "Could not recover after committing a stop envelope");
+                throw error;
+            }
             releaseRunner();
             return { state: "stopped", completed };
         }
@@ -700,12 +785,12 @@ export async function runLoopLane(options) {
         const absoluteDeadline = envelope.deadline;
         const budget = record.deadline_budget_seconds ?? firstDeadline.get(record.envelope_id) ??
             (typeof absoluteDeadline === "string"
-                ? Math.max(1, Math.round((Date.parse(absoluteDeadline) - startedAtMs) / 1000))
+                ? Math.max(1, Math.round((Date.parse(absoluteDeadline) - startedAtMs) / 1000)) // An absolute deadline already in the past still gets a 1 s execution window.
                 : phaseDeadlineBudget(envelope, defaultDeadlineSeconds));
         firstDeadline.set(record.envelope_id, budget);
         record.deadline_budget_seconds = budget;
         atomicJson(file, record);
-        persistStatus(options.runDir, options.lane.lane_id, { state: "running", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: record.envelope_id, active_phase: phaseName(envelope, record.envelope_id), stall_counts: Object.fromEntries(stalls) });
+        persistStatus(options.runDir, options.lane.lane_id, { state: "running", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: record.envelope_id, active_phase: phaseName(envelope, record.envelope_id) });
         const timer = abortAfter(budget * 1000, options.signal);
         try {
             let result;
@@ -751,6 +836,7 @@ export async function runLoopLane(options) {
                 atomicJson(sessionsPath(options.runDir), Object.fromEntries(sessions));
             }
             stalls.delete(record.envelope_id);
+            clearPersistedStallCount(options.runDir, options.lane.lane_id, record.envelope_id);
             completed += 1;
         }
         catch (error) {
@@ -759,49 +845,75 @@ export async function runLoopLane(options) {
                 const pending = path.join(pendingDir(options.runDir), path.basename(file));
                 fs.mkdirSync(pendingDir(options.runDir), { recursive: true });
                 fs.renameSync(file, pending);
-                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
                 releaseRunner();
+                releaseRunner = () => { };
+                clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                 return { state: "aborted", completed };
             }
             if (!timer.signal.aborted) {
                 const failure = error instanceof Error ? error.message : String(error);
                 writeResultAt(options.runDir, file, record, { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "failed", started_at: startedAt, finished_at: now().toISOString(), error: failure });
                 completed += 1;
-                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                 continue;
             }
-            const attempt = (stalls.get(record.envelope_id) ?? 0) + 1;
+            const legacyCount = stalls.get(record.envelope_id) ?? 0;
+            const attempt = (record.stall_attempts ?? legacyCount) + 1;
             stalls.set(record.envelope_id, attempt);
-            persistStatus(options.runDir, options.lane.lane_id, { state: "running", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: record.envelope_id, active_phase: phaseName(envelope, record.envelope_id), stall_counts: Object.fromEntries(stalls) });
+            persistStallCount(options.runDir, options.lane.lane_id, record.envelope_id, attempt);
+            persistStatus(options.runDir, options.lane.lane_id, { state: "running", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: record.envelope_id, active_phase: phaseName(envelope, record.envelope_id) });
             appendJournal(options.runDir, { event: "phase_stalled", envelope_id: record.envelope_id, phase: phaseName(envelope, record.envelope_id), attempt, at: now().toISOString() });
             if (attempt === 1) {
                 timer.clear();
                 sessions.delete(sessionKey);
                 atomicJson(sessionsPath(options.runDir), Object.fromEntries(sessions));
                 // Restore the same envelope at the FIFO head. Rename preserves a single claim.
+                record.stall_attempts = 1;
+                atomicJson(file, record);
                 const head = path.join(pendingDir(options.runDir), `0000000000000-retry-${path.basename(file)}`);
                 fs.mkdirSync(pendingDir(options.runDir), { recursive: true });
                 fs.renameSync(file, head);
-                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                 continue;
             }
             const message = error instanceof Error ? error.message : String(error);
             const questionId = options.raiseQuestion ? randomUUID() : undefined;
             const result = { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "stalled", started_at: startedAt, finished_at: now().toISOString(), error: message, ...(questionId ? { question_id: questionId } : {}) };
             writeResultAt(options.runDir, file, record, result);
-            if (questionId)
-                await options.raiseQuestion?.({ envelope, envelopeId: record.envelope_id, attempt, error: message, questionId });
+            persistStatus(options.runDir, options.lane.lane_id, { state: "parked", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
             completed += 1;
-            persistStatus(options.runDir, options.lane.lane_id, { state: "parked", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
-            releaseRunner();
+            try {
+                if (questionId)
+                    await options.raiseQuestion?.({ envelope, envelopeId: record.envelope_id, attempt, error: message, questionId });
+            }
+            finally {
+                releaseRunner();
+                releaseRunner = () => { };
+                clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+            }
+            const answeredRetryIsPending = envelopeFiles(pendingDir(options.runDir)).some((pendingFile) => path.basename(pendingFile).startsWith("0000000000000-answer-") && fileEnvelope(pendingFile).envelope_id === record.envelope_id);
+            if (answeredRetryIsPending) {
+                try {
+                    releaseRunner = acquireRunnerLease(options.runDir);
+                    persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid, state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
+                    continue;
+                }
+                catch (leaseError) {
+                    if (!(leaseError instanceof Error) || !(leaseError.message.includes("already active") || leaseError.message.includes("claimed by another controller")))
+                        throw leaseError;
+                }
+            }
             return { state: "parked", completed };
         }
         finally {
             timer.clear();
         }
-        persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+        persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
     }
     releaseRunner();
+    clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+    persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
     return { state: "aborted", completed };
 }
 function appendJournal(runDir, value) {

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

@@ -10,6 +10,7 @@
  */
 import { type SessionStateFile } from "../../work-context/state.js";
 import { type RandomFn, type SleepFn } from "./backoff.js";
+import { type WorkLocationResolver } from "./work-location.js";
 import { type SessionEventsPoster } from "./session-events-client.js";
 export declare const HELD_TTL_MS: number;
 /** Re-attempt held events at most this often (spool still flushes every cycle). */
@@ -49,6 +50,11 @@ export interface FlushDeps {
     /** Passed through to bind-best (catalog cache root and HQ_WORK_MESH_CACHE). */
     env?: NodeJS.ProcessEnv;
     home?: string;
+    /**
+     * Derives repo / gitBranch / folder from the local cwd before it is
+     * stripped. Defaults to a per-flush cached git resolver (tests inject).
+     */
+    resolveWorkLocation?: WorkLocationResolver;
 }
 export interface FlushSummary {
     claimed: number;
@@ -67,7 +73,7 @@ export interface FlushSummary {
  * Flush spool + held. Safe to call concurrently with enqueue (claim-by-rename).
  * Recovers orphan `*.claimed` files first; restores unprocessed lines on throw.
  */
-export declare function flushSessionEvents(deps: FlushDeps): Promise<FlushSummary>;
+export declare function flushSessionEvents(inputDeps: FlushDeps): Promise<FlushSummary>;
 /**
  * Assert flush never opens the machine-global bind cache.
  * Used by tests; production flush has no reference to this path.

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

@@ -21,6 +21,7 @@ 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 { createWorkLocationResolver, withWorkLocation, } from "./work-location.js";
 import { SESSION_EVENTS_BATCH_MAX, WRITABLE_CONTEXT_STATUSES, parseSessionEventsBatchAck, } from "./session-events-client.js";
 import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLinesIfAbsent, appendSpoolLine, claimHeld, claimSpool, countDistinctHeldEvents, countJsonlLines, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
 import { workMeshHeldPath, workMeshRoot } from "./paths.js";
@@ -166,7 +167,13 @@ async function postBatchWithRetries(poster, body, deps) {
  * Flush spool + held. Safe to call concurrently with enqueue (claim-by-rename).
  * Recovers orphan `*.claimed` files first; restores unprocessed lines on throw.
  */
-export async function flushSessionEvents(deps) {
+export async function flushSessionEvents(inputDeps) {
+    // One resolver per flush: git lookups are cached per cwd for this flush only.
+    const deps = {
+        ...inputDeps,
+        resolveWorkLocation: inputDeps.resolveWorkLocation ?? createWorkLocationResolver(),
+    };
+    const resolveLocation = deps.resolveWorkLocation;
     const now = deps.now ?? (() => new Date());
     const sleep = deps.sleep ?? defaultSleep;
     const random = deps.random ?? Math.random;
@@ -313,7 +320,7 @@ export async function flushSessionEvents(deps) {
             // 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)));
+            const stripped = flushItems.map((item) => stripLocalOnlyFields(withWorkLocation(enrichSessionEndEvent(item.event), resolveLocation)));
             for (let i = 0; i < stripped.length; i += SESSION_EVENTS_BATCH_MAX) {
                 const chunk = stripped.slice(i, i + SESSION_EVENTS_BATCH_MAX);
                 const originalChunk = flushItems.slice(i, i + SESSION_EVENTS_BATCH_MAX);
@@ -624,12 +631,12 @@ function leaveContextStatus(leave) {
         return "needs_task";
     return "needs_project";
 }
-function synthesizeSessionEnd(sessionId, sample, seq, at) {
+function synthesizeSessionEnd(sessionId, sample, seq, at, resolveLocation) {
     const harnessRaw = eventText(sample, "harness");
     const harness = harnessRaw && SESSION_EVENT_HARNESSES.has(harnessRaw)
         ? harnessRaw
         : "claude-code";
-    return stripLocalOnlyFields(enrichSessionEndEvent({
+    return stripLocalOnlyFields(withWorkLocation(enrichSessionEndEvent({
         v: 1,
         eventId: generateUlid(),
         kind: "session_end",
@@ -639,7 +646,7 @@ function synthesizeSessionEnd(sessionId, sample, seq, at) {
         at,
         seq,
         cwd: eventText(sample, "cwd"),
-    }));
+    }), resolveLocation));
 }
 async function postPresenceLeaveIfNeeded(input) {
     const leave = input.state?.presenceLeave;
@@ -655,13 +662,14 @@ async function postPresenceLeaveIfNeeded(input) {
         : [];
     const remaining = input.items.filter((item) => !leaveItems.includes(item));
     const sample = leaveItems[0]?.event ?? input.items[0]?.event ?? {};
+    const resolveLocation = input.deps.resolveWorkLocation ?? createWorkLocationResolver();
     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 sessionEnd = synthesizeSessionEnd(input.sessionId, sample, maxSeq + 1, input.now().toISOString(), resolveLocation);
     const events = [
-        ...leaveItems.map((item) => stripLocalOnlyFields(item.event)),
+        ...leaveItems.map((item) => stripLocalOnlyFields(withWorkLocation(item.event, resolveLocation))),
         sessionEnd,
     ];
     const body = {

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", "repo", "gitBranch", "prUrls", "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", "folder", "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";
@@ -26,6 +26,8 @@ export interface SpoolEventInput {
     summary?: string;
     repo?: string;
     gitBranch?: string;
+    /** Network-only: basename of the session cwd (never a path). */
+    folder?: string;
     prUrls?: string[];
     cwd?: string;
     hqRoot?: string;

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

@@ -28,6 +28,7 @@ export const SPOOL_KEY_ORDER = [
     "summary",
     "repo",
     "gitBranch",
+    "folder",
     "prUrls",
     "cwd",
     "hqRoot",
@@ -70,6 +71,8 @@ export function buildOrderedSpoolObject(input) {
         out.repo = input.repo;
     if (includeString(input.gitBranch))
         out.gitBranch = input.gitBranch;
+    if (includeString(input.folder) && !/[/\\]/.test(input.folder))
+        out.folder = input.folder;
     if (Array.isArray(input.prUrls) && input.prUrls.length > 0) {
         out.prUrls = input.prUrls.filter(includeString).slice(0, 5);
     }

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

@@ -7,6 +7,8 @@ export type { ProhibitedContentClass, SessionEventValidationResult, } from "./va
 export { InvalidSessionIdentityError, SESSION_ID_ENV_KEYS, isValidSessionId, normalizeSessionIdentity, sessionIdFromEnv, } from "./session-identity.js";
 export type { NormalizeSessionIdentityInput, NormalizedSessionIdentity, } from "./session-identity.js";
 export { LOCAL_ONLY_FIELDS, SPOOL_KEY_ORDER, buildOrderedSpoolObject, formatSpoolLine, stripLocalOnlyFields, } from "./format-spool-line.js";
+export { createWorkLocationResolver, folderFromCwd, resolveWorkLocation, withWorkLocation, } from "./work-location.js";
+export type { WorkLocation, WorkLocationResolver } from "./work-location.js";
 export type { LocalOnlyField, SessionEventHarness, SessionEventKind, SessionEventSource, SpoolEventInput, } from "./format-spool-line.js";
 export { encodeCrockford, generateUlid, isUlid } from "./ulid.js";
 export { workMeshClaimPath, workMeshDeadLetterPath, workMeshDroppedReceiptPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "./paths.js";

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

@@ -5,6 +5,7 @@
 export { getSessionEventValidator, PROHIBITED_CONTENT_CLASSES, PROHIBITED_FIELD_BY_CLASS, redactValidationMessage, resolveHqProSchemaPath, SESSION_EVENT_SCHEMA_PATH, SESSION_EVENT_SCHEMA_SHA256, sha256File, sha256SessionEventSchema, validateSessionEvent, } from "./validate-session-event.js";
 export { InvalidSessionIdentityError, SESSION_ID_ENV_KEYS, isValidSessionId, normalizeSessionIdentity, sessionIdFromEnv, } from "./session-identity.js";
 export { LOCAL_ONLY_FIELDS, SPOOL_KEY_ORDER, buildOrderedSpoolObject, formatSpoolLine, stripLocalOnlyFields, } from "./format-spool-line.js";
+export { createWorkLocationResolver, folderFromCwd, resolveWorkLocation, withWorkLocation, } from "./work-location.js";
 export { encodeCrockford, generateUlid, isUlid } from "./ulid.js";
 export { workMeshClaimPath, workMeshDeadLetterPath, workMeshDroppedReceiptPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "./paths.js";
 export { SPOOL_LINE_MAX_BYTES, SpoolWriteError, appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendJsonlLine, appendSpoolLine, claimHeld, claimJsonlByRename, claimSpool, countJsonlLines, deadLetterNonEmpty, ensureSpoolFile, removeClaimFile, } from "./spool.js";

package/dist/lib/mesh/live/session-event.schema.json

@@ -115,13 +115,20 @@
       "type": "string",
       "minLength": 1,
       "maxLength": 128,
-      "description": "Optional git repository basename on session_end for the quiet work report (US-051)."
+      "description": "Optional git repository basename of the session cwd. Recorded on the session's live row (latest wins)."
     },
     "gitBranch": {
       "type": "string",
       "minLength": 1,
       "maxLength": 128,
-      "description": "Optional git branch of the session cwd on session_end (US-051)."
+      "description": "Optional git branch of the session cwd. Recorded on the session's live row (latest wins)."
+    },
+    "folder": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[^/\\\\]+$",
+      "description": "Optional basename of the session working folder. Never a path. Recorded on the session's live row (latest wins)."
     },
     "prUrls": {
       "type": "array",

package/dist/lib/mesh/live/validate-session-event.d.ts

@@ -8,7 +8,7 @@
 import type { ValidateFunction } from "ajv";
 export declare const SESSION_EVENT_SCHEMA_PATH: string;
 /** Expected SHA-256 of the canonical schema bytes (hq-pro + hq-cli must match). */
-export declare const SESSION_EVENT_SCHEMA_SHA256 = "e3a9b05daf0037688809e8825a286f9dc89d69aa9266696270d776b64bf99dda";
+export declare const SESSION_EVENT_SCHEMA_SHA256 = "28cbf11ac0e4ebbdfbfd65f51c4f547a58523bd46c98429976bf8df53d404f0f";
 export declare const PROHIBITED_CONTENT_CLASSES: readonly ["prompts", "model_output", "transcripts", "message_bodies", "tokens", "credentials"];
 export type ProhibitedContentClass = (typeof PROHIBITED_CONTENT_CLASSES)[number];
 /** Fixture field name → prohibited class. */

package/dist/lib/mesh/live/validate-session-event.js

@@ -13,7 +13,7 @@ import Ajv2020 from "ajv/dist/2020.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const SESSION_EVENT_SCHEMA_PATH = join(HERE, "session-event.schema.json");
 /** Expected SHA-256 of the canonical schema bytes (hq-pro + hq-cli must match). */
-export const SESSION_EVENT_SCHEMA_SHA256 = "e3a9b05daf0037688809e8825a286f9dc89d69aa9266696270d776b64bf99dda";
+export const SESSION_EVENT_SCHEMA_SHA256 = "28cbf11ac0e4ebbdfbfd65f51c4f547a58523bd46c98429976bf8df53d404f0f";
 export const PROHIBITED_CONTENT_CLASSES = [
     "prompts",
     "model_output",

package/dist/lib/mesh/live/work-location.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Work Mesh Live — network-safe work location derived from the local cwd.
+ *
+ * `cwd` is a local-only spool field and never leaves the machine. Before an
+ * event is sent, the flush derives three short labels from it:
+ *   - repo: basename of `git rev-parse --show-toplevel` (omitted outside git)
+ *   - gitBranch: `git rev-parse --abbrev-ref HEAD` (omitted on detached HEAD)
+ *   - folder: basename of the cwd, never a path (no "/" or "\")
+ * Git lookups are cached per cwd for one flush, bounded by a short timeout,
+ * and never throw; on failure the fields are omitted.
+ */
+export type GitRunner = (cwd: string, args: string[]) => string | undefined;
+export interface WorkLocation {
+    repo?: string;
+    gitBranch?: string;
+    folder?: string;
+}
+export type WorkLocationResolver = (cwd: string) => WorkLocation;
+/** Last path segment of `cwd` (POSIX or Windows separators), or undefined. */
+export declare function folderFromCwd(cwd: string): string | undefined;
+/** Resolve the work location for one cwd. Never throws. */
+export declare function resolveWorkLocation(cwd: string, git?: GitRunner): WorkLocation;
+/** A resolver that caches results per cwd (create one per flush). */
+export declare function createWorkLocationResolver(git?: GitRunner): WorkLocationResolver;
+/**
+ * Copy of `event` with repo / gitBranch / folder filled from its local cwd.
+ * Values already on the event win. Call before stripLocalOnlyFields.
+ */
+export declare function withWorkLocation(event: Record<string, unknown>, resolve: WorkLocationResolver): Record<string, unknown>;
+//# sourceMappingURL=work-location.d.ts.map