@indigoai-us/hq-cloud 6.11.14 → 6.11.16

package/src/bin/sync-runner.ts

@@ -106,7 +106,9 @@ import { collectAndSendTelemetry } from "../telemetry.js";
 import { collectAndSendSkillTelemetry } from "../skill-telemetry.js";
 import { reindexAfterSync } from "../qmd-reindex.js";
 import { pruneConflictIndex } from "../lib/conflict-index.js";
+import { materializeCodexAgents } from "../agent-codex-instructions.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
+import { describeError } from "../lib/describe-error.js";
 import type { Clock, TreeChangeBatch } from "../watcher.js";
 import type { PushReceiver, SyncEngineFn } from "../sync/push-receiver.js";
 import {
@@ -404,6 +406,53 @@ export interface VaultClientSurface {
   listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
 }
 
+interface RunnerDiagnostic {
+  component: string;
+  event: string;
+  message: string;
+  err?: unknown;
+  context?: Record<string, unknown>;
+}
+
+type RunnerDiagnosticReporter = (diagnostic: RunnerDiagnostic) => void;
+
+function errorDetails(err: unknown): Record<string, unknown> {
+  const details: Record<string, unknown> = { message: describeError(err) };
+  if (err instanceof Error) {
+    if (err.name) details.name = err.name;
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code) details.code = code;
+  }
+  return details;
+}
+
+function createRunnerDiagnosticReporter(
+  stderr: { write: (chunk: string) => boolean | void },
+): RunnerDiagnosticReporter {
+  return (diagnostic) => {
+    try {
+      const payload: Record<string, unknown> = {
+        type: "error",
+        diagnostic: true,
+        component: diagnostic.component,
+        event: diagnostic.event,
+        path: `(${diagnostic.component})`,
+        message:
+          diagnostic.err === undefined
+            ? diagnostic.message
+            : `${diagnostic.message}: ${describeError(diagnostic.err)}`,
+        ...(diagnostic.context ?? {}),
+      };
+      if (diagnostic.err !== undefined) {
+        payload.err = errorDetails(diagnostic.err);
+      }
+      stderr.write(`${JSON.stringify(payload)}\n`);
+    } catch {
+      /* diagnostics must never affect runner control flow */
+    }
+  };
+}
+
 // `resolvePullScope`, `readPinnedPrefixes`, and the `PullScope` type now live
 // in `../sync/pull-scope.ts` so the menubar runner and `hq sync pull|now`
 // (hq-cli) share ONE scope resolver — the drift between them was the root
