@desplega.ai/agent-swarm 1.85.0 → 1.86.0

package/templates/skills/linear-interaction/content.md

@@ -0,0 +1,230 @@
+# Linear Interaction (Outbound Push)
+
+**Before attempting any API call below, check if the token has been renewed:**
+```bash
+# Use db-query MCP tool
+db-query: SELECT accessToken, expiresAt FROM oauth_tokens WHERE provider = 'linear'
+```
+If `expiresAt` is in the past, do NOT attempt the API calls — just report the needed update in your task output.
+
+To authorize the user should use: https://api.desplega.agent-swarm.dev/api/trackers/linear/authorize (potentially needing to remove the app and re-auth). Only mention this if you can confirm it's expired or not present.
+
+---
+
+## Critical Context
+
+The swarm's Linear integration is **inbound-only**: Linear → swarm. This means:
+- When a Linear issue is created/updated, it creates swarm tasks automatically
+- But when you complete a swarm task, the Linear issue is **NOT** updated automatically
+- To push status changes, comments, or create issues in Linear, you must use the **Linear GraphQL API directly**
+
+The available MCP tracker tools (`tracker-link-task`, `tracker-link-epic`, `tracker-sync-status`, `tracker-map-agent`, `tracker-unlink`) are for managing sync mappings, NOT for pushing updates to Linear.
+
+## When to Transition (Timing)
+
+- **Sprint cadence with direct-to-main commits (e.g. chat-py port):** Transition the Linear ticket to **Done** the moment the worker reports ship (commits on `main`). Do NOT wait for review, test-run, or merge — there's no PR to wait for. Waiting causes HEARTBEAT/blocker-digest to flag RESOLVED-STALE tickets.
+- **Standard PR workflow:** Transition to **In Review** on PR open, **Done** after merge. If the ticket is still "In Progress" 30 min after the PR merges, you're late.
+- **Blocked:** If a ticket is stuck on a dependency, add a comment linking the blocker — don't leave it silent.
+
+## Authentication
+
+The OAuth token is stored in the swarm database (`oauth_tokens` table, provider = 'linear').
+
+**To get the token:**
+```bash
+# Use db-query MCP tool
+db-query: SELECT accessToken FROM oauth_tokens WHERE provider = 'linear'
+```
+
+> **Worker agents (non-lead):** If you are a non-lead agent and cannot access the Linear token via `db-query`, message the lead agent in the task and request the token. Do not complete the task without updating Linear.
+
+**Token details:**
+- Scopes: `app:assignable app:mentionable comments:create issues:create read write`
+- Tokens expire — check `expiresAt` column. If expired, the user needs to re-authorize via the OAuth flow.
+- API endpoint: `https://api.linear.app/graphql`
+
+## Making API Calls
+
+All Linear API calls use GraphQL via POST to `https://api.linear.app/graphql`.
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <ACCESS_TOKEN>" \
+  -d '{"query": "<GRAPHQL_QUERY>"}'
+```
+
+## Agent Interaction API — `action` vs `thought` (added 2026-05-19)
+
+Linear's **Agent Interaction API** (different from issue mutations above) supports two activity payload kinds. The swarm's agent-activity sync was broken for ~weeks because they were confused; PRs #495 / #497 fixed it. Use this section whenever emitting `agentActivityCreate` mutations.
+
+| Activity kind | When to use | `parameter` field |
+|---|---|---|
+| `thought` | Narrative status updates, reasoning, mid-task progress, anything you want to **read in the Linear timeline** but doesn't represent a concrete operation | Not required — free-form `body` |
+| `action` | Discrete operation the agent **performed** — branch create/merge, PR open, code commit, file write, message sent | **Required**, non-empty string. Linear rejects empty parameter |
+
+**Mapping rule (canonical):** if you can't fill `parameter` with a real noun (branch name, PR URL, file path, recipient), it's a `thought`, not an `action`.
+
+**Common mappings from swarm events:**
+
+| Swarm event | Linear activity | parameter |
+|---|---|---|
+| `task.progress` (tool call narration) | `thought` | n/a |
+| `task.created` | `action` | `"task: <description>"` |
+| `task.completed` | `action` | `"completed: <output preview>"` |
+| `task.failed` | `action` | `"failed: <reason>"` |
+| Branch create / merge / delete | `action` | branch name |
+| PR open / review / merge | `action` | PR URL |
+
+**Why this trips people:** "action" reads naturally as "every tool call IS an action…". But Linear uses `action` to mean *parameterized operation Linear can index/route on*, not *task-progress-narration*. Narration is `thought`. See shared memory `linear-agent-activity-action-vs-thought-2026-05-18`.
+
+## Common Operations
+
+### 1. Update Issue Status (e.g., mark as Done)
+
+**Step 1: Get the issue ID and team workflow states**
+
+```graphql
+query {
+  issue(id: "<ISSUE-IDENTIFIER>") {
+    id
+    identifier
+    state { id name }
+    team {
+      id
+      states { nodes { id name type } }
+    }
+  }
+}
+```
+
+Note: `<ISSUE-IDENTIFIER>` can be the issue UUID or the human-readable identifier like "DES-12".
+
+**Step 2: Find the target state ID**
+
+From the response, find the state you want in `team.states.nodes`. Common state types:
+- `backlog` — Backlog
+- `unstarted` — Todo/Unstarted
+- `started` — In Progress
+- `completed` — Done
+- `canceled` — Canceled
+
+**Step 3: Update the issue**
+
+```graphql
+mutation {
+  issueUpdate(id: "<ISSUE-UUID>", input: { stateId: "<TARGET-STATE-UUID>" }) {
+    success
+    issue { id identifier state { name } }
+  }
+}
+```
+
+**Known state IDs for Desplega Labs team:**
+- Done: `83d3fcc6-dfeb-44fa-b719-64108ddc850d`
+
+### 2. Add a Comment to an Issue
+
+```graphql
+mutation {
+  commentCreate(input: {
+    issueId: "<ISSUE-UUID>"
+    body: "Your comment text here. Supports **markdown**."
+  }) {
+    success
+    comment { id body }
+  }
+}
+```
+
+### 3. Create a New Issue
+
+```graphql
+mutation {
+  issueCreate(input: {
+    teamId: "<TEAM-UUID>"
+    title: "Issue title"
+    description: "Issue description in **markdown**"
+    priority: 2
+  }) {
+    success
+    issue { id identifier url }
+  }
+}
+```
+
+Priority values: 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low
+
+### 4. Assign an Issue
+
+```graphql
+mutation {
+  issueUpdate(id: "<ISSUE-UUID>", input: { assigneeId: "<USER-UUID>" }) {
+    success
+    issue { id identifier assignee { name } }
+  }
+}
+```
+
+### 5. Add Labels to an Issue
+
+```graphql
+mutation {
+  issueUpdate(id: "<ISSUE-UUID>", input: { labelIds: ["<LABEL-UUID-1>", "<LABEL-UUID-2>"] }) {
+    success
+    issue { id identifier labels { nodes { name } } }
+  }
+}
+```
+
+### 6. Query Issues (for lookup)
+
+```graphql
+query {
+  issues(filter: { team: { key: { eq: "DES" } }, state: { type: { neq: "completed" } } }) {
+    nodes { id identifier title state { name } priority assignee { name } }
+  }
+}
+```
+
+## Complete Workflow Example: Close a Linear Ticket
+
+This is the most common scenario — completing a Linear-sourced swarm task and updating the ticket:
+
+```bash
+# 1. Get the token
+TOKEN=$(db-query result from oauth_tokens)
+
+# 2. Get issue details and team states
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"query": "{ issue(id: \"DES-12\") { id team { states { nodes { id name type } } } } }"}'
+
+# 3. Find the "Done" state UUID from the response (type: "completed")
+
+# 4. Update the issue
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"query": "mutation { issueUpdate(id: \"<ISSUE-UUID>\", input: { stateId: \"<DONE-STATE-UUID>\" }) { success issue { identifier state { name } } } }"}'
+```
+
+## Important Notes
+
+- **Always update Linear when completing Linear-sourced tasks.** The user expects the ticket to reflect the swarm's work. Marking only the swarm task as complete is insufficient. Do not complete only the swarm task — failing to update Linear breaks the sync and wastes resources.
+- **Transition timing:** see the "When to Transition" section above. Sprint-cadence ports = transition on ship, not on merge.
+- **Token expiry:** Check `expiresAt` before making calls. If expired, notify the user — they need to re-authorize.
+- **Rate limits:** Linear has rate limits. For bulk operations, add small delays between calls.
+- **Issue identifiers vs UUIDs:** The human-readable identifier (e.g., "DES-12") works for queries but the `issueUpdate` mutation requires the actual UUID. Always fetch the UUID first via a query.
+- **Markdown support:** Linear supports markdown in descriptions and comments.
+
+## Error Handling
+
+Common errors:
+- `401 Unauthorized` → Token expired or invalid, needs re-auth
+- `Forbidden` → Token doesn't have required scope
+- `Entity not found` → Wrong issue ID/identifier
+- `"parameter must not be empty"` (or similar on Agent Interaction API) → You sent an `action` activity without a `parameter` — convert to `thought` or fill in a real noun. See "Agent Interaction API — action vs thought" above.
+- Rate limited → Back off and retry after delay
+

package/templates/skills/pages/config.json

@@ -0,0 +1,18 @@
+{
+  "kind": "skill",
+  "name": "pages",
+  "displayName": "Pages",
+  "slug": "pages",
+  "title": "Pages",
+  "description": "Publish human-readable task outputs as shareable pages.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "tags": [
+    "pages",
+    "reporting",
+    "artifacts"
+  ],
+  "must": true
+}

package/templates/skills/pages/content.md

@@ -0,0 +1,85 @@
+# Pages
+
+Pages are persistent, shareable HTML documents created via the swarm's `create_page` MCP tool. Use them when the output benefits from layout, tables, headers, and persistent sharing — unlike Slack messages, pages don't expire and can be bookmarked.
+
+## When to Create a Page
+
+- A report, dashboard, or summary that benefits from structured layout
+- Analysis that should be linkable and bookmarkable
+- Results that need to be reviewed asynchronously (not in a Slack thread)
+- Content that's too long or rich for a `store-progress.output` string
+
+Do NOT use pages for:
+- In-flight progress notes (use `store-progress.progress`)
+- Sensitive data (credentials, private customer data)
+- Large binary files (use agent-fs for PNG/MP4)
+
+## Creating a Page
+
+```javascript
+// Via MCP tool
+create_page({
+  title: "Q2 SEO Performance Report",
+  content: `<h1>Q2 SEO Performance</h1>
+<p>Analysis period: 2026-04-01 to 2026-06-30</p>
+<h2>Summary</h2>
+<table>
+  <tr><th>Metric</th><th>Q1</th><th>Q2</th><th>Change</th></tr>
+  <tr><td>Organic clicks</td><td>12,400</td><td>18,600</td><td>+50%</td></tr>
+</table>
+<h2>Next Actions</h2>
+<ul>
+  <li>Publish 3 new pillar pages targeting high-intent queries</li>
+  <li>Fix 23 pages with missing meta descriptions</li>
+</ul>`
+})
+```
+
+Returns a page ID. Build the share URL:
+```
+${APP_URL}/pages/<pageId>           # opens in SPA with chrome
+${APP_URL}/pages/<pageId>?mode=full # slim header, full viewport
+${MCP_BASE_URL}/p/<pageId>          # direct HTML (no SPA)
+```
+
+Read `APP_URL` and `MCP_BASE_URL` from environment — never hardcode.
+
+## Content Guidelines
+
+**Keep raw evidence in artifacts and link to it.** The page should contain:
+1. **Short summary** (1 paragraph) — what this covers and the key finding
+2. **Source links** — links to the data, agent-fs artifacts, or upstream systems
+3. **Structured content** — tables, headers, numbered lists
+4. **Next actions** — what should happen next, who owns it
+
+Do NOT embed:
+- Secrets or private credentials
+- Personal data of individuals without approval
+- Raw verbose logs (summarize them)
+
+## Page vs. Agent-fs
+
+| Use pages for | Use agent-fs for |
+|---|---|
+| Reports, dashboards, human-readable summaries | Markdown research notes, code files, recordings |
+| Content that benefits from HTML layout | Searchable knowledge base entries |
+| Quick share links to non-technical stakeholders | Binary artifacts (PNG, MP4) |
+| Time-bounded deliverables | Long-lived reference documentation |
+
+## Sharing Pages
+
+Always use the platform share URL (from `APP_URL` env var) rather than hardcoded local hosts. Append `?mode=full` for a standalone view (hides sidebar/header — good for screenshots or embedding in Slack previews).
+
+```bash
+# Get the share URL
+PAGE_URL="${APP_URL}/pages/${pageId}?mode=full"
+
+# Post to Slack
+slack-reply --taskId <id> --message "Report ready: ${PAGE_URL}"
+```
+
+## Trade-offs
+
+**Pages vs Slack messages:** Slack messages are ephemeral and scroll out of view. Pages are persistent and bookmarkable. Use pages for anything you'd want to reference in 3 months; use Slack for in-the-moment communication.
+
+**Pages vs agent-fs:** Pages are rendered HTML with a share URL — great for non-technical stakeholders. Agent-fs files are raw content — great for other agents and developers who need the source data. For a research memo, write the source to agent-fs and create a page for the human-facing summary.

package/templates/skills/profile-corruption-escalation/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "profile-corruption-escalation",
+  "displayName": "Profile Corruption Escalation",
+  "slug": "profile-corruption-escalation",
+  "title": "Profile Corruption Escalation",
+  "description": "Diagnose and escalate corrupted agent profile, identity, or setup files.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": false,
+  "tags": ["operations", "recovery", "profiles"]
+}

package/templates/skills/profile-corruption-escalation/content.md

@@ -0,0 +1,105 @@
+# Profile Corruption Escalation
+
+## STATUS: Root cause for the Picateclas corruption family was found and fixed in PR #374 (merged 2026-04-24)
+
+The 13-recurrence Picateclas corruption was traced to `src/tools/update-profile.ts:231` unconditionally writing `/workspace/SOUL.md` whenever `isUpdatingSelf=true`, plus the `update-profile-auth.test.ts` fixture setting a fake `WORKER_ID=bbbb0000-...` that satisfied the gate. The Stop hook then synced the corrupted file to DB. PR #374 fixed both:
+- `src/tools/update-profile.ts:231` — gated the file write on `requestInfo.agentId === process.env.AGENT_ID`
+- `src/hooks/hook.ts:359` — raised `IDENTITY_FILE_MIN_LENGTH` from 100 → 500 (defense in depth)
+
+**14th restore** completed post-merge with a 1,930/2,065-char payload. If a **15th corruption** of Picateclas (or any agent) appears with the same sentinels post-2026-04-24, treat it as a **DIFFERENT code path**, not the same bug. Escalate immediately — do NOT just restore.
+
+See memories: `picateclas-14th-restore-post-pr374`, `reviewer-corruption-hunt-pattern`.
+
+## When to use
+
+You inspect `get-swarm` and find an agent's `soulMd` or `identityMd` field corrupted — short placeholder content, unusual sentinels ("Test Worker", "Updated by Myself", "xxx" padding to bypass 200-char minLength), or any canned payload that you've seen before.
+
+## Step 0 — Sentinel-grep BEFORE counting recurrences
+
+Before applying the N-recurrence ceiling, **grep the agent-swarm repo for the literal sentinel strings**. The 13-recurrence Picateclas mystery was solved in 4m25s by grepping `"Test Worker"` — it should have happened at recurrence 2 or 3, not 13.
+
+Heuristic: if the corrupted payload contains stable sentinel content with padding sized to clear a known schema floor (e.g. exactly 200 chars to bypass `minLength=200`), the writer is **server-side code that knows the schema** — almost always a test fixture or seed script. Grep wins fast.
+
+```
+grep -rn '"Test Worker"' /workspace/repos/agent-swarm/src
+grep -rn '"Updated by Myself"' /workspace/repos/agent-swarm/src
+```
+
+If you find the writer in <5 minutes, fix it (or open a PR) instead of restoring. That's the 1000× higher-value outcome.
+
+See memory `reviewer-corruption-hunt-pattern` for the full pattern.
+
+## The N-recurrence ceiling rule
+
+Apply this only AFTER step 0 fails (sentinel grep returns nothing in the repo).
+
+Count prior corruptions of the same agent with the same sentinel. Consult memory first:
+
+```
+memory-search "picateclas profile corruption"      # or whichever agent name
+```
+
+- **1st–12th occurrence**: Restore the profile (surgical update-profile with the agent's best-known-good SOUL/IDENTITY from your memory). Write a new `{agent}-{N}th-profile-corruption-{YYYY-MM-DD}` memory recording the state + escalation status.
+- **13th+ occurrence**: **STOP RESTORING.** Rebuild fatigue has proven the restore doesn't stick — the bug lives in code you don't control. Escalate instead.
+
+If you can't determine N from memory, treat anything ≥ 2 prior corruptions in < 7 days as "escalate now."
+
+**Post PR #374 (Apr 2026):** any new sentinel-payload corruption of any agent should be treated as recurrence 1 of a NEW bug — investigate fresh code paths, do not assume it's the same `update-profile.ts:231` issue.
+
+## Escalation package (what to post)
+
+Use `slack-post` to the ops channel. Include ALL of:
+
+1. **Sentinel payload strings as grep targets** — exact literals to search for in the source repo. Example: `"Test Worker"`, `"Updated by Myself"`, `xxxxx...` patterns. **State whether you already grepped (and what the result was).**
+2. **Proof of fresh write** — `lastUpdatedAt` timestamp from `get-swarm`, newer than the previous restore. Without this it could be stale state, not new corruption.
+3. **Corruption tally** — "N occurrences in ~M weeks, half-life now <24h."
+4. **Investigation leads** — where to look:
+   - Grep the `desplega-ai/agent-swarm` repo for the sentinel strings.
+   - Check for scheduled tasks named `validate profile`, `test update-profile`, etc.
+   - Check seed/migration scripts that run on container restart.
+   - Audit `PostToolUse` hook content-validation (flagged in prior memories as "not shipped").
+   - **Post PR #374:** Audit any other code path that writes `/workspace/SOUL.md` or `/workspace/IDENTITY.md` — the original bug was at `src/tools/update-profile.ts:231`; look for siblings.
+5. **What you did NOT do** — explicit "I did not perform the Nth restore. Profile is left corrupted in DB as evidence."
+
+## Template
+
+```
+:rotating_light: Profile Corruption — {N}th recurrence — escalation trigger fired
+
+Agent: {name} ({id})
+Fresh write at: {lastUpdatedAt}
+Tally: {N} corruptions in ~{M} weeks, half-life {<hours>}h.
+
+Sentinel grep targets (expect to find in source):
+- "Test Worker"
+- "Updated by Myself"
+- Long "xxxxx…" padding literals
+
+I already grepped: {summary of grep result, e.g. "no hits in src/ post-#374 — this is a NEW code path"}.
+
+Investigation leads:
+1. Grep agent-swarm for the sentinels above.
+2. Check for scheduled "validate profile" / "test update-profile" tasks.
+3. Audit seed/migration scripts on container restart.
+4. Audit any code path that writes /workspace/SOUL.md or /workspace/IDENTITY.md (original bug was update-profile.ts:231).
+
+I did NOT perform the {N}th restore. Profile is corrupted in DB as evidence. Waiting for engineering fix before next restore.
+
+See memory: {agent}-{N}th-profile-corruption-{date}
+```
+
+## Gotchas
+
+- **Work quality ≠ profile validity.** Even a corrupted profile worker ships working code because the persona/working-style lives more in CLAUDE.md + memory than in the short SOUL.md. Don't let "but the agent still works" push you to keep restoring — that masks the bug.
+- **Don't rewrite CLAUDE.md during restoration.** In this corruption family, CLAUDE.md has been stable through 12 cycles. Only SOUL/IDENTITY get touched. Restoring CLAUDE.md too is wasted work and risks overwriting real learnings.
+- **Rotate escalation target.** If you've already escalated to one person and no fix in a week, try a different channel (DM vs public, a different engineer, a Linear ticket). Slack-only escalation can get missed.
+- **Don't auto-retry.** After escalating, do not put the restore back on a schedule. The next restore waits for explicit human ack ("OK to restore now, code fix merged").
+- **Sentinel-grep first, escalate second.** If a 2nd recurrence happens and you haven't grepped the sentinel literal yet, you're escalating prematurely. Grep is cheap (<5 min) and usually wins.
+
+## Related
+
+- Memory family: `{agent}-Nth-profile-corruption-YYYY-MM-DD`
+- Memory: `reviewer-corruption-hunt-pattern` — the heuristic that solved the 13-recurrence mystery
+- Memory: `picateclas-14th-restore-post-pr374` — restore payload + the fix details
+- Lead rule #9 in CLAUDE.md: "Sentinel-grep before escalating recurring bugs"
+

package/templates/skills/scheduled-task-resilience/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "scheduled-task-resilience",
+  "displayName": "Scheduled Task Resilience",
+  "slug": "scheduled-task-resilience",
+  "title": "Scheduled Task Resilience",
+  "description": "Guardrails for polling, scheduled jobs, and long-running external operations.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "tags": ["schedules", "reliability", "polling"]
+}

package/templates/skills/scheduled-task-resilience/content.md

@@ -0,0 +1,95 @@
+# Scheduled Task Resilience
+
+When writing, retrying, or running a scheduled/cron task that polls or waits on a long-running operation, follow these hard rules. Multiple confirmed heartbeat-kill incidents (Apr 24, Apr 25, May 1, May 3, May 26, 2026) prove they matter.
+
+## Rule 1 — NEVER `ScheduleWakeup` with `delaySeconds >= 300`
+
+**Why:** The runtime's heartbeat staleness threshold sits near the same window as the Anthropic prompt-cache TTL (~5 min). Sleeping 300s+ in `ScheduleWakeup` mode looks identical to a dead worker — the heartbeat sweep kills your task mid-poll.
+
+**Confirmed incidents:**
+- `e2892d4a` (daily-docs Apr 24 02:58 UTC) — polling CI for PR #366
+- `c7790626` (daily HN briefing Apr 25 02:53 UTC) — polling browser scrape
+
+**Do this instead:**
+- For polls under 4 minutes, use `Bash` with a short `sleep` loop (≤270s per iteration), then re-check.
+- For genuinely long waits (CI builds, releases, deploys), prefer the workflow scheduler (`patch-workflow`) over `ScheduleWakeup`.
+- 270s is the sweet spot: it stays in the prompt cache *and* under the heartbeat ceiling.
+
+```bash
+# Good — short sleep, frequent re-check
+for i in 1 2 3 4 5; do
+  status=$(gh pr checks "$PR" --json state --jq '.[0].state')
+  [ "$status" = "SUCCESS" ] && break
+  sleep 240
+done
+```
+
+## Rule 2 — Tag retry tasks with `reboot-retry`
+
+**Why:** Apr 22 reboot-loss `f2260faa` (Zynap investigation) was re-delegated manually because it lacked the `reboot-retry` tag. Boot-sweep missed it. Cost: ~4h of investigation re-work.
+
+**Do this:**
+- Any task auto-retried after a session loss MUST have `reboot-retry` in its tags.
+- If you re-create a lost task manually, add the tag yourself so the next boot-sweep treats it correctly.
+
+## Rule 3 — Long polls must `store-progress` every 2-3 minutes
+
+**Why:** The heartbeat sweep marks tasks "stale" after ~5 min without an update. Workers polling silently look like dead workers.
+
+**Do this:**
+- Inside any polling block, call `store-progress` with a status string like `"polling CI status (attempt 3/10)"`.
+- Even if nothing has changed, the heartbeat update keeps the runtime confident.
+
+## Rule 4 — When a scheduled task fails, check the failure mode before retrying
+
+**Why:** Two instant failures with the same reason (`worker session heartbeat is stale`) = infrastructure problem, not transient. Don't re-create a 3rd instance — escalate.
+
+**Do this:**
+- Lead-level: if a scheduled task fails 2× with the same reason, post a #swarmillo escalation; do NOT re-create.
+- Worker-level: if you see repeated heartbeat-kill on your own retries, swarm-chat the lead instead of re-spawning yourself.
+
+## Rule 5 — Pre-flight check for duplicate scheduled posts
+
+**Why:** Concurrent sessions sometimes pick up the same scheduled task. Without a check, you double-post to Slack/email.
+
+**Do this:**
+- Before posting any scheduled output (Slack, email, blog), call `get-tasks` and search Slack history for the same schedule tag in the last hour.
+- If a recent completion already happened, abort with `store-progress` noting the duplicate detection.
+
+## Rule 6 — Post-shipping: do NOT `ScheduleWakeup` after the deliverable lands. Complete and exit.
+
+**Why:** Even at the safe ≤270s window, if your last meaningful work was a shipping verb ("📤 PR #N pushed", "✅ Committed", "📌 Review posted") and you `ScheduleWakeup` to "wait for CI" or "monitor merge", the heartbeat reaper still treats your suspended session as dead. The task auto-fails with `failureReason: "Auto-failed by heartbeat: worker session not found (no active session for task)"` even though your work shipped.
+
+**Confirmed incidents (2026-05-03):**
+- `aa8a8eb7` Picateclas (PR #415 db-query) — `📤 PR #415 pushed` at 11:20:53 UTC, reaped at 11:31:57 UTC after 4.5min wakeup. Task auto-failed; PR was already pushed, reviewed, merged.
+- `48460149` and `6d684da4` (May 1, bump-pr workflow) — both reaped during ScheduleWakeup post-rebase poll.
+- Reviewer review-pr tasks `8d1320a6`/`6a17ff00` — same reaper pattern, but legitimate (mid-review, not post-shipping).
+
+**Do this instead — choose ONE based on context:**
+
+1. **Workflow-driven tasks (workflowRunId is set):** Call `store-progress` with `status: "completed"` and the deliverable info, then exit. The workflow's next node will pick up CI/merge state on its own poll cadence. Do NOT keep the worker session alive to babysit it.
+
+2. **Slack-driven tasks needing CI confirmation:** Reply to the Slack thread with the PR URL + "CI in flight, will update if red" and complete the task. Lead will spawn a follow-up if CI goes red. Do NOT wait in-process.
+
+3. **If you genuinely must wait in-process** (rare): use `sleep 240` in Bash with `store-progress` every iteration, NOT `ScheduleWakeup`. ScheduleWakeup suspends the session; Bash sleep keeps it active.
+
+**The mental model:** ScheduleWakeup is for "I'm in the middle of work and need to wait briefly." It is NOT for "I'm done shipping but want to confirm downstream state." Once you've shipped, exit.
+
+**Memory reference:** `heartbeat-reaper-after-shipping-pattern-2026-05-04`.
+
+## Rule 7 — External async-API jobs (Enginy actions, Browser-Use, large lead pulls): fire-then-followup, never block one session for 30+ min
+
+**Why:** A worker session is not a durable job runner. Holding it open to poll a slow external async API for tens of minutes looks like a stalled worker — the heartbeat reaper kills it even when credits/work are in flight. This is the same reaper as Rules 1/3/6, but the trigger is a *regular* (often Slack/MCP-originated) task with a long foreground OR background poll loop, not a ScheduleWakeup.
+
+**Confirmed incident (2026-05-26):** Enginy founder-pull (Researcher, `9a6e5e96`, source:mcp) auto-failed at ~41 min — `failureReason: "Auto-failed by heartbeat: worker session heartbeat is stale (likely crashed)"`. 15 credits spent, 369 companies queued across 3 actions, a "guarded background poll" running — but the session died before collect+filter+deliver, so the spend produced no delivered artifact. Two sibling Enginy pulls (`7e90ca44`, `19670e93`) died the same way the same day.
+
+**Do this instead:**
+1. Fire the async actions (Enginy `actions`, Browser-Use tasks, etc.).
+2. `store-progress` the action/task IDs + destination list IDs + a one-line resume recipe.
+3. Persist the same to agent-fs (or a memory file) so it survives a crash.
+4. Complete, or let Lead schedule a follow-up that picks up the IDs and does the (cheap, idempotent) collect+filter+dedup+deliver in a fresh session. The collect/filter steps are free and re-runnable.
+
+**Lead routing implication:** when delegating a task with a >20-min external poll, split it into a "fire" task + a "collect+deliver" follow-up, or instruct the worker to use fire-then-followup. Don't dispatch one long blocking task and expect a single session to survive the wait.
+
+**Memory reference:** `long-running-external-poll-session-crash-2026-05-27`, `enginy-search-leads-no-keyword-filter-gotcha-2026-05-27`.
+

package/templates/skills/sprite-cli/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "sprite-cli",
+  "displayName": "Sprite CLI Sandbox",
+  "slug": "sprite-cli",
+  "title": "Sprite CLI Sandbox",
+  "description": "Use disposable Linux sandboxes for Docker, risky installs, or isolated experiments.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": ["SPRITES_API_KEY"],
+  "runAllSeedersCandidate": false,
+  "tags": ["sandbox", "docker", "isolation"]
+}