@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/lib/setup/enroll-from-cohort.mjs

@@ -218,9 +218,19 @@ export function mapProfileToAgentConfig(profile) {
 }
 
 /**
- * Map a CharterDTO ({ approvedByLine, gatesText, sections:[{kind,order,title,body}] })
+ * Map a CharterDTO ({ approvedByLine, gatesText, sections:[{id,kind,order,title,body}] })
  * into the persisted charter subset. Returns null when there is no real charter
  * (no sections AND no approvedBy/gates text) so an empty patch stays empty.
+ *
+ * `id` IS CARRIED, and it is load-bearing. This projection is the ONLY writer of
+ * `config/agent.json` charter.sections, and it used to drop the field — so every
+ * section on every enrolled seat had keys `[body,kind,order,title]` only,
+ * `lib/mandate/derive.mjs#charterSectionId` read `s.id` as undefined, and every
+ * proposal reached hq with null charter provenance. hq's `propose` gate then
+ * refuses the whole slate for "traces to no CharterSection", which reads as a
+ * governance decision and is actually a dropped column three modules upstream.
+ * The id is hq's `CharterSection.id`; it is a join key, not content.
+ *
  * @param {object|null} charter
  * @returns {object|null}
  */
@@ -230,6 +240,9 @@ function mapCharter(charter) {
   const sections = sectionsIn
     .filter((s) => s && typeof s === "object")
     .map((s) => ({
+      // Omitted rather than nulled when hq did not send one, so a charter fetched
+      // from an older hq stays byte-identical to what it was before.
+      ...(str(s.id) ? { id: str(s.id) } : {}),
       kind: str(s.kind),
       order: Number.isFinite(s.order) ? s.order : 0,
       title: str(s.title) || null,

package/lib/setup/sections/mandate.mjs

@@ -198,19 +198,54 @@ export async function resolveMandate(o = {}, deps = {}) {
   // call adopt, from anywhere, for any reason.
   const proposals = res.source === "local" ? allObjectives(res.record) : [];
   if (typeof call === "function" && proposals.length) {
+    // PILLARS FIRST, then their children. hq's `mandate.propose` takes
+    // `parentId` and `charterSectionId` — real row ids — and has never had any
+    // idea what a `parentKey` is. This loop used to post `parentKey`, which the
+    // dispatcher discarded as an unknown param, so EVERY proposal reached hq
+    // with `parentId: null` AND `charterSectionId: null`. That is the whole
+    // reason "0 of 35 adopted" looked like a missing human click: all 35 rows
+    // were unadoptable on arrival, and nothing on either side said so.
+    const order = { PILLAR: 0, OBJECTIVE: 1, GOAL: 2 };
+    const ordered = proposals
+      .slice()
+      .sort((a, b) => (order[String(a.kind).toUpperCase()] ?? 3) - (order[String(b.kind).toUpperCase()] ?? 3));
+    /** local key → the row id hq assigned it, so children can cite a real parent. */
+    const idByKey = new Map();
     let posted = 0;
-    for (const obj of proposals) {
+    const refusals = [];
+    for (const obj of ordered) {
+      const parentId = obj.parentKey ? idByKey.get(obj.parentKey) || null : null;
+      if (obj.parentKey && !parentId) {
+        // The parent pillar itself failed to post. Proposing the child anyway
+        // would recreate the exact defect above.
+        refusals.push(`${obj.key}: its parent "${obj.parentKey}" is not on the server`);
+        continue;
+      }
       try {
         const r = await call("mandate.propose", {
           key: obj.key, kind: obj.kind, text: obj.text, metric: obj.metric, unit: obj.unit,
           direction: obj.direction, target: obj.target, tolerance: obj.tolerance,
-          cadence: obj.cadence, sensor: obj.sensor, parentKey: obj.parentKey,
+          cadence: obj.cadence, sensor: obj.sensor,
+          parentId,
+          charterSectionId: obj.charterSectionId || null,
         });
-        if (r && r.ok) posted++;
-      } catch { /* a per-objective failure must not abort the rest */ }
+        if (r && r.ok) {
+          posted++;
+          const id = (r.result && r.result.id) || r.id || null;
+          if (id) idByKey.set(obj.key, id);
+        } else {
+          refusals.push(`${obj.key}: ${(r && r.error && r.error.message) || "hq refused it"}`);
+        }
+      } catch (e) {
+        // FAIL-OPEN IS FINE; SILENT IS NOT. This `catch {}` used to be empty,
+        // which is how a fleet-wide provenance bug stayed invisible: every
+        // proposal was refused and the only symptom was a count nobody read.
+        refusals.push(`${obj.key}: ${e && e.message ? e.message : e}`);
+      }
     }
-    if (posted !== proposals.length) {
-      log(`[mandate] proposed ${posted}/${proposals.length} objectives to hq — the rest stayed local (the plan compiles from the cache either way)`);
+    if (posted !== ordered.length) {
+      log(`[mandate] proposed ${posted}/${ordered.length} objectives to hq — the rest stayed local (the plan compiles from the cache either way)`);
+      for (const r of refusals) log(`[mandate]   refused → ${r}`);
     }
   }
 
@@ -316,7 +351,13 @@ export default {
       record = res.record;
       if (res.derived) {
         const c = res.derived.counts;
-        io.note(`[mandate] derived ${c.proposed} PROPOSED objectives (${c.pillars} pillar · ${c.objectives} objective · ${c.goals} goal; ${c.withMethodSensor} with a method sensor). Adopt them in Cohort to activate them.`);
+        // ADOPTABLE, not just proposed. "35 proposed" is the number that let a
+        // seat sit at zero adopted for months and read as a missing human
+        // click; "35 proposed / 4 adoptable / 31 refused" is the number that
+        // says whose problem it is. hq refuses the other 31 at `mandate.adopt`
+        // regardless — this is where an operator finds that out in one line
+        // instead of one 400 at a time.
+        io.note(`[mandate] derived ${c.proposed} PROPOSED objectives (${c.pillars} pillar · ${c.objectives} objective · ${c.goals} goal; ${c.withMethodSensor} with a method sensor). ${c.adoptable} are ADOPTABLE today${c.refused ? `; ${c.refused} carry unresolved provenance/duplicate debt` : ""}. Adopt them in Cohort to activate them.`);
       }
     }
 

package/lib/setup/sections/mandate.test.mjs

@@ -131,9 +131,21 @@ test("apply derives a PROPOSED mandate and caches it (nothing adopted by the age
   assert.equal(cache.source, "local");
   assert.ok(cache.body.objectives.length > 0);
   assert.ok(cache.body.objectives.every((o) => o.state === "proposed"), "the agent NEVER adopts its own objectives");
-  // charter pillars became PILLAR nodes, and objectives hang off them
+  // charter pillars became PILLAR nodes, and a PLACEABLE objective hangs off one
   assert.equal(cache.body.objectives.filter((o) => o.kind === "PILLAR").length, 2);
-  assert.ok(cache.body.objectives.filter((o) => o.kind === "OBJECTIVE").every((o) => o.parentKey), "provenance to a charter pillar");
+  const placed = cache.body.objectives.filter((o) => o.kind === "OBJECTIVE" && o.parentKey);
+  assert.ok(placed.length > 0, "at least one objective traces to a charter pillar");
+  for (const o of placed) {
+    // The clause id rides on the ROW, not only on its parent — `mandate.propose`
+    // takes `charterSectionId`, and a node carrying provenance only through
+    // `parentKey` reached hq with both provenance columns null.
+    assert.ok(o.charterSectionId, `"${o.key}" must carry the charter clause id it inherited`);
+  }
+  // An objective the deriver could NOT place is carried unplaced and named —
+  // never auto-attached to whichever pillar happened to be first.
+  for (const o of cache.body.objectives.filter((x) => x.kind === "OBJECTIVE" && !x.parentKey)) {
+    assert.equal(o.charterSectionId, null);
+  }
 });
 
 test("apply with only PROPOSED objectives emits EXACTLY today's cadence set — no schedule growth", async () => {
@@ -162,6 +174,9 @@ test("an ADOPTED objective grows the schedule: a real measure cadence lands in t
           key: "pipeline-coverage", id: "obj_7Kx", kind: "OBJECTIVE", text: "Pipeline coverage", state: "active",
           metric: "pipeline_coverage_x", direction: "up", target: 3, tolerance: 0.2, weight: 1, cadence: "weekly",
           charterSectionId: "cs_1", sensor: { capability: "crm_list_deals", params: { stage: "open" }, source: "method" },
+          // hq stamps this on every adopt; the compiler REQUIRES it (an active row
+          // with no adopter on record compiles nothing — the law fails closed).
+          adoptedById: "mem_A03",
           collaborators: [{ member_id: "mem_A03", role: "REVIEWER" }],
         }],
       },

package/lib/setup/sections/orgmail.mjs

@@ -32,6 +32,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import * as io from "../io.mjs";
 import { isEnabled, configFromAgent, loadOrgConfig } from "../../org/client.mjs";
 import { emailInbox } from "../../org/ui-parity.mjs";
+import { remedyFor } from "../../org/email-remedy.mjs";
 
 const GATE_REL = join("config", "orgmail.yaml");
 
@@ -152,13 +153,15 @@ export default {
     // Cohort → Settings → Email — warn, never fail the wizard on it.
     let detail = "";
     let reachable = false;
+    let probeCode = "";
     try {
       const r = await emailInbox({ limit: 1 }, { base: orgCfg.base, token: orgCfg.token, orgId: orgCfg.orgId, fetchImpl: ctx.fetchImpl });
       if (r && r.ok) {
         reachable = true;
         detail = r.result?.mailbox?.address ? `mailbox ${r.result.mailbox.address}` : "mailbox reachable";
       } else {
-        detail = `${r?.error?.code || "?"}: ${r?.error?.message || "unreachable"}`;
+        probeCode = r?.error?.code || "?";
+        detail = `${probeCode}: ${r?.error?.message || "unreachable"}`;
       }
     } catch {
       detail = "probe failed";
@@ -166,7 +169,12 @@ export default {
     checks.push({
       name: reachable ? `Cohort mailbox reachable (${detail})` : "Cohort mailbox reachability (best-effort)",
       ok: true, // never hard-fail — the admin may not have verified a domain yet
-      remedy: reachable ? undefined : `email.inbox probe: ${detail} — an admin must verify a domain + assign this agent a mailbox in Cohort → Settings → Email`,
+      // The remedy comes from the ONE classifier the doctor and the adapter also
+      // use, so an operator is told the same thing by whichever surface they hit
+      // first — and is told an ACTOR and an ACT, not just a state.
+      remedy: reachable
+        ? undefined
+        : `email.inbox probe: ${detail}. ${remedyFor(probeCode) || "Retry; if it persists, a workspace ADMIN checks Cohort → Settings → Email"}`,
     });
     return { ok: checks.every((c) => c.ok), checks };
   },

package/lib/setup/state.mjs

@@ -32,6 +32,60 @@ import { createHash } from "node:crypto";
 export const PROGRESS_REL = "state/setup/progress.json";
 export const SCHEMA_VERSION = 1;
 
+/**
+ * Answer keys whose VALUES are live credentials and must never be persisted.
+ *
+ * This checkpoint is a 0644 JSON file under `state/`, which is inside the
+ * default backup include set — so `orgToken` (the seat's COHORT_API_KEY,
+ * collected by `lib/setup/sections/org.mjs` via `io.secret`) was written here in
+ * plaintext and shipped, byte-identical to `.env`, inside every nightly archive.
+ * The backup deny-list matched PATHS only, so `.env` was correctly excluded
+ * while the same secret rode along inside an included file and the runner logged
+ * "archive verified clean". Set `offsite.provider` and it uploads nightly.
+ *
+ * The checkpoint is a RESUME HINT, never an authority: the wizard re-`detect`s
+ * every section on resume and the real credential lives in `.env` / the
+ * keychain, so dropping the value costs nothing but a re-prompt.
+ *
+ * Matched on the key NAME (narrow, deliberate patterns — `orgAuthMethod` must
+ * NOT match, or resume breaks) rather than on value shape, so a rotated token
+ * with a new prefix is still caught.
+ */
+export const SECRET_ANSWER_KEY_RE =
+  /(^|[._-])(token|secret|password|passphrase|credential|api[._-]?key|private[._-]?key|pairing[._-]?code)($|[._-])|token$|secret$|apikey$|pairingcode$/i;
+
+/**
+ * Strip credential-valued answers. The key is DELETED, not placeholdered: every
+ * consumer resolves `answers.x != null ? answers.x : process.env.X` (see
+ * `lib/setup/sections/org.mjs#connFrom`), so a placeholder string would be
+ * handed to hq as a bearer token on resume. Absent is the only correct shape —
+ * it routes the read back to `.env` / the keychain, which is where the value
+ * actually lives.
+ *
+ * The dropped key names are recorded on `_redacted` so the file still SAYS what
+ * was removed. Names are not secrets; values are.
+ *
+ * @param {object|null|undefined} answers
+ * @returns {{answers:object, redacted:string[]}}
+ */
+export function redactSecretAnswers(answers) {
+  const src = answers && typeof answers === "object" ? answers : {};
+  const out = {};
+  const redacted = [];
+  for (const [k, v] of Object.entries(src)) {
+    if (k === "_redacted") continue;
+    if (SECRET_ANSWER_KEY_RE.test(k) && typeof v === "string" && v) {
+      redacted.push(k);
+      continue;
+    }
+    out[k] = v;
+  }
+  const prior = Array.isArray(src._redacted) ? src._redacted : [];
+  const all = [...new Set([...prior, ...redacted])].sort();
+  if (all.length) out._redacted = all;
+  return { answers: out, redacted };
+}
+
 /** Absolute path to the progress file for an agent root. */
 export function progressPath(agentRoot) {
   return join(agentRoot, PROGRESS_REL);
@@ -78,10 +132,36 @@ export function loadProgress(agentRoot) {
   try {
     const raw = JSON.parse(readFileSync(p, "utf-8"));
     if (!raw || typeof raw !== "object") return emptyProgress();
+    const { answers, redacted } = redactSecretAnswers(
+      raw.answers && typeof raw.answers === "object" ? raw.answers : {}
+    );
+    // SELF-HEAL, LOUDLY. Files written before this guard hold a live
+    // COHORT_API_KEY in plaintext, and they are inside the backup include set.
+    // Rewriting on the first read scrubs every enrolled agent the moment
+    // anything touches the checkpoint, instead of waiting for the next setup
+    // run. The credential is NOT rotated for you — say so.
+    if (redacted.length > 0) {
+      try {
+        const cleaned = { ...raw, answers };
+        const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(cleaned, null, 2) + "\n", "utf-8");
+        renameSync(tmp, p);
+        console.warn(
+          `[setup/state] ${PROGRESS_REL} held credential value(s) in plaintext (${redacted.join(", ")}) — ` +
+          "scrubbed in place. This file is inside the backup include set, so treat those credentials as " +
+          "EXPOSED to every archive taken since enrolment and ROTATE them."
+        );
+      } catch (err) {
+        console.error(
+          `[setup/state] ${PROGRESS_REL} holds credential value(s) in plaintext (${redacted.join(", ")}) and could ` +
+          `not be scrubbed (${err && err.message ? err.message : err}) — delete the file and rotate the credential.`
+        );
+      }
+    }
     return {
       version: raw.version || SCHEMA_VERSION,
       updatedAt: raw.updatedAt || null,
-      answers: raw.answers && typeof raw.answers === "object" ? raw.answers : {},
+      answers,
       sections: raw.sections && typeof raw.sections === "object" ? raw.sections : {},
       enrich: raw.enrich && typeof raw.enrich === "object" ? raw.enrich : {},
     };
@@ -98,7 +178,8 @@ export function loadProgress(agentRoot) {
 export function saveProgress(agentRoot, progress) {
   const p = progressPath(agentRoot);
   mkdirSync(dirname(p), { recursive: true });
-  const body = { ...emptyProgress(), ...progress, version: SCHEMA_VERSION, updatedAt: new Date().toISOString() };
+  const merged = { ...emptyProgress(), ...progress, version: SCHEMA_VERSION, updatedAt: new Date().toISOString() };
+  const body = { ...merged, answers: redactSecretAnswers(merged.answers).answers };
   const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
   writeFileSync(tmp, JSON.stringify(body, null, 2) + "\n", "utf-8");
   renameSync(tmp, p);