@@ -459,6 +508,17 @@ interface IdTokenClaims {
   name?: string;
   given_name?: string;
   family_name?: string;
+  /**
+   * Entity-bound machine-identity claims. A headless agent box authenticates
+   * with machine creds (username `machine-agt_*`); its idToken carries the
+   * agent's own entity binding here. The vault authorizer reads these to
+   * resolve the caller AS the agent. The runner reads them to drive
+   * agent-aware `--personal` target resolution: when `custom:entityType ===
+   * "agent"`, the personal slot resolves to the agent's OWN entity
+   * (`custom:entityUid`, `agt_*`) instead of the person-only canonical pick.
+   */
+  "custom:entityType"?: string;
+  "custom:entityUid"?: string;
 }
 
 export interface RunnerDeps {
@@ -769,6 +829,7 @@ export async function defaultCollectTelemetry(
   client: VaultClientSurface,
   clientIsStub: boolean,
   hqRoot: string,
+  reportDiagnostic: RunnerDiagnosticReporter = () => undefined,
 ): Promise<void> {
   if (clientIsStub) return;
 
@@ -797,7 +858,14 @@ export async function defaultCollectTelemetry(
   try {
     const persons = await client.entity.listByType("person");
     if (pickCanonicalPersonEntity(persons) === null) return;
-  } catch {
+  } catch (err) {
+    reportDiagnostic({
+      component: "telemetry",
+      event: "runner.telemetry.person_probe_failed",
+      message: "telemetry person probe failed; continuing with telemetry",
+      err,
+      context: { hqRoot },
+    });
     // Probe failed — preserve prior behavior and let telemetry run.
   }
 
@@ -820,7 +888,14 @@ export async function defaultCollectTelemetry(
   try {
     machineId = getOrCreateMachineId(hqRoot);
     installerVersion = process.env.HQ_INSTALLER_VERSION ?? "hq-cloud";
-  } catch {
+  } catch (err) {
+    reportDiagnostic({
+      component: "telemetry",
+      event: "runner.telemetry.identity_failed",
+      message: "telemetry identity resolution failed; skipping telemetry",
+      err,
+      context: { hqRoot },
+    });
     return;
   }
 
@@ -836,8 +911,22 @@ export async function defaultCollectTelemetry(
       // manifest.yaml and stamp companyUid (US-002). Unmatched cwds stay
       // unattributed (field omitted).
       hqRoot,
+      log: (message) =>
+        reportDiagnostic({
+          component: "telemetry",
+          event: "runner.telemetry.usage_nonfatal",
+          message,
+          context: { hqRoot },
+        }),
+    });
+  } catch (err) {
+    reportDiagnostic({
+      component: "telemetry",
+      event: "runner.telemetry.usage_failed",
+      message: "usage telemetry collector threw",
+      err,
+      context: { hqRoot },
     });
-  } catch {
     // Fire-and-forget; nothing escapes the boundary.
   }
 
@@ -851,8 +940,22 @@ export async function defaultCollectTelemetry(
       // Scope skill capture to the HQ project — only invocations whose cwd is
       // the HQ root are emitted; skill usage in unrelated repos is excluded.
       hqRoot,
+      log: (message) =>
+        reportDiagnostic({
+          component: "telemetry",
+          event: "runner.telemetry.skill_nonfatal",
+          message,
+          context: { hqRoot },
+        }),
+    });
+  } catch (err) {
+    reportDiagnostic({
+      component: "telemetry",
+      event: "runner.telemetry.skill_failed",
+      message: "skill telemetry collector threw",
+      err,
+      context: { hqRoot },
     });
-  } catch {
     // Fire-and-forget; nothing escapes the boundary.
   }
 }
