@cohortapp/agent-sdk 2.18.13 → 2.18.15

package/scripts/daemon/inbox-deferral.mjs

@@ -18,11 +18,26 @@
  *     every `.deferred` file in any service inbox dir whose body
  *     references `channel`. If exactly one is found, renames it back
  *     to its original name (next poll picks it up). If N>1 are found,
- *     keeps only the LATEST (by timestamp), promotes that one, and
- *     marks the others `.processed-bundled` for the audit trail —
- *     the latest item's `thread_context` already contains the prior
- *     messages as conversation history, so Claude sees everything
- *     and can compose a single coherent reply.
+ *     keeps only the LATEST (by timestamp) of each BUNDLING GROUP,
+ *     promotes those, and marks the others `.processed-bundled` for
+ *     the audit trail.
+ *
+ *     WHAT A BUNDLING GROUP IS, AND WHY IT IS NOT JUST "THE SURFACE".
+ *     The collapse is only sound when the promoted item genuinely
+ *     carries what is being folded away. That used to be asserted
+ *     unconditionally — "the latest item's `thread_context` already
+ *     contains the prior messages" — and it is true of a Slack
+ *     channel or DM item and FALSE of a Cohort space post, which
+ *     `lib/org/inbound` never hydrates a thread context for. Fold a
+ *     second person's question into one of those and it is not
+ *     bundled, it is deleted: marked `.processed-bundled` and never
+ *     answered by anyone.
+ *
+ *     So a group is (surface, sender) — a person's own flurry always
+ *     collapses to their latest word — UNLESS the surface's newest
+ *     item carries `thread_context`, in which case the whole surface
+ *     collapses as before, because the session really will see every
+ *     message it stands for.
  *
  * The file format is the YAML emitted by the slack/gmail/calendar
  * pollers (a flat top-level object with quoted scalar fields, plus an
@@ -155,6 +170,42 @@ function readScalar(body, field) {
   return null;
 }
 
+/**
+ * Does this file carry a TOP-LEVEL key at all, block scalar or not?
+ *
+ * `readScalar` answers "what is this field's single-line value", which is the
+ * wrong question for `thread_context`: the pollers write it as a block scalar
+ * (`thread_context: |`), so its value never lives on the key's own line. All
+ * the bundling decision needs to know is whether the field is PRESENT — the
+ * pollers emit it only when there is history to emit (`if (item.thread_context)`
+ * in scripts/poller/utils.mjs), so presence is exactly "this item carries the
+ * conversation around it".
+ *
+ * @param {string} body
+ * @param {string} field
+ * @returns {boolean}
+ */
+function hasTopLevelKey(body, field) {
+  if (typeof body !== "string") return false;
+  // TWO MECHANISMS, ONE PROPERTY, and the redundancy is stated rather than
+  // pretended away: the pattern is anchored at column 0, so an indented line
+  // cannot match it and the `continue` below is a BELT, not the mechanism.
+  // Deleting the `continue` alone changes no behaviour — a mutation of it
+  // leaves the suite green, and that is honest rather than a hole. What the
+  // suite does refuse is the realistic future edit: loosening this anchor to
+  // `^\s*` (the shape `readScalar` had before audit L7) with nothing else in
+  // the way. That is pinned as a BEHAVIOUR, in inbox-deferral.test.mjs — "L7:
+  // body line `thread_context:` in a block scalar does not fake carrying
+  // history" — because the property worth pinning is that a colleague's
+  // question survives, not which of two lines delivered it.
+  const re = new RegExp(`^${escapeRegExp(field)}\\s*:`);
+  for (const line of body.split("\n")) {
+    if (/^\s/.test(line)) continue; // indented — belongs to a block, not top level
+    if (re.test(line)) return true;
+  }
+  return false;
+}
+
 /**
  * Promote every `.deferred` item targeting `channel` back into the
  * live inbox. Bundles bursts: if multiple deferred items exist for
@@ -219,6 +270,26 @@ export function promoteDeferred(channel, agentRoot) {
           readScalar(body, "thread_id") ||
           readScalar(body, "scope_id") ||
           "",
+        // WHO SENT IT, and WHETHER THE ITEM CARRIES ITS CONVERSATION.
+        //
+        // These two decide whether bundling is a bundle or a deletion. The
+        // latest-wins collapse is justified by one sentence in this module's
+        // header — "the latest item's thread_context already contains the
+        // prior messages as conversation history, so Claude sees everything" —
+        // and that sentence is TRUE OF SOME ITEMS AND FALSE OF OTHERS. Slack
+        // channel and DM items carry `thread_context` (slack-poller.mjs:434,
+        // :558); a Cohort space post does NOT, because `lib/org/inbound`
+        // never hydrates one for an untreaded space message. Bundling a
+        // second person's ask into a Cohort item that carries no history is
+        // not folding a duplicate away, it is marking their question
+        // `.processed-bundled` and never answering it.
+        //
+        // So: the collapse now requires evidence. Same sender is always safe
+        // (a person's own flurry — their newest message is their latest word
+        // either way). A DIFFERENT sender may only be folded into an item that
+        // actually carries the room's history.
+        sender: (readScalar(body, "sender") || "").trim().toLowerCase(),
+        carriesHistory: hasTopLevelKey(body, "thread_context"),
       });
     }
     if (matches.length === 0) continue;
@@ -226,13 +297,35 @@ export function promoteDeferred(channel, agentRoot) {
     // Group by surface within the channel, then bundle latest-wins WITHIN each
     // group. Distinct surfaces each promote their own latest; none is dropped
     // just because a newer message landed on a different surface in the room.
-    const groups = new Map();
+    const surfaces = new Map();
     for (const m of matches) {
-      if (!groups.has(m.surface)) groups.set(m.surface, []);
-      groups.get(m.surface).push(m);
+      if (!surfaces.has(m.surface)) surfaces.set(m.surface, []);
+      surfaces.get(m.surface).push(m);
+    }
+
+    // SPLIT A SURFACE BY SENDER UNLESS ITS WINNER CARRIES THE HISTORY.
+    // With history present this is byte-for-byte the old behaviour: one group
+    // per surface, latest wins, everything else bundled. Without it, each
+    // sender keeps their own latest and promotes it — so two people's asks
+    // serialise into two sessions rather than one of them disappearing.
+    const groups = [];
+    for (const group of surfaces.values()) {
+      group.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+      const winner = group[group.length - 1];
+      const senders = new Set(group.map((m) => m.sender));
+      if (senders.size <= 1 || winner.carriesHistory) {
+        groups.push(group);
+        continue;
+      }
+      const bySender = new Map();
+      for (const m of group) {
+        if (!bySender.has(m.sender)) bySender.set(m.sender, []);
+        bySender.get(m.sender).push(m);
+      }
+      for (const g of bySender.values()) groups.push(g);
     }
 
-    for (const group of groups.values()) {
+    for (const group of groups) {
       // Latest-wins: lex-sort ISO timestamps, take the most recent.
       group.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
       const latest = group[group.length - 1];

package/scripts/daemon/session-lock.mjs

@@ -311,6 +311,37 @@ export function checkRecentlySent(channel, threadTs, type) {
   return { allowed: true };
 }
 
+/**
+ * PURE. The ONE definition of which conversation a thread lock covers.
+ *
+ * WHY THIS EXISTS AS A FUNCTION. The normalisation used to be written twice —
+ * once where the lock is taken (agent-daemon, as an inline ternary) and once
+ * where it is released (`releaseThreadLock`, as a different inline rule) — and
+ * the two did not agree. The acquiring side turned a DM into `dm-channel` from
+ * `item.is_dm`; the releasing side only recognised a DM by a channel id
+ * starting with "D", which is a SLACK id shape. A Cohort DM therefore took a
+ * `dm-channel` lock and released nothing, and the room stayed locked for the
+ * full sixty-minute TTL with every later message deferred behind it. Two
+ * copies of a key derivation is one copy too many; this is now the only one.
+ *
+ * @param {object} o
+ * @param {string} o.channel
+ * @param {string} [o.threadId]  the item's own thread id, if it has one
+ * @param {boolean} [o.isDm]     the daemon's own DM verdict (item.is_dm)
+ * @param {boolean} [o.channelMainLock=true] false restores the pre-2026-09-25
+ *        behaviour where an untreaded channel post took no lock at all
+ * @returns {string|null} the lock key, or null when this item takes no lock
+ */
+export function threadLockKey(o = {}) {
+  const channel = o.channel;
+  if (!channel) return null;
+  // A Slack DM id ("D…") is a DM whatever the caller believed.
+  if (String(channel).startsWith("D")) return "dm-channel";
+  if (o.threadId) return String(o.threadId);
+  if (o.isDm === true) return "dm-channel";
+  return o.channelMainLock === false ? null : "channel-main";
+}
+
 /**
  * Check if a session was already dispatched for the same thread recently.
  * Prevents multiple sessions from responding to the same thread when
@@ -516,7 +547,16 @@ export function releaseThreadLock(channel, threadTs) {
   // the first was skipped with "thread_dedup: DM channel already
   // dispatched 1200s ago").
   if (channel.startsWith("D")) threadTs = "dm-channel";
-  if (!threadTs) return; // non-DM channel without a thread — no lock to release
+  // A caller that hands us nothing is asking us to guess, and the only guess
+  // that mirrors the acquiring side is `threadLockKey`'s: an untreaded, non-DM
+  // channel post locks the room's main feed. Unlinking a lock that was never
+  // taken (the off-switch case, or a genuinely lockless item) is a no-op under
+  // the catch below, so guessing here can only ever free a lock, never wedge
+  // one. The reverse — returning early, as this did — left every
+  // `channel-main` lock to expire on its sixty-minute TTL, which is the whole
+  // channel gagged for an hour after one message.
+  if (!threadTs) threadTs = threadLockKey({ channel, threadId: null, isDm: false });
+  if (!threadTs) return;
   const safeKey = sanitiseItemId(`thread-${channel}-${threadTs}`);
   const lockPath = join(LOCKS_DIR, `${safeKey}.lock`);
   try {

package/scripts/emergency-stop.sh

@@ -1,13 +1,42 @@
 #!/bin/bash
 # Emergency Stop — Immediately halts all Maestro agent operations.
-# Usage: ./scripts/emergency-stop.sh
+# Usage: ./scripts/emergency-stop.sh [--dry-run] [--help]
 #
 # This script is the kill switch for all autonomous operations:
 #   1. Drops .emergency-stop flag (every workflow / cadence consumer / enqueue
 #      script honours this on the next tick).
 #   2. Unloads every installed `ai.maestro.<agent>-*` (and legacy
 #      `ai.adaptic.<agent>-*`) launchd job.
-#   3. Kills running Claude Code subagent processes.
+#   3. Kills running Claude Code subagent processes (EXCEPT this process and
+#      its ancestors — see step 3).
+#
+# --dry-run
+#   Report the kill set instead of signalling it. The flag and the launchd
+#   unload still happen; only the signals are withheld — and BOTH the closing
+#   banner and the log line say "DRY RUN — NO PROCESSES SIGNALLED", so a dry
+#   run can never be mistaken for a halt. It exists so the self-sparing in
+#   step 3 is testable without a suite that kills the operator's own session
+#   to prove that it does not.
+#
+#   WHY A FLAG AND NOT AN ENV VAR. This used to be read from the ambient
+#   environment as MAESTRO_EMERGENCY_STOP_DRY_RUN, while step 4 printed
+#   "EMERGENCY STOP COMPLETE — All operations halted" unconditionally. A stray
+#   `export`, a line in .env, or an EnvironmentVariables entry in a plist
+#   would therefore turn the kill switch into a no-op — every claude process
+#   surviving — while the banner and the log both asserted the halt had
+#   succeeded. That is the same fault class this file was being repaired for:
+#   something that looks like it is handling the case and is not. On a
+#   break-glass control the escape hatch must be typed at the call site, once,
+#   deliberately. The env var is NOT consulted; setting it does nothing.
+#
+# SCOPE OF THE KILL (step 3), stated rather than hidden: every process of THIS
+# user whose command line matches `claude`, minus this process and its
+# ancestors. That is machine-wide, not agent-scoped — an unrelated Claude
+# session of yours in another directory WILL be terminated (21 processes
+# matched on the host where this was measured). Nothing here can narrow it
+# honestly, because a Claude Code session's argv does not carry the agent dir;
+# so the set is printed before it is signalled, and --dry-run shows it without
+# signalling anything.
 #
 # Plist resolution: the agent's first-name slug is read from config/agent.json
 # (SOT) so unload targets the correct labels; falls back to the directory
@@ -21,6 +50,25 @@ LOG_FILE="$AGENT_DIR/logs/emergency-stop.log"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
 
+# Argument parsing runs BEFORE anything is halted: a typo must refuse loudly,
+# not drop the flag and then exit.
+DRY_RUN=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --dry-run) DRY_RUN=1 ;;
+        -h | --help)
+            sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+            exit 0
+            ;;
+        *)
+            echo "emergency-stop: unknown argument: $1" >&2
+            echo "Usage: emergency-stop.sh [--dry-run]" >&2
+            exit 2
+            ;;
+    esac
+    shift
+done
+
 # Resolve agent first-name slug from SOT (config/agent.json) so the unload
 # loop targets the right launchd labels. Falls back to the basename of the
 # agent directory (stripping -ai suffix).
@@ -39,7 +87,11 @@ LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
 # (deployed agents whose plists predate the rename). The loops guard with [ -f ].
 PLIST_GLOB="$LAUNCH_AGENTS_DIR/ai.maestro.${AGENT_FIRST}-*.plist $LAUNCH_AGENTS_DIR/ai.adaptic.${AGENT_FIRST}-*.plist"
 
-echo "[$TIMESTAMP] EMERGENCY STOP INITIATED (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
+if [ "$DRY_RUN" -eq 1 ]; then
+    echo "[$TIMESTAMP] EMERGENCY STOP DRY RUN INITIATED (agent=$AGENT_FIRST) — no process will be signalled" | tee -a "$LOG_FILE"
+else
+    echo "[$TIMESTAMP] EMERGENCY STOP INITIATED (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
+fi
 
 # 1. Drop the stop flag FIRST so any in-flight work sees it on next tick.
 echo "$TIMESTAMP" > "$AGENT_DIR/.emergency-stop"
@@ -57,23 +109,72 @@ for plist in $PLIST_GLOB; do
 done
 echo "[$TIMESTAMP] Unloaded $unloaded launchd job(s)" >> "$LOG_FILE"
 
-# 3. Kill running Claude Code subagent processes. Filter to processes that
-#    have AGENT_ROOT or this agent's directory in their cwd to avoid
-#    killing unrelated claude sessions the operator may have running.
+# 3. Kill running Claude Code subagent processes.
+#
+#    THE MIRROR-IMAGE FAULT THIS FIXES: `pgrep -f claude` matches the process
+#    that is RUNNING THIS SCRIPT whenever an agent session invokes it — which
+#    is the normal way it gets invoked. The stop then killed its own caller
+#    mid-flight, so step 4 never ran and the halt was never logged complete:
+#    a script that destroys the condition it needs in order to finish, the
+#    same shape as resume-operations.sh refusing to lift its own stop flag.
+#    The comment here also claimed a cwd filter that did not exist.
+#
+#    So: build the kill set, then subtract this process and every ancestor of
+#    it. Everything else matching `claude` is still terminated — the stop is
+#    still a kill switch, it just no longer includes the hand on the switch.
+#    See SCOPE OF THE KILL in the header: "everything else" really does mean
+#    every matching process of this user on this machine, so it is printed.
 echo "Stopping Claude Code agent processes..."
-# pgrep -lf is more selective than pkill -f
-pids=$(pgrep -f "claude" 2>/dev/null | tr '\n' ' ' || true)
-if [ -n "$pids" ]; then
+
+# PIDs to spare: this shell and its whole ancestor chain (the launching
+# session, its shell, launchd). Walk up via ppid until PID 1.
+SPARE=" $$ "
+_p=$$
+while [ -n "$_p" ] && [ "$_p" -gt 1 ]; do
+    _p=$(ps -o ppid= -p "$_p" 2>/dev/null | tr -d ' ')
+    [ -n "$_p" ] || break
+    SPARE="$SPARE$_p "
+done
+
+# claude_targets — matching PIDs (this user only) minus the spare set.
+claude_targets() {
+    local out=""
+    local pid
+    for pid in $(pgrep -u "$(id -u)" -f "claude" 2>/dev/null || true); do
+        case "$SPARE" in
+            *" $pid "*) continue ;;
+        esac
+        out="$out$pid "
+    done
+    printf '%s' "$out"
+}
+
+pids=$(claude_targets)
+if [ "$DRY_RUN" -eq 1 ]; then
+    echo "[DRY-RUN] sparing:$SPARE"
+    echo "[DRY-RUN] would terminate: ${pids:-<none>}"
+    echo "[$TIMESTAMP] DRY RUN — would terminate: ${pids:-<none>}" >> "$LOG_FILE"
+elif [ -n "$pids" ]; then
+    # Name the set before signalling it — this is machine-wide for this user.
+    echo "Terminating (every matching process of this user, not just this agent): $pids"
     # Send SIGTERM first, give 3s, then SIGKILL stragglers.
     kill -TERM $pids 2>/dev/null || true
     sleep 3
-    still=$(pgrep -f "claude" 2>/dev/null | tr '\n' ' ' || true)
-    [ -n "$still" ] && kill -KILL $still 2>/dev/null || true
+    still=$(claude_targets)
+    if [ -n "$still" ]; then kill -KILL $still 2>/dev/null || true; fi
     echo "[$TIMESTAMP] Claude processes terminated ($pids)" >> "$LOG_FILE"
+else
+    echo "[$TIMESTAMP] No Claude processes to terminate (self/ancestors spared)" >> "$LOG_FILE"
 fi
 
-# 4. Log completion.
-echo "[$TIMESTAMP] EMERGENCY STOP COMPLETE — All operations halted" | tee -a "$LOG_FILE"
+# 4. Log completion. A dry run says so in BOTH places — the banner an operator
+#    reads and the log an incident review reads — because the previous version
+#    printed the halt banner either way.
+if [ "$DRY_RUN" -eq 1 ]; then
+    echo "[$TIMESTAMP] EMERGENCY STOP DRY RUN — NO PROCESSES SIGNALLED (flag set, launchd unloaded)" | tee -a "$LOG_FILE"
+else
+    echo "[$TIMESTAMP] EMERGENCY STOP COMPLETE — All operations halted" | tee -a "$LOG_FILE"
+fi
 echo ""
 echo "To resume operations:"
 echo "  ./scripts/resume-operations.sh"