@indigoai-us/hq-cloud 6.14.1 → 6.14.3

package/src/cli/sync.ts

@@ -12,7 +12,11 @@ import type {
   VaultServiceConfig,
   SyncJournal,
 } from "../types.js";
-import type { SyncMode } from "../vault-client.js";
+import { VaultClient, type SyncMode } from "../vault-client.js";
+import {
+  emitCloudTelemetry,
+  type TelemetryClaims,
+} from "../telemetry-events.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { createSyncProgressRecorder } from "../sync-progress.js";
 import {
@@ -333,13 +337,31 @@ export type SyncProgressEvent =
        * pushed it into the runner's `errors[]` and made every watch pass return
        * exit 2; the menubar supervisor then reported that as
        * "auto-sync watcher exited unexpectedly (code=Some(2))" on every tick —
-       * the fleet-wide HQ-SYNC-4 flood. Surfaced here purely for visibility
+       * the HQ-SYNC-4 flood across user machines. Surfaced here purely for visibility
        * (`bytes` is the offending file's size) so a UI/CLI can tell the user
        * which file was too big without treating it as a failure.
        */
       type: "skip-size-limit";
       path: string;
       bytes: number;
+    }
+  | {
+      /**
+       * Emitted by the PULL leg once per remote key skipped because it is
+       * invalid for the vault's scope — today, a `companies/…`-prefixed key in
+       * a company-scoped vault (the server rejects these with
+       * INVALID_KEY_COMPANIES_SCOPED; see hq-pro files-acl validateObjectKey).
+       * Such keys are bucket poisoning from a client with a stale doubled
+       * local tree writing via direct S3 (incident 2026-07-11). Like
+       * `skip-size-limit`, this is deliberately NOT `type: "error"` — one bad
+       * object must never error a whole company sync (erroring gated
+       * heartbeat toolset refreshes fleet-wide in the incident). Surfaced for
+       * visibility + cloud telemetry; per policy
+       * hq-alert-baseline-calibration the healthy baseline is ZERO such keys,
+       * so any occurrence is signal.
+       */
+      type: "skip-invalid-scoped-key";
+      path: string;
     };
 
 export interface SyncOptions {
@@ -409,6 +431,23 @@ export interface SyncOptions {
    * failure can never silently prune the local tree.
    */
   prefixSet?: ScopePrefixInput[];
+  /**
+   * Company-relative prefixes SUBTRACTED from the effective pull scope in EVERY
+   * mode — the push-only set (US-006). Carries `sessions/`: session transcripts
+   * are pushed into the vault but never auto-pulled onto grantee laptops, even
+   * under `syncMode: "all"` (which otherwise pulls the whole bucket). A remote
+   * key downloads iff it is covered by the inclusion scope (`prefixSet`, or all
+   * of `all` mode) AND NOT covered by any `excludePrefixes` entry; excluded
+   * keys are classified `skip-out-of-scope`.
+   *
+   * CRITICAL: this set is applied ONLY to the download filter. It is
+   * deliberately NOT fed into the scope-shrink pass (which keeps using the
+   * inclusion `prefixSet` + pins), so a locally-authored (`direction:"up"`) or
+   * pinned on-demand-materialized session is NEVER orphaned/pruned — it is
+   * merely not re-pulled. The runner derives this from
+   * `resolvePullScope().excludePrefixes`.
+   */
+  excludePrefixes?: ScopePrefixInput[];
   /**
    * When the effective scope shrinks relative to the last pull and the shrink
    * would orphan locally-modified ("dirty") files, `sync()` aborts with a
@@ -444,6 +483,12 @@ export interface SyncOptions {
    * it from disk, so it stays pure/hermetic; undefined degrades safely.
    */
   callerSub?: string;
+  /**
+   * Optional decoded Cognito claims used only for action telemetry attribution
+   * (agentUid when `custom:entityType=agent`). Sync behavior never branches on
+   * this field.
+   */
+  telemetryClaims?: TelemetryClaims | null;
   /**
    * Skip the post-sync `reindex()` refresh (skill wrappers + personal overlay
    * mirrors + workers registry). By default, when a sync changes on-disk
@@ -547,6 +592,14 @@ interface PullRunContext {
   remoteFiles: RemoteFile[];
   syncMode: SyncMode;
   currentPrefixSet: string[];
+  /**
+   * Coalesced push-only exclusion prefixes (US-006: `sessions/`), subtracted
+   * from the download filter in EVERY mode. Kept SEPARATE from
+   * `currentPrefixSet` on purpose: the scope-shrink pass reads only
+   * `currentPrefixSet` (+ pins), so excluded-but-authored/pinned session files
+   * are never orphaned.
+   */
+  currentExcludeSet: string[];
   fileTombstones: ReadonlyMap<string, CompanyTombstone>;
 }
 
@@ -625,6 +678,7 @@ export async function reportNewFilesToNotify(
   companyUid: string,
   companySlug: string,
   files: Array<{ path: string; bytes: number; addedBy: string | null }>,
+  telemetryClaims?: TelemetryClaims | null,
 ): Promise<void> {
   if (files.length === 0) return;
 
@@ -639,16 +693,19 @@ export async function reportNewFilesToNotify(
     return;
   }
   const base = vaultConfig.apiUrl.replace(/\/+$/, "");
+  const telemetryClient = new VaultClient(vaultConfig);
+  const batchCount = Math.ceil(files.length / NOTIFY_FILE_ADDED_MAX_BATCH);
 
   for (let i = 0; i < files.length; i += NOTIFY_FILE_ADDED_MAX_BATCH) {
     const batch = files.slice(i, i + NOTIFY_FILE_ADDED_MAX_BATCH);
+    const batchIndex = Math.floor(i / NOTIFY_FILE_ADDED_MAX_BATCH) + 1;
     const controller = new AbortController();
     const timer = setTimeout(
       () => controller.abort(),
       NOTIFY_FILE_ADDED_TIMEOUT_MS,
     );
     try {
-      await fetch(`${base}/v1/notify/file-added`, {
+      const response = await fetch(`${base}/v1/notify/file-added`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${token}`,
@@ -665,16 +722,44 @@ export async function reportNewFilesToNotify(
         }),
         signal: controller.signal,
       });
+      void emitCloudTelemetry(telemetryClient, {
+        eventName: "new_files_notification_reported",
+        source: "hq-sync",
+        companyUid,
+        properties: {
+          result: response.ok ? "success" : "failure",
+          fileCount: batch.length,
+          batchIndex,
+          batchCount,
+          statusCode: response.status,
+        },
+      }, { claims: telemetryClaims });
     } catch (err) {
       // Best-effort per chunk: never let notification reporting affect the sync
       // result, and a failed chunk must not abort the remaining chunks.
       logNotifyFailure(err);
+      void emitCloudTelemetry(telemetryClient, {
+        eventName: "new_files_notification_reported",
+        source: "hq-sync",
+        companyUid,
+        properties: {
+          result: "failure",
+          fileCount: batch.length,
+          batchIndex,
+          batchCount,
+          errorCode: safeErrorName(err),
+        },
+      }, { claims: telemetryClaims });
     } finally {
       clearTimeout(timer);
     }
   }
 }
 
+function safeErrorName(err: unknown): string {
+  return err instanceof Error && err.name ? err.name : "error";
+}
+
 /** Log a non-fatal notify failure without ever throwing out of the logger. */
 function logNotifyFailure(err: unknown): void {
   try {
@@ -724,6 +809,7 @@ async function syncWithOperationLockHeld(
   const plan = planPull(run);
 
   emitPullPlan(run.emit, plan);
+  reportInvalidScopedKeys(run, plan);
 
   const scopePlan = planScopeShrink(run);
   const scopeRun = executeScopeShrink(run, scopePlan);
@@ -795,6 +881,13 @@ async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
   const syncMode: SyncMode = options.syncMode ?? "all";
   const currentPrefixSet: string[] =
     syncMode === "all" ? [""] : coalescePrefixes(options.prefixSet ?? []);
+  // Push-only exclusions (US-006). Coalesced independently of `currentPrefixSet`
+  // and applied to EVERY mode's download filter — including `all` — but kept out
+  // of the scope-shrink inputs (see `planScopeShrink`). Empty when the caller
+  // passes nothing (legacy behavior: no exclusions).
+  const currentExcludeSet: string[] = coalescePrefixes(
+    options.excludePrefixes ?? [],
+  );
 
   const remoteFiles = await listRemoteFiles(ctx);
   const fileTombstones =
@@ -817,6 +910,7 @@ async function buildPullContext(options: SyncOptions): Promise<PullRunContext> {
     remoteFiles,
     syncMode,
     currentPrefixSet,
+    currentExcludeSet,
     fileTombstones,
   };
 }
@@ -831,6 +925,7 @@ function planPull(run: PullRunContext): PullPlan {
     run.options.teamSyncedSlugs ?? null,
     run.currentPrefixSet,
     run.fileTombstones,
+    run.currentExcludeSet,
   );
 }
 
@@ -847,6 +942,33 @@ function emitPullPlan(emit: SyncEventEmitter, plan: PullPlan): void {
   });
 }
 
+/**
+ * Surface scope-invalid remote keys the planner skipped (see the
+ * `invalidScopedKeys` doc on PullPlan). One warning event per key on the
+ * existing sync event channel (deliberately NOT `type: "error"` — see the
+ * `skip-invalid-scoped-key` event doc), plus one best-effort cloud telemetry
+ * event on the channel sync already uses (emitCloudTelemetry). Per policy
+ * hq-alert-baseline-calibration the documented healthy baseline is ZERO
+ * INVALID_KEY_COMPANIES_SCOPED occurrences fleet-wide, so consumers can alert
+ * on any non-zero count with no threshold tuning.
+ */
+function reportInvalidScopedKeys(run: PullRunContext, plan: PullPlan): void {
+  if (plan.invalidScopedKeys.length === 0) return;
+  for (const key of plan.invalidScopedKeys) {
+    run.emit({ type: "skip-invalid-scoped-key", path: key });
+  }
+  void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
+    eventName: "sync_invalid_scoped_key_skipped",
+    source: "hq-sync",
+    companyUid: run.ctx.uid,
+    properties: {
+      count: plan.invalidScopedKeys.length,
+      errorCode: "INVALID_KEY_COMPANIES_SCOPED",
+      leg: "pull",
+    },
+  }, { claims: run.options.telemetryClaims });
+}
+
 function createPullCounters(): PullCounters {
   return {
     filesDownloaded: 0,
@@ -870,6 +992,12 @@ function planScopeShrink(run: PullRunContext): ScopeShrinkPlanState {
     journal: run.journal,
     hqRoot: run.companyRoot,
     lastPrefixSet,
+    // INCLUSION scope only (+ pins, already folded into currentPrefixSet by the
+    // resolver). The push-only exclude set (US-006: `sessions/`) is DELIBERATELY
+    // NOT subtracted here: a session file that was authored locally
+    // (`direction:"up"`) or pinned + materialized on demand must never be
+    // orphaned just because sessions are excluded from the download filter.
+    // Feeding `currentExcludeSet` in here would prune exactly those files.
     currentPrefixSet: run.currentPrefixSet,
     callerSub: run.options.callerSub,
     protectUnknownAuthors: true,
@@ -1429,6 +1557,7 @@ async function emitAndReportNewFiles(
     run.ctx.uid,
     run.ctx.slug,
     enrichedNewFiles,
+    run.options.telemetryClaims,
   );
 }
 
@@ -1438,6 +1567,29 @@ async function verifyPlannedJournalTombstones(
 ): Promise<void> {
   if (plan.tombstones.length === 0) return;
 
+  // Scope-invalid journal keys (company mode, `companies/…` prefix) skip the
+  // HEAD verify: the presign transport's server validator rejects such keys
+  // outright (INVALID_KEY_COMPANIES_SCOPED), so a HEAD can never succeed and
+  // would defer the tombstone forever — leaving the poisoned journal entry
+  // (and its doubled-tree local file) re-firing on every sync. The key can
+  // never legitimately exist in a company vault, so treating it as verified
+  // is safe: the executor cleans the local copy + journal entry instead of
+  // the push leg ever re-uploading it (tombstone-not-reupload).
+  const autoVerified: string[] = [];
+  const toHeadVerify: string[] = [];
+  for (const key of plan.tombstones) {
+    if (run.options.personalMode !== true && key.startsWith("companies/")) {
+      autoVerified.push(key);
+    } else {
+      toHeadVerify.push(key);
+    }
+  }
+  plan.tombstones = toHeadVerify;
+  if (plan.tombstones.length === 0) {
+    plan.tombstones = autoVerified;
+    return;
+  }
+
   await primeObjectTransport(run.ctx, "get", plan.tombstones);
 
   const HEAD_VERIFY_CONCURRENCY = 5;
@@ -1466,7 +1618,7 @@ async function verifyPlannedJournalTombstones(
       if (k !== null) verified.push(k);
     }
   }
-  plan.tombstones = verified;
+  plan.tombstones = [...autoVerified, ...verified];
 }
 
 function executeJournalTombstoneDeletes(
@@ -1545,7 +1697,19 @@ function finalizePullRun(
     scopeRun.scopeOrphansRemoved > 0;
   if (!run.options.skipReindex && changedOnDisk) {
     try {
-      reindex({ repoRoot: run.hqRoot, skipLock: true });
+      const result = reindex({ repoRoot: run.hqRoot, skipLock: true });
+      void emitCloudTelemetry(new VaultClient(run.vaultConfig), {
+        eventName: "reindex_run",
+        source: "hq-sync",
+        companyUid: run.ctx.uid,
+        properties: {
+          result: result.status === 0 ? "completed" : "failed",
+          statusCode: result.status,
+          lockResult: "skipped",
+          changedCount:
+            counters.changedPaths.length + scopeRun.changedPaths.length,
+        },
+      }, { claims: run.options.telemetryClaims });
     } catch (err) {
       logPostSyncMaintenanceFailure("post-sync reindex", run.hqRoot, err);
       // best-effort: a post-sync refresh failure never fails the sync
@@ -1780,6 +1944,15 @@ interface PullPlan {
    * `filesToDelete` axis; the per-item executor applies the local delete.
    */
   filesToTombstoneDelete: number;
+  /**
+   * Remote keys skipped because they are invalid for the vault's scope
+   * (company mode only: literal `companies/…` keys — bucket poisoning from a
+   * doubled-tree client via direct S3). Counted in `filesExcludedByPolicy`;
+   * carried by key so the caller can log one warning per key and emit
+   * telemetry. Healthy baseline is an empty array (policy
+   * hq-alert-baseline-calibration: zero expected, any occurrence is signal).
+   */
+  invalidScopedKeys: string[];
 }
 
 /**
@@ -1847,8 +2020,18 @@ function computePullPlan(
   // preserves the legacy behavior bit-for-bit. (Named `fileTombstones` to avoid
   // shadowing the local `tombstones` string[] — the journal-vs-LIST delete set.)
   fileTombstones: ReadonlyMap<string, CompanyTombstone> = new Map(),
+  // Push-only exclusion prefixes (US-006: `sessions/`). Keys covered by any of
+  // these are classified `skip-out-of-scope` in EVERY mode — including `all` —
+  // AFTER passing the inclusion check. Empty (the default) preserves legacy
+  // behavior bit-for-bit. Applied ONLY here (the download filter), never to
+  // scope-shrink, so an authored/pinned excluded key is not re-pulled yet also
+  // never orphaned.
+  excludePrefixes: readonly ScopePrefixInput[] = [],
 ): PullPlan {
   const items: PullPlanItem[] = [];
+  // Company-mode remote keys invalid for the vault's scope (`companies/…` in a
+  // company bucket) — collected so the caller can warn + emit telemetry.
+  const invalidScopedKeys: string[] = [];
   // Clean/current/non-divergent files missing locally — collected here, then
   // resolved post-loop by the bulk-asymmetry decision (tombstone vs. restore).
   const intentionalDeleteCandidates: Array<{
@@ -1874,6 +2057,23 @@ function computePullPlan(
       continue;
     }
 
+    // Scope-invalid key filter (incident 2026-07-11). A company vault bucket
+    // is already company-scoped, so a literal `companies/…` key can only be
+    // bucket poisoning — a client with a stale doubled local tree
+    // (companies/{slug}/companies/{slug}/…) pushing via the direct-S3 STS
+    // transport, which bypasses the server validator. The presign download
+    // API rejects these keys (INVALID_KEY_COMPANIES_SCOPED), so attempting to
+    // download them errors the WHOLE company sync. Skip them here — one bad
+    // object must never take down a company sync — and record them on the
+    // plan so the caller can warn + emit telemetry (baseline is zero; any
+    // occurrence is signal). Mirrors the personalMode/malformed-key filters
+    // above. Upload-side counterpart: validateVaultUploadKey in s3.ts.
+    if (!personalMode && remoteFile.key.startsWith("companies/")) {
+      invalidScopedKeys.push(remoteFile.key);
+      items.push({ action: "skip-excluded-policy", remoteFile, localPath });
+      continue;
+    }
+
     if (
       personalMode &&
       remoteFile.key.startsWith("companies/") &&
@@ -1917,6 +2117,20 @@ function computePullPlan(
       continue;
     }
 
+    // Push-only exclusion filter (US-006). A key that PASSED the inclusion check
+    // above is STILL not downloaded if it falls under a push-only exclude prefix
+    // (`sessions/`). This is what makes sessions push-only in EVERY mode — it
+    // subtracts from `all` (whose `prefixSet` is `[""]`, covering everything)
+    // and from an owner's role-wide scope alike. Empty `excludePrefixes` (the
+    // default) makes this a no-op. Deliberately AFTER inclusion and reported on
+    // the same `filesOutOfScope` axis. The matching local file (if a session was
+    // previously pulled, authored locally, or pinned+materialized) is NOT pruned
+    // here or by scope-shrink — see `planScopeShrink`, which never sees this set.
+    if (isCoveredByAny(remoteFile.key, excludePrefixes)) {
+      items.push({ action: "skip-out-of-scope", remoteFile, localPath });
+      continue;
+    }
+
     // LIST gives us no kind signal for the remote object — we don't
     // know whether this key is a regular file or a symlink record
     // until we either HEAD it (expensive — N extra calls per pull) or
@@ -2420,6 +2634,7 @@ function computePullPlan(
     filesOutOfScope,
     filesToTombstoneDelete,
     tombstones,
+    invalidScopedKeys,
   };
 }
 
@@ -2502,5 +2717,9 @@ function defaultConsoleLogger(event: SyncProgressEvent): void {
     console.warn(
       `  ! ${event.path} skipped — ${mb} MB exceeds the 50 MB sync size limit`,
     );
+  } else if (event.type === "skip-invalid-scoped-key") {
+    console.warn(
+      `  ! ${event.path} skipped — invalid 'companies/'-prefixed key in a company-scoped vault (bucket poisoning; INVALID_KEY_COMPANIES_SCOPED)`,
+    );
   }
 }

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");