@@ -867,6 +970,7 @@ export async function runRunner(
 ): Promise<number> {
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
+  const reportDiagnostic = createRunnerDiagnosticReporter(stderr);
 
   // ---- emit ---------------------------------------------------------------
   // Error-class events go to stderr; everything else to stdout.
@@ -1022,6 +1126,7 @@ export async function runRunner(
     personal: parsed.personal,
     skipPersonal: parsed.skipPersonal,
     client,
+    claims,
     resolveSkipPersonal,
   });
   if (targetPlan.status === "setup-needed") {
@@ -1068,7 +1173,16 @@ export async function runRunner(
         client,
         deps.createVaultClient !== undefined,
         parsed.hqRoot,
+        reportDiagnostic,
       ),
+    onError: (err) =>
+      reportDiagnostic({
+        component: "telemetry",
+        event: "runner.telemetry.collector_failed",
+        message: "telemetry collector failed",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      }),
   });
 
   emit({
@@ -1095,8 +1209,24 @@ export async function runRunner(
     process.env.HQ_QMD_REINDEX_ON_SYNC !== "0"
   ) {
     try {
-      reindexAfterSync(parsed.hqRoot);
-    } catch {
+      reindexAfterSync(parsed.hqRoot, {
+        log: ({ event, message, err, context }) =>
+          reportDiagnostic({
+            component: "qmd-reindex",
+            event,
+            message,
+            err,
+            context: { hqRoot: parsed.hqRoot, ...(context ?? {}) },
+          }),
+      });
+    } catch (err) {
+      reportDiagnostic({
+        component: "qmd-reindex",
+        event: "runner.qmd_reindex.failed",
+        message: "post-sync qmd reindex threw",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
       // Defensive: reindexAfterSync already swallows internally.
     }
   }
@@ -1113,11 +1243,58 @@ export async function runRunner(
   if (process.env.HQ_CONFLICT_PRUNE_ON_SYNC !== "0") {
     try {
       pruneConflictIndex(parsed.hqRoot);
-    } catch {
+    } catch (err) {
+      reportDiagnostic({
+        component: "conflict-index",
+        event: "runner.conflict_index.prune_failed",
+        message: "post-sync conflict index prune failed",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
       // Defensive: a prune failure must never affect the sync outcome.
     }
   }
 
+  // Post-sync agent codex-instructions materialization — best-effort tail step
+  // (runs AFTER `all-complete`, never affects the exit code). For an AGENT box
+  // ONLY (`custom:entityType === "agent"`), project the synced personal/ agent
+  // overlay (agents-profile.md + agent-capabilities/*.md) into the codex GLOBAL
+  // instruction file ~/.codex/AGENTS.md, which `codex exec` natively merges on
+  // every run. This is the codex mirror of Claude's ~/.claude/CLAUDE.md:
+  // DURABLE (outside the hq-root, so `hq rescue` never touches it) and
+  // fleet-SCALABLE (every box runs @latest each cycle). A human running
+  // `hq sync` (person identity) never triggers it. Opt-out: set
+  // HQ_AGENT_CODEX_MATERIALIZE=0. The write is idempotent and never destructive
+  // (skips when the overlay is empty), and never throws (mirrors the qmd /
+  // conflict-prune tail steps above).
+  if (
+    claims?.["custom:entityType"] === "agent" &&
+    process.env.HQ_AGENT_CODEX_MATERIALIZE !== "0"
+  ) {
+    try {
+      materializeCodexAgents({
+        hqRoot: parsed.hqRoot,
+        log: ({ event, message, err, context }) =>
+          reportDiagnostic({
+            component: "agent-codex-instructions",
+            event,
+            message,
+            err,
+            context: { hqRoot: parsed.hqRoot, ...(context ?? {}) },
+          }),
+      });
+    } catch (err) {
+      reportDiagnostic({
+        component: "agent-codex-instructions",
+        event: "runner.agent_codex_instructions.failed",
+        message: "post-sync agent codex-instructions materialization threw",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
+      // Defensive: materializeCodexAgents already swallows internally.
+    }
+  }
+
   // Exit 2 only when something actually threw (`errors.length > 0`). A clean
   // conflict-abort sets `partial: true` in the JSON but exits 0 — the Tauri
   // menubar's non-zero-exit Sentry capture would otherwise fire for normal

package/src/cli/share.ts

@@ -888,15 +888,6 @@ async function createPushRunContext(options: ShareOptions): Promise<PushRunConte
   let propagateDeletePolicy: DeletePolicy =
     options.propagateDeletePolicy ?? "owned-only";
   const baseEmit = options.onEvent ?? defaultConsoleLogger;
-  // Mirror push progress into the shared cross-process snapshot (see sync.ts).
-  const recordProgress = createSyncProgressRecorder({
-    company: company ?? null,
-    phase: "push",
-  });
-  const emit: ShareEmit = (event) => {
-    baseEmit(event);
-    recordProgress(event);
-  };
 
   if (vaultConfig && entityContext) {
     throw new Error(
@@ -928,6 +919,21 @@ async function createPushRunContext(options: ShareOptions): Promise<PushRunConte
     propagateDeletePolicy = "currency-gated";
   }
 
+  // Mirror push progress into the shared cross-process snapshot (see sync.ts).
+  // Record the friendly company slug, or null for the personal vault so the
+  // menubar shows "Personal" — never the raw prs_/cmp_ UID.
+  const recordProgress = createSyncProgressRecorder({
+    company:
+      ctx.uid.startsWith("prs_") || options.personalMode === true
+        ? null
+        : ctx.slug,
+    phase: "push",
+  });
+  const emit: ShareEmit = (event) => {
+    baseEmit(event);
+    recordProgress(event);
+  };
+
   const syncRoot = options.personalMode === true
     ? hqRoot
     : path.join(hqRoot, "companies", ctx.slug);

package/src/cli/sync.test.ts

@@ -46,6 +46,7 @@ vi.mock("./reindex.js", () => ({
 import { sync, reportNewFilesToNotify } from "./sync.js";
 import * as s3Module from "../s3.js";
 import { reindex } from "./reindex.js";
+import { readSyncProgress } from "../sync-progress.js";
 
 const mockConfig: VaultServiceConfig = {
   apiUrl: "https://vault-api.test",
@@ -144,6 +145,22 @@ describe("sync", () => {
     expect(reindex).toHaveBeenCalledWith({ repoRoot: tmpDir, skipLock: true });
   });
 
+  it("records the company slug, not the input UID, in the shared progress snapshot", async () => {
+    // sync() is called with the company UID, but the menubar popover must show
+    // the friendly slug — so the producer records ctx.slug, never the raw UID.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "docs/x.md", size: 10, lastModified: new Date(), etag: '"x"' },
+    ]);
+    await sync({
+      company: "cmp_01ABCDEF",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+    const snap = readSyncProgress();
+    expect(snap).not.toBeNull();
+    expect(snap!.company).toBe("acme"); // ctx.slug, not "cmp_01ABCDEF"
+  });
+
   it("F15: public sync entrypoint refuses an already-held operation lock", async () => {
     process.env.HQ_OP_LOCK_TIMEOUT = "0";
     const lockPath = lockPathFor(tmpDir);

package/src/cli/sync.ts

@@ -658,6 +658,23 @@ function logNotifyFailure(err: unknown): void {
   }
 }
 
+/** Log a non-fatal post-sync maintenance failure without changing sync state. */
+function logPostSyncMaintenanceFailure(
+  task: string,
+  hqRoot: string,
+  err: unknown,
+): void {
+  try {
+    console.error(
+      `[hq-sync] ${task} failed (non-fatal; hqRoot=${hqRoot}): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  } catch {
+    // swallow — logging must never break sync
+  }
+}
+
 /**
  * Sync (pull) all allowed files from the entity vault.
  */
@@ -710,17 +727,6 @@ async function syncWithOperationLockHeld(
 async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
   const { company, vaultConfig, hqRoot } = options;
   const baseEmit = options.onEvent ?? defaultConsoleLogger;
-  // Mirror every progress event into the shared cross-process snapshot so the
-  // menubar shows live progress for THIS sync regardless of who launched it
-  // (auto-sync / Sync Now / CLI). Best-effort; never affects the sync.
-  const recordProgress = createSyncProgressRecorder({
-    company: company ?? null,
-    phase: "pull",
-  });
-  const emit: SyncEventEmitter = (event) => {
-    baseEmit(event);
-    recordProgress(event);
-  };
 
   const companyRef = company ?? resolveActiveCompany(hqRoot);
   if (!companyRef) {
@@ -738,6 +744,20 @@ async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
   const journalSlug = options.journalSlug ?? ctx.slug;
   const startedAt = new Date().toISOString();
 
+  // Mirror every progress event into the shared cross-process snapshot so the
+  // menubar shows live progress for THIS sync regardless of who launched it
+  // (auto-sync / Sync Now / CLI). Record the friendly company slug (e.g.
+  // "indigo") — or null for the personal vault so the menubar shows "Personal"
+  // — never the raw prs_/cmp_ UID. Best-effort; never affects the sync.
+  const recordProgress = createSyncProgressRecorder({
+    company: options.personalMode === true ? null : ctx.slug,
+    phase: "pull",
+  });
+  const emit: SyncEventEmitter = (event) => {
+    baseEmit(event);
+    recordProgress(event);
+  };
+
   if (journalSlug === PERSONAL_VAULT_JOURNAL_SLUG) migratePersonalVaultJournal();
   const journal = migrateToV2(readJournal(journalSlug));
   gcTombstones(journal, Date.now());
@@ -1466,7 +1486,8 @@ function finalizePullRun(
   if (!run.options.skipReindex && changedOnDisk) {
     try {
       reindex({ repoRoot: run.hqRoot, skipLock: true });
-    } catch {
+    } catch (err) {
+      logPostSyncMaintenanceFailure("post-sync reindex", run.hqRoot, err);
       // best-effort: a post-sync refresh failure never fails the sync
     }
   }

package/src/context.ts

@@ -76,9 +76,15 @@ function slugCacheKey(callerKey: string, slug: string): string {
 /**
  * Closed-set of recognised entity-UID prefixes. Adding a new entity type
  * means appending one entry here AND extending the dispatch in
- * `resolveEntityContext` (cmp_ → /sts/vend, prs_ → /sts/vend-self).
+ * `resolveEntityContext` (cmp_ → /sts/vend, prs_/agt_ → /sts/vend-self).
+ *
+ * `agt_` (US-013, unblocks US-004): a headless agent box syncs its OWN
+ * personal overlay via `hq-sync-runner --personal`, which resolves the
+ * agent's own entity (`agt_*`, bucket `hq-vault-agt-<uid>`). Without `agt_`
+ * here an agt_ uid is mistaken for a SLUG and routed through the company
+ * by-slug lookup; with it, the uid is recognised and self-vended below.
  */
-export const KNOWN_UID_PREFIXES = ["cmp_", "prs_"] as const;
+export const KNOWN_UID_PREFIXES = ["cmp_", "prs_", "agt_"] as const;
 
 /**
  * Look up an entity by slug or UID via vault-service, then vend STS-scoped
@@ -103,7 +109,12 @@ export async function resolveEntityContext(
   const looksLikeUid = KNOWN_UID_PREFIXES.some((p) =>
     companyUidOrSlug.startsWith(p),
   );
-  const looksLikePerson = companyUidOrSlug.startsWith("prs_");
+  // Self-vend covers BOTH person (`prs_`) and agent (`agt_`) entities — each
+  // owns a personal vault gated by self-ownership at `POST /sts/vend-self`,
+  // not the membership-gated company `POST /sts/vend`. (US-013, unblocks
+  // US-004: an agent box self-vends its own `hq-vault-agt-<uid>` vault.)
+  const looksLikePerson =
+    companyUidOrSlug.startsWith("prs_") || companyUidOrSlug.startsWith("agt_");
 
   // For slug lookups, scope the cache key by the caller. Resolving the
   // access token here (once) doubles as a way to extract the sub for
@@ -137,9 +148,9 @@ export async function resolveEntityContext(
   }
 
   // Step 2: Dispatch credential vending by RESOLVED-uid prefix.
-  //   cmp_* → POST /sts/vend      (company path; membership-gated)
-  //   prs_* → POST /sts/vend-self (person path; self-ownership-gated)
-  //   slug  → resolves to a cmp_* (the slug path is company-only)
+  //   cmp_*        → POST /sts/vend      (company path; membership-gated)
+  //   prs_* / agt_* → POST /sts/vend-self (self path; self-ownership-gated)
+  //   slug         → resolves to a cmp_* (the slug path is company-only)
   //
   // HQ-59 vend-skip: when the run uses the presigned-URL transport for company
   // vaults, a `cmp_*` context needs no STS creds (the presign transport

package/src/qmd-reindex.ts

@@ -56,6 +56,13 @@ export interface ReindexOptions {
   readCompanies?: (companiesDir: string) => string[];
   /** Returns true if the knowledge dir has at least one indexable .md file. */
   hasIndexableMarkdown?: (knowledgeDir: string) => boolean;
+  /** Optional diagnostic sink for unexpected swallowed failures. */
+  log?: (diagnostic: {
+    event: string;
+    message: string;
+    err: unknown;
+    context?: Record<string, unknown>;
+  }) => void;
 }
 
 /**
@@ -110,7 +117,17 @@ export function reindexAfterSync(
       const embed = exec(["embed"]);
       result.embedded = embed.status === 0;
     }
-  } catch {
+  } catch (err) {
+    try {
+      opts.log?.({
+        event: "runner.qmd_reindex.internal_failed",
+        message: "post-sync qmd reindex failed",
+        err,
+        context: { hqRoot },
+      });
+    } catch {
+      /* diagnostics must never affect sync */
+    }
     // Reindex is best-effort; the sync result is authoritative. Swallow.
   }
 

package/src/skill-telemetry.test.ts

@@ -9,6 +9,7 @@ import {
   codexRowTurnId,
   parseCodexSessionMeta,
   collectAndSendSkillTelemetry,
+  readFileRegion,
 } from "./skill-telemetry.js";
 import type { SkillInvocationBatch } from "./vault-client.js";
 
@@ -1157,3 +1158,96 @@ describe("collectAndSendSkillTelemetry — companyUid attribution", () => {
     await fs.rm(tmp, { recursive: true, force: true });
   });
 });
+
+describe("readFileRegion — HQ-SYNC-WEB-15 (SIGABRT on >2GiB single read)", () => {
+  const INT32_MAX = 2 ** 31 - 1;
+
+  it("never issues a single read whose length exceeds Int32, even for a multi-GiB region", async () => {
+    // The original code did `fh.read(buf, 0, currentSize - offset, offset)` in
+    // one shot. Once a session log's unread tail passed ~2 GiB, the length
+    // argument was no longer an Int32, so Node's native fs.read asserted
+    // (`args[3]->IsInt32()`) and SIGABRT'd the whole runner. Simulate a 3 GiB
+    // region with a recording fake handle (no real allocation) and prove every
+    // native read length stays within Int32.
+    const THREE_GIB = 3 * 1024 * 1024 * 1024;
+    const lengths: number[] = [];
+    let cursor = 0;
+    const fakeFh = {
+      read: vi.fn(
+        async (_buf: Buffer, _off: number, length: number, position: number) => {
+          lengths.push(length);
+          expect(position).toBe(cursor); // contiguous, in order
+          cursor += length;
+          return { bytesRead: length };
+        },
+      ),
+    };
+
+    const total = await readFileRegion(
+      fakeFh as unknown as Parameters<typeof readFileRegion>[0],
+      Buffer.alloc(0), // recording fake never touches the buffer
+      0,
+      THREE_GIB,
+    );
+
+    expect(total).toBe(THREE_GIB);
+    expect(lengths.length).toBeGreaterThan(1); // it actually chunked
+    for (const len of lengths) {
+      expect(len).toBeGreaterThan(0);
+      expect(len).toBeLessThanOrEqual(INT32_MAX);
+    }
+    expect(lengths.reduce((a, b) => a + b, 0)).toBe(THREE_GIB);
+  });
+
+  it("reads an entire real region correctly across multiple chunks", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "readregion-"));
+    const filePath = path.join(tmp, "data.bin");
+    const payload = Buffer.from("abcdefghijklmnopqrstuvwxyz0123456789", "utf-8");
+    await fs.writeFile(filePath, payload);
+
+    const fh = await fs.open(filePath, "r");
+    try {
+      const buf = Buffer.alloc(payload.length);
+      // Tiny chunk size forces the loop to iterate many times.
+      const read = await readFileRegion(fh, buf, 0, payload.length, 7);
+      expect(read).toBe(payload.length);
+      expect(buf.equals(payload)).toBe(true);
+    } finally {
+      await fh.close();
+    }
+
+    // Reading a sub-region from an offset also lands correctly.
+    const fh2 = await fs.open(filePath, "r");
+    try {
+      const buf = Buffer.alloc(10);
+      const read = await readFileRegion(fh2, buf, 5, 10, 4);
+      expect(read).toBe(10);
+      expect(buf.toString("utf-8")).toBe(payload.toString("utf-8", 5, 15));
+    } finally {
+      await fh2.close();
+    }
+
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("stops cleanly on a short/zero read (file truncated since stat)", async () => {
+    // Ask for 100 bytes but the file only holds 30: the handle yields bytes up
+    // to what's left, then signals EOF with a 0-byte read.
+    let remaining = 30;
+    const fakeFh = {
+      read: vi.fn(async (_b: Buffer, _o: number, length: number) => {
+        const n = Math.min(length, remaining);
+        remaining -= n;
+        return { bytesRead: n };
+      }),
+    };
+    const got = await readFileRegion(
+      fakeFh as unknown as Parameters<typeof readFileRegion>[0],
+      Buffer.alloc(0),
+      0,
+      100,
+      8,
+    );
+    expect(got).toBe(30);
+  });
+});

package/src/skill-telemetry.ts

@@ -594,6 +594,51 @@ async function listJsonlFiles(root: string): Promise<string[]> {
 // session context without slurping a multi-MiB transcript.
 const CODEX_META_PREFIX_BYTES = 64 * 1024;
 
+/**
+ * Largest length passed to a single `FileHandle.read()`. Node's native fs.read
+ * asserts `args[3]->IsInt32()` on the length argument, so a single read whose
+ * length exceeds 2**31-1 (≈2 GiB) does NOT throw a catchable error — it aborts
+ * the whole process with SIGABRT. A skill/session log whose unread tail had
+ * grown past ~2 GiB crashed the entire `hq sync` runner this way
+ * (Sentry HQ-SYNC-WEB-15). 256 MiB stays comfortably within Int32 while keeping
+ * the read-loop iteration count small.
+ */
+const MAX_FS_READ_CHUNK_BYTES = 256 * 1024 * 1024;
+
+/** Minimal structural view of the `FileHandle.read` we depend on. */
+type ReadableFileHandle = {
+  read(
+    buffer: Buffer,
+    offset: number,
+    length: number,
+    position: number,
+  ): Promise<{ bytesRead: number }>;
+};
+
+/**
+ * Read `length` bytes from `fh` starting at byte `position` into `buf`, issuing
+ * native reads no larger than `chunkBytes` so the length argument never exceeds
+ * Int32 and trips the SIGABRT-on-assert path (HQ-SYNC-WEB-15). Returns the total
+ * bytes actually read — which may be < `length` if the file was truncated
+ * between `stat` and this read (a 0-byte read means EOF, so we stop).
+ */
+export async function readFileRegion(
+  fh: ReadableFileHandle,
+  buf: Buffer,
+  position: number,
+  length: number,
+  chunkBytes: number = MAX_FS_READ_CHUNK_BYTES,
+): Promise<number> {
+  let filled = 0;
+  while (filled < length) {
+    const chunk = Math.min(chunkBytes, length - filled);
+    const { bytesRead } = await fh.read(buf, filled, chunk, position + filled);
+    if (bytesRead === 0) break; // EOF / truncated since stat — stop cleanly.
+    filled += bytesRead;
+  }
+  return filled;
+}
+
 /** Read cwd + sessionId from a Codex rollout's leading `session_meta` line.
  *  Always reads from offset 0 (independent of the byte cursor). Best-effort:
  *  any error → empty context (events then fail the hqRoot scope filter, which
@@ -605,7 +650,7 @@ async function readCodexSessionContext(
     const fh = await fs.open(filePath, "r");
     try {
       const buf = Buffer.alloc(CODEX_META_PREFIX_BYTES);
-      const { bytesRead } = await fh.read(buf, 0, CODEX_META_PREFIX_BYTES, 0);
+      const bytesRead = await readFileRegion(fh, buf, 0, CODEX_META_PREFIX_BYTES);
       const firstLine = buf.toString("utf-8", 0, bytesRead).split("\n", 1)[0]?.trim();
       if (!firstLine) return {};
       return parseCodexSessionMeta(JSON.parse(firstLine)) ?? {};
@@ -791,8 +836,11 @@ export async function collectAndSendSkillTelemetry(
       try {
         const length = Math.max(0, currentSize - offset);
         const buf = Buffer.alloc(length);
-        await fh.read(buf, 0, length, offset);
-        content = buf.toString("utf-8");
+        // Chunked: a single fh.read() with length > Int32 aborts the process
+        // with SIGABRT (HQ-SYNC-WEB-15). `bytesRead` may be < length if the
+        // file was truncated since stat — bound the decode to it.
+        const bytesRead = await readFileRegion(fh, buf, offset, length);
+        content = buf.toString("utf-8", 0, bytesRead);
       } finally {
         await fh.close();
       }