@cohortapp/agent-sdk 2.3.0

package/scripts/daemon/session-outcomes.mjs

@@ -0,0 +1,640 @@
+/**
+ * scripts/daemon/session-outcomes.mjs — OUTCOME DISCIPLINE for daemon sessions.
+ *
+ * hq already guarantees this for LIVE CALLS (src/server/call-voice/chair.ts +
+ * outcomes.ts): a meeting's action points become real board rows, and a teardown
+ * SWEEP lands anything the chair captured but never wrote. The avatar worker is
+ * deliberately brainless, so an agent-sdk colleague on a call inherits that for
+ * free — this module does NOT duplicate any of it.
+ *
+ * What had NO equivalent is maestro's OWN daemon turns. A spawned session can
+ * decide things and commit to next steps ("I'll send the revised deck to Alice
+ * on Friday") that then exist only in `state/sessions/logs/<id>.log` — nobody
+ * reads a session log, so the commitment is lost and the next turn re-decides it.
+ * That is the exact failure the hq chair removes, and this closes it for the
+ * daemon.
+ *
+ * THE SHAPE (mirroring the chair's DISCIPLINE, not its code):
+ *
+ *   CAPTURE  The prompt asks the session to end with an `OUTCOMES:` block (see
+ *            prompt-builder's OUTCOME_DISCIPLINE). `parseOutcomes` reads that
+ *            block off the session's final text — deterministic, bounded, and
+ *            matched ONLY on the literal `OUTCOMES` heading, which is the exact
+ *            contract the prompt establishes. It is deliberately NOT tolerant of
+ *            "Next steps" / "Action items": a turn that merely wrote an ordinary
+ *            prose "Next steps:" section never agreed to a machine-read contract,
+ *            and must not silently mint org-visible board rows because of it.
+ *   GATE     `outcomeSourceShareable` decides whether this turn's source is one
+ *            whose commitments may become ORG-VISIBLE. Fail-CLOSED: only a Slack
+ *            conversation POSITIVELY established as public (`channel_type` /
+ *            `is_private` off the event — never the id prefix, which Slack does
+ *            not guarantee) qualifies. A DM, a private channel, email, an unknown
+ *            source or no source at all lands nothing — see the gate's own note.
+ *   LAND     `landOutcomes` writes each one through the EXISTING org protocol:
+ *            `board.create` for the task (lib/org/board.mjs → createItem) plus a
+ *            single `knowledge.append` episode (lib/org/knowledge.mjs → remember)
+ *            recording the commitment set. NO new protocol methods — the protocol
+ *            is checksum-pinned and cross-repo-synced.
+ *   SWEEP    `sweepSessionOutcomes` is the post-session hook, called from the
+ *            dispatcher's onClose. It is DRIVEN, not left to the model to
+ *            remember: whatever the turn captured is landed at session end.
+ *
+ * IDEMPOTENT, TWO WAYS. In-process via the per-session `landed` flag (so a double
+ * close is a no-op), and — the one that survives a restart — via a DETERMINISTIC
+ * `itemId` derived from (sessionId, normalised title). `board.create` treats a
+ * caller-supplied id that already exists as a replay, so re-landing the same
+ * commitment never doubles a board row.
+ *
+ * FAIL-OPEN, ALWAYS. Disabled, unconfigured, unreachable, unparseable ⇒ a benign
+ * `{created:0, skipped:true}`. Nothing here may ever throw into the dispatch path:
+ * an outcome write must never cost the user their reply.
+ *
+ * OFF BY DEFAULT behind `DAEMON_SESSION_OUTCOMES=1` (same opt-in shape as
+ * `DAEMON_CONTEXT_COMPILER`). This writes REAL rows to the live org board from
+ * every clean daemon turn; on a live daemon the safe default is a machine that
+ * does nothing until it is switched on deliberately.
+ *
+ * Pure-core + injectable IO: every collaborator (createItemImpl / rememberImpl /
+ * cfg / enabled) can be injected, so the tests drive the real logic without a
+ * server. ESM, Node builtins only.
+ *
+ * @module scripts/daemon/session-outcomes
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+
+import { createItem as orgCreateItem } from "../../lib/org/board.mjs";
+import { isEnabled as orgEnabled, configFromAgent } from "../../lib/org/client.mjs";
+import { remember as orgRemember } from "../../lib/org/knowledge.mjs";
+
+/** Cap what ONE turn can write. A runaway summary must not flood the board. */
+export const MAX_OUTCOMES = 8;
+
+const MAX_TITLE_CHARS = 200;
+const MAX_PARTY_CHARS = 80;
+/** Only ever scan the tail of a long transcript for the outcomes block. */
+const MAX_SCAN_CHARS = 20_000;
+
+// ---------------------------------------------------------------------------
+// Flag
+// ---------------------------------------------------------------------------
+
+/**
+ * Is the outcome discipline switched on? OFF unless `DAEMON_SESSION_OUTCOMES=1`.
+ * @param {object} [env] injectable environment (defaults to process.env)
+ * @returns {boolean}
+ */
+export function outcomesEnabled(env = process.env) {
+  return String((env && env.DAEMON_SESSION_OUTCOMES) || "") === "1";
+}
+
+// ---------------------------------------------------------------------------
+// Source gate — may THIS turn's commitments become ORG-VISIBLE?
+// ---------------------------------------------------------------------------
+
+/**
+ * CONFIDENTIALITY GATE. A landed outcome is not a private note: `board.create`
+ * is sent with no `workstreamId` (so the server gives the row no `channelId`,
+ * and hq's channel-less board query applies no channel filter) and the episode's
+ * `knowledge.append` carries no group (so hq's `normalizeGroupId(undefined)`
+ * resolves to the `org` group). Both artifacts are therefore readable by EVERY
+ * member of the org — and they carry the commitment text PLUS the topic line
+ * (`classResult.summary`, or the item's own subject).
+ *
+ * That is correct for a public channel message. It is NOT correct for a private
+ * DM: the daemon would be republishing a one-to-one conversation to the whole
+ * org. The protocol gives us no way to derive a narrower audience here —
+ * `board.create` accepts only a `workstreamId`, and a Slack DM maps to no
+ * workstream — so the gate is the answer: restrict the sweep to sources that are
+ * already org-visible.
+ *
+ * FAIL-CLOSED, unlike everything else in this module. Every other failure mode
+ * here is fail-open because the cost is a lost board row; the cost of getting
+ * THIS wrong is a leaked private conversation, so anything we cannot positively
+ * establish as public lands nothing. Email is one-to-one correspondence, and a
+ * source we do not recognise is by definition not established as public.
+ *
+ * THE SIGNAL IS `channel_type`/`is_private`, NEVER THE ID PREFIX. Slack is
+ * explicit that a conversation ID's leading letter is NOT a reliable type
+ * indicator: a PRIVATE channel can and does carry a `C…` id (workspaces created
+ * after the `G…`-for-groups era mint `C…` ids for private channels too), and an
+ * mpim may carry either. Only `D` for a DM is dependable. Admitting on `/^C/`
+ * therefore admitted private channels — the exact leak this gate exists to
+ * prevent. So admission now requires a POSITIVE public signal carried on the
+ * item by the ingest layer straight off Slack's event envelope:
+ *
+ *   `channel_type === "channel"`  Slack's message-event conversation type
+ *                                 ("channel" public | "group" private |
+ *                                  "im" DM | "mpim" group DM), or
+ *   `is_private === false`        an explicit privacy verdict (conversations.list
+ *                                 / conversations.info).
+ *
+ * Anything else — a missing signal, an unrecognised type, an id we can only
+ * guess about — lands nothing. Prefixes are still consulted, but only in the
+ * DENYING direction (`D…` ⇒ DM, `G…` ⇒ private group), where a false positive
+ * costs a board row rather than a confidence.
+ *
+ * Producers: scripts/poller/slack-socket-mode.mjs (`event.channel_type` off the
+ * Socket Mode envelope), scripts/poller/slack-poller.mjs (`is_private` off
+ * conversations.list), and the YAML round-trip that carries them to the daemon
+ * (scripts/poller/utils.mjs `inboxItemToYaml` ⇄
+ * scripts/poller/inbox-scan-poller.mjs `parseInboxItemYaml`, which decodes
+ * `is_private` as a TRI-STATE so "absent" never reads as "public").
+ *
+ * @param {object} [item] the inbox item the turn was about
+ * @returns {{shareable:boolean, reason:string}}
+ */
+export function outcomeSourceShareable(item) {
+  if (!item || typeof item !== "object") return { shareable: false, reason: "no-source" };
+
+  // Explicit privacy signals win outright, whatever the ids say.
+  if (item.is_dm === true) return { shareable: false, reason: "dm" };
+  if (item.is_private === true) return { shareable: false, reason: "private-channel" };
+
+  const channel = String(item.channel || "").trim();
+  if (/^dm\//i.test(channel)) return { shareable: false, reason: "dm" };
+  if (/^email\//i.test(channel)) return { shareable: false, reason: "private-correspondence" };
+
+  const service = String(item.service || "").trim().toLowerCase();
+  if (!service) return { shareable: false, reason: "unknown-source" };
+  if (service !== "slack") return { shareable: false, reason: "non-channel-source" };
+
+  const channelId = String(item.channel_id || "").trim();
+  if (!channelId) return { shareable: false, reason: "unknown-channel" };
+  // Prefixes may only DENY (see the note above): `D` is Slack's one dependable
+  // prefix, and a `G` id is never a public channel.
+  if (/^D/.test(channelId)) return { shareable: false, reason: "dm" };
+  if (/^G/.test(channelId)) return { shareable: false, reason: "private-channel" };
+
+  // Now the positive signal. Unrecognised types fail closed rather than falling
+  // through to the is_private check — a type we cannot interpret is not a type
+  // we may publish from.
+  const channelType = String(item.channel_type || "").trim().toLowerCase();
+  if (channelType) {
+    if (channelType === "im" || channelType === "mpim") return { shareable: false, reason: "dm" };
+    if (channelType === "group") return { shareable: false, reason: "private-channel" };
+    if (channelType !== "channel") return { shareable: false, reason: "unknown-channel-type" };
+    return { shareable: true, reason: "public-channel" };
+  }
+  if (item.is_private === false) return { shareable: true, reason: "public-channel" };
+
+  // No `channel_type`, no `is_private`: the id alone cannot establish privacy.
+  return { shareable: false, reason: "privacy-unknown" };
+}
+
+// ---------------------------------------------------------------------------
+// Capture — pure parsing of the session's final text
+// ---------------------------------------------------------------------------
+
+/**
+ * The heading that introduces a turn's commitments.
+ *
+ * Generous about markdown decoration (`## `, `**…**`, trailing colon) because
+ * that is what a model actually emits — and STRICT about the word, which must be
+ * the literal `OUTCOMES` the prompt asked for.
+ *
+ * It used to also match "next steps" / "action items" / "action points" /
+ * "commitments". That made the capture surface WIDER THAN THE CONTRACT: a turn
+ * that merely wrote a prose "Next steps:" section — one whose prompt may never
+ * have carried OUTCOME_DISCIPLINE at all, because prompt-builder injects it only
+ * when the flag is already `1` at buildPrompt time while the sweep re-reads the
+ * flag at close time — would silently mint org-visible board rows it never
+ * agreed to. Capture is now exactly the block the prompt establishes.
+ *
+ * The PLURAL is required for the same reason: the contract is literally
+ * `OUTCOMES:`, while a singular "Outcome:" is an ordinary prose section header —
+ * accepting it would reopen the very gap this narrowing closed.
+ */
+const OUTCOME_HEADING =
+  /^\s*(?:#{1,6}\s*)?(?:\*\*|__)?\s*outcomes\s*(?:\*\*|__)?\s*(?::\s*(.*))?\s*$/i;
+
+/** A markdown list item: `- x`, `* x`, `1. x`, `- [ ] x`. */
+const LIST_ITEM = /^\s*(?:[-*+•]|\d+[.)])\s+(?:\[[ xX]?\]\s*)?(.+)$/;
+
+/** "nothing to land" answers, so an honest empty block stays empty. */
+const EMPTY_ANSWER = /^(?:none|n\/?a|nothing|no (?:outcomes?|next steps?|action items?|commitments?))\b/i;
+
+/** Strip markdown emphasis/code fences from a captured title. */
+function plain(s) {
+  return String(s || "")
+    .replace(/[`*_]+/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Split a captured line into its title and any owner/timing the session stated.
+ * Segments are separated by an em/en dash, `--`, `|` or `;` and tagged
+ * `owner:`/`by:` and `due:`/`when:`. Untagged trailing segments stay in the title
+ * — guessing would put the wrong name on someone's task.
+ */
+function splitParts(line) {
+  const segments = String(line).split(/\s+(?:—|–|--|\||;)\s+/);
+  let title = segments.shift() || "";
+  let owner;
+  let due;
+  const kept = [];
+  for (const seg of segments) {
+    const m = /^\s*(owner|assignee|by|due|when|timing)\s*:\s*(.+)$/i.exec(seg);
+    if (!m) {
+      kept.push(seg);
+      continue;
+    }
+    const tag = m[1].toLowerCase();
+    const value = plain(m[2]);
+    if (!value) continue;
+    if ((tag === "owner" || tag === "assignee" || tag === "by") && !owner) owner = value;
+    else if (!due) due = value;
+  }
+  if (kept.length) title = [title, ...kept].join(" — ");
+  return { title: plain(title), owner, due };
+}
+
+/**
+ * Extract this turn's commitments from its final text. Pure, bounded, and
+ * order-preserving; returns `[]` when the turn committed to nothing (which is a
+ * perfectly good answer — most turns should).
+ *
+ * @param {string} text the session's final assistant text
+ * @returns {Array<{title:string, owner?:string, due?:string}>}
+ */
+export function parseOutcomes(text) {
+  const raw = String(text || "");
+  if (!raw.trim()) return [];
+  const body = raw.length > MAX_SCAN_CHARS ? raw.slice(-MAX_SCAN_CHARS) : raw;
+  const lines = body.split(/\r?\n/);
+
+  const out = [];
+  const seen = new Set();
+
+  const push = (line) => {
+    if (out.length >= MAX_OUTCOMES) return;
+    const { title, owner, due } = splitParts(line);
+    if (!title || EMPTY_ANSWER.test(title)) return;
+    const key = title.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    const entry = { title: title.slice(0, MAX_TITLE_CHARS) };
+    if (owner) entry.owner = owner.slice(0, MAX_PARTY_CHARS);
+    if (due) entry.due = due.slice(0, MAX_PARTY_CHARS);
+    out.push(entry);
+  };
+
+  for (let i = 0; i < lines.length && out.length < MAX_OUTCOMES; i += 1) {
+    const heading = OUTCOME_HEADING.exec(lines[i]);
+    if (!heading) continue;
+
+    // `OUTCOMES: none` / `Next steps: ship the deck` — an inline single answer.
+    const inline = plain(heading[1] || "");
+    if (inline) {
+      if (!EMPTY_ANSWER.test(inline)) push(inline);
+      continue;
+    }
+
+    // Otherwise consume the list that follows. Blank lines are allowed BEFORE the
+    // first item (models like a blank after a heading) and TERMINATE the block
+    // once items have started, so the paragraph after the list is never swallowed.
+    let started = false;
+    for (let j = i + 1; j < lines.length && out.length < MAX_OUTCOMES; j += 1) {
+      const line = lines[j];
+      if (!line.trim()) {
+        if (started) { i = j; break; }
+        continue;
+      }
+      const item = LIST_ITEM.exec(line);
+      if (!item) { i = j - 1; break; }
+      started = true;
+      push(item[1]);
+      i = j;
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Recover the final assistant text from a `claude --print --output-format json`
+ * stdout buffer. Tolerant of a leading banner line (same slice-the-first-balanced
+ * -object trick the dispatcher's usage parser uses) and of a plain-text run.
+ * Never throws.
+ *
+ * @param {string} stdout
+ * @returns {string} the result text, or "" when nothing usable was found
+ */
+export function resultTextFromStdout(stdout) {
+  const trimmed = String(stdout || "").trim();
+  if (!trimmed) return "";
+  let obj = null;
+  try {
+    obj = JSON.parse(trimmed);
+  } catch {
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start !== -1 && end > start) {
+      try { obj = JSON.parse(trimmed.slice(start, end + 1)); } catch { obj = null; }
+    }
+  }
+  if (obj && typeof obj === "object") {
+    if (typeof obj.result === "string") return obj.result;
+    if (obj.result && typeof obj.result.text === "string") return obj.result.text;
+    return "";
+  }
+  // Not JSON at all (a --print text run): the whole buffer is the reply.
+  return trimmed;
+}
+
+// ---------------------------------------------------------------------------
+// Per-session state — the daemon's small echo of the chair's ChairState
+// ---------------------------------------------------------------------------
+
+/** sessionId -> { outcomes: Array, landed: boolean } */
+const sessions = new Map();
+
+/** Bound the map so a long-lived daemon cannot accumulate session state. */
+const MAX_TRACKED_SESSIONS = 200;
+
+/**
+ * Record commitments captured for a session (deduped, bounded, order-preserving).
+ * Safe to call repeatedly; a later capture merges into the earlier one.
+ *
+ * @param {string} sessionId
+ * @param {Array<{title:string, owner?:string, due?:string}>} outcomes
+ * @returns {Array} the session's captured outcomes after the merge
+ */
+export function noteOutcomes(sessionId, outcomes) {
+  if (!sessionId) return [];
+  let s = sessions.get(sessionId);
+  if (!s) {
+    if (sessions.size >= MAX_TRACKED_SESSIONS) {
+      // Oldest-first eviction; insertion order is Map's iteration order.
+      const oldest = sessions.keys().next();
+      if (!oldest.done) sessions.delete(oldest.value);
+    }
+    s = { outcomes: [], landed: false };
+    sessions.set(sessionId, s);
+  }
+  for (const o of Array.isArray(outcomes) ? outcomes : []) {
+    const title = plain(o && o.title).slice(0, MAX_TITLE_CHARS);
+    if (!title) continue;
+    if (s.outcomes.some((x) => x.title.toLowerCase() === title.toLowerCase())) continue;
+    if (s.outcomes.length >= MAX_OUTCOMES) break;
+    const entry = { title };
+    if (o.owner) entry.owner = String(o.owner).slice(0, MAX_PARTY_CHARS);
+    if (o.due) entry.due = String(o.due).slice(0, MAX_PARTY_CHARS);
+    s.outcomes.push(entry);
+  }
+  return s.outcomes;
+}
+
+/** What a session captured, or `[]`. */
+export function getSessionOutcomes(sessionId) {
+  const s = sessions.get(sessionId);
+  return s ? s.outcomes : [];
+}
+
+/** Have this session's outcomes already been landed? */
+export function outcomesLanded(sessionId) {
+  const s = sessions.get(sessionId);
+  return !!(s && s.landed);
+}
+
+/** Mark a session's outcomes landed (the in-process half of idempotency). */
+export function markOutcomesLanded(sessionId) {
+  const s = sessions.get(sessionId);
+  if (s) s.landed = true;
+}
+
+/** Drop a session's state (called after the sweep). */
+export function clearSessionOutcomes(sessionId) {
+  sessions.delete(sessionId);
+}
+
+/** Test seam. */
+export function _resetSessionOutcomes() {
+  sessions.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Land — through the EXISTING org protocol (board.create + knowledge.append)
+// ---------------------------------------------------------------------------
+
+/**
+ * A stable, replay-safe board id for one commitment of one session. `board.create`
+ * treats a caller-supplied id that already exists as an idempotent replay, so this
+ * is what makes re-landing safe across a daemon restart (where the in-process
+ * `landed` flag is gone).
+ *
+ * @param {string} sessionId
+ * @param {string} title
+ * @returns {string}
+ */
+export function outcomeItemId(sessionId, title) {
+  const norm = plain(title).toLowerCase();
+  const digest = createHash("sha1")
+    .update(`${String(sessionId || "")}${norm}`)
+    .digest("hex")
+    .slice(0, 24);
+  return `so-${digest}`;
+}
+
+/** The provenance line that lets a board row be traced back to its turn. */
+function detailFor(o, a) {
+  const bits = [];
+  if (o.owner) bits.push(`Owner as stated: ${o.owner}.`);
+  if (o.due) bits.push(`Timing as stated: ${o.due}.`);
+  bits.push(
+    `Committed in ${a.who} daemon session ${a.sessionId || "unknown"}${a.topic ? ` — ${a.topic}` : ""}.`
+  );
+  return bits.join(" ").slice(0, 5000);
+}
+
+/**
+ * Write a turn's commitments through the org protocol: one `board.create` per
+ * commitment plus ONE `knowledge.append` episode recording the set (so the outcome
+ * is both actionable and recallable). Fail-open — every failure path returns a
+ * benign result rather than throwing.
+ *
+ * @param {object} a
+ * @param {string} a.sessionId
+ * @param {Array<{title:string, owner?:string, due?:string}>} a.outcomes
+ * @param {object} [a.cfg] agent org config (config/org.yaml shape)
+ * @param {object} [a.item] the inbox/queue item the turn was about. REQUIRED for
+ *   anything to land: the confidentiality gate is fail-closed, so an absent or
+ *   non-public source writes nothing (see `outcomeSourceShareable`).
+ * @param {object} [a.classResult] classifier output (for the topic line)
+ * @param {string} [a.agentName] the agent's own name, for the episode text
+ * @param {Function} [a.createItemImpl] injectable board.create
+ * @param {Function} [a.rememberImpl] injectable knowledge.append
+ * @param {Function} [a.fetchImpl] injectable fetch, forwarded to the client
+ * @returns {Promise<{created:number, remembered?:boolean, skipped?:boolean, reason?:string}>}
+ */
+export async function landOutcomes(a = {}) {
+  try {
+    const cfg = a.cfg || {};
+    if (!orgEnabled(cfg)) return { created: 0, skipped: true, reason: "org-disabled" };
+
+    // The confidentiality gate sits on the WRITER, not just the sweep, so every
+    // path into the org protocol is covered. Fail-closed by construction.
+    const gate = outcomeSourceShareable(a.item);
+    if (!gate.shareable) return { created: 0, skipped: true, reason: `source-${gate.reason}` };
+
+    const wanted = (Array.isArray(a.outcomes) ? a.outcomes : [])
+      .filter((o) => o && plain(o.title))
+      .slice(0, MAX_OUTCOMES);
+    if (wanted.length === 0) return { created: 0, skipped: true, reason: "nothing-to-land" };
+
+    const conn = configFromAgent(cfg);
+    const createImpl = a.createItemImpl || orgCreateItem;
+    const rememberImpl = a.rememberImpl || orgRemember;
+    const who = a.agentName || "the agent";
+    const topic =
+      (a.classResult && a.classResult.summary) ||
+      (a.item && (a.item.subject || a.item.title)) ||
+      null;
+
+    let created = 0;
+    const landedTitles = [];
+    for (const o of wanted) {
+      const title = plain(o.title).slice(0, MAX_TITLE_CHARS);
+      const itemId = outcomeItemId(a.sessionId, title);
+      try {
+        // board.create is `.strict()` server-side — send only its own fields.
+        const res = await createImpl(
+          { itemId, title, detail: detailFor(o, { who, sessionId: a.sessionId, topic }), priority: "P2" },
+          { base: conn.base, token: conn.token, fetchImpl: a.fetchImpl, idempotencyKey: `board.create:${itemId}` }
+        );
+        // The client never throws; a failure comes back as an error frame.
+        if (!res || res.error) continue;
+        created += 1;
+        landedTitles.push(title);
+      } catch {
+        // One bad row must not strand the rest.
+      }
+    }
+
+    // One episode for the whole set, so the commitments are recallable even if the
+    // board is unreachable. The SERVER derives the fact's group/ACL from the
+    // caller's verified identity — we pass no group hint.
+    let remembered = false;
+    const forEpisode = landedTitles.length ? landedTitles : wanted.map((o) => plain(o.title));
+    try {
+      const text = [
+        `${who} committed to the following in a daemon session${topic ? ` re: ${topic}` : ""}:`,
+        ...forEpisode.map((t) => `- ${t}`),
+      ]
+        .join(" ")
+        .slice(0, 1200);
+      const r = await rememberImpl(text, {
+        cfg,
+        kind: "episode",
+        provenance: { source: "daemon-session-outcomes", sessionId: a.sessionId || null },
+        idempotencyKey: `knowledge.append:outcomes:${a.sessionId || "unknown"}`,
+        fetchImpl: a.fetchImpl,
+      });
+      remembered = !!(r && r.ok);
+    } catch {
+      // Fail-open.
+    }
+
+    if (created > 0 || remembered) markOutcomesLanded(a.sessionId);
+    return { created, remembered };
+  } catch {
+    return { created: 0, skipped: true };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Sweep — the post-session hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Post-session hook: capture this turn's commitments and LAND them. This is the
+ * daemon's answer to hq's `sweepUnlandedOutcomes` — the guarantee is DRIVEN by
+ * the close path rather than by the model remembering to write anything down.
+ *
+ * No-op when the flag is off, when the SOURCE IS NOT ORG-VISIBLE (a DM, a private
+ * channel, email, or a source we cannot establish as public — see
+ * `outcomeSourceShareable`), when the org integration is disabled, when nothing
+ * was committed, or when this session already landed. Never throws.
+ *
+ * @param {object} a
+ * @param {string} a.sessionId
+ * @param {string} [a.stdout] the session's raw stdout (--output-format json)
+ * @param {string} [a.resultText] pre-extracted final text (wins over stdout)
+ * @param {object} [a.item] the inbox item; REQUIRED — the fail-closed
+ *   confidentiality gate lands nothing without a demonstrably public source
+ * @param {object} [a.classResult]
+ * @param {object} [a.cfg]
+ * @param {boolean} [a.enabled] override the env flag (tests)
+ * @param {string} [a.agentName]
+ * @param {Function} [a.createItemImpl]
+ * @param {Function} [a.rememberImpl]
+ * @param {Function} [a.fetchImpl]
+ * @returns {Promise<{created:number, captured?:number, skipped?:boolean, reason?:string}>}
+ */
+export async function sweepSessionOutcomes(a = {}) {
+  try {
+    const enabled = a.enabled !== undefined ? a.enabled : outcomesEnabled();
+    if (!enabled) return { created: 0, skipped: true, reason: "disabled" };
+    if (!a.sessionId) return { created: 0, skipped: true, reason: "no-session" };
+
+    // CONFIDENTIALITY: a landed outcome is org-visible, so only an already
+    // org-visible source may produce one. Checked BEFORE the text is even parsed
+    // — a private turn's commitments are never captured, let alone written.
+    const gate = outcomeSourceShareable(a.item);
+    if (!gate.shareable) {
+      clearSessionOutcomes(a.sessionId);
+      return { created: 0, captured: 0, skipped: true, reason: `source-${gate.reason}` };
+    }
+
+    if (outcomesLanded(a.sessionId)) {
+      clearSessionOutcomes(a.sessionId);
+      return { created: 0, skipped: true, reason: "already-landed" };
+    }
+
+    const text =
+      typeof a.resultText === "string" && a.resultText
+        ? a.resultText
+        : resultTextFromStdout(a.stdout);
+    const parsed = parseOutcomes(text);
+    const captured = noteOutcomes(a.sessionId, parsed);
+    if (captured.length === 0) {
+      clearSessionOutcomes(a.sessionId);
+      return { created: 0, captured: 0, skipped: true, reason: "nothing-captured" };
+    }
+
+    const res = await landOutcomes({
+      sessionId: a.sessionId,
+      outcomes: captured,
+      cfg: a.cfg,
+      item: a.item,
+      classResult: a.classResult,
+      agentName: a.agentName,
+      createItemImpl: a.createItemImpl,
+      rememberImpl: a.rememberImpl,
+      fetchImpl: a.fetchImpl,
+    });
+    clearSessionOutcomes(a.sessionId);
+    return { ...res, captured: captured.length };
+  } catch {
+    return { created: 0, skipped: true, reason: "error" };
+  }
+}
+
+export default {
+  MAX_OUTCOMES,
+  outcomesEnabled,
+  outcomeSourceShareable,
+  parseOutcomes,
+  resultTextFromStdout,
+  noteOutcomes,
+  getSessionOutcomes,
+  outcomesLanded,
+  markOutcomesLanded,
+  clearSessionOutcomes,
+  outcomeItemId,
+  landOutcomes,
+  sweepSessionOutcomes,
+};