@indigoai-us/hq-cli 5.299.0 → 5.301.0

package/dist/commands/meetings.js

@@ -3,6 +3,25 @@ import { readFile } from "node:fs/promises";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid, resolveCallerPersonUid, } from "../utils/vault-api.js";
 import { isPlanGateError, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
+// Two minutes gives a large transcript time to arrive over a slow connection,
+// while keeping the interactive command from waiting indefinitely.
+const MEETING_DOCUMENT_DOWNLOAD_TIMEOUT_MS = 120_000;
+async function downloadMeetingDocument(url, readBody) {
+    const signal = AbortSignal.timeout(MEETING_DOCUMENT_DOWNLOAD_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, { signal });
+        if (!response.ok)
+            return { response, ok: false };
+        return { response, ok: true, body: await readBody(response) };
+    }
+    catch (err) {
+        if ((signal.aborted && signal.reason instanceof DOMException && signal.reason.name === "TimeoutError") ||
+            (err instanceof DOMException && err.name === "TimeoutError")) {
+            throw new Error(`Meeting document download timed out after ${MEETING_DOCUMENT_DOWNLOAD_TIMEOUT_MS / 1000} seconds. Check your network connection and try again.`);
+        }
+        throw err;
+    }
+}
 function formatDuration(seconds) {
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);
@@ -495,12 +514,12 @@ export function registerMeetingsCommand(program) {
                     console.error(chalk.red("No document available for this meeting."));
                     process.exit(1);
                 }
