@indigoai-us/hq-cloud 6.14.0 → 6.14.2

package/src/company-resolver.test.ts

@@ -11,6 +11,7 @@ import * as path from "path";
 import {
   buildRepoCompanyMap,
   resolveCompanyForCwd,
+  resolveCompanyForSkill,
 } from "./company-resolver.js";
 
 const INDIGO = "cmp_01INDIGO";
@@ -132,5 +133,55 @@ describe("buildRepoCompanyMap + resolveCompanyForCwd", () => {
     hqRoot = setupHqRoot(":\n  not: [valid: yaml");
     const map = await buildRepoCompanyMap(hqRoot);
     expect(map.entries).toHaveLength(0);
+    expect(map.bySlug.size).toBe(0);
+  });
+});
+
+describe("resolveCompanyForSkill", () => {
+  let hqRoot: string;
+  afterEach(() => {
+    if (hqRoot) fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  it("attributes a company-namespaced skill to its company, regardless of cwd", async () => {
+    hqRoot = setupHqRoot();
+    const map = await buildRepoCompanyMap(hqRoot);
+    // The slug map is populated from the manifest keys with a cloud_uid.
+    expect(resolveCompanyForSkill("indigo:signals", map)).toBe(INDIGO);
+    expect(resolveCompanyForSkill("hpo:some-skill", map)).toBe(HPO);
+    // Multi-segment skill name: only the leading slug is the company.
+    expect(resolveCompanyForSkill("indigo:hq-dev-thread", map)).toBe(INDIGO);
+  });
+
+  it("returns undefined for a core (un-namespaced) skill", async () => {
+    hqRoot = setupHqRoot();
+    const map = await buildRepoCompanyMap(hqRoot);
+    expect(resolveCompanyForSkill("startwork", map)).toBeUndefined();
+    expect(resolveCompanyForSkill("review", map)).toBeUndefined();
+  });
+
+  it("returns undefined for a non-company namespace (personal/pack) and a leading colon", async () => {
+    hqRoot = setupHqRoot();
+    const map = await buildRepoCompanyMap(hqRoot);
+    // `personal` has no cloud_uid → not in the slug map.
+    expect(resolveCompanyForSkill("personal:startwork", map)).toBeUndefined();
+    expect(
+      resolveCompanyForSkill("hq-pack-engineering:review", map),
+    ).toBeUndefined();
+    expect(resolveCompanyForSkill(":oops", map)).toBeUndefined();
+  });
+
+  it("returns undefined for a slug whose company is not cloud-backed", async () => {
+    hqRoot = setupHqRoot();
+    const map = await buildRepoCompanyMap(hqRoot);
+    // `liverecover` is in the manifest but carries no cloud_uid.
+    expect(resolveCompanyForSkill("liverecover:foo", map)).toBeUndefined();
+  });
+
+  it("handles a missing/undefined skill safely", async () => {
+    hqRoot = setupHqRoot();
+    const map = await buildRepoCompanyMap(hqRoot);
+    expect(resolveCompanyForSkill(undefined, map)).toBeUndefined();
+    expect(resolveCompanyForSkill("", map)).toBeUndefined();
   });
 });

package/src/company-resolver.ts

@@ -54,6 +54,14 @@ import yaml from "js-yaml";
 export interface RepoCompanyMap {
   /** Absolute, normalized repo root → owning company `cmp_*` uid. */
   entries: Array<{ repoRoot: string; companyUid: string }>;
+  /**
+   * Company SLUG → owning company `cmp_*` uid, from the manifest keys. Backs
+   * skill-based attribution: a company skill is invoked as `<slug>:<skill>`
+   * (mirroring `companies/<slug>/skills/`), so its usage belongs to the company
+   * named by that slug regardless of the cwd it ran in. Manifest keys are unique,
+   * so a slug resolves to exactly one cloud-backed company here.
+   */
+  bySlug: Map<string, string>;
 }
 
 interface ManifestCompany {
@@ -87,23 +95,28 @@ export async function buildRepoCompanyMap(hqRoot: string): Promise<RepoCompanyMa
     const raw = await fs.readFile(manifestPath, "utf-8");
     const parsed = yaml.load(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return { entries: [] };
+      return { entries: [], bySlug: new Map() };
     }
     doc = parsed as ManifestShape;
   } catch {
     // Missing / unreadable / unparseable — no attribution this run.
-    return { entries: [] };
+    return { entries: [], bySlug: new Map() };
   }
 
   const companies = doc.companies;
-  if (!companies || typeof companies !== "object") return { entries: [] };
+  if (!companies || typeof companies !== "object") {
+    return { entries: [], bySlug: new Map() };
+  }
 
   const entries: Array<{ repoRoot: string; companyUid: string }> = [];
-  for (const company of Object.values(companies)) {
+  const bySlug = new Map<string, string>();
+  for (const [slug, company] of Object.entries(companies)) {
     if (!company || typeof company !== "object") continue;
     const cloudUid = company.cloud_uid;
     // Only cloud-backed companies (with a cmp_* uid) attribute events.
     if (typeof cloudUid !== "string" || !cloudUid.startsWith("cmp_")) continue;
+    // Slug → uid for skill-based attribution (a `<slug>:<skill>` invocation).
+    if (typeof slug === "string" && slug.length > 0) bySlug.set(slug, cloudUid);
     const repos = company.repos;
     if (!Array.isArray(repos)) continue;
     for (const repo of repos) {
@@ -118,7 +131,29 @@ export async function buildRepoCompanyMap(hqRoot: string): Promise<RepoCompanyMa
   // Longest repoRoot first so the first containment match is the most specific
   // (handles nested repo layouts where one repo path prefixes another).
   entries.sort((a, b) => b.repoRoot.length - a.repoRoot.length);
-  return { entries };
+  return { entries, bySlug };
+}
+
+/**
+ * Resolve a skill INVOCATION to its owning company's `cmp_*` uid, or `undefined`
+ * when the skill is not a cloud-backed company's skill.
+ *
+ * A company skill is invoked as `<slug>:<skill>` (the namespaced form of
+ * `companies/<slug>/skills/<skill>`); the leading `<slug>` names the owning
+ * company. We look that slug up in the manifest's slug→uid map, so a company
+ * skill attributes to ITS company no matter which cwd it ran in — this is what
+ * surfaces company-skill usage in the company console. A core / `personal:` /
+ * `hq-pack-*:` / `anthropic-skills:` skill has no matching manifest company, so
+ * it resolves to `undefined` (the cwd resolver remains the fallback).
+ */
+export function resolveCompanyForSkill(
+  skill: string | undefined,
+  map: RepoCompanyMap,
+): string | undefined {
+  if (typeof skill !== "string") return undefined;
+  const idx = skill.indexOf(":");
+  if (idx <= 0) return undefined; // un-namespaced (core) skill
+  return map.bySlug.get(skill.slice(0, idx));
 }
 
 /**

package/src/ignore.test.ts

@@ -29,6 +29,8 @@ describe("isExpectedIgnore", () => {
     expect(isExpectedIgnore("x/.env")).toBe(true);
     expect(isExpectedIgnore("a/b/.hq-sync.pid")).toBe(true);
     expect(isExpectedIgnore("y/foo.pyc")).toBe(true);
+    // Cloud-only skill hero images (US-014) are an expected by-design exclusion.
+    expect(isExpectedIgnore(".claude/skills/foo/.skill-media/hero.png")).toBe(true);
   });
 
   it("keeps nested repos/workspace and ordinary content noteworthy", () => {
@@ -138,7 +140,7 @@ describe("createIgnoreFilter", () => {
 
   it("v12–v14 layout (no core/core.yaml): root core.yaml IS the manifest and MUST sync", () => {
     // Regression for DEV-1729 / the ~98 "no core.yaml in vault, version
-    // undetectable" fleet users. On v12–v14 roots there is NO `core/core.yaml`
+    // undetectable" sync users. On v12–v14 roots there is NO `core/core.yaml`
     // — the ROOT `core.yaml` is the scaffold/version manifest. The old
     // unconditional `/core.yaml` exclusion silently dropped it (while
     // computePersonalVaultPaths still enumerated it), so the vault never
@@ -181,6 +183,21 @@ describe("createIgnoreFilter", () => {
     expect(shouldSync(path.join(hqRoot, ".claude/skills/foo/SKILL.md"))).toBe(true);
   });
 
+  it("permissive mode: .skill-media/ (cloud-only skill images) is ignored (US-014)", () => {
+    const shouldSync = createIgnoreFilter(hqRoot);
+    // Skill hero images are cloud-only — excluded from push AND pull at any depth.
+    expect(
+      shouldSync(path.join(hqRoot, ".claude/skills/lead-qualifier/.skill-media/hero.png")),
+    ).toBe(false);
+    expect(
+      shouldSync(path.join(hqRoot, "companies/indigo/skills/foo/.skill-media/cover.jpg")),
+    ).toBe(false);
+    expect(shouldSync(path.join(hqRoot, "skills/bar/.skill-media"), true)).toBe(false);
+    // The skill's SKILL.md and other content still sync — the rule is scoped to
+    // the media dir only, never the skill.
+    expect(shouldSync(path.join(hqRoot, ".claude/skills/lead-qualifier/SKILL.md"))).toBe(true);
+  });
+
   it("permissive mode: .hq-* internal state is ignored, .hqignore family still sync", () => {
     const shouldSync = createIgnoreFilter(hqRoot);
     // Internal state files that must never round-trip through the bucket.

package/src/ignore.ts

@@ -18,6 +18,16 @@
  *     three exclusion layers still subtract on top — so even allowlisted
  *     subtrees won't push `node_modules/` or `.env`. Privacy-by-default for
  *     HQ trees that contain mixed personal + shareable data.
+ *
+ * SESSIONS ARE PUSH-ONLY, NOT PUSH-IGNORED (US-006). The company-vault
+ * `sessions/{personUid}/...` prefix (session transcripts) is intentionally NOT
+ * added to `DEFAULT_IGNORES`: push-only means it MUST still upload on the push
+ * walk. Its never-AUTO-pull semantics are enforced ONE layer over, in the pull
+ * scope resolver — `resolvePullScope().excludePrefixes` (src/sync/pull-scope.ts)
+ * subtracts `sessions/` from the effective pull scope in EVERY mode (including
+ * `all`), and `computePullPlan` classifies those keys `skip-out-of-scope`.
+ * Ignoring `sessions/` HERE would wrongly block the upload too, so the split is
+ * deliberate: this module governs the push walk; pull-scope governs never-pull.
  */
 
 import * as fs from "fs";
@@ -93,7 +103,7 @@ export const DEFAULT_IGNORES = [
   // `core.yaml` is a stale per-machine duplicate that must not round-trip; on
   // v12–v14 roots there is NO `core/core.yaml` and the ROOT `core.yaml` IS the
   // scaffold/version manifest, which MUST sync (else the vault has no version
-  // marker and the file is undetectable fleet-side).
+  // marker and the file is undetectable across user installs).
   // hq modules manifest — local module-resolution state, never synced.
   "modules/modules.yaml",
   // per-company identity file — written locally on first sync, never round-tripped.
@@ -130,6 +140,16 @@ export const DEFAULT_IGNORES = [
   "**/.claude/settings.json",
   "**/.claude/settings.local.json",
 
+  // Skill hero images (skills-first-class US-014) — cloud-only artifacts stored
+  // under a skill's `.skill-media/` dir (e.g. `skills/<name>/.skill-media/hero.png`).
+  // They live in the vault/DB and are surfaced by the console, but must NEVER
+  // round-trip through the file sync onto agent machines: agents run the skill
+  // from SKILL.md and have no use for the image, and pulling it would litter
+  // every skill dir with binary blobs. Anchored `**/` so it matches at any depth
+  // (hqRoot skills, company skills, embedded knowledge repos) — excludes them
+  // from BOTH push and pull. Mirrors the `**/.claude/worktrees/` anchor shape.
+  "**/.skill-media/",
+
   // HQ repos directory (managed separately, not synced). Root-anchored so
   // only hqRoot/repos/ is excluded; bare `repos/` would match any nested
   // directory named repos (for example companies/<co>/knowledge/repos/),
@@ -247,6 +267,8 @@ export const EXPECTED_IGNORE_SEGMENTS = new Set([
   ".tmp",
   ".hq",
   ".claude",
+  // Cloud-only skill hero images (US-014) — never synced onto agent machines.
+  ".skill-media",
 ]);
 
 /**
@@ -310,7 +332,7 @@ export function createIgnoreFilter(
   //     stale/duplicate per-machine marker, never the authoritative manifest.
   //   - v12–v14 (core/core.yaml absent): do NOT exclude root `core.yaml` — it
   //     IS the manifest and must round-trip, else the file is undetectable
-  //     fleet-side (the ~98 "no core.yaml in vault" users were all old-layout).
+  //     across user installs (the ~98 "no core.yaml in vault" users were all old-layout).
   // Root-anchored (`/core.yaml`) so this never affects `core/core.yaml`.
   if (fs.existsSync(path.join(hqRoot, "core", "core.yaml"))) {
     ig.add("/core.yaml");

package/src/index.ts

@@ -152,7 +152,11 @@ export type {
 // the SAME effective scope the menubar runner does, instead of defaulting every
 // CLI pull to `syncMode: "all"` (the seed of the all→shared scope-shrink wedge,
 // DEV-1768).
-export { resolvePullScope, readPinnedPrefixes } from "./sync/pull-scope.js";
+export {
+  resolvePullScope,
+  readPinnedPrefixes,
+  SESSIONS_SCOPE_PREFIX,
+} from "./sync/pull-scope.js";
 export type { PullScope, PullScopeClient } from "./sync/pull-scope.js";
 
 // Personal-vault scope helpers — shared between hq-sync-runner and `hq sync`
@@ -200,6 +204,9 @@ export type {
   TelemetryOptInResponse,
   UsageBatch,
   UsageIngestResult,
+  RawTelemetryEventInput,
+  TelemetryEventsBatch,
+  TelemetryEventsIngestResult,
   SkillInvocationBatch,
   SkillInvocationIngestResult,
   // US-004 — browse-vs-sync membership sync-mode + ACL surface
@@ -219,6 +226,20 @@ export type {
   TelemetryClientSurface,
 } from "./telemetry.js";
 
+// hq-cloud ACTION telemetry (`/v1/telemetry/events`). Unlike token/skill
+// collectors, these sync/CLI events are not gated by `/v1/usage` opt-in.
+export {
+  agentUidFromClaims,
+  emitCloudTelemetry,
+} from "./telemetry-events.js";
+export type {
+  CloudTelemetryClient,
+  EmitCloudTelemetryOptions,
+  TelemetryClaims,
+  TelemetryEvent,
+  TelemetryProperties,
+} from "./telemetry-events.js";
+
 // Skill-invocation telemetry collector (`/v1/skill-invocations`). Reads the
 // same Claude Code session logs as the token collector but extracts which
 // skill / slash-command was invoked. Independent cursor; same opt-in gate.

package/src/journal.ts

@@ -404,6 +404,18 @@ export function hashSymlinkTarget(target: string): string {
     .digest("hex");
 }
 
+/**
+ * Record a per-file journal entry after a transfer.
+ *
+ * `direction` (`"up"` = pushed / locally authored, `"down"` = pulled) is what
+ * lets scope-shrink tell your own work apart from a mirror of someone else's.
+ * It underpins the US-006 push-only sessions contract: a session transcript
+ * this machine authored and pushed is stamped `direction:"up"`, so even though
+ * `sessions/` is excluded from every pull scope, `buildScopeShrinkPlan` skips
+ * `direction:"up"` entries and never orphans it. (Sessions fetched on demand
+ * via `hq files get` are pulled — `direction:"down"` — but ride the pin union
+ * in the caller's inclusion prefixSet, so they are likewise never pruned.)
+ */
 export function updateEntry(
   journal: SyncJournal,
   relativePath: string,

package/src/lib/exit-codes.ts

@@ -0,0 +1,24 @@
+/**
+ * Runner exit code for a partial sync pass: the pass ran to completion but one
+ * or more per-file transfers threw (`errors.length > 0` in the all-complete
+ * aggregate). Deterministic per-file failures — an oversized object on a
+ * pre-skip runner, a presign denial, an expired token late in a long pass, a
+ * corrupt doubly-scoped vault key — all land here.
+ *
+ * A one-shot `hq sync` exits with this code so humans and scripts see the
+ * failure. The watch loop must NOT exit on it: auto-sync runs unattended, and
+ * a watcher that dies on every partial pass gets hot-respawned by the menubar
+ * supervisor, which Sentry-captures each death as "auto-sync watcher exited
+ * unexpectedly (code=Some(2))". Because the watcher typically runs healthily
+ * for minutes before the failing pass, the supervisor's fast-crash-loop
+ * dampening never engages and EVERY death ships an event — the July 2026
+ * #hq-sentry-alerts flood (~1,700 events across 60+ machines in 5 days).
+ * Instead the loop logs, stays alive, and re-attempts on the next tick; the
+ * per-file errors still surface through the ndjson `error` events and the
+ * `partial: true` all-complete aggregate.
+ *
+ * Kept off the other codes in use by the runner: 0 ok, 1 hard error, 17
+ * op-locked (`OPERATION_LOCKED_EXIT`), 75 transient network
+ * (`TRANSIENT_NETWORK_EXIT`).
+ */
+export const PARTIAL_SYNC_EXIT = 2;

package/src/object-io.test.ts

@@ -234,13 +234,78 @@ describe("PresignObjectIO.putObject", () => {
     // per-path skip (scopeExcludedSet) + the "N paths skipped — outside your
     // granted access" aggregate, instead of a fatal `type:"error"` that exits
     // the runner non-zero and floods Sentry. This is the PUT/GET symmetry that
-    // fixes the fleet-wide presign-put-denied crash-loop.
+    // fixes the presign-put-denied crash-loop across user machines.
     expect((caught as Error).name).toBe("Forbidden");
     expect(isAccessDenied(caught)).toBe(true);
     // Denied at mint time — the byte-moving PUT is never attempted.
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  it("US-006 AC5: a transcript-consent denial (FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED) is skip-with-log, not fatal", async () => {
+    const { vault, setPresign } = makeVault();
+    // The US-005 consent code ends `_REQUIRED`, not `_FORBIDDEN`, so the plain
+    // suffix test alone would MISS it and let it fall through to the fatal
+    // generic Error — the recurring partial-failure this AC5 fix prevents.
+    setPresign([
+      {
+        key: "sessions/prs_1/2026-07-11T10-00-00.json",
+        op: "get",
+        error: "transcript consent required",
+        code: "FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED",
+      },
+    ]);
+    const io = new PresignObjectIO(vault, COMPANY);
+    // Monkeypatch console.warn (vitest's console interception can shadow a spy)
+    // to assert the REAL skip log fires.
+    const warnings: string[] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    let caught: unknown;
+    try {
+      await io
+        .getObject("sessions/prs_1/2026-07-11T10-00-00.json")
+        .catch((e) => {
+          caught = e;
+        });
+    } finally {
+      console.warn = originalWarn;
+    }
+    // Same shape a denied GET already throws → isAccessDenied → the per-key
+    // scope-excluded skip, NOT a fatal `type:"error"` that poisons the run.
+    expect((caught as Error).name).toBe("Forbidden");
+    expect(isAccessDenied(caught)).toBe(true);
+    // A one-line skip log fires so operators can see WHY the key was skipped.
+    expect(
+      warnings.some((w) =>
+        w.includes("FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED"),
+      ),
+    ).toBe(true);
+  });
+
+  it("US-006 AC5: a sessions structural-ACL denial (FILES_PRESIGN_SESSIONS_FORBIDDEN) is skip-with-log", async () => {
+    const { vault, setPresign } = makeVault();
+    // A spoofed/foreign `sessions/{uid}/` prefix the hq-pro structural gate
+    // refuses to presign. Ends `_FORBIDDEN`, so the suffix test already covers
+    // it — this pins that coverage as a regression contract for US-006.
+    setPresign([
+      {
+        key: "sessions/prs_other/y.json",
+        op: "get",
+        error: "not your session prefix",
+        code: "FILES_PRESIGN_SESSIONS_FORBIDDEN",
+      },
+    ]);
+    const io = new PresignObjectIO(vault, COMPANY);
+    let caught: unknown;
+    await io.getObject("sessions/prs_other/y.json").catch((e) => {
+      caught = e;
+    });
+    expect((caught as Error).name).toBe("Forbidden");
+    expect(isAccessDenied(caught)).toBe(true);
+  });
+
   it("a non-authorization presign failure stays a generic (fatal) error — not silently skipped", async () => {
     const { vault, setPresign } = makeVault();
     setPresign([

package/src/object-io.ts

@@ -344,6 +344,35 @@ function metaFromHeaders(headers: Headers): Record<string, string> {
   return meta;
 }
 
+/**
+ * Per-key presign denial codes that are EXPECTED and must be reclassified as
+ * skip-with-log — throwing the `name: "Forbidden"` shape (see
+ * {@link accessDeniedError}) so `isAccessDenied` in sync.ts / share.ts routes
+ * them into the silent per-key scope-excluded skip, never a FATAL sync error.
+ *
+ * Two families qualify:
+ *   1. Any `*_FORBIDDEN` code — an authorization/ACL denial. Covers
+ *      FILES_PRESIGN_FORBIDDEN (no write on a shared prefix), FILES_RAW_FORBIDDEN,
+ *      and — the structural sessions-ACL rejection this US-006 phase relies on —
+ *      FILES_PRESIGN_SESSIONS_FORBIDDEN (a spoofed/foreign `sessions/{uid}/`
+ *      prefix the server refuses to presign).
+ *   2. FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED — the US-005 transcript-consent
+ *      denial. It ends `_REQUIRED`, not `_FORBIDDEN`, so the suffix test alone
+ *      would MISS it and let it fall through to the fatal generic Error below,
+ *      re-introducing exactly the recurring partial-failure that poisons every
+ *      subsequent sync run (US-006 AC5).
+ */
+const SKIP_WITH_LOG_DENIAL_CODES: ReadonlySet<string> = new Set([
+  "FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED",
+]);
+
+function isSkipWithLogDenialCode(code: unknown): code is string {
+  return (
+    typeof code === "string" &&
+    (code.endsWith("_FORBIDDEN") || SKIP_WITH_LOG_DENIAL_CODES.has(code))
+  );
+}
+
 function firstRowOrThrow(
   results: PresignResultRow[],
   key: string,
@@ -354,22 +383,30 @@ function firstRowOrThrow(
     throw new Error(`presign ${op} returned no row for ${key}`);
   }
   if (row.error || !row.url) {
-    // An authorization denial (server `*_FORBIDDEN` code — e.g.
-    // FILES_PRESIGN_FORBIDDEN when the caller lacks write on a shared prefix,
-    // or FILES_RAW_FORBIDDEN) must throw the SAME `name: "Forbidden"` shape the
-    // GET/HEAD path uses (see {@link accessDeniedError}) so it routes through
-    // the `isAccessDenied` skip in sync.ts / share.ts. Without this, a denied
-    // PUT presign fell to the generic Error below — `isAccessDenied` returned
-    // false — and the per-file ACL skip the GET path handles gracefully became
-    // a FATAL sync error: the crash-loop + Sentry flood behind the fleet-wide
-    // "presign put denied" incident (members pushing net-new keys to a
-    // company-wide-read prefix under private-by-default). The denial is
-    // expected; only the fatal handling of it was the bug.
-    if (typeof row.code === "string" && row.code.endsWith("_FORBIDDEN")) {
+    // An expected per-key denial (see {@link isSkipWithLogDenialCode}) must
+    // throw the SAME `name: "Forbidden"` shape the GET/HEAD path uses so it
+    // routes through the `isAccessDenied` skip in sync.ts / share.ts. Without
+    // this, a denied presign fell to the generic Error below — `isAccessDenied`
+    // returned false — and the per-file ACL skip the GET path handles gracefully
+    // became a FATAL sync error: the crash-loop + Sentry flood behind the
+    // widespread "presign put denied" incident (members pushing net-new keys to
+    // a company-wide-read prefix under private-by-default), and — for the
+    // sessions/consent codes — a recurring partial-failure that poisoned every
+    // subsequent sync run (US-006 AC5). The denial is expected; only the fatal
+    // handling of it was the bug. Log a one-line skip so the reason is visible
+    // without the run failing.
+    if (isSkipWithLogDenialCode(row.code)) {
+      // Shared presign layer: this fires for sync legs AND for non-sync callers
+      // (hq files get, signals/sources internals) where the denial surfaces as a
+      // user-facing error, not a continued sync. State only what THIS layer did
+      // (denied → skipped this row) and let the caller own any "sync continues"
+      // / error framing — don't assert an outcome the caller may not take.
+      console.warn(
+        `presign ${op} denied for '${key}' (${row.code}) — skipped`,
+      );
       throw accessDeniedError(
         key,
-        `no write access to '${key}' (server ${op} denied: ${row.code}) — ` +
-          `ask an admin to grant write on this shared prefix`,
+        `no ${op} access to '${key}' (server ${op} denied: ${row.code})`,
       );
     }
     throw new Error(

package/src/operation-lock.test.ts

@@ -73,6 +73,39 @@ describe("operation-lock", () => {
     expect(lockPathFor(rootA + path.sep)).toBe(a);
   });
 
+  it("scopes partition the lock: same root, different scope → different file, no mutual block", () => {
+    // feedback_ed98d810: reindex must not be starved by a long-lived sync/watch
+    // holder. Distinct scopes hash to distinct lock files and never block each
+    // other, while the same scope stays a real cross-process mutex.
+    const opPath = lockPathFor(rootA); // default "operation" scope
+    const reindexPath = lockPathFor(rootA, "reindex");
+    expect(reindexPath).not.toBe(opPath);
+    expect(path.basename(reindexPath).startsWith("reindex-")).toBe(true);
+    expect(path.basename(opPath).startsWith("operation-")).toBe(true);
+
+    let opHandle: ReturnType<typeof acquireOperationLock> | undefined;
+    let reindexHandle: ReturnType<typeof acquireOperationLock> | undefined;
+    try {
+      // A live "operation" holder (as a watch-mode runner keeps) does NOT block
+      // a "reindex"-scope acquire, even with no wait.
+      opHandle = acquireOperationLock(rootA, "sync");
+      expect(() => {
+        reindexHandle = acquireOperationLock(rootA, "reindex", {
+          scope: "reindex",
+          wait: false,
+        });
+      }).not.toThrow();
+      expect(reindexHandle && fs.existsSync(reindexHandle.path)).toBe(true);
+      // ...but a second acquire on the SAME "reindex" scope is still refused.
+      expect(() =>
+        acquireOperationLock(rootA, "reindex", { scope: "reindex", wait: false }),
+      ).toThrowError(OperationLockedError);
+    } finally {
+      reindexHandle?.release();
+      opHandle?.release();
+    }
+  });
+
   it("F14: symlink aliases share the same root lock", () => {
     const aliasParent = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rootA-link-"));
     const aliasRoot = path.join(aliasParent, "alias");

package/src/operation-lock.ts

@@ -3,10 +3,19 @@
  * (`sync`, `rescue`, `reindex`).
  *
  * Contract:
- *   - At most ONE of sync / rescue / reindex runs at a time **per HQ root**.
- *     The lock is shared across all three (keyed only by the root, not the
- *     command), so e.g. a rescue refuses while a sync holds it. Different HQ
- *     roots are fully independent — they hash to different lock files.
+ *   - `sync` and `rescue` share ONE per-root lock (the "operation" scope, keyed
+ *     only by the root, not the command), so at most one of them runs at a time
+ *     and e.g. a rescue refuses while a sync holds it. Different HQ roots are
+ *     fully independent — they hash to different lock files.
+ *   - `reindex` uses a SEPARATE per-root scope ("reindex"), so it is guarded
+ *     against other reindexes but is NOT blocked by a held sync/rescue lock.
+ *     This is deliberate: a watch-mode `hq-sync-runner` holds the "operation"
+ *     lock across its entire lifetime, and a shared lock would starve a
+ *     standalone `hq reindex` indefinitely (feedback_ed98d810). reindex only
+ *     READS the source trees to rebuild derived artifacts (skill wrappers,
+ *     overlay mirrors, the workers registry) and is idempotent + re-run after
+ *     every sync pass, so decoupling it from the sync writer lock is safe.
+ *     See {@link lockPathFor} for how the scope partitions the lock file.
  *   - The push watcher / watch+event-push runner is EXEMPT: it never calls in
  *     here, so it neither takes the lock nor is blocked by it (its targeted
  *     in-process push passes are likewise lock-free).
@@ -202,6 +211,13 @@ export interface AcquireOptions {
    * (or a no-op) to redirect/silence the status line.
    */
   onWaitStart?: (holder: LockInfo, attempted: string) => void;
+  /**
+   * Lock scope — partitions the per-root mutex into independent lock files (see
+   * {@link lockPathFor}). Defaults to {@link DEFAULT_LOCK_SCOPE} ("operation"),
+   * which `sync`/`rescue` share. `reindex` passes "reindex" so it is guarded
+   * against other reindexes without being blocked by a held sync/rescue lock.
+   */
+  scope?: string;
 }
 
 interface ResolvedWaitConfig {
@@ -280,11 +296,26 @@ function canonicalRoot(hqRoot: string): string {
   }
 }
 
-/** Absolute lock path for a given HQ root. Exported for tests. */
-export function lockPathFor(hqRoot: string): string {
+/**
+ * Default lock scope. `sync` and `rescue` share this one so they stay mutually
+ * exclusive with each other, keyed only by the root.
+ */
+export const DEFAULT_LOCK_SCOPE = "operation";
+
+/**
+ * Absolute lock path for a given HQ root and `scope`. Exported for tests.
+ *
+ * The `scope` prefixes the lock filename so callers can partition the mutex:
+ * `sync`/`rescue` use {@link DEFAULT_LOCK_SCOPE} ("operation"); `reindex` uses
+ * its own "reindex" scope so a long-lived watch-mode sync-runner (which holds
+ * the "operation" lock across its whole lifetime) can never starve a standalone
+ * `hq reindex`. Different scopes hash to different lock files and never block
+ * one another; the same scope is a real cross-process mutex.
+ */
+export function lockPathFor(hqRoot: string, scope: string = DEFAULT_LOCK_SCOPE): string {
   const canon = canonicalRoot(hqRoot);
   const key = crypto.createHash("sha1").update(canon).digest("hex").slice(0, 16);
-  return path.join(stateDir(), "locks", `operation-${key}.lock`);
+  return path.join(stateDir(), "locks", `${scope}-${key}.lock`);
 }
 
 /**
@@ -425,8 +456,12 @@ export function rethrowLockCreateError(err: unknown, lockDir: string): never {
 }
 
 /** Build the lock payload + ensure the locks dir exists. */
-function prepareLock(hqRoot: string, command: string): { p: string; info: LockInfo; payload: string } {
-  const p = lockPathFor(hqRoot);
+function prepareLock(
+  hqRoot: string,
+  command: string,
+  scope: string = DEFAULT_LOCK_SCOPE,
+): { p: string; info: LockInfo; payload: string } {
+  const p = lockPathFor(hqRoot, scope);
   const dir = path.dirname(p);
   try {
     fs.mkdirSync(dir, { recursive: true });
@@ -565,7 +600,7 @@ export function acquireOperationLock(
 ): LockHandle {
   if (process.env.HQ_DISABLE_OP_LOCK === "1") return disabledHandle(hqRoot, command);
 
-  const { p, info, payload } = prepareLock(hqRoot, command);
+  const { p, info, payload } = prepareLock(hqRoot, command, opts.scope);
   const cfg = resolveWaitConfig(opts);
   const deadline = cfg.timeoutMs === null ? null : Date.now() + cfg.timeoutMs;
   let announced = false;
@@ -596,7 +631,7 @@ export async function acquireOperationLockAsync(
 ): Promise<LockHandle> {
   if (process.env.HQ_DISABLE_OP_LOCK === "1") return disabledHandle(hqRoot, command);
 
-  const { p, info, payload } = prepareLock(hqRoot, command);
+  const { p, info, payload } = prepareLock(hqRoot, command, opts.scope);
   const cfg = resolveWaitConfig(opts);
   const deadline = cfg.timeoutMs === null ? null : Date.now() + cfg.timeoutMs;
   let announced = false;