@indigoai-us/hq-cloud 5.31.0 → 5.33.0

package/src/lib/machine-id.ts

@@ -0,0 +1,175 @@
+/**
+ * Machine-ID provisioning — owns the per-host identity used to attribute
+ * conflict mirrors, telemetry rows, and `.hq-conflicts/index.json` entries.
+ *
+ * Historically the menubar app (`indigoai-us/hq-sync`) was the sole writer
+ * of `machineId` via `~/.hq/menubar.json`, and every other sync caller
+ * best-effort read from there. That arrangement is backwards: hq-cloud is
+ * the engine that runs on every sync host (macOS-with-menubar, macOS CLI,
+ * Linux HQ Pro Outposts, future Windows), while the menubar is an optional
+ * macOS-only UI. Linux outposts therefore had no menubar.json, so
+ * `readShortMachineId()` returned the literal string `"unknown"` and
+ * every conflict file on those hosts was tagged `-unknown` (which then
+ * also slipped past `EPHEMERAL_PATH_PATTERN` in `src/cli/share.ts` — see
+ * Fix 2 — and rode S3 round-trips as a regular file).
+ *
+ * This module flips ownership: hq-cloud provisions a UUID on first call
+ * and persists it to `<hqRoot>/.hq/machine-id` (one line, plain text).
+ * Every subsequent call hits the persisted file. Existing macOS installs
+ * with menubar-written IDs are migrated forward on first call: tier 3
+ * picks up the menubar.json value, writes it to `<hqRoot>/.hq/machine-id`,
+ * and returns it — so the id is stable across the migration window.
+ *
+ * Resolution order (first hit wins, every miss falls through):
+ *   1. `process.env.HQ_MACHINE_ID` — explicit override for CI / tests.
+ *   2. `<hqRoot>/.hq/machine-id` — source-of-truth on the host.
+ *   3. `~/.hq/menubar.json` `machineId` field — back-compat for existing
+ *      macOS installs; migrated forward to tier 2 on first read.
+ *   4. Autogen — write a fresh UUID to `<hqRoot>/.hq/machine-id` and return.
+ *
+ * Concurrent autogen race is benign: two writers each pick a fresh UUID,
+ * last-writer-wins on disk, both processes re-read the now-stable file on
+ * their next call. The window is narrow (single sync run startup) and the
+ * downside (one extra conflict-file rename across a single race window) is
+ * trivial compared to the litter-ratchet bug it replaces.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/**
+ * Path to `~/.hq/menubar.json`. Evaluated lazily at call time (not module
+ * load) so tests overriding `HOME` post-import see the right file. Going
+ * through `os.homedir()` rather than `process.env.HOME` keeps the Windows
+ * USERPROFILE fallback intact.
+ */
+function menubarJsonPath(): string {
+  return path.join(os.homedir(), ".hq", "menubar.json");
+}
+
+/**
+ * Path to `<hqRoot>/.hq/machine-id` — the source-of-truth file.
+ */
+function hqRootMachineIdPath(hqRoot: string): string {
+  return path.join(hqRoot, ".hq", "machine-id");
+}
+
+/**
+ * Read the persisted id from `<hqRoot>/.hq/machine-id`, or undefined if
+ * absent/unreadable/empty. Trims trailing whitespace so manual edits with
+ * a final newline don't break attribution.
+ */
+function readHqRootMachineId(hqRoot: string): string | undefined {
+  try {
+    const raw = fs.readFileSync(hqRootMachineIdPath(hqRoot), "utf-8").trim();
+    return raw.length > 0 ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read the menubar-written id from `~/.hq/menubar.json`, or undefined if
+ * the file is missing / unreadable / doesn't contain a string `machineId`.
+ */
+function readMenubarMachineId(): string | undefined {
+  try {
+    const raw = fs.readFileSync(menubarJsonPath(), "utf-8");
+    const parsed = JSON.parse(raw) as { machineId?: unknown };
+    if (typeof parsed.machineId === "string" && parsed.machineId.length > 0) {
+      return parsed.machineId;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persist `id` to `<hqRoot>/.hq/machine-id`. Best-effort — failures are
+ * silent so a read-only hqRoot (e.g. a CI mount) still gets a working id
+ * for the current process, even if it can't be persisted for the next run.
+ */
+function persistMachineId(hqRoot: string, id: string): void {
+  try {
+    fs.mkdirSync(path.join(hqRoot, ".hq"), { recursive: true });
+    fs.writeFileSync(hqRootMachineIdPath(hqRoot), `${id}\n`);
+  } catch {
+    // Read-only filesystem or permission issue — caller gets the id back
+    // anyway. Next sync run will retry the persist.
+  }
+}
+
+/**
+ * Resolve or provision the machine id for this host, persisting it to
+ * `<hqRoot>/.hq/machine-id` so the result is stable across sync runs.
+ *
+ * Returns the full id (UUID-shaped on first generation, free-form when
+ * migrated from a menubar.json that wrote something non-UUID). Use
+ * {@link readShortMachineId} for the 6-char prefix used in conflict
+ * filenames.
+ */
+export function getOrCreateMachineId(hqRoot: string): string {
+  // Tier 1: env override.
+  const fromEnv = process.env.HQ_MACHINE_ID;
+  if (fromEnv && fromEnv.length > 0) return fromEnv;
+
+  // Tier 2: persisted source-of-truth.
+  const persisted = readHqRootMachineId(hqRoot);
+  if (persisted) return persisted;
+
+  // Tier 3: back-compat read of menubar.json. Migrate forward on first hit
+  // so subsequent calls take tier 2 and the menubar dependency drops out.
+  const fromMenubar = readMenubarMachineId();
+  if (fromMenubar) {
+    persistMachineId(hqRoot, fromMenubar);
+    return fromMenubar;
+  }
+
+  // Tier 4: autogen + persist.
+  const fresh = randomUUID();
+  persistMachineId(hqRoot, fresh);
+  return fresh;
+}
+
+/**
+ * Short form (six hex chars) for use in conflict filenames. The short
+ * token is what gets stamped into `<orig>.conflict-<ts>-<short>.<ext>` —
+ * see `buildConflictPath` in `./conflict-file.ts`.
+ *
+ * **Always returns `[a-f0-9]{6}`** so the resulting filename matches the
+ * `EPHEMERAL_PATH_PATTERN` in `src/cli/share.ts`. Tier 1 (`HQ_MACHINE_ID`)
+ * and tier 3 (legacy menubar values) can return arbitrary non-hex strings
+ * — e.g. an env override of `"ci-runner-42"` or a menubar-written
+ * `"menubar-legacy-id"`. Slicing those raw would produce `ci-run` or
+ * `menuba`, which the ephemeral filter would refuse and the push walker
+ * would round-trip to S3 — the exact litter-ratchet bug this module
+ * exists to close.
+ *
+ * Normalization: if the first 6 chars of the resolved id are all hex
+ * (the typical UUID / hex-id case), use them as-is so the short token
+ * remains an intuitive prefix of the full id. Otherwise derive a
+ * deterministic SHA-1 hash of the full id and take the first 6 chars —
+ * stable across calls, attributable to the same machine, always hex.
+ */
+export function readShortMachineId(hqRoot: string): string {
+  const full = getOrCreateMachineId(hqRoot);
+  const head = full.slice(0, 6);
+  if (/^[a-f0-9]{6}$/.test(head)) return head;
+  return createHash("sha1").update(full).digest("hex").slice(0, 6);
+}
+
+/**
+ * Test-only exports. Mirrors the `_testing` namespace pattern used by
+ * `src/cli/share.ts` so regression-critical helpers can be pinned by
+ * direct unit tests without round-tripping through the public API.
+ */
+export const _testing = {
+  menubarJsonPath,
+  hqRootMachineIdPath,
+  readHqRootMachineId,
+  readMenubarMachineId,
+  persistMachineId,
+};

package/src/personal-vault.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Unit tests for the personal-vault path-discovery helpers.
+ *
+ * These cover the column-anchored `cloud: false` marker regex and the
+ * `companies/{slug}/` enumeration filter — both are pure functions over
+ * disk + caller-supplied option sets, so we exercise them against tmp
+ * directories rather than mocking fs.
+ *
+ * The sync-runner-level integration (env-var gate, team-synced slug
+ * derivation, end-to-end share() invocation) lives in
+ * `bin/sync-runner.test.ts` — tests G, H, I.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  computePersonalCompanySubdirs,
+  computePersonalVaultPaths,
+  PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS,
+  PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
+} from "./personal-vault.js";
+
+describe("personal-vault helpers", () => {
+  let hqRoot: string;
+
+  beforeEach(() => {
+    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-pv-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  /** Helper: write `companies/{slug}/company.yaml` with arbitrary content. */
+  function writeCompany(slug: string, yaml: string | null): void {
+    const dir = path.join(hqRoot, "companies", slug);
+    fs.mkdirSync(dir, { recursive: true });
+    if (yaml !== null) fs.writeFileSync(path.join(dir, "company.yaml"), yaml);
+  }
+
+  /** Helper: relative-paths-sorted projection of an absolute-path list. */
+  function rel(abs: string[]): string[] {
+    return abs.map((p) => path.relative(hqRoot, p)).sort();
+  }
+
+  // ── Exported constants ─────────────────────────────────────────────────
+  it("constants: PERSONAL_VAULT_EXCLUDED_TOP_LEVEL contains the canonical four names", () => {
+    expect([...PERSONAL_VAULT_EXCLUDED_TOP_LEVEL].sort()).toEqual([
+      ".git",
+      "companies",
+      "repos",
+      "workspace",
+    ]);
+  });
+
+  it("constants: PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS hard-lists `_template`", () => {
+    expect(PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS).toContain("_template");
+  });
+
+  // ── computePersonalCompanySubdirs: marker-regex acceptance ─────────────
+  it("marker: accepts canonical `cloud: false` at column 0", () => {
+    writeCompany("foo", "cloud: false\nname: Foo\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  it("marker: accepts `cloud:false` (no space after colon)", () => {
+    writeCompany("foo", "cloud:false\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  it("marker: accepts trailing comment after `cloud: false`", () => {
+    writeCompany("foo", "cloud: false   # local-only, never upload to team\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  it("marker: accepts CRLF line endings", () => {
+    writeCompany("foo", "cloud: false\r\nname: Foo\r\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  it("marker: accepts `cloud: false` even when it is NOT the first line", () => {
+    writeCompany("foo", "name: Foo\nslug: foo\ncloud: false\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "foo"),
+    ]);
+  });
+
+  // ── computePersonalCompanySubdirs: marker-regex rejection ──────────────
+  it("marker: rejects `cloud: true`", () => {
+    writeCompany("foo", "cloud: true\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects missing company.yaml entirely", () => {
+    writeCompany("foo", null);
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects empty company.yaml", () => {
+    writeCompany("foo", "");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects nested `cloud: false` (column-0 anchor — false-positive guard)", () => {
+    // Regression for an audit finding: an earlier `^[ \t]*cloud:` regex
+    // allowed arbitrary leading whitespace, which silently matched
+    // nested keys like `meta.cloud = false`. The tightened `^cloud:` regex
+    // rejects this, matching the canonical column-0 shape that
+    // `/designate-team`'s awk emits.
+    writeCompany("foo", "meta:\n  cloud: false\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects list-item style `- cloud: false`", () => {
+    writeCompany("foo", "tags:\n- cloud: false\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects flow-mapping `{ cloud: false }`", () => {
+    writeCompany("foo", "{ cloud: false }\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects YAML-alt boolean spellings (False, FALSE, no, off)", () => {
+    for (const variant of ["cloud: False\n", "cloud: FALSE\n", "cloud: no\n", "cloud: off\n"]) {
+      writeCompany("foo", variant);
+      expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+      fs.rmSync(path.join(hqRoot, "companies", "foo"), { recursive: true });
+    }
+  });
+
+  it("marker: rejects quoted `cloud: \"false\"` (the quote breaks the literal-false match)", () => {
+    writeCompany("foo", 'cloud: "false"\n');
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  it("marker: rejects `cloud: falsehood` (word-boundary guard)", () => {
+    writeCompany("foo", "cloud: falsehood\n");
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  // ── Subdir-level filters ───────────────────────────────────────────────
+  it("filter: skips _template even with cloud:false marker", () => {
+    writeCompany("_template", "cloud: false\n");
+    writeCompany("real", "cloud: false\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "real"),
+    ]);
+  });
+
+  it("filter: skips slugs in the teamSyncedSlugs set", () => {
+    writeCompany("free", "cloud: false\n");
+    writeCompany("team-acme", "cloud: false\n");
+    expect(
+      rel(computePersonalCompanySubdirs(hqRoot, new Set(["team-acme"]))),
+    ).toEqual([path.join("companies", "free")]);
+  });
+
+  it("filter: skips stray files under companies/ (only directories considered)", () => {
+    // Hypothetical: someone drops a README.md at companies/. Should not
+    // crash, should not be enumerated as a company subdir.
+    fs.mkdirSync(path.join(hqRoot, "companies"), { recursive: true });
+    fs.writeFileSync(path.join(hqRoot, "companies", "README.md"), "# README");
+    writeCompany("real", "cloud: false\n");
+    expect(rel(computePersonalCompanySubdirs(hqRoot))).toEqual([
+      path.join("companies", "real"),
+    ]);
+  });
+
+  it("filter: missing hqRoot/companies/ returns []", () => {
+    // No `companies/` dir at all (fresh install or atypical layout).
+    expect(computePersonalCompanySubdirs(hqRoot)).toEqual([]);
+  });
+
+  // ── computePersonalVaultPaths: top-level + company-subdir composition ──
+  it("composition: includeLocalCompanies=false skips companies/ entirely", () => {
+    fs.mkdirSync(path.join(hqRoot, ".claude"));
+    fs.mkdirSync(path.join(hqRoot, "knowledge"));
+    writeCompany("foo", "cloud: false\n");
+
+    const out = rel(computePersonalVaultPaths(hqRoot));
+    // Top-level entries present, no companies/* subdir.
+    expect(out).toContain(".claude");
+    expect(out).toContain("knowledge");
+    expect(out.some((p) => p.startsWith("companies"))).toBe(false);
+  });
+
+  it("composition: includeLocalCompanies=true adds opt-in company subdirs", () => {
+    fs.mkdirSync(path.join(hqRoot, "knowledge"));
+    writeCompany("foo", "cloud: false\n");
+    writeCompany("bar", "cloud: true\n");
+
+    const out = rel(computePersonalVaultPaths(hqRoot, { includeLocalCompanies: true }));
+    expect(out).toContain("knowledge");
+    expect(out).toContain(path.join("companies", "foo"));
+    expect(out).not.toContain(path.join("companies", "bar"));
+    // The companies/ top-level entry itself is never present — only specific
+    // opted-in subdirs. Preserves the invariant that share() never walks
+    // the whole companies/ tree under personalMode.
+    expect(out).not.toContain("companies");
+  });
+
+  it("composition: includeLocalCompanies=true + teamSyncedSlugs filter combine correctly", () => {
+    writeCompany("foo", "cloud: false\n");
+    writeCompany("synced", "cloud: false\n");
+
+    const out = rel(
+      computePersonalVaultPaths(hqRoot, {
+        includeLocalCompanies: true,
+        teamSyncedSlugs: new Set(["synced"]),
+      }),
+    );
+    expect(out).toContain(path.join("companies", "foo"));
+    expect(out).not.toContain(path.join("companies", "synced"));
+  });
+
+  it("composition: missing hqRoot returns []", () => {
+    fs.rmSync(hqRoot, { recursive: true });
+    expect(computePersonalVaultPaths(hqRoot, { includeLocalCompanies: true })).toEqual([]);
+  });
+});

package/src/personal-vault.ts

@@ -14,8 +14,14 @@
  *   - `.git`: a git repo's own metadata is hostile to multi-machine
  *     sync; .gitignore alone doesn't cover `.git/` because it's the repo
  *     itself, not a tracked path.
- *   - `companies/`: synced separately by the runner's per-membership
- *     fanout; do not double-write into the personal vault.
+ *   - `companies/`: the top-level `companies/` directory is never enumerated
+ *     wholesale. Team-backed companies are synced by the runner's
+ *     per-membership fanout (one bucket per company). Individual
+ *     `companies/{slug}/` subdirs MAY be added back via
+ *     `computePersonalCompanySubdirs()` for companies that explicitly
+ *     declare `cloud: false` in `company.yaml` and are not in the operator's
+ *     team-synced membership set — those land under the personal bucket as
+ *     `companies/{slug}/...` keys.
  *   - `repos/`, `workspace/`: per user directive — heavy local-only
  *     content (cloned remotes, session threads) that has no business in
  *     the personal vault.
@@ -41,23 +47,143 @@ export const PERSONAL_VAULT_EXCLUDED_TOP_LEVEL: readonly string[] = [
 ];
 
 /**
- * Compute absolute paths to share for the personal vault: every top-level
- * entry under `hqRoot` whose basename is NOT in
- * `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL`. Mirrors the Rust
- * `is_personal_vault_path` predicate (just hoisted to the top-level step).
+ * Company slugs that are never eligible for the personal-bucket fallback,
+ * regardless of their `cloud:` marker. `_template` is the scaffolding
+ * source for `/newcompany` — copying it into the personal vault would
+ * pollute every machine's vault with the template tree.
+ */
+export const PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS: readonly string[] = [
+  "_template",
+];
+
+export interface PersonalVaultOptions {
+  /**
+   * Slugs of companies that already have their own team bucket (i.e. the
+   * operator has an active Membership row for them). These are excluded
+   * from the personal-bucket fallback so a single company's content never
+   * ends up in two buckets.
+   */
+  teamSyncedSlugs?: ReadonlySet<string>;
+  /**
+   * When true, walk `companies/` and include subdirs that explicitly opt in
+   * via `cloud: false` in their `company.yaml` (after applying the standard
+   * filter: exclude `_template`, exclude team-synced slugs). When false
+   * (the default), `companies/` is never enumerated — same as the legacy
+   * personal-vault scope. Gated behind a runtime flag so the new behavior
+   * stays opt-in until operators explicitly request it via
+   * `HQ_SYNC_LOCAL_COMPANIES_TO_PERSONAL=1`.
+   */
+  includeLocalCompanies?: boolean;
+}
+
+/**
+ * Compute absolute paths to share for the personal vault.
+ *
+ * Two sources are concatenated:
+ *   1. Every top-level entry under `hqRoot` whose basename is NOT in
+ *      `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL`.
+ *   2. Every `companies/{slug}/` subdir that opts into the personal
+ *      bucket via `company.yaml: cloud: false`, after excluding (a)
+ *      `_template`, (b) slugs already in `opts.teamSyncedSlugs`, and
+ *      (c) any subdir without an explicit `cloud: false` marker.
+ *
  * Order is whatever `fs.readdirSync` returns — share() doesn't care, and
  * the per-file walk inside share() handles recursion uniformly. Missing
  * hqRoot returns []; callers treat that as "no personal content to push"
  * rather than a hard error.
  */
-export function computePersonalVaultPaths(hqRoot: string): string[] {
+export function computePersonalVaultPaths(
+  hqRoot: string,
+  opts: PersonalVaultOptions = {},
+): string[] {
   let entries: string[];
   try {
     entries = fs.readdirSync(hqRoot);
   } catch {
     return [];
   }
-  return entries
+  const topLevel = entries
     .filter((name) => !PERSONAL_VAULT_EXCLUDED_TOP_LEVEL.includes(name))
     .map((name) => path.join(hqRoot, name));
+  const companySubdirs = opts.includeLocalCompanies === true
+    ? computePersonalCompanySubdirs(hqRoot, opts.teamSyncedSlugs)
+    : [];
+  return [...topLevel, ...companySubdirs];
+}
+
+/**
+ * Discover `companies/{slug}/` subdirs that should sync to the personal
+ * bucket as a fallback for companies the operator has not designated as
+ * team-backed. Filter rules (all must hold):
+ *
+ *   1. The subdir is a directory (skip stray files).
+ *   2. The slug is NOT in `PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS`
+ *      (currently just `_template`).
+ *   3. The slug is NOT in `teamSyncedSlugs` (membership-backed slugs sync
+ *      to their own bucket and must not be double-written).
+ *   4. `companies/{slug}/company.yaml` exists and contains a
+ *      `cloud: false` line. A missing file or `cloud: true` opts the
+ *      directory OUT of the personal vault — silent inclusion would
+ *      capture scratch/dead dirs the user never intended to ship.
+ *
+ * Returns absolute paths.
+ */
+export function computePersonalCompanySubdirs(
+  hqRoot: string,
+  teamSyncedSlugs: ReadonlySet<string> = new Set(),
+): string[] {
+  const companiesRoot = path.join(hqRoot, "companies");
+  let slugs: string[];
+  try {
+    slugs = fs.readdirSync(companiesRoot);
+  } catch {
+    return [];
+  }
+  const eligible: string[] = [];
+  for (const slug of slugs) {
+    if (PERSONAL_VAULT_COMPANY_EXCLUDED_SLUGS.includes(slug)) continue;
+    if (teamSyncedSlugs.has(slug)) continue;
+    const subdir = path.join(companiesRoot, slug);
+    let isDir = false;
+    try {
+      isDir = fs.statSync(subdir).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+    if (!companyHasCloudFalseMarker(subdir)) continue;
+    eligible.push(subdir);
+  }
+  return eligible;
+}
+
+/**
+ * True iff `{subdir}/company.yaml` exists and contains an explicit
+ * top-level `cloud: false` line. Matches the canonical shape
+ * `/designate-team` writes — that command's awk is the only producer of
+ * this key, and it always emits `cloud: <bool>` at column zero with no
+ * indentation, no quoting, lowercase boolean, optional trailing comment.
+ *
+ * Anchored at column 0 deliberately:
+ *   - rejects `meta:\n  cloud: false` (nested key, would be `meta.cloud`
+ *     in a real YAML parser — false positive for us if we allowed
+ *     arbitrary leading whitespace)
+ *   - rejects `- cloud: false` (list item, also a nested key)
+ *   - rejects flow mappings like `{ cloud: false }`
+ *
+ * Other intentional rejections (lowercase `false` only, no YAML-alt
+ * boolean spellings): `cloud: False`, `cloud: FALSE`, `cloud: no`,
+ * `cloud: off`, `cloud: "false"`, `cloud: 'false'`. None of these are
+ * produced by `/designate-team`; matching them risks confusing
+ * round-trips with hand-edited YAML.
+ */
+function companyHasCloudFalseMarker(subdir: string): boolean {
+  const yamlPath = path.join(subdir, "company.yaml");
+  let text: string;
+  try {
+    text = fs.readFileSync(yamlPath, "utf8");
+  } catch {
+    return false;
+  }
+  return /^cloud:\s*false\b/m.test(text);
 }