@indigoai-us/hq-cli 5.304.0 → 5.305.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.305.0] — 2026-10-01
+
+- Work Mesh project discovery skips projects whose matching local lifecycle state is archived or retired.
+
+- `hq lanes show` now treats a newer terminal primary mirror as authoritative when an Outpost owner snapshot is behind, avoiding a misleading refresh warning while preserving warnings for nonterminal conflicts.
+- Self-updates detect an unwritable npm global prefix before install, show the command to repair that install, and report the handled permission state as a rate-limited warning.
+- Keep Work Mesh held events unique by event ID across retries, including interrupted overflow recovery.
+- Added `hq mcp list` as an alias for the existing MCP status command. `hq version` can show cached CLI update guidance on stderr when the default-off `cli.version-update-nudge` flag is enabled. Bare `hq --version` prints only the installed CLI semver and starts no flag or network work.
+- Keep-alive no longer lets a newer terminal lane or a same-profile lane under a distinct lane senior supersede a running lane.
+- With `cli.company-errors-sdk-warning` enabled, `hq people` uses shared active-company guidance when local metadata is missing, and files commands show the AWS SDK Node-version notice only with verbose diagnostics.
+- Remove the unrelated secret-sharing hint from active member listings.
+
 ## [5.304.0] — 2026-10-01
 - `hq lanes show` skips owner refresh only when a failed Outpost dispatch explicitly recorded `pickup_persisted: false` and no owner heartbeat; it reports `remote_refresh: "skipped_undispatched"` in that case.
 

package/dist/command-catalog.generated.d.ts

