heylead 0.10.332__tar.gz → 0.10.334__tar.gz

{heylead-0.10.332 → heylead-0.10.334}/AGENTS.md

@@ -33,7 +33,7 @@ HeyLead is an autonomous LinkedIn SDR (Sales Development Representative) that ru
 
 ## Agent ops
 
-When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes.
+When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes. If they ask what the agents left for the next tick, what the swarm thinks, or who went dark, call `inspect(action='commons')`.
 
 A hold: `prospect(action="conversation", outreach_id="...")` then `send_message(action="reply", outreach_id="...")`. Operator replies skip the reply agent.
 
@@ -41,7 +41,7 @@ Never paste model-authored text as the LinkedIn message. The send tools generate
 
 Never launch a draft unless the user asked.
 
-In-process agents default to observe. Turn act on with `edit_campaign(enable_reply_agent="on")`, `edit_campaign(enable_strategist_replan_agent="on")`, or `edit_campaign(enable_hot_lead_closer="on")`. Use `"observe"` to return to logging-only, `"off"` to disable.
+In-process agents default to observe. Turn act on with `edit_campaign(enable_reply_agent="on")`, `edit_campaign(enable_strategist_replan_agent="on")`, `edit_campaign(enable_hot_lead_closer="on")`, or `edit_campaign(enable_coordinator_agent="on")`. Use `"observe"` to return to logging-only, `"off"` to disable.
 
 ## Authentication
 

{heylead-0.10.332 → heylead-0.10.334}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: heylead
-Version: 0.10.332
+Version: 0.10.334
 Summary: MCP-native autonomous LinkedIn SDR. Your AI sales rep, one command to fill your pipeline.
 Project-URL: Homepage, https://github.com/D4umak/heylead
 Project-URL: Repository, https://github.com/D4umak/heylead

{heylead-0.10.332 → heylead-0.10.334}/SKILL.md

@@ -77,7 +77,7 @@ After adding the MCP server, tell your OpenClaw agent:
 
 ## Agent ops
 
-When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes.
+When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes. If they ask what the agents left for the next tick, what the swarm thinks, or who went dark, call `inspect(action='commons')`.
 
 A hold: `prospect(action="conversation", outreach_id="...")` then `send_message(action="reply", outreach_id="...")`. Operator replies skip the reply agent.
 
@@ -85,7 +85,7 @@ Never paste model-authored text as the LinkedIn message. The send tools generate
 
 Never launch a draft unless the user asked.
 
-In-process agents default to observe. Turn act on with `edit_campaign(enable_reply_agent="on")`, `edit_campaign(enable_strategist_replan_agent="on")`, or `edit_campaign(enable_hot_lead_closer="on")`. Use `"observe"` to return to logging-only, `"off"` to disable.
+In-process agents default to observe. Turn act on with `edit_campaign(enable_reply_agent="on")`, `edit_campaign(enable_strategist_replan_agent="on")`, `edit_campaign(enable_hot_lead_closer="on")`, or `edit_campaign(enable_coordinator_agent="on")`. Use `"observe"` to return to logging-only, `"off"` to disable.
 
 ## Safety Model
 

{heylead-0.10.332 → heylead-0.10.334}/clawhub/SKILL.md

@@ -80,7 +80,7 @@ After adding the MCP server, tell your OpenClaw agent:
 
 ## Agent ops
 
-When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes.
+When the user asks what the agents did, who is held, or why a reply was skipped, call `inspect()` first. It is read-only and never writes. If they ask what the agents left for the next tick, what the swarm thinks, or who went dark, call `inspect(action='commons')`.
 
 A hold: `prospect(action="conversation", outreach_id="...")` then `send_message(action="reply", outreach_id="...")`. Operator replies skip the reply agent.
 
@@ -88,7 +88,7 @@ Never paste model-authored text as the LinkedIn message. The send tools generate
 
 Never launch a draft unless the user asked.
 
