@cohortapp/agent-sdk 2.3.0

package/lib/session-permissions.test.mjs

@@ -0,0 +1,100 @@
+/**
+ * session-permissions.test.mjs — node:test coverage for the H1 permission
+ * scoping helper. Pure-function tests: no real claude spawn, no filesystem.
+ *
+ * Each test that mutates MAESTRO_SCOPED_PERMISSIONS saves + restores it in a
+ * try/finally so the env change can't leak into other tests in the same node
+ * --test process.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  sessionPermissionArgs,
+  CONSERVATIVE_DEFAULT_ALLOWLIST,
+} from "./session-permissions.mjs";
+import { getCadenceDef } from "../scripts/daemon/cadence-handlers.mjs";
+
+/**
+ * Run `fn` with MAESTRO_SCOPED_PERMISSIONS set to `value` (or deleted when
+ * value is undefined), restoring the prior value afterwards.
+ */
+function withScopedEnv(value, fn) {
+  const prev = process.env.MAESTRO_SCOPED_PERMISSIONS;
+  try {
+    if (value === undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS;
+    else process.env.MAESTRO_SCOPED_PERMISSIONS = value;
+    return fn();
+  } finally {
+    if (prev === undefined) delete process.env.MAESTRO_SCOPED_PERMISSIONS;
+    else process.env.MAESTRO_SCOPED_PERMISSIONS = prev;
+  }
+}
+
+test("default (env unset) returns the skip-permissions arg — UNCHANGED behaviour", () => {
+  withScopedEnv(undefined, () => {
+    assert.deepEqual(
+      sessionPermissionArgs({ cadence: "daily-morning-brief", mode: "escalate" }),
+      ["--dangerously-skip-permissions"],
+    );
+    // Also unchanged when called with no args at all.
+    assert.deepEqual(sessionPermissionArgs(), ["--dangerously-skip-permissions"]);
+  });
+});
+
+test("non-'1' values do NOT enable scoped mode (only the exact opt-in '1' counts)", () => {
+  for (const v of ["0", "true", "yes", "", "01"]) {
+    withScopedEnv(v, () => {
+      assert.deepEqual(
+        sessionPermissionArgs({ cadence: "daily-morning-brief" }),
+        ["--dangerously-skip-permissions"],
+        `value ${JSON.stringify(v)} must not enable scoped mode`,
+      );
+    });
+  }
+});
+
+test("scoped mode emits --allowedTools from the cadence registry allowlist", () => {
+  // Pick a cadence that carries an explicit allowedTools fixture in the
+  // registry. meeting-prep is read-leaning so it's a natural scoped fixture.
+  const cadence = "meeting-prep";
+  const def = getCadenceDef(cadence);
+  assert.ok(Array.isArray(def?.allowedTools) && def.allowedTools.length > 0,
+    `test fixture expects ${cadence} to declare a non-empty allowedTools array in the registry`);
+  withScopedEnv("1", () => {
+    const args = sessionPermissionArgs({ cadence, mode: def.mode });
+    assert.equal(args.length, 2);
+    assert.equal(args[0], "--allowedTools");
+    assert.equal(args[1], def.allowedTools.join(","));
+  });
+});
+
+test("scoped mode falls back to the conservative default for an unknown cadence", () => {
+  withScopedEnv("1", () => {
+    const args = sessionPermissionArgs({ cadence: "totally-unknown-cadence-xyz" });
+    assert.deepEqual(args, ["--allowedTools", CONSERVATIVE_DEFAULT_ALLOWLIST.join(",")]);
+  });
+});
+
+test("scoped mode falls back to the conservative default when cadence is omitted", () => {
+  withScopedEnv("1", () => {
+    const args = sessionPermissionArgs({});
+    assert.deepEqual(args, ["--allowedTools", CONSERVATIVE_DEFAULT_ALLOWLIST.join(",")]);
+  });
+});
+
+test("conservative default allowlist is read-only / search-only (no write, shell, send, or control-plane tools)", () => {
+  const banned = [
+    "Bash", "Write", "Edit", "exec", "spawn", "shell", "run",
+    "send_slack", "send_email", "cron", "schedule", "gateway",
+  ];
+  for (const tool of CONSERVATIVE_DEFAULT_ALLOWLIST) {
+    assert.ok(
+      !banned.includes(tool),
+      `conservative default must not include the dangerous tool ${tool}`,
+    );
+  }
+  // And it must be non-empty so scoped mode never emits an empty allowlist.
+  assert.ok(CONSERVATIVE_DEFAULT_ALLOWLIST.length > 0);
+});

package/lib/setup/claude-probe.mjs

@@ -0,0 +1,74 @@
+/**
+ * lib/setup/claude-probe.mjs — reachability probe for the Claude API.
+ *
+ * Mirrors the curl check in bin/maestro.mjs (doctor, ~:1566): POST a 5-token
+ * ping to api.anthropic.com with the .env key. Returns a structured result with
+ * a remedy line so the wizard's capability table and doctor can share the logic.
+ *
+ * Honors MAESTRO_PREFER_SUBSCRIPTION_AUTH (subscription/keychain OAuth wins → the
+ * probe reports `ok` without an API key).
+ *
+ * @module lib/setup/claude-probe
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+/** Parse a single KEY from a .env file body. */
+function envValue(body, key) {
+  const m = body.match(new RegExp(`^${key}=(.+)$`, "m"));
+  return m ? m[1].trim().replace(/^["']|["']$/g, "") : "";
+}
+
+/**
+ * Probe Claude API reachability for an agent repo.
+ * @param {string} agentRoot
+ * @param {object} [opts]
+ * @param {(args:string[])=>{stdout?:string}} [opts.curl]  injectable curl (for tests)
+ * @returns {{ok:boolean, mode:'subscription'|'api-key'|'none', code?:string, name:string, remedy?:string}}
+ */
+export function probeClaude(agentRoot, opts = {}) {
+  const envPath = join(agentRoot, ".env");
+  const body = existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
+  const preferSubs = /^(1|true|yes)$/i.test(envValue(body, "MAESTRO_PREFER_SUBSCRIPTION_AUTH"));
+  if (preferSubs) {
+    return { ok: true, mode: "subscription", name: "Claude API (subscription auth)" };
+  }
+  const key = envValue(body, "ANTHROPIC_API_KEY");
+  if (!key) {
+    return {
+      ok: false, mode: "none", name: "Claude API reachable",
+      remedy: "set ANTHROPIC_API_KEY in .env, or MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 to use Claude Code subscription",
+    };
+  }
+  const run = opts.curl || ((args) => spawnSync("curl", args, { encoding: "utf-8" }));
+  let code = "";
+  try {
+    const res = run([
+      "-s", "-o", "/dev/null", "-w", "%{http_code}",
+      "-X", "POST",
+      "-H", `x-api-key: ${key}`,
+      "-H", "anthropic-version: 2023-06-01",
+      "-H", "content-type: application/json",
+      "--max-time", "8",
+      "https://api.anthropic.com/v1/messages",
+      "-d", JSON.stringify({ model: "claude-haiku-4-5", max_tokens: 5, messages: [{ role: "user", content: "ping" }] }),
+    ]);
+    code = (res && res.stdout ? res.stdout : "").trim();
+  } catch { code = ""; }
+
+  if (code === "200") return { ok: true, mode: "api-key", code, name: "Claude API reachable" };
+  if (code === "401") {
+    return {
+      ok: false, mode: "api-key", code, name: "Claude API reachable",
+      remedy: "ANTHROPIC_API_KEY is INVALID (HTTP 401) — replace it, or set MAESTRO_PREFER_SUBSCRIPTION_AUTH=1",
+    };
+  }
+  if (!code) {
+    return { ok: false, mode: "api-key", code, name: "Claude API reachable", remedy: "no network / curl missing — could not verify the key" };
+  }
+  return { ok: false, mode: "api-key", code, name: "Claude API reachable", remedy: `unexpected HTTP ${code} (expected 200)` };
+}

package/lib/setup/completeness.mjs

@@ -0,0 +1,175 @@
+/**
+ * lib/setup/completeness.mjs — the operating-model completeness gate.
+ *
+ * Single source of truth for "is this agent fully set up?", shared by both the
+ * `maestro setup` wizard (verify section) and `maestro doctor`. Extracted from
+ * the inline doctor gate so the two never drift.
+ *
+ * `assertComplete(agentRoot)` → { ok, missing: [{ artifact, reason }] }
+ *
+ * Passes iff:
+ *   - identity is populated (non-placeholder firstName/lastName/title/email +
+ *     function/altitude that RESOLVES via resolveArchetype)
+ *   - all six operating-model artifacts are present & placeholder-free:
+ *       config/operating-charter.md         (findCharterPlaceholders → none)
+ *       config/priorities.yaml              (≥1 priority)
+ *       state/queues/backlog.yaml           (≥5 open items)
+ *       config/agent-roster.yaml
+ *       config/cadences.yaml
+ *       policies/communication-profile.yaml
+ *       policies/action-classification.yaml
+ *
+ * Pure-ish: reads files, no writes, no spawns. yaml is loaded lazily (maestro
+ * dep) but the gate degrades to a regex count if it is unavailable.
+ *
+ * @module lib/setup/completeness
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = join(HERE, "..", "..");
+
+/** Placeholder identity values shipped by the scaffold. */
+const PLACEHOLDER_VALUES = new Set(["", "UNCONFIGURED", "AGENT", "Unconfigured Agent", "Unconfigured Role"]);
+
+function isPlaceholder(v) {
+  if (v === undefined || v === null) return true;
+  const s = String(v).trim();
+  if (s === "") return true;
+  if (PLACEHOLDER_VALUES.has(s)) return true;
+  if (/\{\{[^}]+\}\}/.test(s)) return true; // unresolved token
+  return false;
+}
+
+async function loadCharterLib() {
+  return import(pathToFileURL(join(MAESTRO_ROOT, "lib", "charter.mjs")).href);
+}
+async function loadArchetypeLib() {
+  return import(pathToFileURL(join(MAESTRO_ROOT, "lib", "archetype.mjs")).href);
+}
+let _yaml = null;
+async function getYaml() {
+  if (_yaml) return _yaml;
+  try { const m = await import("js-yaml"); _yaml = m && m.default ? m.default : m; }
+  catch { _yaml = null; }
+  return _yaml;
+}
+
+/** Count list items in a yaml file under `key` (falls back to a regex). */
+async function countYamlList(path, key) {
+  if (!existsSync(path)) return 0;
+  const body = readFileSync(path, "utf-8");
+  const yaml = await getYaml();
+  if (yaml) {
+    try {
+      const doc = yaml.load(body);
+      const arr = doc && doc[key];
+      if (Array.isArray(arr)) return arr.length;
+    } catch { /* fall through to regex */ }
+  }
+  return (body.match(/(^|\n)\s*-\s+\S/g) || []).length;
+}
+
+/** Count `status: open` occurrences across state/queues backlog. */
+function countOpenBacklog(agentRoot) {
+  const f = join(agentRoot, "state", "queues", "backlog.yaml");
+  if (!existsSync(f)) return 0;
+  try { return (readFileSync(f, "utf-8").match(/status:\s*open/g) || []).length; }
+  catch { return 0; }
+}
+
+/**
+ * Evaluate identity completeness. Returns the list of missing artifacts (empty
+ * = complete) plus the resolved archetype selector (or null).
+ * @param {object|null} identity  config/agent.json contents
+ * @param {object} archetypeLib
+ */
+async function checkIdentity(identity, archetypeLib) {
+  const missing = [];
+  if (!identity) {
+    missing.push({ artifact: "config/agent.json", reason: "missing — run `maestro setup`" });
+    return { missing, sel: null };
+  }
+  for (const field of ["firstName", "lastName", "title", "email"]) {
+    if (isPlaceholder(identity[field])) {
+      missing.push({ artifact: `identity.${field}`, reason: "unset or placeholder" });
+    }
+  }
+  // archetype must resolve
+  const { resolveArchetype, migrateLegacyArchetype } = archetypeLib;
+  let sel = identity.function && identity.altitude
+    ? { function: identity.function, altitude: identity.altitude }
+    : migrateLegacyArchetype(identity.archetype);
+  if (!sel) {
+    missing.push({ artifact: "identity.archetype", reason: "no { function, altitude } and no legacy archetype" });
+  } else {
+    try { await resolveArchetype(sel); }
+    catch (e) {
+      missing.push({ artifact: "identity.archetype", reason: `unresolvable: ${e && e.message ? e.message : e}` });
+      sel = null;
+    }
+  }
+  return { missing, sel };
+}
+
+/**
+ * The completeness gate. Never throws — failures are reported as `missing`.
+ * @param {string} agentRoot
+ * @returns {Promise<{ok:boolean, missing:Array<{artifact:string, reason:string}>, identityOk:boolean, archetypeOk:boolean}>}
+ */
+export async function assertComplete(agentRoot) {
+  const missing = [];
+  let identity = null;
+  try { const raw = join(agentRoot, "config", "agent.json"); if (existsSync(raw)) identity = JSON.parse(readFileSync(raw, "utf-8")); }
+  catch (e) { missing.push({ artifact: "config/agent.json", reason: `malformed JSON: ${e && e.message ? e.message : e}` }); }
+
+  const archetypeLib = await loadArchetypeLib();
+  const id = await checkIdentity(identity, archetypeLib);
+  for (const m of id.missing) missing.push(m);
+  const identityOk = id.missing.every((m) => !m.artifact.startsWith("identity") && m.artifact !== "config/agent.json")
+    ? true
+    : id.missing.length === 0;
+  const archetypeOk = !!id.sel;
+
+  // 1. operating charter (present + placeholder-free)
+  const charterPath = join(agentRoot, "config", "operating-charter.md");
+  if (!existsSync(charterPath)) {
+    missing.push({ artifact: "config/operating-charter.md", reason: "missing — run generate-charter.mjs" });
+  } else {
+    try {
+      const { findCharterPlaceholders } = await loadCharterLib();
+      const marks = findCharterPlaceholders(readFileSync(charterPath, "utf-8"));
+      if (marks.length) missing.push({ artifact: "config/operating-charter.md", reason: `un-enriched placeholders: ${marks.join(", ")}` });
+    } catch (e) {
+      missing.push({ artifact: "config/operating-charter.md", reason: `unreadable: ${e && e.message ? e.message : e}` });
+    }
+  }
+
+  // 2. priorities ≥1
+  const prioCount = await countYamlList(join(agentRoot, "config", "priorities.yaml"), "priorities");
+  if (prioCount < 1) missing.push({ artifact: "config/priorities.yaml", reason: "empty or missing — run generate-backlog.mjs" });
+
+  // 3. backlog ≥5 open
+  const openItems = countOpenBacklog(agentRoot);
+  if (openItems < 5) missing.push({ artifact: "state/queues/backlog.yaml", reason: `${openItems} open item(s) (<5) — run generate-backlog.mjs` });
+
+  // 4-7. presence of the remaining four artifacts
+  const required = [
+    ["config/agent-roster.yaml", "generate-capability.mjs"],
+    ["config/cadences.yaml", "generate-cadences.mjs"],
+    ["policies/communication-profile.yaml", "generate-comms.mjs"],
+    ["policies/action-classification.yaml", "generate-autonomy.mjs"],
+  ];
+  for (const [rel, gen] of required) {
+    if (!existsSync(join(agentRoot, rel))) missing.push({ artifact: rel, reason: `missing — run ${gen}` });
+  }
+
+  return { ok: missing.length === 0, missing, identityOk, archetypeOk };
+}
+
+export { isPlaceholder };

package/lib/setup/completeness.test.mjs

@@ -0,0 +1,110 @@
+/**
+ * completeness.test.mjs — the shared operating-model gate (lib/setup/completeness.mjs).
+ * Detects placeholders / missing artifacts; passes on a fully generated repo.
+ * Run: `node --test lib/setup/completeness.test.mjs`
+ * @module lib/setup/completeness.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { assertComplete } from "./completeness.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAESTRO_ROOT = resolve(HERE, "..", "..");
+
+function tmpRoot() {
+  const r = mkdtempSync(join(tmpdir(), "maestro-complete-"));
+  mkdirSync(join(r, "config"), { recursive: true });
+  return r;
+}
+
+const POPULATED_IDENTITY = {
+  firstName: "Jacob", lastName: "Chen", fullName: "Jacob Chen",
+  title: "VP, Engineering", email: "jacob@acme.com",
+  function: "technical-leader", altitude: "vp", archetype: "technical-leader",
+  company: "Acme", companyDomain: "acme.com",
+  principal: { firstName: "Dana", lastName: "Reyes", fullName: "Dana Reyes", title: "CEO", email: "dana@acme.com" },
+  schedule: { morningBrief: "08:00", commsTriage: ["09:00"], eveningWrap: "18:00", overnightMonitoring: "22:00" },
+  communication: { defaultTone: "warm-professional", externalTone: "formal", voiceModes: [] },
+  responsibilities: [], operatingPrinciples: [],
+};
+
+function runGen(script, root) {
+  execFileSync(process.execPath, [join(MAESTRO_ROOT, "scripts", "setup", script)], {
+    cwd: root,
+    env: { ...process.env, MAESTRO_ROOT, AGENT_ROOT: root },
+    encoding: "utf-8",
+  });
+}
+
+test("assertComplete reports identity placeholders on a fresh scaffold-like repo", async () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify({
+    firstName: "UNCONFIGURED", lastName: "AGENT", title: "Unconfigured Role", email: "",
+    function: "executive-operator", altitude: "c-suite",
+  }, null, 2));
+  const res = await assertComplete(root);
+  assert.equal(res.ok, false);
+  const arts = res.missing.map((m) => m.artifact);
+  assert.ok(arts.includes("identity.firstName"));
+  assert.ok(arts.includes("identity.email"));
+  // operating-model artifacts also missing
+  assert.ok(arts.includes("config/operating-charter.md"));
+});
+
+test("assertComplete is green after running the real generators on a populated identity", async () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify(POPULATED_IDENTITY, null, 2) + "\n");
+  // company.json so generate-company can run (not gated by completeness but harmless)
+  writeFileSync(join(root, "config/company.json"), JSON.stringify({ name: "Acme", website: "https://acme.com" }, null, 2));
+
+  runGen("generate-charter.mjs", root);
+  runGen("generate-backlog.mjs", root);
+  runGen("generate-capability.mjs", root);
+  runGen("generate-comms.mjs", root);
+  runGen("generate-autonomy.mjs", root);
+  runGen("generate-cadences.mjs", root);
+
+  // The deterministic charter skeleton intentionally leaves "TBD" company slots
+  // (KPI targets, named stakeholders) that the enrich section fills. Simulate
+  // that enrichment so we can assert the green path of the gate itself.
+  const charterPath = join(root, "config/operating-charter.md");
+  const enriched = readFileSync(charterPath, "utf-8")
+    .replace(/\bTBD\b/g, "Q4 target")
+    .replace(/_\(to be defined during init enrichment\)_/g, "defined");
+  writeFileSync(charterPath, enriched);
+
+  const res = await assertComplete(root);
+  assert.equal(res.ok, true, "expected green gate, missing: " + JSON.stringify(res.missing));
+  assert.equal(res.identityOk, true);
+  assert.equal(res.archetypeOk, true);
+});
+
+test("assertComplete flags a charter that still has placeholders", async () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify(POPULATED_IDENTITY, null, 2) + "\n");
+  mkdirSync(join(root, "config"), { recursive: true });
+  writeFileSync(join(root, "config/operating-charter.md"), "# Charter\nMandate: {{agent.firstName}} TBD\n");
+  const res = await assertComplete(root);
+  const charter = res.missing.find((m) => m.artifact === "config/operating-charter.md");
+  assert.ok(charter, "charter placeholder must be flagged");
+  assert.match(charter.reason, /placeholder/);
+});
+
+test("assertComplete flags a too-small backlog (<5 open)", async () => {
+  const root = tmpRoot();
+  writeFileSync(join(root, "config/agent.json"), JSON.stringify(POPULATED_IDENTITY, null, 2) + "\n");
+  mkdirSync(join(root, "state/queues"), { recursive: true });
+  writeFileSync(join(root, "state/queues/backlog.yaml"), "items:\n  - id: 1\n    status: open\n  - id: 2\n    status: open\n");
+  const res = await assertComplete(root);
+  const backlog = res.missing.find((m) => m.artifact === "state/queues/backlog.yaml");
+  assert.ok(backlog);
+  assert.match(backlog.reason, /<5/);
+});

package/lib/setup/context-pack.mjs

@@ -0,0 +1,173 @@
+/**
+ * lib/setup/context-pack.mjs — deterministic context gathering for enrichment.
+ *
+ * Builds `state/setup/context-pack.json` from on-disk, non-LLM sources so the
+ * `enrich` section has a bounded, reproducible grounding bundle:
+ *   - the agent identity (config/agent.json)
+ *   - the company brief (config/company.json)
+ *   - any operator-supplied company context docs (docs/company-context/*.md|txt)
+ *   - the repo README (first N chars)
+ *
+ * NO model calls happen here — that is the whole point (the spine is
+ * deterministic; the LLM is a bounded function called later).
+ *
+ * @module lib/setup/context-pack
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join, dirname, extname } from "node:path";
+
+export const CONTEXT_PACK_REL = "state/setup/context-pack.json";
+
+/** Max bytes pulled from any single doc / README so the pack stays bounded. */
+const MAX_DOC_BYTES = 8000;
+const MAX_DOCS = 20;
+
+function readSafe(path, max = MAX_DOC_BYTES) {
+  try { return readFileSync(path, "utf-8").slice(0, max); }
+  catch { return ""; }
+}
+
+function readJsonSafe(path) {
+  try { return existsSync(path) ? JSON.parse(readFileSync(path, "utf-8")) : null; }
+  catch { return null; }
+}
+
+/** Collect company-context docs (markdown/text) under docs/company-context/. */
+function gatherContextDocs(agentRoot) {
+  const dir = join(agentRoot, "docs", "company-context");
+  if (!existsSync(dir)) return [];
+  const out = [];
+  let names;
+  try { names = readdirSync(dir).sort(); } catch { return []; }
+  for (const name of names) {
+    if (out.length >= MAX_DOCS) break;
+    const ext = extname(name).toLowerCase();
+    if (![".md", ".txt", ".markdown"].includes(ext)) continue;
+    const p = join(dir, name);
+    try { if (!statSync(p).isFile()) continue; } catch { continue; }
+    const body = readSafe(p);
+    if (body.trim()) out.push({ name, excerpt: body });
+  }
+  return out;
+}
+
+/** Max items pulled from any single org-context list so the excerpt stays bounded. */
+const MAX_ORG_ITEMS = 8;
+
+/**
+ * Distil `config/org-context.json` (written by the Cohort bootstrap) into a
+ * bounded, LLM-groundable excerpt: the agent's authoritative org SoT — strategy
+ * north star + levers + streams, escalation path, reports, adopted decisions, and
+ * the ready board frontier. Returns null when there is no cached context so a
+ * standalone (un-enrolled) agent's pack stays exactly as before.
+ * @param {string} agentRoot
+ * @returns {object|null}
+ */
+function gatherOrgContextExcerpt(agentRoot) {
+  const ctx = readJsonSafe(join(agentRoot, "config", "org-context.json"));
+  if (!ctx || typeof ctx !== "object") return null;
+  const profile = ctx.profile && typeof ctx.profile === "object" ? ctx.profile : {};
+  const strategy = ctx.strategy && typeof ctx.strategy === "object" ? ctx.strategy : {};
+  const rel = ctx.relationships && typeof ctx.relationships === "object" ? ctx.relationships : {};
+  const decisions = Array.isArray(ctx.decisions) ? ctx.decisions : [];
+  const board = Array.isArray(ctx.board) ? ctx.board : [];
+  const streams = Array.isArray(strategy.streams) ? strategy.streams : [];
+  const levers = Array.isArray(strategy.levers) ? strategy.levers : [];
+
+  const excerpt = {
+    fetchedAt: ctx.fetchedAt || null,
+    self: {
+      slug: profile.slug || "",
+      title: profile.title || "",
+      escalationPath: profile.escalationPath || "",
+      autonomyLevel: profile.autonomyLevel || "",
+    },
+    strategy: {
+      northStar: strategy.northStar || strategy.northstar || "",
+      levers: levers.slice(0, MAX_ORG_ITEMS).map((l) => (l && (l.label || l.name)) || String(l || "")).filter(Boolean),
+      streams: streams.slice(0, MAX_ORG_ITEMS).map((s) => ({
+        code: (s && s.code) || "",
+        name: (s && s.name) || "",
+        mission: (s && s.mission) || "",
+      })).filter((s) => s.code || s.name),
+    },
+    reports: (Array.isArray(profile.reports) ? profile.reports : (Array.isArray(rel.reports) ? rel.reports : []))
+      .slice(0, MAX_ORG_ITEMS)
+      .map((r) => (r && r.member && (r.member.displayName || r.member.slug)) || (r && (r.displayName || r.slug)) || "")
+      .filter(Boolean),
+    adoptedDecisions: decisions.slice(0, MAX_ORG_ITEMS).map((d) => (d && (d.title || d.summary)) || "").filter(Boolean),
+    readyBoard: board.slice(0, MAX_ORG_ITEMS).map((b) => (b && (b.title || b.name)) || "").filter(Boolean),
+  };
+  return excerpt;
+}
+
+/**
+ * Gather the deterministic context pack object (does not write).
+ * @param {string} agentRoot
+ * @returns {object}
+ */
+export function buildContextPack(agentRoot) {
+  const identity = readJsonSafe(join(agentRoot, "config", "agent.json")) || {};
+  const company = readJsonSafe(join(agentRoot, "config", "company.json")) || {};
+  const docs = gatherContextDocs(agentRoot);
+  const readme = readSafe(join(agentRoot, "README.md"));
+  const orgContext = gatherOrgContextExcerpt(agentRoot);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    identity: {
+      firstName: identity.firstName || "",
+      lastName: identity.lastName || "",
+      fullName: identity.fullName || "",
+      title: identity.title || "",
+      function: identity.function || "",
+      altitude: identity.altitude || "",
+      archetype: identity.archetype || "",
+      company: identity.company || company.name || "",
+      companyDomain: identity.companyDomain || company.domain || "",
+      principal: identity.principal || {},
+    },
+    company: {
+      name: company.name || identity.company || "",
+      legalName: company.legalName || "",
+      website: company.website || "",
+      domain: company.domain || "",
+      industry: company.industry || "",
+      stage: company.stage || "",
+      tagline: company.tagline || "",
+      description: company.description || "",
+      products: Array.isArray(company.products) ? company.products : [],
+      strategicPriorities: Array.isArray(company.strategicPriorities) ? company.strategicPriorities : [],
+      keyPeople: Array.isArray(company.keyPeople) ? company.keyPeople : [],
+      competitors: Array.isArray(company.competitors) ? company.competitors : [],
+    },
+    contextDocs: docs,
+    readmeExcerpt: readme,
+    // The org's authoritative view of this agent (from Cohort), when enrolled.
+    // Omitted entirely for a standalone agent so the pack shape is unchanged there.
+    ...(orgContext ? { orgContext } : {}),
+  };
+}
+
+/**
+ * Build and persist the context pack to state/setup/context-pack.json (atomic).
+ * @param {string} agentRoot
+ * @returns {object} the pack written
+ */
+export function gatherContextPack(agentRoot) {
+  const pack = buildContextPack(agentRoot);
+  const out = join(agentRoot, CONTEXT_PACK_REL);
+  mkdirSync(dirname(out), { recursive: true });
+  const tmp = `${out}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(pack, null, 2) + "\n", "utf-8");
+  renameSync(tmp, out);
+  return pack;
+}
+
+/** Read a previously written context pack (or null). */
+export function readContextPack(agentRoot) {
+  return readJsonSafe(join(agentRoot, CONTEXT_PACK_REL));
+}