-                const docRes = await fetch(documentUrl);
-                if (!docRes.ok) {
-                    console.error(chalk.red(`Failed to download meeting document (${docRes.status})`));
+                const download = await downloadMeetingDocument(documentUrl, (response) => response.text());
+                if (!download.ok) {
+                    console.error(chalk.red(`Failed to download meeting document (${download.response.status})`));
                     process.exit(1);
                 }
-                const markdown = await docRes.text();
+                const markdown = download.body;
                 if (meetings.opts().json) {
                     console.log(JSON.stringify({ meetingId: detail.meetingId, sourceShape: "markdown", markdown }, null, 2));
                     return;
@@ -513,12 +532,12 @@ export function registerMeetingsCommand(program) {
                 console.error(chalk.red("No document URL available for this meeting."));
                 process.exit(1);
             }
-            const docRes = await fetch(detail.documentUrl);
-            if (!docRes.ok) {
-                console.error(chalk.red(`Failed to download meeting document (${docRes.status})`));
+            const download = await downloadMeetingDocument(detail.documentUrl, (response) => response.json());
+            if (!download.ok) {
+                console.error(chalk.red(`Failed to download meeting document (${download.response.status})`));
                 process.exit(1);
             }
-            const doc = (await docRes.json());
+            const doc = download.body;
             if (meetings.opts().json) {
                 console.log(JSON.stringify(doc.transcript, null, 2));
                 return;
@@ -573,12 +592,12 @@ export function registerMeetingsCommand(program) {
                     console.log(chalk.yellow("No notes available for this meeting."));
                     return;
                 }
-                const docRes = await fetch(documentUrl);
-                if (!docRes.ok) {
-                    console.error(chalk.red(`Failed to download meeting document (${docRes.status})`));
+                const download = await downloadMeetingDocument(documentUrl, (response) => response.text());
+                if (!download.ok) {
+                    console.error(chalk.red(`Failed to download meeting document (${download.response.status})`));
                     process.exit(1);
                 }
-                const markdown = await docRes.text();
+                const markdown = download.body;
                 if (meetings.opts().json) {
                     console.log(JSON.stringify({ meetingId: detail.meetingId, sourceShape: "markdown", markdown }, null, 2));
                     return;
@@ -591,12 +610,12 @@ export function registerMeetingsCommand(program) {
                 console.error(chalk.red("No document URL available for this meeting."));
                 process.exit(1);
             }
-            const docRes = await fetch(detail.documentUrl);
-            if (!docRes.ok) {
-                console.error(chalk.red(`Failed to download meeting document (${docRes.status})`));
+            const download = await downloadMeetingDocument(detail.documentUrl, (response) => response.json());
+            if (!download.ok) {
+                console.error(chalk.red(`Failed to download meeting document (${download.response.status})`));
                 process.exit(1);
             }
-            const doc = (await docRes.json());
+            const doc = download.body;
             if (meetings.opts().json) {
                 console.log(JSON.stringify(doc.notes, null, 2));
                 return;

package/dist/commands/safe-extract.d.ts

@@ -111,10 +111,10 @@ export declare function assertLinkTargetContained(packDir: string, entryAbs: str
 /**
  * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
  * argv form, never a shell string, keeps hostile filenames out of shell syntax.
- * When the default-off compatibility flag is enabled, Windows drive paths use
- * a basename relative to the archive directory. GNU tar cannot parse `C:\\...`
- * as remote `host:path`, and Windows' bundled bsdtar accepts the same relative
- * argv without GNU-only `--force-local`.
+ * Windows drive paths use a basename relative to the archive directory by
+ * default. GNU tar cannot parse `C:\\...` as remote `host:path`, and Windows'
+ * bundled bsdtar accepts the same relative argv without GNU-only `--force-local`.
+ * Callers can still explicitly opt out with `useRelativeWindowsDrivePath: false`.
  */
 export declare function listTarball(tarballPath: string, opts?: Pick<SafeExtractOptions, 'platform' | 'useRelativeWindowsDrivePath' | 'execFileSync'>): TarEntry[];
 /**

package/dist/commands/safe-extract.js

@@ -35,7 +35,6 @@
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { installPathCompatibilityEnabled } from '../lib/install-path-compatibility-flag.js';
 export const DEFAULT_CAPS = {
     // A content pack is docs/skills/policies/small scripts. 256 MiB is already
     // generous; anything larger is almost certainly a bomb or a mistake.
@@ -218,14 +217,14 @@ function tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath)
 /**
  * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
  * argv form, never a shell string, keeps hostile filenames out of shell syntax.
- * When the default-off compatibility flag is enabled, Windows drive paths use
- * a basename relative to the archive directory. GNU tar cannot parse `C:\\...`
- * as remote `host:path`, and Windows' bundled bsdtar accepts the same relative
- * argv without GNU-only `--force-local`.
+ * Windows drive paths use a basename relative to the archive directory by
+ * default. GNU tar cannot parse `C:\\...` as remote `host:path`, and Windows'
+ * bundled bsdtar accepts the same relative argv without GNU-only `--force-local`.
+ * Callers can still explicitly opt out with `useRelativeWindowsDrivePath: false`.
  */
 export function listTarball(tarballPath, opts = {}) {
     const platform = opts.platform ?? process.platform;
-    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? installPathCompatibilityEnabled();
+    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? true;
     const location = tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath);
     const out = (opts.execFileSync ?? execFileSync)('tar', ['-tvf', location.archiveArg], {
         encoding: 'utf-8',
@@ -330,7 +329,7 @@ export function safeExtractTarball(tarballPath, finalDir, opts = {}) {
     }
     // Resolve once so listing and extraction use the same archive location.
     const platform = opts.platform ?? process.platform;
-    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? installPathCompatibilityEnabled();
+    const useRelativeWindowsDrivePath = opts.useRelativeWindowsDrivePath ?? true;
     const exec = opts.execFileSync ?? execFileSync;
     const location = tarballArgvLocation(tarballPath, platform, useRelativeWindowsDrivePath);
     // 1. Pre-flight against headers (no bytes written yet).

package/dist/lib/core-utils/token-usage-report.js

@@ -120,7 +120,7 @@ function comparison(projectDirs, before, after, minHours, json, stdout) {
 /** Print token usage totals from Claude session JSONL files. */
 export function tokenUsageReport(args = [], options = {}) {
     const { stdout, stderr } = ioFor(options);
-    let lastDays = 7, since = "", json = false, before = "", after = "", minHours = 0;
+    let lastDays = 7, since = "", json = false, before = "", after = "", minHours = 0, projectDir = options.projectDir, projectDirSeen = false;
     for (let index = 0; index < args.length;) {
         const arg = args[index];
         if (arg === "--last") {
@@ -149,8 +149,22 @@ export function tokenUsageReport(args = [], options = {}) {
             minHours = Number.parseFloat(args[index + 1] ?? "");
             index += 2;
         }
+        else if (arg === "--project-dir") {
+            const value = args[index + 1];
+            if (!value || value.startsWith("--")) {
+                line(stderr, "--project-dir requires a path");
+                return 1;
+            }
+            if (projectDirSeen) {
+                line(stderr, "--project-dir may be specified only once");
+                return 1;
+            }
+            projectDir = value;
+            projectDirSeen = true;
+            index += 2;
+        }
         else if (arg === "-h" || arg === "--help") {
-            stdout("token-usage-report.sh — Daily effective-token totals + top burners from Claude Code session JSONLs.\nUsage:\n  scripts/token-usage-report.sh                # last 7 days, table\n  scripts/token-usage-report.sh --last 14      # last 14 days\n  scripts/token-usage-report.sh --since 2026-05-01\n  scripts/token-usage-report.sh --json         # machine-readable\nEffective tokens weighting (matches weekly rate-limit volume):\n  input + 5×output + 1.25×cache_creation + 0.1×cache_read\n--- Compare-windows mode (US-011) ---\nFormat: --before YYYY-MM-DD:YYYY-MM-DD --after YYYY-MM-DD:YYYY-MM-DD\n");
+            stdout("token-usage-report.sh — Daily effective-token totals + top burners from Claude Code session JSONLs.\nUsage:\n  scripts/token-usage-report.sh                # last 7 days, table\n  scripts/token-usage-report.sh --last 14      # last 14 days\n  scripts/token-usage-report.sh --since 2026-05-01\n  scripts/token-usage-report.sh --json         # machine-readable\n  scripts/token-usage-report.sh --project-dir <path> # use one Claude activity folder\nEffective tokens weighting (matches weekly rate-limit volume):\n  input + 5×output + 1.25×cache_creation + 0.1×cache_read\n--- Compare-windows mode (US-011) ---\nFormat: --before YYYY-MM-DD:YYYY-MM-DD --after YYYY-MM-DD:YYYY-MM-DD\n");
             return 0;
         }
         else {
@@ -158,7 +172,7 @@ export function tokenUsageReport(args = [], options = {}) {
             return 1;
         }
     }
-    const projectDirs = resolveProjectDirs(options).filter((dir) => fs.existsSync(dir) && fs.statSync(dir).isDirectory());
+    const projectDirs = resolveProjectDirs({ ...options, projectDir }).filter((dir) => fs.existsSync(dir) && fs.statSync(dir).isDirectory());
     if (before && after) {
         comparison(projectDirs, before, after, minHours, json, stdout);
         return 0;

package/dist/lib/index-render/companies.d.ts

@@ -1,3 +1,6 @@
 import { RenderContext, RenderResult } from "./shared.js";
-export declare function renderCompanies(context: RenderContext): RenderResult;
+export declare class CompanyIndexUserError extends Error {
+    constructor(message: string);
+}
+export declare function renderCompanies(context: RenderContext, args?: string[]): RenderResult;
 //# sourceMappingURL=companies.d.ts.map

package/dist/lib/index-render/companies.js

@@ -1,6 +1,12 @@
 import * as fs from "fs";
 import * as path from "path";
 import { basename, countImmediate, date, exists, immediateEntries, isHidden, log, projectStatus, readJson, sanitize, titleize, truncate, write } from "./shared.js";
+export class CompanyIndexUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CompanyIndexUserError";
+    }
+}
 function description(root, company, name) {
     const base = `companies/${company}/${name}`;
     const nonHidden = (child) => !isHidden(child);
@@ -17,9 +23,66 @@ function description(root, company, name) {
         default: return "—";
     }
 }
-export function renderCompanies(context) {
+export function renderCompanies(context, args = []) {
+    if (args.some((arg) => arg === "--help" || arg === "-h")) {
+        (context.output ?? ((message) => process.stdout.write(message)))("Usage: hq core rebuild-index companies [--company <slug>]\n\n" +
+            "Regenerate company root INDEX.md files. Without --company, all companies are regenerated.\n" +
+            "--company <slug> regenerates only that company's index.\n" +
+            "Company-scoped writes require the cli.rebuild-index-company-scope flag.\n");
+        return { written: [] };
+    }
+    let selectedCompany;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--company") {
+            if (selectedCompany !== undefined)
+                throw new CompanyIndexUserError("rebuild-index companies: --company may be supplied once");
+            const value = args[index + 1];
+            if (!value || value.startsWith("--"))
+                throw new CompanyIndexUserError("rebuild-index companies: --company requires a company slug");
+            selectedCompany = value;
+            index += 1;
+        }
+        else if (arg.startsWith("--company=")) {
+            if (selectedCompany !== undefined)
+                throw new CompanyIndexUserError("rebuild-index companies: --company may be supplied once");
+            selectedCompany = arg.slice("--company=".length);
+            if (!selectedCompany)
+                throw new CompanyIndexUserError("rebuild-index companies: --company requires a company slug");
+        }
+        else {
+            throw new CompanyIndexUserError(`rebuild-index companies: unknown option ${arg}`);
+        }
+    }
     const written = [];
-    for (const directory of immediateEntries(context.root, "companies", "dir")) {
+    let scopedDirectories;
+    if (selectedCompany === undefined) {
+        scopedDirectories = immediateEntries(context.root, "companies", "dir");
+    }
+    else {
+        if (selectedCompany === "." || selectedCompany === ".." ||
+            selectedCompany.includes("/") || selectedCompany.includes("\\") ||
+            path.basename(selectedCompany) !== selectedCompany ||
+            selectedCompany.startsWith("_") || isHidden(selectedCompany)) {
+            throw new CompanyIndexUserError(`rebuild-index companies: invalid company slug "${selectedCompany}"`);
+        }
+        const companiesRoot = path.resolve(context.root, "companies");
+        const selectedDirectory = path.resolve(companiesRoot, selectedCompany);
+        let selectedStat;
+        try {
+            selectedStat = fs.lstatSync(selectedDirectory);
+        }
+        catch (cause) {
+            if (cause.code !== "ENOENT")
+                throw cause;
+            throw new CompanyIndexUserError(`rebuild-index companies: no company directory named "${selectedCompany}"`);
+        }
+        if (!selectedStat.isDirectory()) {
+            throw new CompanyIndexUserError(`rebuild-index companies: no company directory named "${selectedCompany}"`);
+        }
+        scopedDirectories = [selectedDirectory];
+    }
+    for (const directory of scopedDirectories) {
         const company = basename(directory);
         if (company.startsWith("_") || isHidden(company))
             continue;
@@ -40,7 +103,7 @@ export function renderCompanies(context) {
                 const parsed = readJson(prd);
                 let text = typeof parsed?.description === "string" ? parsed.description : "";
                 text = truncate(sanitize(text), 110) || "—";
-                lines.push(`| \`${project}\` | ${projectStatus(context.root, project, prd, "active")} | ${text} |`);
+                lines.push(`| \`${project}\` | ${projectStatus(context.root, project, prd, "active", prd)} | ${text} |`);
             }
         }
         else

package/dist/lib/index-render/index.d.ts

@@ -2,4 +2,5 @@ import { RenderContext, RenderResult } from "./shared.js";
 export type IndexTarget = "all" | "companies" | "company-knowledge" | "orchestrator" | "projects" | "public-knowledge" | "reports" | "social-drafts" | "threads" | "workers";
 export declare function renderIndexTarget(target: IndexTarget, context: RenderContext, args?: string[]): RenderResult;
 export { atomicWrite, comparePath, immediateEntries, type RenderContext, type RenderResult } from "./shared.js";
+export { CompanyIndexUserError } from "./companies.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index-render/index.js

@@ -10,7 +10,7 @@ import { renderWorkers } from "./workers.js";
 const allOrder = ["threads", "orchestrator", "companies", "projects", "company-knowledge", "public-knowledge", "workers", "reports", "social-drafts"];
 export function renderIndexTarget(target, context, args = []) {
     switch (target) {
-        case "companies": return renderCompanies(context);
+        case "companies": return renderCompanies(context, args);
         case "company-knowledge": return renderCompanyKnowledge(context);
         case "orchestrator": return renderOrchestrator(context);
         case "projects": return renderProjects(context);
@@ -40,4 +40,5 @@ export function renderIndexTarget(target, context, args = []) {
     }
 }
 export { atomicWrite, comparePath, immediateEntries } from "./shared.js";
+export { CompanyIndexUserError } from "./companies.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/index-render/shared.d.ts

@@ -39,7 +39,7 @@ export declare function hasUnclosedKeepMarker(content: string): boolean;
 export declare function looksAutoGenerated(content: string): boolean;
 export declare function generatedStamp(content: string): string | undefined;
 export declare function log(context: RenderContext, message: string): void;
-export declare function projectStatus(root: string, project: string, prdPath: string, fallback: string): string;
+export declare function projectStatus(root: string, project: string, prdPath: string, fallback: string, expectedStatePrdPath?: string): string;
 export declare function basename(file: string): string;
 export declare function isHidden(name: string): boolean;
 export declare function mtime(file: string): number;

package/dist/lib/index-render/shared.js

@@ -134,9 +134,11 @@ export function generatedStamp(content) {
     return content.match(/^<!-- hq-generated-sha256: ([a-f0-9]{64}) -->/m)?.[1];
 }
 export function log(context, message) { context.log?.(message); }
-export function projectStatus(root, project, prdPath, fallback) {
+export function projectStatus(root, project, prdPath, fallback, expectedStatePrdPath) {
     const state = readJson(at(root, `workspace/orchestrator/${project}/state.json`));
-    if (state) {
+    const stateMatchesPrd = expectedStatePrdPath === undefined || (typeof state?.prd_path === "string" &&
+        path.resolve(root, state.prd_path) === path.resolve(root, expectedStatePrdPath));
+    if (state && stateMatchesPrd) {
         const raw = typeof state.status === "string" ? state.status : "active";
         if (["completed", "complete"].includes(raw))
             return "complete";

package/dist/lib/lanes/reconcile.js

@@ -32,6 +32,7 @@ import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuesti
 import { SILENCE_MS, appendWatcherEvent, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
 import { activeLaneStories, laneStories, terminalEnvelopeStoryStatus } from "./stories.js";
+import { applyStorySwitchEnvelope } from "./story-switch.js";
 import { decideEnvelopeRepair, envelopeQuestionIds, routeProviderFailure } from "./watcher.js";
 import { PROVIDER_REJECTED_REASON, providerRejectionDetails, readProviderRejection, } from "./provider-rejection.js";
 /** Spec §9: unanswered at the current hop for 60 minutes → one hop. */
@@ -1271,11 +1272,28 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     }
                     if (terminalEnvelope && latest) {
                         const envelope = terminalEnvelope;
-                        const storyStatus = terminalEnvelopeStoryStatus(current, envelope.decision, envelope.story_status);
+                        next.last_envelope = {
+                            ref: latest.ref,
+                            decision: envelope.decision,
+                            at: nowIso,
+                            artifacts: envelope.artifacts,
+                            ...(envelope.blocked_reason !== undefined ? { blocked_reason: envelope.blocked_reason } : {}),
+                        };
+                        const storySwitch = applyStorySwitchEnvelope(current, envelope, nowIso, latest.ref);
+                        if (storySwitch.clearPending) {
+                            next.story_switch_pending = undefined;
+                        }
+                        if (storySwitch.storySwitchUnacknowledged !== undefined) {
+                            next.story_switch_unacknowledged = storySwitch.storySwitchUnacknowledged;
+                            next.attribution_history = storySwitch.attributionHistory ?? current.attribution_history;
+                        }
+                        const storyStatus = storySwitch.suppressCompletion
+                            ? "in_progress"
+                            : terminalEnvelopeStoryStatus(current, envelope.decision, envelope.story_status);
                         if (storyStatus !== undefined) {
-                            next.story_status = envelope.story_status;
-                            next.story_complete = envelope.story_complete;
-                            next.story_complete_reason = envelope.story_complete_reason;
+                            next.story_status = storySwitch.suppressCompletion ? "in_progress" : envelope.story_status;
+                            next.story_complete = storySwitch.suppressCompletion ? false : envelope.story_complete;
+                            next.story_complete_reason = storySwitch.suppressCompletion ? undefined : envelope.story_complete_reason;
                             next.stories = laneStories(current).map((story) => story.project_id === current.project_id && story.story_id === current.story_id
                                 ? {
                                     ...story,

package/dist/lib/lanes/story-switch.d.ts

@@ -0,0 +1,21 @@
+import type { AttributionHistoryEntry, LaneEnvelope, LaneRecord, StorySwitchUnacknowledgedNote } from "./types.js";
+export declare function storySwitchNotice(previousProjectId: string, previousStoryId: string, projectId: string, storyId: string): string | undefined;
+export declare function artifactIdentityKeys(artifacts: readonly unknown[] | undefined): string[];
+export interface StorySwitchRollbackSnapshot {
+    message_id: string;
+    project_id: string;
+    story_id: string;
+    no_story_reason?: string;
+    added_story?: NonNullable<LaneRecord["stories"]>[number];
+    story_switch_unacknowledged: StorySwitchUnacknowledgedNote | undefined;
+}
+/** Restore only the attribution write owned by this failed command attempt. */
+export declare function rollbackStorySwitchAttribution(current: LaneRecord, snapshot: StorySwitchRollbackSnapshot): LaneRecord;
+/** Apply and consume one attribution-switch marker when the next envelope arrives. */
+export declare function applyStorySwitchEnvelope(lane: LaneRecord, envelope: LaneEnvelope, at: string, envelopeRef: string): {
+    suppressCompletion: boolean;
+    clearPending: boolean;
+    storySwitchUnacknowledged?: StorySwitchUnacknowledgedNote;
+    attributionHistory?: AttributionHistoryEntry[];
+};
+//# sourceMappingURL=story-switch.d.ts.map

package/dist/lib/lanes/story-switch.js

@@ -0,0 +1,75 @@
+export function storySwitchNotice(previousProjectId, previousStoryId, projectId, storyId) {
+    if (previousProjectId === projectId && previousStoryId === storyId)
+        return undefined;
+    const from = `${previousProjectId}/${previousStoryId || "(no story)"}`;
+    const to = `${projectId}/${storyId || "(no story)"}`;
+    return `Story changed: ${from} -> ${to}. The previous story is closed; report only on the new story in this turn's envelope.`;
+}
+export function artifactIdentityKeys(artifacts) {
+    if (!Array.isArray(artifacts))
+        return [];
+    return artifacts.flatMap((artifact) => {
+        if (typeof artifact === "string" && artifact.trim())
+            return [`value:${artifact.trim()}`];
+        if (artifact === null || typeof artifact !== "object" || Array.isArray(artifact))
+            return [];
+        const record = artifact;
+        const url = typeof record.url === "string" ? record.url.trim() : "";
+        const path = typeof record.path === "string" ? record.path.trim() : "";
+        const values = [url && `url:${url}`, path && `path:${path}`].filter((value) => Boolean(value));
+        return values;
+    }).sort();
+}
+/** Restore only the attribution write owned by this failed command attempt. */
+export function rollbackStorySwitchAttribution(current, snapshot) {
+    if (current.story_switch_pending?.message_id !== snapshot.message_id)
+        return current;
+    const addedStory = snapshot.added_story;
+    const stories = (current.stories ?? []).filter((story) => !(addedStory && story.project_id === addedStory.project_id && story.story_id === addedStory.story_id &&
+        story.added_at === addedStory.added_at));
+    return {
+        ...current,
+        project_id: snapshot.project_id,
+        story_id: snapshot.story_id,
+        no_story_reason: snapshot.no_story_reason,
+        stories,
+        attribution_history: current.attribution_history.filter((entry) => entry.message_id !== snapshot.message_id),
+        story_switch_pending: undefined,
+        story_switch_unacknowledged: snapshot.story_switch_unacknowledged,
+    };
+}
+function sameKeys(left, right) {
+    return left.length > 0 && left.length === right.length && left.every((key, index) => key === right[index]);
+}
+/** Apply and consume one attribution-switch marker when the next envelope arrives. */
+export function applyStorySwitchEnvelope(lane, envelope, at, envelopeRef) {
+    const pending = lane.story_switch_pending;
+    if (!pending)
+        return { suppressCompletion: false, clearPending: false };
+    if (envelope.story_complete !== true)
+        return { suppressCompletion: false, clearPending: false };
+    const currentKeys = artifactIdentityKeys(envelope.artifacts);
+    const suppressCompletion = sameKeys(pending.previous_artifact_keys, currentKeys);
+    if (!suppressCompletion)
+        return { suppressCompletion: false, clearPending: true };
+    const note = {
+        event: "story_switch_unacknowledged",
+        previous_project_id: pending.previous_project_id,
+        previous_story_id: pending.previous_story_id,
+        project_id: pending.project_id,
+        story_id: pending.story_id,
+        message_id: pending.message_id,
+        envelope_ref: envelopeRef,
+        at,
+        artifact_keys: currentKeys,
+    };
+    return {
+        suppressCompletion: true,
+        clearPending: true,
+        storySwitchUnacknowledged: note,
+        attributionHistory: lane.attribution_history.map((entry) => entry.message_id === pending.message_id
+            ? { ...entry, story_switch_unacknowledged: note }
+            : entry),
+    };
+}
+//# sourceMappingURL=story-switch.js.map

package/dist/lib/lanes/types.d.ts

@@ -351,6 +351,27 @@ export interface AttributionHistoryEntry {
     story_id: string;
     message_id: string;
     at: string;
+    story_switch_unacknowledged?: StorySwitchUnacknowledgedNote;
+}
+export interface StorySwitchPending {
+    previous_project_id: string;
+    previous_story_id: string;
+    project_id: string;
+    story_id: string;
+    message_id: string;
+    at: string;
+    previous_artifact_keys: string[];
+}
+export interface StorySwitchUnacknowledgedNote {
+    event: "story_switch_unacknowledged";
+    previous_project_id: string;
+    previous_story_id: string;
+    project_id: string;
+    story_id: string;
+    message_id: string;
+    envelope_ref: string;
+    at: string;
+    artifact_keys: string[];
 }
 export interface LastEnvelopeRef {
     ref: string;
@@ -573,6 +594,10 @@ export interface LaneRecord {
     envelope_summary?: string;
     attribution_history: AttributionHistoryEntry[];
     last_envelope?: LastEnvelopeRef;
+    /** Pending attribution change, consumed by the next terminal envelope. */
+    story_switch_pending?: StorySwitchPending;
+    /** Last completion suppressed because the new story repeated prior evidence. */
+    story_switch_unacknowledged?: StorySwitchUnacknowledgedNote;
     /** Effective model id recorded at create/spawn. Omitted when the provider chooses. */
     model?: string;
     /** Where the effective model came from; repaired models stay pinned across the account move. */

package/dist/lib/lanes/types.js

@@ -227,7 +227,7 @@ export const LANE_FIELD_WRITERS = {
     priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], registry_worker: ["creator", "command", "spawn"], registry_worker_approval_history: ["command", "watcher", "reconcile"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
     keep_alive: ["creator", "command"], keep_alive_standing: ["command"], keep_alive_opted_in_at: ["creator", "command"], keep_alive_blocked_reason: ["command", "reconcile"], keep_alive_resume_count: ["command", "reconcile"], keep_alive_history: ["reconcile"], keep_alive_blocked_resume_streak: ["reconcile", "spawn", "watcher"], keep_alive_last_resume_at: ["command", "reconcile"], keep_alive_next_eligible_at: ["command", "reconcile"], keep_alive_exhausted_at: ["command", "reconcile"],
     provider: ["creator"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
-    version: ["creator"], created_at: ["creator"], updated_at: ["creator"], ended_at: ["reconcile"], envelope_summary: ["reconcile"], attribution_history: ["command"],
+    version: ["creator"], created_at: ["creator"], updated_at: ["creator"], ended_at: ["reconcile"], envelope_summary: ["reconcile"], attribution_history: ["command", "watcher", "reconcile"], story_switch_pending: ["command", "watcher", "reconcile"], story_switch_unacknowledged: ["watcher", "reconcile"],
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher", "reconcile"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],

package/dist/lib/lanes/watcher.js

@@ -37,6 +37,7 @@ import { LanesError } from "./errors.js";
 import { questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { isTerminalLaneState, ENVELOPE_INVALID_REASON, parseLaneEnvelope, STORY_STATUSES, LANE_PROVIDERS, } from "./types.js";
 import { laneStories, terminalEnvelopeStoryStatus } from "./stories.js";
+import { applyStorySwitchEnvelope } from "./story-switch.js";
 import { appendCappedHistory, listQuestionIds, readLane, readQuestion, retryUpdateLane, withLaneHireLocks } from "./store.js";
 import { enforceRegistryApprovalGate } from "./approval-gate.js";
 import { readWorkerRunResult } from "./delivery.js";
@@ -414,6 +415,7 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
             }), current.registry_worker_approval_history ?? []);
         }
         if (envelope) {
+            const storySwitch = applyStorySwitchEnvelope(current, envelope, at, envelopeRef);
             if (envelope.decision !== "blocked")
                 next.keep_alive_blocked_resume_streak = 0;
             next.last_envelope = {
@@ -423,11 +425,20 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
                 artifacts: envelope.artifacts,
                 ...(envelope.blocked_reason !== undefined ? { blocked_reason: envelope.blocked_reason } : {}),
             };
-            const storyStatus = terminalEnvelopeStoryStatus(current, envelope.decision, envelope.story_status);
+            if (storySwitch.clearPending) {
+                next.story_switch_pending = undefined;
+            }
+            if (storySwitch.storySwitchUnacknowledged !== undefined) {
+                next.story_switch_unacknowledged = storySwitch.storySwitchUnacknowledged;
+                next.attribution_history = storySwitch.attributionHistory ?? current.attribution_history;
+            }
+            const storyStatus = storySwitch.suppressCompletion
+                ? "in_progress"
+                : terminalEnvelopeStoryStatus(current, envelope.decision, envelope.story_status);
             if (storyStatus !== undefined) {
-                next.story_status = envelope.story_status;
-                next.story_complete = envelope.story_complete;
-                next.story_complete_reason = envelope.story_complete_reason;
+                next.story_status = storySwitch.suppressCompletion ? "in_progress" : envelope.story_status;
+                next.story_complete = storySwitch.suppressCompletion ? false : envelope.story_complete;
+                next.story_complete_reason = storySwitch.suppressCompletion ? undefined : envelope.story_complete_reason;
                 const currentProject = current.project_id;
                 const currentStory = current.story_id;
                 const updatedStories = laneStories(current).map((story) => story.project_id === currentProject && story.story_id === currentStory

package/dist/lib/mesh/live/daemon/mqtt-events.d.ts

@@ -0,0 +1,7 @@
+import type { MqttClientEventCallbacks } from "mqtt";
+/** Event callbacks shared by the daemon's two MQTT client seams. */
+export type MeshMqttEventMap = Pick<MqttClientEventCallbacks, "connect" | "error" | "close" | "message">;
+export interface MeshMqttEventClient {
+    on<Event extends keyof MeshMqttEventMap>(event: Event, handler: MeshMqttEventMap[Event]): unknown;
+}
+//# sourceMappingURL=mqtt-events.d.ts.map

package/dist/lib/mesh/live/daemon/mqtt-events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mqtt-events.js.map

package/dist/lib/mesh/live/daemon/mqtt-events.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mqtt-events.test-d.d.ts.map

package/dist/lib/mesh/live/daemon/mqtt-events.test-d.js

@@ -0,0 +1,10 @@
+// @ts-expect-error unsupported event names are not part of mqtt's event map
+presence.on("conect", () => { });
+// @ts-expect-error MQTT message handlers receive a string topic
+presence.on("message", (topic) => void topic);
+// @ts-expect-error unsupported event names are not part of mqtt's event map
+workCache.on("conect", () => { });
+// @ts-expect-error MQTT message handlers receive a string topic
+workCache.on("message", (topic) => void topic);
+export {};
+//# sourceMappingURL=mqtt-events.test-d.js.map

package/dist/lib/mesh/live/daemon/presence.d.ts

@@ -12,6 +12,7 @@
  * - Server credential refusals use a long retry (default 10m ±20%)
  */
 import { type IClientOptions, type MqttClient } from "mqtt";
+import type { MeshMqttEventClient } from "./mqtt-events.js";
 import { type Contract3Bundle, type CredentialsFetcher, type TimerHost } from "./credentials.js";
 export type MqttConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
 /**
@@ -49,8 +50,7 @@ export interface PresencePayload {
     at: string;
 }
 /** Structural mqtt client surface used by PresenceClient (test seam). */
-export interface MeshMqttClientLike {
-    on(event: string, handler: (...args: any[]) => void): unknown;
+export interface MeshMqttClientLike extends MeshMqttEventClient {
     publish(topic: string, message: string | Buffer, opts: {
         qos: 0 | 1 | 2;
         retain?: boolean;