@@ -3622,7 +3622,7 @@ export declare const COMMAND_CATALOG: readonly [{
     readonly subcommands: readonly [{
         readonly name: "status";
         readonly description: "Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)";
-        readonly aliases: readonly [];
+        readonly aliases: readonly ["list"];
         readonly hidden: false;
         readonly usage: "[options]";
         readonly arguments: readonly [];

package/dist/command-catalog.generated.js

@@ -4674,7 +4674,9 @@ export const COMMAND_CATALOG = [
             {
                 "name": "status",
                 "description": "Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)",
-                "aliases": [],
+                "aliases": [
+                    "list"
+                ],
                 "hidden": false,
                 "usage": "[options]",
                 "arguments": [],

package/dist/command-registration-plan.js

@@ -85,6 +85,7 @@ export const REGISTRATION_PLAN = [
 ];
 async function executePlan(program, steps) {
     const parents = new Map([["program", program]]);
+    let filesRuntimeConfigured = false;
     for (const step of steps) {
         if (step.type === "group") {
             const group = program.command(step.name, step.hidden ? { hidden: true } : {});
@@ -94,6 +95,13 @@ async function executePlan(program, steps) {
         const parent = parents.get(step.parent);
         if (!parent)
             throw new Error(`Missing command parent '${step.parent}' for '${step.exportName}'`);
+        if (step.root === "files" && !filesRuntimeConfigured) {
+            // The SDK emits its Node support notice during module evaluation. Set
+            // its narrow suppression switch before loading any files command module.
+            const { configureAwsSdkNodeVersionWarningOutput } = await import("./lib/aws-sdk-node-warning-output.js");
+            configureAwsSdkNodeVersionWarningOutput();
+            filesRuntimeConfigured = true;
+        }
         const imported = await import(step.module);
         const register = imported[step.exportName];
         if (!register)

package/dist/commands/lanes.js

@@ -5065,6 +5065,19 @@ async function refreshOutpostLaneCopiesForShow(ctx, lane, localLanes) {
             return syncLaneRecordFromOwner(ctx.hqRoot(), laneId, outpostId, ownerLane, undefined, { allowNonTerminal: true });
         }
         catch (err) {
+            if (isLanesError(err) && err.error === "outpost_lane_sync_conflict") {
+                const ownerVersion = err.details.owner_version;
+                const primaryVersion = err.details.primary_version;
+                if (typeof ownerVersion === "number" &&
+                    typeof primaryVersion === "number" &&
+                    ownerVersion < primaryVersion) {
+                    const currentPrimary = readLane(ctx.hqRoot(), laneId);
+                    if (currentPrimary.version === primaryVersion &&
+                        isTerminalLaneState(currentPrimary.state)) {
+                        return currentPrimary;
+                    }
+                }
+            }
             const detail = isLanesError(err)
                 ? `${err.error}: ${err.message}`
                 : `outpost_lane_sync_unavailable: ${dispatchErrorMessage(err)}`;

package/dist/commands/mcp-status.js

@@ -374,6 +374,7 @@ export function registerMcpCommand(program) {
         .description('MCP pack observability (read-only) across Claude + Codex');
     mcp
         .command('status')
+        .alias('list')
         .description('Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)')
         .option('--json', 'Emit the structured report as JSON (for CI / scripting)')
         .action((opts) => {

package/dist/commands/members.js

@@ -672,7 +672,6 @@ export function registerMembersCommand(program) {
                 const name = m.personName ?? m.personSlug ?? "";
                 console.log([email.padEnd(emailW), m.role.padEnd(roleW), name].join("  "));
             }
-            console.log(chalk.gray("Share a secret with a member: hq secrets share <path> --with <email>"));
         }
         catch (err) {
             if (err instanceof InviteHttpError) {

package/dist/commands/people.d.ts

@@ -17,6 +17,9 @@ import { resolveNameToEmail, type PersonRecord } from "../utils/people.js";
 export type FetchPeopleRoster = (hqRoot: string, companySlug: string) => Promise<PersonRecord[]>;
 interface PeopleCommandDeps {
     fetchRoster?: FetchPeopleRoster;
+    /** Test seam for the shared active-membership ambiguity resolver. */
+    resolveMissingManifestMemberships?: () => Promise<void>;
+    companySelectionGuidanceEnabled?: () => boolean;
 }
 interface PeopleLookupOpts {
     localOnly?: boolean;

package/dist/commands/people.js

@@ -19,6 +19,7 @@ import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath } from "./cloud-provision.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
+import { companyErrorsSdkWarningEnabled } from "../lib/company-errors-sdk-warning-flag.js";
 import { listActiveMembers } from "./members.js";
 import { assertSafeCompanySlug, listCompanyPeople, searchPeople, resolveNameToEmail, companyPeopleDir, } from "../utils/people.js";
 function slugify(value) {
@@ -108,6 +109,29 @@ export function resolveCompanySlug(hqRoot, explicit) {
     throw new Error("Multiple companies found — re-run with --company <slug> to pick one:\n" +
         slugs.map((s) => `  --company ${s}`).join("\n"));
 }
+async function resolvePeopleCompanySlug(hqRoot, explicit, localOnly, deps) {
+    try {
+        return resolveCompanySlug(hqRoot, explicit);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const ambiguous = message.includes("companies/manifest.yaml not found") ||
+            message.startsWith("Multiple companies found");
+        const enabled = (deps.companySelectionGuidanceEnabled ?? companyErrorsSdkWarningEnabled)();
+        if (!explicit && !localOnly && enabled && ambiguous) {
+            const resolveMemberships = deps.resolveMissingManifestMemberships ??
+                (async () => {
+                    const token = await ensureCognitoToken();
+                    await getCompanyUid(token, undefined);
+                });
+            // The shared resolver throws members-style guidance for multiple active
+            // companies. A single membership cannot provide a local slug without a
+            // manifest, so preserve the existing missing-manifest error in that case.
+            await resolveMemberships();
+        }
+        throw error;
+    }
+}
 /** Resolve the HQ root: explicit override (tests) → cwd walk-up. */
 function resolveHqRoot(opts) {
     return opts.hqRoot ?? findHqRoot();
@@ -192,7 +216,7 @@ export function registerPeopleCommand(program, deps = {}) {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
-            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const slug = await resolvePeopleCompanySlug(hqRoot, scope.company, opts.localOnly, deps);
             let records = listCompanyPeople(hqRoot, slug);
             if (!opts.localOnly) {
                 const roster = await tryFetchRoster(deps.fetchRoster ?? fetchMembershipRoster, hqRoot, slug);
@@ -223,7 +247,7 @@ export function registerPeopleCommand(program, deps = {}) {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
-            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const slug = await resolvePeopleCompanySlug(hqRoot, scope.company, opts.localOnly, deps);
             const matches = await searchPeopleWithRosterFallback({
                 hqRoot,
                 slug,
@@ -255,7 +279,7 @@ export function registerPeopleCommand(program, deps = {}) {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
-            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const slug = await resolvePeopleCompanySlug(hqRoot, scope.company, opts.localOnly, deps);
             const result = await resolvePersonWithRosterFallback({
                 hqRoot,
                 slug,

package/dist/index.js

@@ -22,9 +22,14 @@ if (isVersionRequest(process.argv)) {
     // compare). `hq version` and `--json` print the labelled HQ/CLI report.
     // Lazy so this path still skips the command graph.
     if (wantsLabelledVersionReport(process.argv)) {
-        void import("./utils/version-report.js").then(({ runVersionCommand }) => runVersionCommand(process.argv));
+        void import("./lib/flag-registry.js").then(({ kickFlagRegistryReadiness }) => {
+            kickFlagRegistryReadiness();
+            return import("./utils/version-report.js").then(({ runVersionCommand }) => runVersionCommand(process.argv));
+        });
     }
     else {
+        // Keep the benchmarked updater fast route limited to the installed semver.
+        // Registry checks and flag resolution belong to the regular command path.
         void import("./cli-version.js").then(({ CLI_VERSION }) => {
             process.stdout.write(`${CLI_VERSION}\n`);
         });

package/dist/lazy-commands.js

@@ -55,8 +55,11 @@ function commandForToken(token) {
  * preserve the complete help and unknown-command recovery surfaces.
  */
 export function findLazyCommand(argv) {
-    const first = argv[2];
-    const token = first === "help" ? argv[3] : first;
+    let commandIndex = 2;
+    while (argv[commandIndex] === "--verbose")
+        commandIndex += 1;
+    const first = argv[commandIndex];
+    const token = first === "help" ? argv[commandIndex + 1] : first;
     if (typeof token !== "string" || token.startsWith("-"))
         return null;
     const command = commandForToken(token);

package/dist/lib/aws-sdk-node-warning-output.d.ts

@@ -0,0 +1,12 @@
+export declare const AWS_SDK_NODE_VERSION_WARNING_ENV = "AWS_SDK_JS_NODE_VERSION_SUPPORT_WARNING_DISABLED";
+export interface AwsSdkWarningOutputOptions {
+    argv?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    enabled?: boolean;
+}
+/**
+ * Configure the AWS SDK's documented, warning-specific switch before loading
+ * the files command and its SDK clients. No other SDK warnings are affected.
+ */
+export declare function configureAwsSdkNodeVersionWarningOutput(options?: AwsSdkWarningOutputOptions): void;
+//# sourceMappingURL=aws-sdk-node-warning-output.d.ts.map

package/dist/lib/aws-sdk-node-warning-output.js

@@ -0,0 +1,22 @@
+import { companyErrorsSdkWarningEnabled } from "./company-errors-sdk-warning-flag.js";
+export const AWS_SDK_NODE_VERSION_WARNING_ENV = "AWS_SDK_JS_NODE_VERSION_SUPPORT_WARNING_DISABLED";
+/**
+ * Configure the AWS SDK's documented, warning-specific switch before loading
+ * the files command and its SDK clients. No other SDK warnings are affected.
+ */
+export function configureAwsSdkNodeVersionWarningOutput(options = {}) {
+    const env = options.env ?? process.env;
+    const argv = options.argv ?? process.argv;
+    const enabled = options.enabled ?? companyErrorsSdkWarningEnabled();
+    if (!enabled)
+        return;
+    const verbose = argv.includes("--verbose");
+    const debug = /^(1|true|yes)$/i.test(env.HQ_DEBUG?.trim() ?? "");
+    if (verbose || debug) {
+        delete env[AWS_SDK_NODE_VERSION_WARNING_ENV];
+    }
+    else {
+        env[AWS_SDK_NODE_VERSION_WARNING_ENV] = "true";
+    }
+}
+//# sourceMappingURL=aws-sdk-node-warning-output.js.map

package/dist/lib/company-errors-sdk-warning-flag.d.ts

@@ -0,0 +1,5 @@
+export declare const COMPANY_ERRORS_SDK_WARNING_FLAG = "cli.company-errors-sdk-warning";
+export declare const COMPANY_ERRORS_SDK_WARNING_FALLBACK = false;
+/** One default-off rollout gate for the two US-163 CLI compatibility fixes. */
+export declare function companyErrorsSdkWarningEnabled(): boolean;
+//# sourceMappingURL=company-errors-sdk-warning-flag.d.ts.map

package/dist/lib/company-errors-sdk-warning-flag.js

@@ -0,0 +1,8 @@
+import { resolveProcessFlagGate } from "./flag-registry.js";
+export const COMPANY_ERRORS_SDK_WARNING_FLAG = "cli.company-errors-sdk-warning";
+export const COMPANY_ERRORS_SDK_WARNING_FALLBACK = false;
+/** One default-off rollout gate for the two US-163 CLI compatibility fixes. */
+export function companyErrorsSdkWarningEnabled() {
+    return resolveProcessFlagGate(COMPANY_ERRORS_SDK_WARNING_FLAG, {}, () => COMPANY_ERRORS_SDK_WARNING_FALLBACK);
+}
+//# sourceMappingURL=company-errors-sdk-warning-flag.js.map

package/dist/lib/doctor/checks/work-context.js

@@ -10,7 +10,7 @@ import { readDeviceConfig, } from "../../work-context/config.js";
 import { outboxStats, listOutboxOperations } from "../../work-context/outbox.js";
 import { outboxQuarantineStatusEnabled } from "../../work-context/outbox-quarantine-status-flag.js";
 import { workContextRoot, workContextSessionsDir } from "../../work-context/paths.js";
-import { countJsonlLines, deadLetterNonEmpty, } from "../../mesh/live/spool.js";
+import { countDistinctHeldEvents, countJsonlLines, deadLetterNonEmpty, } from "../../mesh/live/spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../../mesh/live/paths.js";
 import { collectDaemonDoctor, formatDaemonDoctor, } from "../../mesh/live/daemon/doctor.js";
 export const WORK_CONTEXT_FAMILY_ID = "work-context";
@@ -139,7 +139,7 @@ function runChecks(deps) {
     const heldPath = workMeshHeldPath(meshRoot);
     const deadLetterPath = workMeshDeadLetterPath(meshRoot);
     const spoolDepth = countJsonlLines(spoolPath);
-    const heldDepth = countJsonlLines(heldPath);
+    const heldDepth = countDistinctHeldEvents(heldPath);
     results.push({
         status: "PASS",
         checkId: "work-context.spool-depth",

package/dist/lib/lanes/keep-alive.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { LanesError } from "./errors.js";
 import { dropboxInboxHasMessages } from "./dropbox.js";
 import { appendCappedHistory, listQuestionIds, readQuestion, retryUpdateLane } from "./store.js";
-import { isIsoDateTime } from "./types.js";
+import { isTerminalLaneState, isIsoDateTime, } from "./types.js";
 export const LEAD_LANE_KEEP_ALIVE_FLAG = "lanes.lead-keep-alive";
 export const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
 export const LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_FLAG = "lanes.keep-alive-next-check-at";
@@ -254,7 +254,10 @@ export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESS
     return lanes.find((candidate) => {
         if (candidate.lane_id === lane.lane_id || Date.parse(candidate.created_at) <= createdAt)
             return false;
-        if (candidate.state === "cancelled" || candidate.state === "killed" || candidate.state === "failed")
+        if (candidate.state === "cancelled" ||
+            candidate.state === "killed" ||
+            candidate.state === "failed" ||
+            (lane.state === "running" && isTerminalLaneState(candidate.state)))
             return false;
         const candidateCompany = companyOf(candidate) ?? null;
         const sameCompany = laneCompany === null
@@ -270,8 +273,16 @@ export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESS
         const sameLaneSenior = (lane.senior.kind === "lane" || lane.senior.kind === "session") &&
             candidate.senior.kind === lane.senior.kind &&
             candidate.senior.id === lane.senior.id;
+        const differentKnownSenior = lane.senior.kind === "lane" &&
+            candidate.senior.kind === "lane" &&
+            typeof lane.senior.id === "string" &&
+            lane.senior.id.trim().length > 0 &&
+            typeof candidate.senior.id === "string" &&
+            candidate.senior.id.trim().length > 0 &&
+            candidate.senior.id !== lane.senior.id;
         const sameProfile = lane.worker_profile !== undefined &&
             candidate.worker_profile === lane.worker_profile &&
+            !(lane.state === "running" && differentKnownSenior) &&
             !(lineageAware && sameLaneSenior);
         const projectLead = lane.project_id !== undefined &&
             candidate.project_id === lane.project_id &&

package/dist/lib/mesh/live/daemon/doctor.js

@@ -11,7 +11,7 @@ import { readSessionState } from "../../../work-context/state.js";
 import { workContextRoot } from "../../../work-context/paths.js";
 import { outboxQuarantineStatusEnabled } from "../../../work-context/outbox-quarantine-status-flag.js";
 import { formatDroppedPresenceCompany } from "./credentials.js";
-import { countJsonlLines, countUnattributedEvents, } from "../spool.js";
+import { countDistinctHeldEvents, countJsonlLines, countUnattributedEvents, } from "../spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../paths.js";
 import { daemonDir, daemonPidPath } from "./paths.js";
 import { readEmitState } from "../emit.js";
@@ -178,7 +178,7 @@ export function collectDaemonDoctor(deps = {}) {
     const heldPath = workMeshHeldPath(meshRoot);
     const deadPath = workMeshDeadLetterPath(meshRoot);
     const spoolDepth = countJsonlLines(spoolPath);
-    const heldCount = countJsonlLines(heldPath);
+    const heldCount = countDistinctHeldEvents(heldPath);
     const trustedRoots = readDaemonConfig(dir).trustedHqRoots;
     const outboxOperations = listOutboxOperations(ctxRoot);
     const heldWithNoLocalEvidence = readHeldSessions(meshRoot).filter((ref) => {

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

@@ -14,7 +14,7 @@ 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). */
 export declare const HELD_RETRY_INTERVAL_MS: number;
-/** 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 declare const HELD_MAX_LINES = 20000;
 /**
  * Re-check an unbound session against the project catalog at most this often.
@@ -46,7 +46,7 @@ export interface FlushDeps {
     lastHeldRetryAtMs?: number;
     /** Invoked when this flush claims held, so the daemon can advance its timestamp. */
     onHeldClaimed?: (atMs: number) => void;
-    /** Max lines retained in held.jsonl after a flush. Default HELD_MAX_LINES. */
+    /** Max distinct eventIds retained in held.jsonl after a flush. Default HELD_MAX_LINES. */
     heldMaxLines?: number;
     /** Optional logger (daemon wires this); used once per overflow trim. */
     log?: (message: string) => void;

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

@@ -22,7 +22,7 @@ import { defaultSleep, FLUSH_MAX_ATTEMPTS, fullJitterDelayMs, } from "./backoff.
 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;
@@ -31,7 +31,7 @@ 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.
@@ -279,11 +279,9 @@ export async function flushSessionEvents(deps) {
                 state = readSessionState(sessionId, deps.workContextRoot) ?? state;
                 if (!allowed) {
                     const heldAt = now().toISOString();
-                    for (const item of remainingItems) {
-                        appendHeldLine(heldEnvelope(item.event, "NEEDS_COMPANY", item.heldAt ?? heldAt), deps.workMeshRoot);
-                        summary.held += 1;
+                    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;
                 }
             }
@@ -306,11 +304,9 @@ export async function flushSessionEvents(deps) {
             }
             if (decision.action === "hold") {
                 const heldAt = now().toISOString();
-                for (const item of remainingItems) {
-                    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 a bounded portion of this session's remaining backlog (after any
@@ -368,11 +364,9 @@ export async function flushSessionEvents(deps) {
                         deps.log?.(`work-mesh: session ${sessionId} project missing (HTTP 404); downgraded to needs_project and held events`);
                     }
                     const heldAt = now().toISOString();
-                    for (const item of originalChunk) {
-                        appendHeldLine(heldEnvelope(item.event, "NEEDS_PROJECT", item.heldAt ?? heldAt), deps.workMeshRoot);
-                        summary.held += 1;
+                    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) {
@@ -429,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)
@@ -447,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);
@@ -475,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;
@@ -496,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;

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

@@ -19,6 +19,10 @@ export declare function ensureSpoolFile(filePath: string): void;
 export declare function appendJsonlLine(filePath: string, line: string): void;
 export declare function appendSpoolLine(line: string, root?: string): string;
 export declare function appendHeldLine(line: string, root?: string): string;
+/** Append a held envelope only when its eventId is not already held. */
+export declare function appendHeldLineIfAbsent(line: string, root?: string): boolean;
+/** Append a deduplicated held batch under one file lock and one write. */
+export declare function appendHeldLinesIfAbsent(lines: string[], root?: string): number;
 export declare function appendDeadLetterLine(line: string, root?: string): string;
 export declare function appendDroppedReceipt(receipt: Record<string, unknown>, root?: string): string;
 export interface ClaimResult {
@@ -49,6 +53,8 @@ export declare function recoverOrphanClaims(root: string): {
 export declare function removeClaimFile(claimPath: string | null): void;
 export declare function deadLetterNonEmpty(root?: string): boolean;
 export declare function countJsonlLines(filePath: string): number;
+/** Count held eventIds once; legacy rows without an eventId remain line-counted. */
+export declare function countDistinctHeldEvents(filePath: string): number;
 /** Local queues that still lack a usable company attribution. */
 export interface UnattributedEventCounts {
     spool: number;