-In-process agents default to observe. Turn act on with `edit_campaign(enable_reply_agent="on")`, `edit_campaign(enable_strategist_replan_agent="on")`, or `edit_campaign(enable_hot_lead_closer="on")`. Use `"observe"` to return to logging-only, `"off"` to disable.
+In-process agents default to observe. Turn act on with `edit_campaign(enable_reply_agent="on")`, `edit_campaign(enable_strategist_replan_agent="on")`, `edit_campaign(enable_hot_lead_closer="on")`, or `edit_campaign(enable_coordinator_agent="on")`. Use `"observe"` to return to logging-only, `"off"` to disable.
 
 ## Safety Model
 

{heylead-0.10.332 → heylead-0.10.334}/clawhub.json

@@ -17,7 +17,7 @@
     "icp",
     "campaign-management"
   ],
-  "version": "0.10.332",
+  "version": "0.10.334",
   "license": "MIT",
   "author": {
     "name": "HeyLead",

heylead-0.10.334/docs/superpowers/plans/2026-09-09-agent-commons-heartbeat.md

@@ -0,0 +1,53 @@
+# Agent Commons + Heartbeat Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Official inspectable scratch so later ticks can read earlier notes, and a host can see when a sibling agent went dark.
+
+**Architecture:** New `agent_commons` table (beat upsert per agent+campaign; append-only notes with 24h expiry). Sidecar `record_agent_beat` after each of the four `run_agent_loop` returns. Kernel passes `reason`/`note` into tools that accept them. `inspect(action='commons')` is read-only. Client SQLite only.
+
+**Tech Stack:** Python 3.12, SQLite, existing `run_agent_loop` / `inspect` / pytest (`PYTHONPATH=src python3.12 -m pytest`).
+
+**Spec:** `docs/superpowers/specs/2026-09-09-agent-commons-heartbeat-design.md`
+
+---
+
+## Files
+
+- Create: `src/heylead/services/agent_commons.py`
+- Create: `tests/test_agent_commons.py`
+- Modify: `src/heylead/db/schema.py` (`SCHEMA_VERSION` 9→10, `_SCHEMA_SQL`, `_apply_migrations`)
+- Modify: `tests/test_migration_backup_gating.py` (`EXPECTED_MIGRATION_STATEMENTS`)
+- Modify: `src/heylead/ai/agent_loop.py` (pass kwargs into tools)
+- Modify: `src/heylead/ai/schemas.py` (four step enums + `note`)
+- Modify: `src/heylead/services/reply_agent.py`, `strategist_replan.py`, `hot_lead_closer.py`, `icp_research.py`
+- Modify: `src/heylead/tools/inspect.py`, `src/heylead/server.py`
+- Modify: `tests/test_agent_loop.py`, `tests/test_inspect.py`, `tests/test_host_ops_playbook.py`
+- Modify: `AGENTS.md`, `SKILL.md`, `clawhub/SKILL.md`
+
+Do not commit unless asked. Do not bump the package version here.
+
+### Task 1: Failing tests
+
+- [ ] `tests/test_agent_commons.py` — beat upsert, off skips beat, one note per run, expiry, 500-char refuse, inspect commons/agents, inspect does not write
+- [ ] Extend `test_agent_loop.py` — tool receives `reason`/`note`
+- [ ] Extend inspect unknown-action + no-write lists with `commons`
+- [ ] Playbook requires `inspect(action='commons')`
+
+### Task 2: Schema + service + kernel
+
+- [ ] Table + SCHEMA_VERSION 10
+- [ ] `agent_commons` service
+- [ ] Kernel `_invoke_tool`
+
+### Task 3: Hook four loops + inspect + playbook
+
+- [ ] Tools + `record_agent_beat` after each loop
+- [ ] `inspect(action='commons')` and agents one-liner
+- [ ] Playbook / MCP instructions / inspect docstring
+
+### Task 4: Verify
+
+```
+PYTHONPATH=src python3.12 -m pytest tests/test_agent_commons.py tests/test_agent_loop.py tests/test_inspect.py tests/test_host_ops_playbook.py tests/test_migration_backup_gating.py tests/test_reply_agent.py tests/test_icp_research.py tests/test_strategist_replan.py tests/test_hot_lead_closer.py -q
+```

heylead-0.10.334/docs/superpowers/plans/2026-09-09-agent-coordinator.md

@@ -0,0 +1,18 @@
+# Agent Coordinator Implementation Plan
+
+> **For agentic workers:** Use executing-plans. Checkbox steps below.
+
+**Goal:** After each sibling loop, post an inspectable digest and optionally a coordinator note/hold.
+
+**Architecture:** Sidecar upserts `coordinator` beat + one `digest` per campaign. A 2-step kernel loop (off skips the loop) may note or, in act, persist a campaign `hold`. Never calls the other four. Never sends LinkedIn.
+
+**Spec:** `docs/superpowers/specs/2026-09-09-agent-coordinator-design.md`
+
+- [x] Failing tests in `tests/test_agent_coordinator.py`
+- [x] Schema step + constants + `services/coordinator.py`
+- [x] Hook four siblings via `after_sibling_loop`
+- [x] `edit_campaign(enable_coordinator_agent=...)` + MCP wrapper
+- [x] `inspect` digest / coordinator hold
+- [x] Playbook names coordinator flag + `inspect(action='commons')`
+
+Do not commit unless asked. Do not bump the package version here.

heylead-0.10.334/docs/superpowers/specs/2026-09-09-agent-commons-heartbeat-design.md

@@ -0,0 +1,84 @@
+# Agent commons + heartbeat
+
+Date: 2026-09-09
+
+The four in-process agents write `actions_log`. They barely read each other, and a host cannot see whether a sibling went dark. This spec adds an official, inspectable scratch — not a covert channel.
+
+Inspiration is the May–June 2026 OpenAI wiki swarm (cross-run notes, heartbeat, adapt when the world changes). We copy that *shape*. We do not copy covert GET-writes, fighting the operator, impersonation, or sandbox escape.
+
+First slice of a larger program (coordinator and `heylead-api` port come later). Client SQLite only.
+
+## Goals
+
+- Table `agent_commons` with two kinds of row: `beat` and `note`.
+- Python sidecar upserts a beat after every `run_agent_loop` return (observe or act).
+- Kernel tools `read_commons` and `write_commons` on all four registries. One note per run.
+- `inspect(action='commons')` lists beats, ages, live notes, and stale agents.
+- `inspect(action='agents')` gains one commons/liveness line.
+- Playbook: if they ask what the agents left for the next tick, or who went dark, call `inspect(action='commons')`.
+- Notes expire in 24h. Body ≤ 500 characters.
+- Stale = beat older than 6 hours and that agent is not `off`.
+
+## Non-goals
+
+- Coordinator agent.
+- Porting loops to `heylead-api`.
+- Syncing commons to the backend.
+- Operator-delete tool (v1: turn the agent `off`, or wait 24h). `inspect` stays read-only.
+- Recreating a forgotten note under a new key (`ZZZ…`).
+- LinkedIn / email / calendar writes from commons.
+- Changing default observe behavior or act flags.
+- New MCP tool.
+
+## Data
+
+`agent` is `reply` | `strategist` | `closer` | `icp_research`.
+
+| kind | uniqueness | fields |
+|---|---|---|
+| `beat` | one current row per `(campaign_id, agent)` | `decision`, `reason` (≤240 chars), `timestamp`. ICP research uses `campaign_id=""`. |
+| `note` | append | `body`, optional `outreach_id`, `created_at`, `expires_at` (= created + 24h) |
+
+`off` does not run the loop, so the beat is not refreshed and ages. That is the liveness signal.
+
+## Kernel
+
+Today tools are invoked as `tool()` with no arguments. `write_commons` needs the note text.
+
+`run_agent_loop` passes `reason` and extras into a tool when the callable accepts them (`reason=`, `note=` from extras, otherwise ignored). Each vertical step schema adds `read_commons` and `write_commons` to its `action` enum, plus a `note` string (empty = use `reason`).
+
+`write_commons` refuses a second call in the same run. Empty / overlong body is refused. It writes only to `agent_commons`.
+
+`read_commons` returns current beats plus unexpired notes, scoped to the campaign (and outreach when the loop has one).
+
+Sidecar `record_agent_beat` runs after the loop returns, including `none` / exhausted. It does not run when the vertical is `off` (loop skipped).
+
+## Inspect
+
+`inspect(action='commons')` — never writes, no LLM, no LinkedIn.
+
+- Last beat per agent: age, last decision, short reason.
+- Live notes (unexpired).
+- Stale line when a beat is older than 6 hours and mode is not `off`.
+
+`inspect(action='agents')` adds one line: live note count and the newest beat age (e.g. `commons: 2 live notes, reply beat 12m ago`).
+
+Unknown action still lists the valid set (now includes `commons`).
+
+## Failure
+
+- Query failure → short error; nothing written.
+- `write_commons` refused → tool result string, loop continues.
+- Missing table on old DBs → create via existing schema init (`CREATE TABLE IF NOT EXISTS`).
+
+## Tests
+
+- Beat upserted after a reply (and strategist / closer / ICP) loop.
+- `off` does not refresh the beat.
+- `write_commons` first call persists; second call in the same run is refused.
+- Expired notes are hidden from `read_commons` and `inspect(action='commons')`.
+- Body over 500 characters is refused.
+- `inspect(action='commons')` does not write.
+- `inspect(action='agents')` mentions commons / beat.
+- MCP `inspect` signature / dispatch includes `commons`.
+- Playbook names `inspect(action='commons')`.

heylead-0.10.334/docs/superpowers/specs/2026-09-09-agent-coordinator-design.md

@@ -0,0 +1,83 @@
+# Agent coordinator
+
+Date: 2026-09-09
+
+Commons + heartbeat shipped (`agent_commons` beats/notes, `inspect(action='commons')`). The four loops still do not post a shared state. This spec adds a fifth vertical: a coordinator that reads that scratch and writes one current digest the host can inspect.
+
+Same inspiration as commons (cross-run shared state). Same refusals: no covert channel, no calling the other four, no LinkedIn, no fighting the operator.
+
+Client SQLite only. API port stays later.
+
+## Goals
+
+- After each sibling `run_agent_loop` return (reply, strategist, closer, ICP research), run coordinator. Not when that sibling was `off`. Never after itself.
+- Sidecar always: upsert `coordinator` beat; upsert one `kind=digest` row per `campaign_id` (sibling decisions, live note count, stale flags).
+- 2-step kernel loop when mode is not `off`. Tools: `read_commons`, `read_digest`, `write_commons`. Decisions: `none` | `note` | `hold`.
+- `edit_campaign(enable_coordinator_agent="")` — `on` | `off` | `observe`. Empty = no change. Unset = observe. Same boolean/`observe`-deletes-keys pattern as the other three campaign flags.
+- **observe:** loop may append one extra note; `hold` is logged on the beat only.
+- **act:** `hold` also upserts `kind=hold` on that campaign (campaign-level coordinator hold).
+- **off:** no loop. Digest and beat still refresh.
+- `inspect(action='commons')` shows digest + coordinator beat + coordinator hold.
+- `inspect(action='holds')` lists campaign-level coordinator holds as well as outreach `hold_for_operator` rows.
+- `inspect(action='agents')` one-liner includes the coordinator beat age.
+- Playbook: if they ask what the swarm thinks, or whether a sibling went dark, `inspect(action='commons')`.
+- `VALID_AGENTS` includes `coordinator`. Notes still ≤500 chars, 24h expiry, one `write_commons` per coordinator run.
+
+## Non-goals
+
+- Invoking reply / strategist / closer / ICP from the coordinator.
+- LinkedIn, email, calendar, or turning sibling flags on/off.
+- Porting to `heylead-api`.
+- New MCP tool.
+- Operator-delete of digest/hold (turn coordinator `off`, or wait for the next sibling to refresh the digest; hold clears when a later act-run decides `none` or `note`).
+
+## Trigger
+
+Call `maybe_run_coordinator(campaign_id, trigger_agent)` after `record_agent_beat` in the four sibling services.
+
+- ICP research uses `campaign_id=""`.
+- Empty `campaign_id`: sidecar still runs; loop defaults to observe; `hold` cannot persist (no campaign). Log only.
+- If the sibling returned without running the loop (`off`), do not call the coordinator.
+
+## Data
+
+| kind | uniqueness | writer |
+|---|---|---|
+| `beat` | one current `(campaign_id, agent)` including `coordinator` | sidecar |
+| `digest` | one current `campaign_id` | sidecar (overwrite) |
+| `note` | append, 24h | loop `write_commons` only |
+| `hold` | one current `campaign_id` | act + decision `hold`. Cleared when a later act-run decides `none` or `note`. |
+
+Digest body is Python-authored (not model text): agent → last decision, ages, live note count, stale yes/no. Cap ~800 chars.
+
+## Kernel
+
+`COORDINATOR_AGENT_STEP`: actions `read_commons` | `read_digest` | `write_commons` | `decide`. Decisions `none` | `note` | `hold`. Extra `note` string.
+
+Budget: 2 steps, same style as other verticals (small token/timeout constants).
+
+`write_commons` is the existing one-per-run tool, agent=`coordinator`.
+
+## Inspect
+
+- `commons`: digest block, coordinator beat, live notes, STALE lines, coordinator hold if present.
+- `holds`: existing outreach holds, then coordinator holds (`campaign` + reason).
+- `agents`: commons line includes coordinator beat age when present.
+- `inspect` still never writes.
+
+## Failure
+
+Sibling success must not depend on the coordinator. Coordinator exception → log, skip, sibling outcome unchanged.
+
+## Tests
+
+- After a reply loop, coordinator beat + digest exist.
+- Sibling `off` does not run coordinator.
+- Coordinator does not re-enter itself.
+- Observe `hold` does not write `kind=hold`; act `hold` does.
+- Act `none`/`note` clears a previous hold.
+- Empty `campaign_id`: no hold row.
+- `write_commons` second call in the same coordinator run refused.
+- `inspect(action='commons')` shows digest; `holds` shows act hold; inspect does not write.
+- `edit_campaign(enable_coordinator_agent=...)` on/off/observe + MCP signature.
+- Playbook names `inspect(action='commons')` for swarm / dark sibling (already true; keep it).

{heylead-0.10.332 → heylead-0.10.334}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "heylead"
-version = "0.10.332"
+version = "0.10.334"
 description = "MCP-native autonomous LinkedIn SDR. Your AI sales rep, one command to fill your pipeline."
 readme = "README.md"
 license = "MIT"

{heylead-0.10.332 → heylead-0.10.334}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.D4umak/heylead",
   "title": "HeyLead \u2014 Autonomous LinkedIn SDR",
   "description": "Autonomous LinkedIn SDR \u2014 voice-matched outreach, ICP generation, and campaign management.",
-  "version": "0.10.332",
+  "version": "0.10.334",
   "websiteUrl": "https://github.com/D4umak/heylead",
   "repository": {
     "url": "https://github.com/D4umak/heylead",
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "heylead",
-      "version": "0.10.332",
+      "version": "0.10.334",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{heylead-0.10.332 → heylead-0.10.334}/src/heylead/ai/agent_loop.py

@@ -100,7 +100,7 @@ async def run_agent_loop(
             transcript += f"\n\nTOOL {action}: unknown tool"
             continue
         try:
-            result = tool()
+            result = _invoke_tool(tool, reason=reason, extras=extras)
             if inspect.isawaitable(result):
                 result = await result
             text = str(result)
@@ -137,3 +137,18 @@ def _parse_step(raw: str, valid_decisions: frozenset[str]) -> dict[str, Any]:
         "done": done,
         "extras": extras,
     }
+
+
+def _invoke_tool(tool: ToolFn, *, reason: str, extras: dict[str, str]) -> str | Awaitable[str]:
+    kwargs: dict[str, str] = {}
+    try:
+        sig = inspect.signature(tool)
+    except (TypeError, ValueError):
+        return tool()
+    params = sig.parameters
+    accepts_var = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values())
+    if accepts_var or "reason" in params:
+        kwargs["reason"] = reason
+    if accepts_var or "note" in params:
+        kwargs["note"] = extras.get("note") or ""
+    return tool(**kwargs) if kwargs else tool()

heylead-0.10.334/src/heylead/ai/coordinator.py

@@ -0,0 +1,19 @@
+"""Prompts for the agent coordinator."""
+
+from __future__ import annotations
+
+COORDINATOR_SYSTEM = """You coordinate HeyLead in-process agents.
+Read the commons digest, then decide.
+
+Decisions:
+- none: sidecar digest is enough
+- note: leave one short note for the next tick
+- hold: a human should look (stale sibling, conflicting notes, or you are unsure)
+
+Do not write LinkedIn messages. Do not turn other agents on or off.
+Default to none when nothing is wrong."""
+
+
+def build_coordinator_context(*, trigger_agent: str, campaign_id: str) -> str:
+    camp = campaign_id or "(account)"
+    return f"Trigger: {trigger_agent}\nCampaign: {camp}\nRead tools if you need the digest."

{heylead-0.10.332 → heylead-0.10.334}/src/heylead/ai/schemas.py

@@ -67,7 +67,10 @@ SENTIMENT = _obj({
 AGENT_STEP = _obj({
     "action": {
         "type": "string",
-        "enum": ["read_thread", "read_timeline", "read_icp", "read_fit", "decide"],
+        "enum": [
+            "read_thread", "read_timeline", "read_icp", "read_fit",
+            "read_commons", "write_commons", "decide",
+        ],
     },
     "decision": {
         "type": "string",
@@ -75,13 +78,17 @@ AGENT_STEP = _obj({
     },
     "reason": _STR,
     "done": {"type": "boolean"},
+    "note": _STR,
 })
 
 # ICP research vertical — extra strings are a flat filter patch (empty = no change).
 ICP_AGENT_STEP = _obj({
     "action": {
         "type": "string",
-        "enum": ["read_icp", "preview_search", "read_filters", "decide"],
+        "enum": [
+            "read_icp", "preview_search", "read_filters",
+            "read_commons", "write_commons", "decide",
+        ],
     },
     "decision": {
         "type": "string",
@@ -89,6 +96,7 @@ ICP_AGENT_STEP = _obj({
     },
     "reason": _STR,
     "done": {"type": "boolean"},
+    "note": _STR,
     "titles_include": _STR,
     "titles_exclude": _STR,
     "locations_include": _STR,
@@ -101,7 +109,10 @@ ICP_AGENT_STEP = _obj({
 REPLAN_AGENT_STEP = _obj({
     "action": {
         "type": "string",
-        "enum": ["read_plan", "read_signals", "read_thread", "read_status", "decide"],
+        "enum": [
+            "read_plan", "read_signals", "read_thread", "read_status",
+            "read_commons", "write_commons", "decide",
+        ],
     },
     "decision": {
         "type": "string",
@@ -109,6 +120,7 @@ REPLAN_AGENT_STEP = _obj({
     },
     "reason": _STR,
     "done": {"type": "boolean"},
+    "note": _STR,
     "remaining_json": _STR,
 })
 
@@ -116,7 +128,10 @@ REPLAN_AGENT_STEP = _obj({
 CLOSER_AGENT_STEP = _obj({
     "action": {
         "type": "string",
-        "enum": ["read_thread", "read_contact", "read_calendar_target", "decide"],
+        "enum": [
+            "read_thread", "read_contact", "read_calendar_target",
+            "read_commons", "write_commons", "decide",
+        ],
     },
     "decision": {
         "type": "string",
@@ -124,7 +139,23 @@ CLOSER_AGENT_STEP = _obj({
     },
     "reason": _STR,
     "done": {"type": "boolean"},
+    "note": _STR,
     "attendee_email": _STR,
     "start_iso": _STR,
     "duration_minutes": _STR,
 })
+
+# Coordinator — digest is sidecar-authored; the loop may note or hold.
+COORDINATOR_AGENT_STEP = _obj({
+    "action": {
+        "type": "string",
+        "enum": ["read_commons", "read_digest", "write_commons", "decide"],
+    },
+    "decision": {
+        "type": "string",
+        "enum": ["none", "note", "hold"],
+    },
+    "reason": _STR,
+    "done": {"type": "boolean"},
+    "note": _STR,
+})

{heylead-0.10.332 → heylead-0.10.334}/src/heylead/constants.py

@@ -1355,6 +1355,12 @@ HOT_LEAD_CLOSER_RESULT_CHARS = 2000
 HOT_LEAD_CLOSER_MAX_BOOKS_PER_DAY = 5
 HOT_LEAD_CLOSER_VALID_DECISIONS = frozenset({"book", "hold", "none"})
 
+COORDINATOR_MAX_STEPS = 2
+COORDINATOR_MAX_TOKENS = 600
+COORDINATOR_TIMEOUT_SECONDS = 20
+COORDINATOR_RESULT_CHARS = 1500
+COORDINATOR_VALID_DECISIONS = frozenset({"none", "note", "hold"})
+
 STRATEGIST_AVAILABLE_ACTIONS = frozenset({
     "profile_view",
     "follow",

{heylead-0.10.332 → heylead-0.10.334}/src/heylead/db/schema.py

@@ -35,7 +35,7 @@ _DB_RETRY_BACKOFF = 0.1  # seconds, doubles each attempt
 #    dedup read it as "already in a campaign" and never let the person back in.
 # 7: outreaches.chat_id (and headline A/B columns) — a v6 stamp skipped the
 #    ALTER, so planning died with `no such column: o.chat_id`.
-SCHEMA_VERSION = 9  # 9: contacts.timezone (per-prospect planning windows); 8: versioned outreach sync
+SCHEMA_VERSION = 10  # 10: agent_commons (beats + notes); 9: contacts.timezone
 
 # Singleton connection — avoids opening multiple connections per process
 # which causes "database is locked" errors with WAL mode.
@@ -605,6 +605,24 @@ CREATE TABLE IF NOT EXISTS company_posts_tracked (
 );
 CREATE INDEX IF NOT EXISTS idx_cpt_watchlist ON company_posts_tracked(watchlist_id);
 CREATE INDEX IF NOT EXISTS idx_cpt_post_id ON company_posts_tracked(post_id);
+
+-- In-process agent scratch (heartbeat + short notes for the next tick)
+CREATE TABLE IF NOT EXISTS agent_commons (
+    id           TEXT PRIMARY KEY,
+    kind         TEXT NOT NULL,
+    agent        TEXT NOT NULL,
+    campaign_id  TEXT NOT NULL DEFAULT '',
+    outreach_id  TEXT,
+    body         TEXT,
+    decision     TEXT,
+    reason       TEXT,
+    created_at   INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+    expires_at   INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_agent_commons_beat
+    ON agent_commons(campaign_id, agent, kind);
+CREATE INDEX IF NOT EXISTS idx_agent_commons_notes
+    ON agent_commons(campaign_id, kind, expires_at);
 """
 
 
@@ -2278,6 +2296,31 @@ def _apply_migrations(conn: sqlite3.Connection) -> None:
             _reraise_if_migration_interrupted(e)
         logger.warning("Migration: outreach dedup failed: %s", e)
 
+    try:
+        conn.execute("SELECT 1 FROM agent_commons LIMIT 0")
+    except sqlite3.OperationalError as e:
+        _reraise_if_migration_interrupted(e)
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS agent_commons (
+                id           TEXT PRIMARY KEY,
+                kind         TEXT NOT NULL,
+                agent        TEXT NOT NULL,
+                campaign_id  TEXT NOT NULL DEFAULT '',
+                outreach_id  TEXT,
+                body         TEXT,
+                decision     TEXT,
+                reason       TEXT,
+                created_at   INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+                expires_at   INTEGER
+            );
+            CREATE INDEX IF NOT EXISTS idx_agent_commons_beat
+                ON agent_commons(campaign_id, agent, kind);
+            CREATE INDEX IF NOT EXISTS idx_agent_commons_notes
+                ON agent_commons(campaign_id, kind, expires_at);
+        """)
+        conn.commit()
+        logger.info("Migration: added agent_commons table")
+
 
 def _backfill_global_contacts(conn: sqlite3.Connection) -> None:
     """One-time backfill: create global_contacts from existing campaign contacts.

{heylead-0.10.332 → heylead-0.10.334}/src/heylead/server.py

@@ -28,6 +28,18 @@ from .ops_log import run_traced
 _CHANGELOG = """\
 # HeyLead Changelog
 
+## v0.10.334 (2026-09-09)
+- New: after each sibling loop a coordinator upserts a digest and
+  beat. inspect(action='commons') shows it; act can persist a
+  campaign hold. edit_campaign(enable_coordinator_agent=on).
+  Never sends LinkedIn (#279)
+
+## v0.10.333 (2026-09-09)
+- New: in-process agents leave an inspectable commons — a heartbeat after
+  every loop, and one short note per run for the next tick.
+  inspect(action='commons') shows beats, live notes, and who went dark
+  (#275)
+
 ## v0.10.332 (2026-09-09)
 - New: brand_strategy(action="set_headline", focus="...") sets the LinkedIn
   headline to exactly the text you pass. execute and makeover both write a
@@ -1234,9 +1246,12 @@ mcp = FastMCP(
         "    Never paste model-authored text as the LinkedIn message; the send\n"
         "    tools generate it. Agents default to observe. Turn act on with\n"
         "    edit_campaign(enable_reply_agent='on'),\n"
-        "    edit_campaign(enable_strategist_replan_agent='on'), or\n"
-        "    edit_campaign(enable_hot_lead_closer='on'). Use 'observe' to\n"
-        "    return to logging-only, 'off' to disable.\n"
+        "    edit_campaign(enable_strategist_replan_agent='on'),\n"
+        "    edit_campaign(enable_hot_lead_closer='on'), or\n"
+        "    edit_campaign(enable_coordinator_agent='on'). Use 'observe' to\n"
+        "    return to logging-only, 'off' to disable. If they ask what the\n"
+        "    agents left for the next tick, what the swarm thinks, or who\n"
+        "    went dark, call inspect(action='commons').\n"
         "  - book_meeting() — put an agreed call on your Google Calendar and invite them\n"
         "  - suggest_next_action() — AI-recommended next step\n"
         "  - analytics(action='report') — detailed analytics with outcomes and stale lead warnings\n"
@@ -2058,6 +2073,7 @@ async def edit_campaign(
     enable_reply_agent: str = "",
     enable_strategist_replan_agent: str = "",
     enable_hot_lead_closer: str = "",
+    enable_coordinator_agent: str = "",
     engagement_mode: str = "",
     max_followups: int = 0,
     followup_delay_days: str = "",
@@ -2114,6 +2130,8 @@ async def edit_campaign(
             "observe". Empty keeps the current value.
         enable_hot_lead_closer: Hot-lead closer: "on", "off", or "observe".
             Empty keeps the current value.
+        enable_coordinator_agent: Coordinator digest/hold: "on", "off", or
+            "observe". Empty keeps the current value.
         engagement_mode: Engagement style: "auto" (30% react / 70% comment),
             "comment_only", or "react_only".
         max_followups: Max follow-up messages (1-5). 0 to keep current.
@@ -2162,6 +2180,7 @@ async def edit_campaign(
                 enable_reply_agent=enable_reply_agent,
                 enable_strategist_replan_agent=enable_strategist_replan_agent,
                 enable_hot_lead_closer=enable_hot_lead_closer,
+                enable_coordinator_agent=enable_coordinator_agent,
                 engagement_mode=engagement_mode,
                 max_followups=max_followups,
                 followup_delay_days=followup_delay_days,
@@ -2294,11 +2313,12 @@ async def inspect(
     Args:
         action: What to show:
             "agents"  — one-screen digest of holds, replans, closer, skips, jobs (default)
-            "holds"   — fresh hold_for_operator rows (reply agent + closer)
+            "holds"   — fresh hold_for_operator rows and coordinator campaign holds
             "replans" — today's strategist_replan_decision rows
             "closer"  — today's hot_lead_closer_decision rows
             "skips"   — recent reply skips (hard gates, cap, dedup, agent skip)
             "jobs"    — pending scheduler jobs and recent gated-job refusals
+            "commons" — digest, beats, live notes, coordinator hold, stale liveness
         campaign_id: Optional campaign filter (full id or prefix).
         outreach_id: Optional outreach filter (full id or prefix).
         limit: Max rows per slice, 1-100 (default 20).