@indigoai-us/hq-cloud 5.31.0 → 5.32.0

package/src/lib/describe-error.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { describeError } from "./describe-error.js";
+
+describe("describeError", () => {
+  it("returns String(value) for non-Error throws", () => {
+    expect(describeError("plain string")).toBe("plain string");
+    expect(describeError(42)).toBe("42");
+    expect(describeError(null)).toBe("null");
+    expect(describeError(undefined)).toBe("undefined");
+  });
+
+  it("returns just the message for a plain Error (skips generic 'Error' name)", () => {
+    expect(describeError(new Error("acme blew up"))).toBe("acme blew up");
+  });
+
+  it("includes named subclasses (TypeError, RangeError, …)", () => {
+    expect(describeError(new TypeError("nope"))).toBe("TypeError nope");
+  });
+
+  it("surfaces AWS SDK v3 UnknownError with cause chain (the bug this fixes)", () => {
+    const sdkErr = new Error("UnknownError");
+    sdkErr.name = "UnknownError";
+    const dnsErr = new Error(
+      "getaddrinfo ENOTFOUND privy.s3.us-east-1.amazonaws.com",
+    );
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).code =
+      "ENOTFOUND";
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).syscall =
+      "getaddrinfo";
+    (dnsErr as Error & { code?: string; syscall?: string; hostname?: string }).hostname =
+      "privy.s3.us-east-1.amazonaws.com";
+    (sdkErr as Error & { cause?: unknown }).cause = dnsErr;
+
+    const msg = describeError(sdkErr);
+    expect(msg).toContain("UnknownError");
+    expect(msg).toContain("cause=ENOTFOUND");
+    expect(msg).toContain("syscall=getaddrinfo");
+    expect(msg).toContain("host=privy.s3.us-east-1.amazonaws.com");
+  });
+
+  it("surfaces $metadata.httpStatusCode when present (AccessDenied, etc.)", () => {
+    const err = new Error("The provided credentials were not authorized.");
+    err.name = "AccessDenied";
+    (err as Error & { $metadata?: { httpStatusCode?: number } }).$metadata = {
+      httpStatusCode: 403,
+    };
+    const msg = describeError(err);
+    expect(msg).toContain("AccessDenied");
+    expect(msg).toContain("http=403");
+    expect(msg).toContain("The provided credentials");
+  });
+
+  it("includes own .code attribute on the top-level error", () => {
+    const err = new Error("connect timeout") as Error & { code?: string };
+    err.code = "ETIMEDOUT";
+    expect(describeError(err)).toContain("code=ETIMEDOUT");
+  });
+
+  it("walks up to 3 cause levels, no further", () => {
+    // top → c1 → c2 → c3 → c4 (5 errors, 4 cause hops). The walk should
+    // surface c1/c2/c3 codes but stop before c4.
+    const c4 = new Error("c4");
+    (c4 as Error & { code?: string }).code = "C4_CODE";
+    const c3 = new Error("c3");
+    (c3 as Error & { code?: string; cause?: unknown }).code = "C3_CODE";
+    (c3 as Error & { cause?: unknown }).cause = c4;
+    const c2 = new Error("c2");
+    (c2 as Error & { code?: string; cause?: unknown }).code = "C2_CODE";
+    (c2 as Error & { cause?: unknown }).cause = c3;
+    const c1 = new Error("c1");
+    (c1 as Error & { code?: string; cause?: unknown }).code = "C1_CODE";
+    (c1 as Error & { cause?: unknown }).cause = c2;
+    const top = new Error("top");
+    (top as Error & { cause?: unknown }).cause = c1;
+    const msg = describeError(top);
+    expect(msg).toContain("cause=C1_CODE");
+    expect(msg).toContain("cause=C2_CODE");
+    expect(msg).toContain("cause=C3_CODE");
+    // c4 is the 4th cause level — outside the 3-level walk
+    expect(msg).not.toContain("C4_CODE");
+  });
+
+  it("breaks on a cycle in the cause chain", () => {
+    const a = new Error("a");
+    const b = new Error("b");
+    (a as Error & { cause?: unknown }).cause = b;
+    (b as Error & { cause?: unknown }).cause = a;
+    // Should not infinite-loop; should return something containing "a" and "b".
+    const msg = describeError(a);
+    expect(msg).toContain("a");
+    expect(msg).toContain("b");
+  });
+
+  it("de-dups consecutive identical fragments (the 'UnknownError UnknownError' case)", () => {
+    const err = new Error("UnknownError");
+    err.name = "UnknownError";
+    // Without de-dup the output would start "UnknownError UnknownError".
+    expect(describeError(err)).toBe("UnknownError");
+  });
+});

package/src/lib/describe-error.ts

@@ -0,0 +1,58 @@
+/**
+ * Surface AWS SDK v3's opaque `UnknownError` wrapper.
+ *
+ * When the SDK can't match a response to a modeled exception (which includes
+ * every Node-side networking failure — `getaddrinfo ENOTFOUND`, `ECONNRESET`,
+ * `EHOSTUNREACH`, expired-DNS-cache hits, etc.) it raises an error whose
+ * `name` and `message` are both literally "UnknownError" and stashes the
+ * underlying Node error on `.cause`. Plain `err.message` extraction at the
+ * catch site loses the cause chain entirely, leaving operators with an
+ * unactionable "UnknownError" in the event stream.
+ *
+ * This walks the cause chain (capped at 3 levels) and stitches together a
+ * single diagnostic line that preserves the original failure mode.
+ *
+ * Example outputs:
+ *   "UnknownError cause=ENOTFOUND syscall=getaddrinfo host=hq-vault-cmp-…s3.us-east-1.amazonaws.com"
+ *   "AccessDenied http=403 The provided credentials …"
+ *   "Error code=ETIMEDOUT cause=ETIMEDOUT host=api.example.com"
+ */
+export function describeError(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+
+  const parts: string[] = [];
+  const e = err as Error & {
+    code?: string;
+    $metadata?: { httpStatusCode?: number; requestId?: string };
+    cause?: unknown;
+  };
+
+  if (e.name && e.name !== "Error") parts.push(e.name);
+  if (e.code) parts.push(`code=${e.code}`);
+  if (e.$metadata?.httpStatusCode) parts.push(`http=${e.$metadata.httpStatusCode}`);
+
+  // Walk cause chain to capture the underlying syscall / hostname / code
+  // that the SDK swallowed. Cap depth at 3 and de-cycle with a Set.
+  const seen = new Set<unknown>([err]);
+  let cur: unknown = e.cause;
+  for (let i = 0; i < 3 && cur && !seen.has(cur); i++) {
+    seen.add(cur);
+    const c = cur as {
+      code?: string;
+      syscall?: string;
+      hostname?: string;
+      message?: string;
+      cause?: unknown;
+    };
+    if (c.code) parts.push(`cause=${c.code}`);
+    if (c.syscall) parts.push(`syscall=${c.syscall}`);
+    if (c.hostname) parts.push(`host=${c.hostname}`);
+    if (c.message && c.message !== e.message) parts.push(c.message);
+    cur = c.cause;
+  }
+
+  if (e.message) parts.push(e.message);
+
+  // De-dup consecutive repeats (SDK's "UnknownError UnknownError" case)
+  return parts.filter((p, i) => i === 0 || p !== parts[i - 1]).join(" ");
+}

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