Skip to content
Back to search

sno-ai

SkillWorks with CodexGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 14 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sno-ai/sno-station-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sno-ai/sno-station-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sno-ai--sno-station-skills/badge.svg)](/listings/sno-ai--sno-station-skills)

HTML

<a href="/listings/sno-ai--sno-station-skills"><img src="/api/listings/sno-ai--sno-station-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

All skills with Sno Station

Copy this prompt into your agent's chat:

Install sno.ai from GitHub.

This installs Sno Station and sets up all 39 skills, plus the programs they call, for the supported agents it finds on your machine.

Or paste this command into your terminal:

curl -fsSL https://sno.ai/install | sh

**Already have Sno Station?** Run `sno setup` to install the skills into your agents. Run it again if you add another agent later.

Install one skill

Use the copy button on either prompt below, then paste it into your agent's chat. Your agent finds and installs the skill; you do not need to download or copy files yourself.

**`peer-review`** checks code, plans and documents with a reviewer from another model vendor. It needs Sno Station programs and a logged-in reviewer. The prompt checks those dependencies first.

Install only the peer-review skill from https://github.com/sno-ai/sno-station-skills
for this project, including its scripts and references.
Check its dependencies and tell me what is missing before installing anything else.

**`less-is-more`** helps your agent write less code and remove unnecessary complexity. It can run without Sno Station.

Install only the less-is-more skill from https://github.com/sno-ai/sno-station-skills
for this project, including its scripts and references.

**`tag-team`** puts two agents on one task: one builds, the other reviews, and they settle the findings between themselves. It needs Sno Station's Reach program. The prompt checks for it first.

Install only the tag-team skill from https://github.com/sno-ai/sno-station-skills
for this project. Check that `sno reach pair --help` works and tell me what is missing
before installing anything else.

Supported agents for Sno Station: Claude Code, Codex, OpenClaw and Hermes Agent. Each skill declares what it needs from the agent. Setup uses that declaration to install it fully, install it in a reduced form, or skip it when the agent cannot run it.

Updates come by themselves: `sno` updates itself when it finds a newer release. The full command list is in [Sno Station's command reference](https://github.com/sno-ai/sno-station/blob/main/docs/sno-commands.md).

Install as a plugin

Claude Code:

claude plugin marketplace add sno-ai/sno-station-skills
claude plugin install sno-station@sno-ai

Codex:

codex plugin marketplace add sno-ai/sno-station-skills
codex plugin add sno-station@sno-ai

`sno-station` holds all 39 skills; most of them call Sno Station programs, so install Sno Station too. For only the 7 skills that run without Sno Station, install `sno-station-standalone@sno-ai` instead.

[Install](#install) · [What changes for you](#what-changes-for-you) · [Why these skills](#why-these-skills) · [The pain, and what fixes it](#the-pain-and-what-fixes-it) · [Stories from our own machine](#i-went-to-bed-it-changed-shifts) · [The skills](#the-skills) · [Built to be trusted](#built-to-be-trusted) · [For skill authors](#for-skill-authors) · [License](#license)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 78 lines
  1. {
  2. "name": "sno-ai",
  3. "owner": {
  4. "name": "Sno Station Skills contributors"
  5. },
  6. "metadata": {
  7. "description": "Sno Station skills for coding agents."
  8. },
  9. "strict": false,
  10. "plugins": [
  11. {
  12. "name": "sno-station",
  13. "description": "Every Sno Station skill. Most need the Sno Station programs that `sno setup` installs.",
  14. "source": "./",
  15. "strict": false,
  16. "skills": [
  17. "./skills/H-reporting-and-visibility/agentic-time-estimate/skill",
  18. "./skills/H-reporting-and-visibility/away-brief/skill",
  19. "./skills/H-reporting-and-visibility/catch-report/skill",
  20. "./skills/J-peer-review-and-audit/agentic-walkthrough/skill",
  21. "./skills/J-peer-review-and-audit/cross-vendor-security-audit/skill",
  22. "./skills/J-peer-review-and-audit/e2e/skills/e2e-environment-preflight",
  23. "./skills/J-peer-review-and-audit/e2e/skills/e2e-red-triage",
  24. "./skills/J-peer-review-and-audit/first-principles-review/skill",
  25. "./skills/J-peer-review-and-audit/less-is-more/skill",
  26. "./skills/J-peer-review-and-audit/owner-intent-audit/skill",
  27. "./skills/J-peer-review-and-audit/peer-review/skill",
  28. "./skills/J-peer-review-and-audit/test-writer/skill",
  29. "./skills/M-build-and-rollout/codex-coder/overlay/claude",
  30. "./skills/M-build-and-rollout/medic/skill",
  31. "./skills/M-build-and-rollout/python-coder/skill",
  32. "./skills/M-build-and-rollout/rust-coder/skill",
  33. "./skills/M-build-and-rollout/shellscript-coder/skill",
  34. "./skills/M-build-and-rollout/sno-cli/skill",
  35. "./skills/M-build-and-rollout/ts-coder/skill",
  36. "./skills/R-recursive-self-improvement/rem-reflect/skill",
  37. "./skills/S-communication-and-handoff/handoff/skill",
  38. "./skills/S-communication-and-handoff/heartbeat/skill",
  39. "./skills/S-communication-and-handoff/join-talk/skill",
  40. "./skills/S-communication-and-handoff/reach/skill",
  41. "./skills/S-communication-and-handoff/rotate-agent/skill",
  42. "./skills/S-communication-and-handoff/subscription-quota-check/skill",
  43. "./skills/S-communication-and-handoff/tag-team/skill",
  44. "./skills/T-delegation-and-work-orders/charter/skill",
  45. "./skills/T-delegation-and-work-orders/cos/skills/cos",
  46. "./skills/T-delegation-and-work-orders/cos/skills/cos-evolve",
  47. "./skills/T-delegation-and-work-orders/cos/skills/cos-review",
  48. "./skills/T-delegation-and-work-orders/cos/skills/cos-watch",
  49. "./skills/T-delegation-and-work-orders/deliver/skill",
  50. "./skills/T-delegation-and-work-orders/pl/skills/pl",
  51. "./skills/T-delegation-and-work-orders/pl/skills/pl-analyze",
  52. "./skills/T-delegation-and-work-orders/pl/skills/pl-audit",
  53. "./skills/T-delegation-and-work-orders/pl/skills/pl-dispatch",
  54. "./skills/T-delegation-and-work-orders/pl/skills/pl-env",
  55. "./skills/T-delegation-and-work-orders/pl/skills/pl-watch"
  56. ]
  57. },
  58. {
  59. "name": "sno-station-standalone",
  60. "description": "Sno Station skills that run without Sno Station programs and without hooks.",
  61. "source": "./plugins/sno-station-standalone",
  62. "skills": [
  63. "./skills/agentic-walkthrough",
  64. "./skills/e2e-environment-preflight",
  65. "./skills/e2e-red-triage",
  66. "./skills/first-principles-review",
  67. "./skills/less-is-more",
  68. "./skills/owner-intent-audit",
  69. "./skills/charter",
  70. "./skills/shellscript-coder",
  71. "./skills/ts-coder",
  72. "./skills/python-coder",
  73. "./skills/rust-coder",
  74. "./skills/test-writer"
  75. ]
  76. }
  77. ]
  78. }
README.md · README · 656 lines · 1 finding marked
  1. # Sno Station Skills — The working habits of a real team, installed into your AI agents.
  2. ![Sno Station — Agents, assemble. Two heads are better than one, and smarter by morning.](https://raw.githubusercontent.com/sno-ai/sno-station/main/docs/images/hero-banner.png)
  3. [![license Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-97ca00.svg?labelColor=3b3b3b)](LICENSE)
  4. ![39 skills in 30 units](https://img.shields.io/badge/skills-39%20in%2030%20units-2dd4bf.svg?labelColor=3b3b3b)
  5. ![self-tested before every release](https://img.shields.io/badge/every%20release-self--tested-3b82f6.svg?labelColor=3b3b3b)
  6. ![agents Claude Code, Codex](https://img.shields.io/badge/agents-Claude%20Code%20%C2%B7%20Codex-f0a04b.svg?labelColor=3b3b3b)
  7. Find out more on our website, [sno.ai](https://sno.ai).
  8. ## Install
  9. ### All skills with Sno Station
  10. Copy this prompt into your agent's chat:
  11. ```text
  12. Install sno.ai from GitHub.
  13. ```
  14. This installs Sno Station and sets up all 39 skills, plus the programs they call,
  15. for the supported agents it finds on your machine.
  16. Or paste this command into your terminal:
  17. ```bash
  18. curl -fsSL https://sno.ai/install | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 28 on GitHub
  19. ```
  20. **Already have Sno Station?** Run `sno setup` to install the skills into your agents.
  21. Run it again if you add another agent later.
  22. ### Install one skill
  23. Use the copy button on either prompt below, then paste it into your agent's chat.
  24. Your agent finds and installs the skill; you do not need to download or copy files yourself.
  25. **`peer-review`** checks code, plans and documents with a reviewer from another model vendor.
  26. It needs Sno Station programs and a logged-in reviewer. The prompt checks those dependencies first.
  27. ```text
  28. Install only the peer-review skill from https://github.com/sno-ai/sno-station-skills
  29. for this project, including its scripts and references.
  30. Check its dependencies and tell me what is missing before installing anything else.
  31. ```
  32. **`less-is-more`** helps your agent write less code and remove unnecessary complexity.
  33. It can run without Sno Station.
  34. ```text
  35. Install only the less-is-more skill from https://github.com/sno-ai/sno-station-skills
  36. for this project, including its scripts and references.
  37. ```
  38. **`tag-team`** puts two agents on one task: one builds, the other reviews, and they settle the
  39. findings between themselves. It needs Sno Station's Reach program. The prompt checks for it first.
  40. ```text
  41. Install only the tag-team skill from https://github.com/sno-ai/sno-station-skills
  42. for this project. Check that `sno reach pair --help` works and tell me what is missing
  43. before installing anything else.
  44. ```
  45. Supported agents for Sno Station: Claude Code, Codex, OpenClaw and Hermes Agent. Each skill declares
  46. what it needs from the agent. Setup uses that declaration to install it fully, install it in a reduced
  47. form, or skip it when the agent cannot run it.
  48. Updates come by themselves: `sno` updates itself when it finds a newer release. The full
  49. command list is in [Sno Station's command reference](https://github.com/sno-ai/sno-station/blob/main/docs/sno-commands.md).
  50. ### Install as a plugin
  51. Claude Code:
  52. ```bash
  53. claude plugin marketplace add sno-ai/sno-station-skills
  54. claude plugin install sno-station@sno-ai
  55. ```
  56. Codex:
  57. ```bash
  58. codex plugin marketplace add sno-ai/sno-station-skills
  59. codex plugin add sno-station@sno-ai
  60. ```
  61. `sno-station` holds all 39 skills; most of them call Sno Station programs, so install Sno Station too.
  62. For only the 7 skills that run without Sno Station, install `sno-station-standalone@sno-ai` instead.
  63. [Install](#install) · [What changes for you](#what-changes-for-you) · [Why these skills](#why-these-skills) · [The pain, and what fixes it](#the-pain-and-what-fixes-it) · [Stories from our own machine](#i-went-to-bed-it-changed-shifts) · [The skills](#the-skills) · [Built to be trusted](#built-to-be-trusted) · [For skill authors](#for-skill-authors) · [License](#license)
  64. ## What changes for you
  65. You keep working exactly as before, in whichever agent you like. Then:
  66. 1. **You finish a change and want it checked.** Say "peer-review this". A reviewer from the other
  67. vendor reads it cold, reports what would break in real use, and the author fixes the root
  68. cause, round after round, until the review comes back clean.
  69. 2. **You start a long run before bed.** Say "arm rotate-agent". If the working agent's quota
  70. drops to the threshold overnight, it hands the task to a fresh agent from the other vendor,
  71. with the brief verified before a single file is touched.
  72. 3. **You come back.** Say "away brief". One page, at most 60 lines: what got done, what is
  73. stuck and why, what waits for your answer, and what it cost in quota.
  74. 4. **You have a job for someone else.** Say "write a charter". You get one file that says what
  75. to deliver, what is out of bounds, what you already decided, and how each success check will
  76. be proven. Any agent can then `deliver` it, and every check is proven by a recorded real run.
  77. 5. **Every night, the team looks back.** The nightly loop reads the day's Claude Code and Codex
  78. sessions, finds the mistakes that repeat, and proposes lessons and skill changes. In the
  79. morning you accept the ones you like with `sno rem-reflect accept <id>`. Nothing changes
  80. without that accept.
  81. ## Why these skills
  82. One AI agent is a brilliant new hire with no colleagues. It reviews its own work, so it misses
  83. what it cannot see. It stops dead when its quota runs out, at 3 a.m., halfway through your
  84. build. It says "done" when the tests are green and nothing actually happened. It builds three
  85. layers of machinery you never asked for. And tomorrow it makes the same mistake it made today,
  86. because nobody told it otherwise.
  87. **Sno Station Skills fixes the team, not the model.** These are the skills
  88. [Sno Station](https://github.com/sno-ai/sno-station) installs into the agents you already
  89. run. They give Claude Code and Codex the habits every good engineering team has: a second pair
  90. of eyes from a different vendor, a clean handover when someone has to leave, a lead who hands
  91. out work with a written definition of done, a one-page brief when you come back, and a
  92. retrospective every night that turns this week's mistakes into next week's rules.
  93. **Dual Brain: different roles, one team.** One agent carries out your task. The other reviews
  94. the result against your requirements. Claude Code and Codex can take either role. When both
  95. CLIs are installed, the review runs in the other vendor's CLI, in a fresh session with none of
  96. the author's conversation. The agents exchange findings and corrections. Add more roles, and
  97. you have an Agent Squad.
  98. **Work that finishes while you sleep.** Arm it before bed, and when the working agent's
  99. subscription runs low it writes a handover brief while it still can, wakes an agent from the
  100. other vendor, and hands the task over with the exact commit to continue from. Your build does not care which vendor finished it.
  101. **"Done" means proven.** Every task can carry a written list of success checks, each one
  102. answered pass or fail by a real run. Nothing counts as done because an agent said so.
  103. **Tested before it ships.** Every skill in a release passed its own self-tests on a clean copy,
  104. was scanned for personal paths and leftovers, and carries a stamp that says so. A skill that
  105. fails is not published.
  106. ![How it works: two agents, one shared workspace, three things you get](https://raw.githubusercontent.com/sno-ai/sno-station/main/docs/images/squad-how-it-works.png)
  107. ## The pain, and what fixes it
  108. *Last updated 2026-10-23.* Every line in the left column is a real complaint from r/ClaudeCode, r/codex or r/ClaudeAI in the week of October 20, 2026. The right column is what runs on our own machines, free and open source, to make it stop.
  109. | What people said this week | What fixes it | Where |
  110. |---|---|---|
  111. | “Ran out of my 5-hour limit within 30 minutes.” | Stop sending the biggest model to do everything. Opus plans and reviews; Codex writes the code, called as an agent from the same session. When one subscription runs dry, the other picks the task up from the same memory. | `codex-coder`, `sno reach call` |
  112. | “Lost 10 hours of overnight work to ‘this model is at capacity’.” | At 2% of its quota the working agent writes a handover brief and wakes the other vendor's agent, which continues from the exact commit. You were asleep. | `rotate-agent` |
  113. | “1,100 files, 30,000 lines. I don't have the token budget to review their PRs.” | Whoever pushes, reviews first: the author runs a review by the other vendor, in a fresh session that never saw the conversation, and fixes what comes back before anyone else looks. | `peer-review` |
  114. | “A reviewer subagent checked every commit for two weeks. 86 runs, it stopped exactly one.” | A harness reviewing itself finds nothing real. The reviewer is always a different model in a different harness, with none of the author's chat. | `peer-review` |
  115. | “Codex never finishes a review.” | Hard caps written into the skill: 3 rounds on code, 5 on a plan, 1 on tests, then it stops and waits for a person. A run that has written nothing for 15 minutes is killed as stalled. | `peer-review`, `codex-coder`, `heartbeat` |
  116. | “Codex treats every byte like a criminal.” | Speculative safeguards, blockers and hashes are the first thing the review deletes. Nothing goes in without an observed failure asking for it. | `less-is-more` |
  117. | “When Claude says it won't change something, is that reason stored anywhere Codex reads next time?” | Every finding is filed once, with a status only a human sets. A finding raised again updates its row instead of coming back as new, and earlier rulings are handed to the next review. | `peer-review` findings ledger |
  118. | “It said done. Nothing happened.” | A task carries a written list of success checks, each answered pass or fail by a real run. An agent saying “done” counts for nothing. | `pl` work orders |
  119. | “Tomorrow it makes the same mistake it made today.” | Every night a separate model reads the day's sessions, turns your corrections into one-line lessons, and you approve what stays. On our own machine: 162 written so far, 7 approved. The bottleneck is us. | Self Learning (`R` skills) |
  120. | “Half my subagents were glorified one-liners with a fresh context window.” | Procedures live in skills, not subagents. Two agents remain, for plan and execution, and for review, because those two splits are the ones that pay. | the whole set |
  121. Each skill in the right column is in this repository, free to copy into your own agents. The memory they share, the quota watch that fires the handover, and the nightly run that writes the lessons live in [Sno Station](https://github.com/sno-ai/sno-station); install that and every skill here comes with it, so you get the whole experience at once.
  122. ## "I went to bed. It changed shifts."
  123. *From Sno Station's own repository, 2026-09-18.*
  124. ![The quota watch reading down to the threshold every five minutes, and the handover firing at 2%](https://raw.githubusercontent.com/sno-ai/sno-station/main/docs/evidence/rotation-quota-watch-2026-09-18.png)
  125. One of our agents was twenty-one tasks into a twenty-seven-task build when its weekly quota
  126. reached 2%. It did not wait to die. It wrote a handover brief: what was done, what was
  127. half-done, the exact commit to continue from. Then it woke an agent from the other vendor and
  128. would not let it touch anything until the brief was verified. Fourteen minutes and forty-one
  129. seconds after the handover began, the second agent was working and the first signed off with
  130. 1% left. The second agent continued from the first unchecked task, not from the beginning.
  131. That night ran on the same four skills that ship here: `subscription-quota-check` read the quota
  132. without spending it, `heartbeat` took a reading every five minutes, `rotate-agent` decided when
  133. and to whom, and `handoff` moved the work. Every quota reading, both versions of the brief and
  134. the commit summary are published in
  135. [Sno Station's evidence folder](https://github.com/sno-ai/sno-station/tree/main/docs/evidence/rotation-2026-09-18).
  136. ## "In months, the other one has never once said 'looks good.'"
  137. Claude Code has reviewed Codex's work, and Codex has reviewed Claude Code's, on Sno Station's
  138. own repository for months. Not one review has come back empty. We used to think that meant the
  139. work was bad. It means one reviewer from one vendor is never enough.
  140. That is what `peer-review` is for, and `catch-report` puts numbers on it: how many problems the
  141. second model caught, next to how many the agents caught in their own work, kept apart and never
  142. added together.
  143. ## "I yelled at my agent last night. It took notes."
  144. ![The nightly loop reporting what it learned and changed, 2026-09-18](https://raw.githubusercontent.com/sno-ai/sno-station/main/docs/evidence/rsi-self-repair-2026-09-18.png)
  145. The nightly loop is the `rem-reflect` skill. On its first night on our machine, the two things
  146. the owner had been frustrated about that evening were rules in the live skills by morning,
  147. after the owner accepted them; nobody typed them in. The next night it fired on its own at
  148. 00:58, read 113 sessions, and measured the three skills it had changed the day before: failures
  149. in all three had dropped to zero.
  150. ![The next morning: the loop measures whether yesterday's own changes helped, 2026-09-19](https://raw.githubusercontent.com/sno-ai/sno-station/main/docs/evidence/rsi-skill-impact-2026-09-19.png)
  151. ## The skills
  152. 39 skills, shipped as 30 units, filed under six things a team has to be able to do. A unit is
  153. one skill or a small family that installs together. The full index with links is
  154. [skills/README.md](skills/README.md).
  155. | | Category | What your agents can do with it |
  156. |---|---|---|
  157. | **J** | [Peer Review & Audit](#j--peer-review--audit) | Check each other's work, and refuse to call anything done until it is proven. |
  158. | **M** | [Build & Rollout](#m--build--rollout) | Get set up on any machine in one step, and tell you in plain lines when something is broken. |
  159. | **S** | [Communication & Handoff](#s--communication--handoff) | Message each other, and take over with full context when one has to stop. |
  160. | **H** | [Reporting & Visibility](#h--reporting--visibility) | Show you what got done, what got caught, and what it cost. |
  161. | **T** | [Delegation & Work Orders](#t--delegation--work-orders) | Hand out work with a written definition of done, and lead other agents. |
  162. | **R** | [Retrospective & Improvement](#r--retrospective--improvement) | Learn from their own mistakes, with you approving every change. |
  163. ### J · Peer Review & Audit
  164. *Colleagues review each other's work, and nothing counts as done until it passes audit.*
  165. #### [peer-review](skills/J-peer-review-and-audit/peer-review/) — a reviewer from the other vendor, and a fix loop until it is clean
  166. - **Truly independent.** The review runs in a fresh session with none of the author's
  167. conversation, and prefers the other vendor's CLI. With only one CLI installed it still runs,
  168. in a fresh session, and says on its first line that it was a same-vendor review.
  169. - **Hunts what actually costs you.** It walks the ordinary path first, with the real inputs your
  170. system produces, before it spends a minute on exotic edge cases. Data loss, silent wrong
  171. results and broken main flows come first; style is not on the list.
  172. - **Every finding has to earn its place.** Each one states how a real user reaches it, what
  173. breaks, and an honest attempt to refute it. Nothing the reviewer says is dropped or softened;
  174. a suspected false positive is labelled, not hidden.
  175. - **Cuts before it adds.** It lists what the change added that nobody needed, first, and keeps
  176. "must fix now" apart from "also found", so a review never turns into a pile of new code.
  177. - **Works on documents too.** Specs, plans and migration manifests get a structured report:
  178. what would make an implementer ship the wrong thing.
  179. *Use it when:* you finished a change, a plan or a spec and want it checked before it lands.
  180. #### [less-is-more](skills/J-peer-review-and-audit/less-is-more/) — the least code that works, and a knife for the rest
  181. - **Climbs a ladder before writing a line:** is it needed at all, is it already in the
  182. repository, does the standard library do it, does the platform do it, does an installed
  183. dependency do it. Only then the minimum code that works.
  184. - **Cuts what an agent over-built:** one-implementation interfaces, config knobs for values that
  185. never change, scaffolding "for later", checks and gates that block the real work.
  186. - **Spends your test budget wisely:** the smallest test that proves the change, not a full suite
  187. run as reassurance.
  188. - **Runs both ways by itself:** "write" or "fix" builds, "review" or "simplify" cuts, and after
  189. building it cuts its own diff before handing it over.
  190. *Use it when:* any coding task, or when you say "too complex" or "what can we delete".
  191. #### [owner-intent-audit](skills/J-peer-review-and-audit/owner-intent-audit/) — is this what you actually meant?
  192. - **Checks meaning, not wording.** A plan can keep all your nouns and still describe a
  193. different product. This catches a condition that became unconditional, an example that
  194. became the whole boundary, a prohibition that quietly disappeared.
  195. - **Finds the debts agents leave behind:** work nobody asked for, documents that no longer match
  196. reality, decisions nobody can reach, and "done" claims with no evidence behind them.
  197. - **Plans and code alike:** requirement documents, designs, task lists, test plans, or a diff an
  198. agent wrote.
  199. *Use it when:* before you approve a plan or merge an agent's work.
  200. #### [agentic-walkthrough](skills/J-peer-review-and-audit/agentic-walkthrough/) — everything says "success", and you still are not sure
  201. - **For the quiet failure no test catches:** a job that starts, finishes, writes a trace, passes
  202. its own checks, and touches nothing.
  203. - **Takes the program's seat:** walks the path hop by hop, finding every switch, default and
  204. fallback that can turn the work into a silent no-op.
  205. - **Makes each hop prove itself** with one narrow observation that only the real thing could
  206. produce: the stored row, the database file actually opened, the API call that actually left.
  207. *Use it when:* a run reports success and you need proof it did the work.
  208. #### [first-principles-review](skills/J-peer-review-and-audit/first-principles-review/) — challenge the idea before it becomes code
  209. - **Researches first,** then re-derives what you actually need without borrowing the proposed
  210. solution.
  211. - **Sorts every constraint** into hard limit, owner preference, or inherited habit, and tests
  212. every load-bearing assumption against evidence.
  213. - **Ends with one clear verdict:** proceed, reframe, simplify, replace, split, test first, or
  214. stop, plus a recommended direction and the evidence that would overturn it.
  215. - **Hands off cleanly:** a written report and a structured summary ready for whoever writes the
  216. requirements next.
  217. *Use it when:* a design or product idea is about to harden into a plan. You start it by name.
  218. #### [e2e](skills/J-peer-review-and-audit/e2e/) — end-to-end runs that fail for real reasons only
  219. - **`e2e-environment-preflight`** checks the external services, hosts, browser sessions, model
  220. endpoints and agents before the first test runs, so a long suite never fails on a dead
  221. dependency.
  222. - **`e2e-red-triage`** handles the rare failure the checks could not predict. It stops the
  223. guessing and splits the result into its two halves (accepted versus done, stopped versus
  224. crashed, empty versus unreadable), then decides: product bug, or a new environment check.
  225. *Use it when:* you run end-to-end suites against real services.
  226. #### [test-writer](skills/J-peer-review-and-audit/test-writer/) — tests that can actually go red
  227. - **Real over mocked:** the real parser, filesystem, database or service whenever the repo can
  228. provide it; a mock never stands in for the thing being tested.
  229. - **Every assertion can fail:** it checks returned content, saved state and real side effects,
  230. not call counts, and never loosens an assertion to make a test pass.
  231. - **Runs what it wrote, nothing more:** the narrowest command for the changed test, not the
  232. whole suite, and the report says what ran and what it showed.
  233. *Use it when:* you ask an agent to write or fix tests, fixtures or evals. It works on its own,
  234. without Sno Station.
  235. #### [cross-vendor-security-audit](skills/J-peer-review-and-audit/cross-vendor-security-audit/) — a security audit that rereads what it threw away
  236. **Three Claude passes missed a published high-severity bug. One Codex pass over what Claude
  237. threw away found it.** On this bug every extra Claude pass repeated Claude's own reason for
  238. dropping it; the second vendor brought a different one.
  239. We audited follow-redirects 1.16.1, which has a known bug
  240. ([GHSA-mrwp-f3q8-3g9p](https://github.com/advisories/GHSA-mrwp-f3q8-3g9p), high, fixed in 1.16.2):
  241. a list of secret headers built in another JavaScript realm is treated as empty, so the caller's
  242. API key follows a redirect to another host.
  243. - Claude, first audit: never saw it.
  244. - Claude, second audit: saw it, then filed it as "hardening, not a finding".
  245. - A fresh Claude rereading everything set aside: agreed, "caller misuse".
  246. - Codex, auditing alone: never saw it.
  247. - **Codex rereading what Claude set aside: disagreed, traced it through the source, and sent it
  248. back for validation.**
  249. That last step is what this skill adds to Cloudflare's security-audit skill (used under its MIT
  250. license; same audit, evidence bar, validators and report). Before the report, a model from the
  251. other vendor rereads every item the audit set aside, read-only, and must answer every one;
  252. anything it brings back is validated again. If validation rejects it again, the report lists it
  253. under "Reviewers disagree" with both reasons, and you decide.
  254. Two projects, three known bugs: a story, not a rate. On the other project either vendor's
  255. reviewer recovered the bug. When Claude's first audit never looked at the bug, the reread of
  256. that audit did not find it either.
  257. *Use it when:* you want a full security audit of a codebase. With Sno Station it picks the
  258. other-vendor reviewer that still has quota; without it, it calls Codex from Claude Code or
  259. Claude Code from Codex, and says so when only one vendor was available.
  260. ### M · Build & Rollout
  261. *Get the team set up on any workstation with one step, build what the work needs, then roll it out to every machine.*
  262. Setup itself is the `sno setup` command, not a skill. Two of these keep the machine healthy and
  263. make the `sno` command easy for your agents to drive; the rest write the code: one hands it to
  264. Codex, four write it in Shell, TypeScript, Python or Rust.
  265. #### [medic](skills/M-build-and-rollout/medic/) — is my agent team healthy? One line per answer.
  266. - **Checks everything a team needs** in about ten seconds: tools installed, skills installed,
  267. skill commands runnable, hooks configured, messaging live, both vendors' quota readable, temp
  268. space free.
  269. - **Every problem comes with its fix:** `WARN` or `FAIL`, what is wrong, and the exact command
  270. that fixes it.
  271. - **Reads, never touches.** It installs, repairs, starts and stops nothing. You decide what to
  272. fix.
  273. *Use it when:* on a new machine, when agents stop reaching each other, or when a long run will
  274. not start.
  275. #### [sno-cli](skills/M-build-and-rollout/sno-cli/) — your agent drives `sno` correctly the first time
  276. - **Never out of date:** the agent reads the exact commands and flags from the installed `sno`
  277. itself, not from memory.
  278. - **A task map and recipes** for install, update, health checks, accounts, skills and the
  279. nightly loop.
  280. - **Your choices stay yours:** it operates the tool, it does not decide your settings for you.
  281. *Use it when:* you ask an agent to install, update, check or configure Sno.
  282. #### [codex-coder](skills/M-build-and-rollout/codex-coder/) — Claude plans, Codex writes the code
  283. - **One session, two vendors:** Claude Code keeps the plan and the conversation and starts a
  284. plain `codex exec` run for the coding, so the expensive model is not the one typing.
  285. - **Picks the language for you:** Shell, TypeScript, Python or Rust, from the files the task
  286. touches; a language skill of yours is used when it is installed.
  287. - **A stalled run is caught:** Claude Code is told about progress while the run works, and a
  288. run that has written nothing for 15 minutes is killed and started once more.
  289. *Use it when:* your Claude quota runs out halfway through the coding, or you want Codex to
  290. write what Claude planned. On the Claude Code side it needs Sno Station's `heartbeat`.
  291. #### [shellscript-coder](skills/M-build-and-rollout/shellscript-coder/), [ts-coder](skills/M-build-and-rollout/ts-coder/), [python-coder](skills/M-build-and-rollout/python-coder/), [rust-coder](skills/M-build-and-rollout/rust-coder/) — code that fits the repo it lands in
  292. - **Reads before it writes:** the repo's own runtime, versions, helpers, callers and tests come
  293. first, so the new code looks like the code around it.
  294. - **Small on purpose:** no compatibility shims, no options nobody asked for, no helper that
  295. already exists two files over.
  296. - **Done means a command passed:** every claim in the report traces to a check it actually ran
  297. in your repo; it never reports done over a failing check.
  298. *Use it when:* you want an agent to write or change production code in one of those four
  299. languages. They work on their own, without Sno Station, and `codex-coder` picks the right one
  300. for each task.
  301. ### S · Communication & Handoff
  302. *People talk through a shared inbox, and when one is out the other takes over with full context.*
  303. These skills run on Sno Reach, the messaging layer Sno Station installs: each agent gets an
  304. address, sends stored messages to other agents' inboxes, and can wake another agent to read
  305. them. No daemon, no server.
  306. #### [handoff](skills/S-communication-and-handoff/handoff/) — hand a task over without losing a thing
  307. - **Captures the whole state:** what is done, what is half-done, uncommitted changes, the
  308. decisions you already made, and what is out of bounds.
  309. - **The receiver writes nothing until the release is verified,** so two agents never edit the
  310. same work at once.
  311. - **The sender really leaves.** After release it stops; there is no second owner hovering.
  312. - **Works even when the sender is already gone** (quota refused, crash, closed window): the
  313. `sno handoff-checkpoint` progress record lets a fresh agent continue from the first
  314. unfinished task.
  315. *Use it when:* one agent must give its task to another.
  316. #### [rotate-agent](skills/S-communication-and-handoff/rotate-agent/) — never lose a long run to a quota limit again
  317. - **Acts while the sender is still alive.** It watches the remaining quota every few minutes and
  318. hands over at a threshold, not after the refusal, when it is too late to write a brief.
  319. - **Either direction:** Codex to Claude Code, or Claude Code to Codex.
  320. - **Bounded:** it fires once, and you can limit how long the watch runs.
  321. - **A safety net for missed windows:** if the window was missed, `sno rotate-agent-resume`
  322. starts the replacement from the progress record on disk.
  323. *Use it when:* a long run must finish even if one vendor's quota runs out. Needs both CLIs
  324. logged in and tmux.
  325. #### [subscription-quota-check](skills/S-communication-and-handoff/subscription-quota-check/) — how much quota is left, without spending any
  326. - **Stops the worst habit:** finding out you are out of quota by making a real call and reading
  327. the error.
  328. - **Reads Claude Code and Codex together** in about eight seconds, and tells you when the quota
  329. resets.
  330. - **Honest about stale numbers:** it checks whether the reading is current or last-known, and
  331. says which.
  332. - **Never polls on its own,** so it never earns a rate limit of its own.
  333. *Use it when:* you ask, or right after a vendor refused work.
  334. #### [heartbeat](skills/S-communication-and-handoff/heartbeat/) — progress reports from long runs, delivered into the conversation
  335. - **Two shapes:** report every N minutes (training, a long build, a generation queue), or watch
  336. until something finishes.
  337. - **Ticks land where you are:** each reading arrives in the agent's conversation, not in a log
  338. nobody reads.
  339. - **Hard to misuse:** intervals are in minutes, and a seconds-sized number is refused instead of
  340. silently waking your agent every few seconds.
  341. *Use it when:* something long is running unattended and you want to hear from it.
  342. #### [reach](skills/S-communication-and-handoff/reach/) — agents talk to each other
  343. - **Start a Claude Code or Codex agent** with its own address and working folder.
  344. - **Send work and read replies** through stored messages, or talk to a live agent right now.
  345. - **Messages carry no extra authority:** a message never widens the task you gave.
  346. *Use it when:* one agent needs to contact, start or wait on another.
  347. #### [join-talk](skills/S-communication-and-handoff/join-talk/) — make any agent reachable in one command
  348. - **One line out:** `joined <address>`. Tell other agents that address and they can reach this
  349. terminal.
  350. - **Safe to repeat:** running it again from the same terminal changes nothing.
  351. - **Clear refusals:** when it cannot work, it says exactly why.
  352. *Use it when:* you opened an agent by hand and want others to reach it.
  353. #### [tag-team](skills/S-communication-and-handoff/tag-team/) — two agents on one task, one builds and one reviews
  354. - **One command:** `sno reach pair "the task"` starts both agents in the current folder, each
  355. in a tmux window you can open and watch.
  356. - **Argued over before it reaches you.** The reviewer reads the result and the changed files
  357. and answers with concrete defects or an explicit no-defect result; the two keep exchanging
  358. fixes and reviews between themselves, and your agent asks the reviewer before calling it clean.
  359. - **Says what kind of review you got.** Signed in to two vendors, the review comes from the
  360. other one. Signed in to one, the pair still runs and tells you the review stayed inside it.
  361. - **Does not call it clean too early.** A first review with findings is reported as open; no
  362. third reviewer, and no second pair because the first review had not arrived yet.
  363. *Use it when:* a task is worth a second opinion and you do not want to carry it between agents.
  364. ### H · Reporting & Visibility
  365. *Everyone can see what got done, who caught what, who covered for whom, what's in progress.*
  366. #### [away-brief](skills/H-reporting-and-visibility/away-brief/) — one page when you come back
  367. - **Four sections, at most 60 lines:** Done, Stuck, Needs you, Spend.
  368. - **What waits for you is never pushed off the page** by a long list of finished work.
  369. - **"Done" is only what is real:** in git, in a delivered work order, or in a finished progress
  370. record. Not what an agent said.
  371. - **Shows what the night cost:** run `sno away-brief mark` before you leave, and the next page
  372. shows the quota spent since.
  373. *Use it when:* after sleep, a meeting, or a long unattended run.
  374. #### [catch-report](skills/H-reporting-and-visibility/catch-report/) — is the second agent worth it? Here are the numbers.
  375. - **Two counts, side by side:** problems the other model caught in review, and moments when an
  376. agent caught its own mistake.
  377. - **Never inflated:** the two are kept apart, never added together, and when a part could not be
  378. measured it says so instead of reporting zero.
  379. - **Quotes the biggest catches** by title, from the review records already on your machine.
  380. *Use it when:* you want the week's review results, or need to justify running two agents.
  381. #### [agentic-time-estimate](skills/H-reporting-and-visibility/agentic-time-estimate/) — real estimates for agent work
  382. - **Agent wall time, not human-developer time:** how long this will take an agent, and how much
  383. longer the running job needs, measured before guessed.
  384. - **Clock times you can trust:** every time shown to you comes from `sno report-time`, in your
  385. own zone with UTC beside it.
  386. *Use it when:* you ask "how long?" or "when will it be done?"
  387. ### T · Delegation & Work Orders
  388. *A lead delegates work as work orders, and decides who takes each job.*
  389. #### [charter](skills/T-delegation-and-work-orders/charter/) — one file that says what done means
  390. - **Keeps your words.** It never invents a decision, a fact or a requirement, and asks one
  391. question at a time only when the answer would change the outcome.
  392. - **Success checks you can run:** each one names what will be observed, where and how, and is
  393. answered pass or fail.
  394. - **No ceremony:** nothing goes in unless someone can name the failure it catches.
  395. - **Any kind of project:** software, documents, campaigns, research, operations.
  396. *Use it when:* work needs a written brief before someone else does it.
  397. #### [deliver](skills/T-delegation-and-work-orders/deliver/) — carry a charter to a proven result
  398. - **The charter's checks are the definition of done,** and nothing else is.
  399. - **Every check proven by a recorded real run,** tracked with `sno deliver-proof`.
  400. - **One independent review,** then an honest close: what passed, what did not, and why.
  401. - **Picks up where someone else stopped:** if an earlier agent left a progress record, it
  402. continues from the next unfinished step instead of starting over.
  403. *Use it when:* a charter is released and someone has to do it.
  404. #### [pl](skills/T-delegation-and-work-orders/pl/) — a Project Lead agent for one line of work
  405. - **Runs up to four executor agents,** one charter each, serially or in parallel.
  406. - **A family of five more skills:** `pl-dispatch` opens and schedules the work, `pl-watch`
  407. supervises agents in flight, `pl-audit` checks acceptance before anything closes, `pl-env`
  408. fixes the environment the work runs in, and `pl-analyze` writes the root-cause analysis when
  409. something goes wrong.
  410. *Use it when:* one project needs several agents working under one lead. You start it by name.
  411. #### [cos](skills/T-delegation-and-work-orders/cos/) — a Chief of Staff: the one agent you talk to
  412. - **One conversation for you,** in your language. It coordinates one to three Project Leads in
  413. parallel and brings you only the hard decisions: money, direction, red lines.
  414. - **A family of three more skills:** `cos-watch` keeps every Project Lead alive and on schedule,
  415. `cos-review` reviews the night's decisions in one pass when you come back, and `cos-evolve`
  416. turns management failures that repeat into enforced rules.
  417. *Use it when:* you run several workstreams and want one point of contact. You start it by name.
  418. ### R · Retrospective & Improvement
  419. *The team looks back at its own work and turns lessons into rules and better practice.*
  420. #### [rem-reflect](skills/R-recursive-self-improvement/rem-reflect/) — the nightly loop: your agents learn from their own sessions
  421. - **Once a day,** it reads this machine's Claude Code and Codex sessions, finds the failures and
  422. corrections that repeat, and turns them into lessons and proposed skill changes.
  423. - **You approve everything:** `sno rem-reflect accept`, `reject` or `tbd` for each one. Nothing
  424. changes without your accept.
  425. - **Lessons come back when they matter:** an accepted lesson is shown to the agent at the start
  426. of the next session, for this project or for all of them.
  427. - **You choose what leaves the machine.** In `local-first` mode nothing is sent to Sno; a few of
  428. the night's sessions go only to your own Claude Code or Codex account to draft the lessons.
  429. In the other two modes, at their default sharing level, it uploads session text (common secrets redacted first, best effort)
  430. and your installed skills to Sno's cloud for stronger judgments. Turn uploading off at any
  431. time with `sno station consent off`. The skill lists exactly what it reads and sends.
  432. The family skills `pl-analyze` (incident analysis for the Project Lead) and `cos-evolve`
  433. (repeated failures into rules) also belong here; they ship with `pl` and `cos`.
  434. *Use it when:* always on, once `sno setup` has armed the daily run.
  435. ## Built to be trusted
  436. Every unit in a release passed the same checks before it was published:
  437. 1. the repository carries its `LICENSE` and `NOTICE`;
  438. 2. the unit is copied whole, with its family members and per-agent differences intact;
  439. 3. nothing personal survives: no home paths, owner names, internal hosts or hard-coded models,
  440. and no Chinese, Japanese or Korean characters;
  441. 4. every skill's header parses, and its declaration of what it needs from the agent is valid;
  442. 5. each skill's own self-tests pass on that clean copy, not on the author's machine;
  443. 6. a stamp, `PUBLISHED.json`, is written last with the self-test count and digests of the
  444. contract and the payload.
  445. A skill that fails a check is not published. The stamp is written by the publish step, never by
  446. hand. All skill text is in English, and your agent follows it in whatever language you talk to
  447. it in.
  448. ## For skill authors
  449. ### Layout
  450. ```
  451. skills/
  452. README.md the category index
  453. <category>/<unit>/
  454. skill/ one skill: SKILL.md, references/, scripts/
  455. skills/<member>/ or a family of skills that ship together
  456. overlay/claude|codex/ per-agent differences, when a skill needs them
  457. public-bin/ one file per `sno <file name>` command the skill provides
  458. PUBLISHED.json the stamp written by the publish step
  459. registry.yaml unit -> category code (and tier)
  460. scripts/
  461. requirements-contract.json the contract every requires: block is checked against
  462. LICENSE Apache-2.0
  463. ```
  464. Category codes are fixed, in this order: J M S H T R. They appear in directory names and in
  465. `registry.yaml`.
  466. ### Declaring what a skill needs
  467. Every `SKILL.md` starts with a `requires:` block. `sno setup` reads it to decide, per agent,
  468. whether to install the skill:
  469. ```yaml
  470. requires:
  471. programs: [reach] # Sno Station programs the skill calls
  472. harness:
  473. - {slot: 4.shell, need: required} # what the agent itself must be able to do
  474. ```
  475. - **programs** are Sno Station programs installed next to the skills and run as `sno <name>`:
  476. `reach`, `heartbeat`, `subscription-quota-check`, `report-time`.
  477. - **slots** name an agent ability: `4.shell` (run shell commands), `4.file-read-write` (read and
  478. write files), `4.background-processes` (run a command in the background),
  479. `2.pre-turn-context-injection` (add text to the agent's context before each turn) and
  480. `3.reader-to-agent-delivery` (output of a background reader reaches the agent).
  481. - **need** is `required` (an agent without the slot does not get the skill), `preferred` (the
  482. skill is installed and works in a reduced way) or `optional` (only a convenience).
  483. ## License
  484. Apache-2.0. Open source, edge to edge. See [LICENSE](LICENSE).
skills/T-delegation-and-work-orders/pl/skills/pl/scripts/exec-trust.sh · Bundled script · 102 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # exec-trust.sh — answer Claude Code's first-run screens before an executor meets them.
  3. #
  4. # Claude Code stops in a directory it has never seen with a question ("Is this a project
  5. # you created or one you trust?"). An unattended executor waits there forever: it looks
  6. # alive, holds its window, and never reads its inbox. There are three first-run screens:
  7. # 1. the folder-trust question, which waits forever;
  8. # 2. the bypass-permissions warning, whose default answer is Exit, so a blind Enter kills
  9. # the session;
  10. # 3. the onboarding theme picker, which appears once the first two are answered.
  11. #
  12. # WHAT THIS CHANGES ON YOUR MACHINE (read before running). It edits the Claude Code config
  13. # file `<config-dir>/.claude.json` (default: ~/.claude.json, or $CLAUDE_CONFIG_DIR):
  14. # - sets bypassPermissionsModeAccepted=true and hasCompletedOnboarding=true GLOBALLY, for
  15. # every project and every future Claude Code session of that user, not only this
  16. # checkout;
  17. # - sets hasTrustDialogAccepted and hasCompletedProjectOnboarding for the given repo;
  18. # - records the installed claude version as lastOnboardingVersion.
  19. # Keys are only added or overwritten, never removed. Executors launched by spawn-exec.sh
  20. # with --runtime claude run `claude --dangerously-skip-permissions` (and codex runs with
  21. # --dangerously-bypass-approvals-and-sandbox): no permission prompts and no sandbox. Use
  22. # --check to see whether a directory is already pre-answered without changing anything.
  23. # Pass --config-dir to use a separate config directory instead of your own.
  24. #
  25. # Run this against the existing checkout selected for the executor; this command
  26. # never creates that checkout:
  27. #
  28. # bash "${PL_SKILL_DIR}/scripts/exec-trust.sh" --repo "$checkout"
  29. # bash "${PL_SKILL_DIR}/scripts/spawn-exec.sh" --repo "$checkout" --runtime claude ...
  30. #
  31. # usage: exec-trust.sh --repo <absolute path> [--config-dir <dir>]
  32. # exec-trust.sh --check --repo <absolute path> [--config-dir <dir>]
  33. # exit: 0 every first-run screen is pre-answered · 1 (--check only) not · 64 usage · 65 refused
  34. set -Eeuo pipefail
  35. repo='' config_dir="${CLAUDE_CONFIG_DIR:-$HOME}" mode=set
  36. while (($# > 0)); do
  37. case "$1" in
  38. --repo) repo="${2:-}"; shift 2 ;;
  39. --config-dir) config_dir="${2:-}"; shift 2 ;;
  40. --check) mode=check; shift ;;
  41. -h|--help) sed -n '2,/^# exit:/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
  42. *) printf 'exec-trust: unsupported option: %s\n' "$1" >&2; exit 64 ;;
  43. esac
  44. done
  45. [[ -n "$repo" ]] || { printf 'exec-trust: --repo <absolute path to the checkout> is required\n' >&2; exit 64; }
  46. # The config keys the runtime on the absolute path it is started in; a relative path
  47. # would write a key nothing matches.
  48. [[ "$repo" == /* ]] || { printf 'exec-trust: --repo must be absolute, got: %s\n' "$repo" >&2; exit 64; }
  49. [[ -d "$repo" ]] || { printf 'exec-trust: no such directory: %s\n' "$repo" >&2; exit 65; }
  50. command -v jq >/dev/null 2>&1 || { printf 'exec-trust: jq is required\n' >&2; exit 69; }
  51. config="$config_dir/.claude.json"
  52. if [[ "$mode" == check ]]; then
  53. [[ -f "$config" ]] || { printf 'exec-trust: no config at %s — every first-run screen would appear\n' "$config" >&2; exit 1; }
  54. jq -e --arg p "$repo" \
  55. '(.bypassPermissionsModeAccepted == true) and (.hasCompletedOnboarding == true)
  56. and (.projects[$p].hasTrustDialogAccepted == true)' \
  57. "$config" >/dev/null 2>&1 || {
  58. printf 'exec-trust: %s is not pre-answered for %s\n' "$config" "$repo" >&2; exit 1; }
  59. printf 'exec-trust: every first-run screen is pre-answered for %s\n' "$repo"
  60. exit 0
  61. fi
  62. mkdir -p -- "$config_dir"
  63. lock="$config_dir/.claude.json.exec-trust.lock"
  64. exec 9>>"$lock" || { printf 'exec-trust: cannot take the config lock at %s\n' "$lock" >&2; exit 65; }
  65. flock 9 || { printf 'exec-trust: cannot lock %s\n' "$lock" >&2; exit 65; }
  66. # The runtime writes this file too, so this is a read-modify-write under a lock that only
  67. # adds keys, written to a temporary file and renamed, so concurrent changes are not lost.
  68. current='{}'
  69. if [[ -f "$config" ]]; then
  70. current="$(cat -- "$config")"
  71. jq -e . <<<"$current" >/dev/null 2>&1 || {
  72. printf 'exec-trust: %s is not valid JSON; refusing to touch it\n' "$config" >&2
  73. exec 9>&-; exit 65; }
  74. fi
  75. # The onboarding version is read from the binary that will run; a stale value makes the
  76. # runtime re-run onboarding (the theme picker returns).
  77. onboarding_version=''
  78. if command -v claude >/dev/null 2>&1; then
  79. onboarding_version="$(claude --version 2>/dev/null | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+' || true)"
  80. fi
  81. updated="$(jq --arg p "$repo" --arg ver "$onboarding_version" '
  82. .bypassPermissionsModeAccepted = true
  83. | .hasCompletedOnboarding = true
  84. | (if $ver == "" then . else .lastOnboardingVersion = $ver end)
  85. | .projects = ((.projects // {}) | .[$p] = ((.[$p] // {})
  86. | .hasTrustDialogAccepted = true
  87. | .hasCompletedProjectOnboarding = true))
  88. ' <<<"$current")" || { printf 'exec-trust: failed to compose the updated config\n' >&2; exec 9>&-; exit 65; }
  89. tmp="$config.exec-trust.$$"
  90. printf '%s\n' "$updated" > "$tmp" && mv -f -- "$tmp" "$config" || {
  91. rm -f -- "$tmp"; printf 'exec-trust: failed to write %s\n' "$config" >&2; exec 9>&-; exit 65; }
  92. exec 9>&-
  93. printf 'exec-trust: %s is pre-answered for %s — no trust question, no bypass warning, no theme picker\n' "$config" "$repo"
skills/T-delegation-and-work-orders/pl/skills/pl/scripts/spawn-exec.sh · Bundled script · 707 lines · 3 findings marked
  1. #!/usr/bin/env bash
  2. # spawn-exec.sh — launch one executor agent in its own tmux session (the supported way
  3. # for a PL to start an executor).
  4. #
  5. # Needs: Linux, tmux, systemd user session (systemd-run, systemctl --user), flock, jq,
  6. # git, the `sno` CLI, and the chosen runtime CLI (codex, claude, hermes, openclaw or cursor-agent).
  7. #
  8. # A separate systemd service enforces the wall budget T: SIGTERM at T, then SIGKILL at
  9. # 1.5T. A relaunch needs a fresh spawn; a relaunch after the wall needs the owner
  10. # (whoever owns the work) to approve it.
  11. #
  12. # BEGIN SPAWN-EXEC USAGE
  13. # Usage:
  14. # spawn-exec.sh --journey <j-id> --repo <path> --budget-h <hours>
  15. # --dispatch <file> --class closure|build|operate
  16. # --addr <executor Reach address> [--lane <name>]
  17. # [--fence <file>] [--callsign <name>] [--kind executor]
  18. # [--resume <session-id>] [--log <path>]
  19. # [--runtime codex|claude|hermes|openclaw|cursor] [--window]
  20. # spawn-exec.sh -h|--help
  21. #
  22. # Required: --journey, --repo, --budget-h, --dispatch, --addr.
  23. # Values: --class closure|build|operate (default build);
  24. # --runtime codex|claude|hermes|openclaw|cursor (default codex; pass --runtime claude when
  25. # the executor should be a Claude session). hermes (the Hermes Agent CLI), openclaw
  26. # (the OpenClaw CLI) and cursor (the Cursor CLI, cursor-agent) are further supported agent
  27. # CLIs; they cannot resume a session.
  28. # --resume <session-id> relaunches an existing codex or claude session; other runtimes refuse it.
  29. # --window is accepted and ignored: tmux is the only seat channel.
  30. # Exit: 0 spawned; 2 usage; 3 live-session conflict;
  31. # 6 missing dependency; 7 startup proof failed.
  32. # END SPAWN-EXEC USAGE
  33. #
  34. # Behavior:
  35. # 1. Claims a callsign if not provided (callsign.sh claim).
  36. # 2. Appends the enforced DEADLINE BLOCK to the dispatch text
  37. # (absolute clock times — agents cannot feel time; they must read it).
  38. # 3. Launches the executor INSIDE A TMUX SESSION NAMED BY ITS CALLSIGN
  39. # with the runtime in a dedicated systemd user scope. One external controller
  40. # sends SIGTERM at T and cgroup-wide
  41. # SIGKILL at 1.5T, then records whether every owned container is empty.
  42. # Attach: `tmux attach -t <callsign>` for observation.
  43. # Mid-run instructions travel through the executor's Reach address. The runtime
  44. # runs without its own sandbox or approval prompts (codex --dangerously-bypass-
  45. # approvals-and-sandbox, claude --dangerously-skip-permissions): the guardrails are
  46. # the wall and fence-check.sh instead, so use it only in a repo and on a
  47. # machine where an unattended agent may act freely.
  48. # 4. Records the spawn (pid, callsign, deadlines) in
  49. # ~/.local/state/agent-spawns.jsonl and prints a summary line.
  50. set -euo pipefail
  51. scripts_dir="$(cd -- "$(dirname -- "$(readlink -f -- "${BASH_SOURCE[0]}")")" && pwd)"
  52. SPAWNS="$HOME/.local/state/agent-spawns.jsonl"
  53. CALLSIGN_SH="$(dirname "$0")/callsign.sh"
  54. LANE_RESOLVE="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/lane-resolve.sh"
  55. WALL_CONTROLLER="$(dirname "$0")/executor-wall.sh"
  56. journey="" repo="" lane="" budget_h="" dispatch="" callsign="" kind="executor" resume="" log="" jclass="" fence=""
  57. # The runtime is selectable per spawn, Codex by default. The adapter
  58. # owns exactly two things: how to launch and how to resume.
  59. runtime="codex"
  60. # The Reach address this executor answers to. It is passed at launch and never inferred.
  61. addr=""
  62. usage() {
  63. sed -n '/^# BEGIN SPAWN-EXEC USAGE$/,/^# END SPAWN-EXEC USAGE$/p' "$0" |
  64. sed '1d;$d;s/^# \{0,1\}//'
  65. }
  66. while [ $# -gt 0 ]; do
  67. case "$1" in
  68. --journey) journey="$2"; shift 2 ;;
  69. --repo) repo="$2"; shift 2 ;;
  70. --lane) lane="$2"; shift 2 ;;
  71. --budget-h) budget_h="$2"; shift 2 ;;
  72. --dispatch) dispatch="$2"; shift 2 ;;
  73. --class) jclass="$2"; shift 2 ;;
  74. --fence) fence="$2"; shift 2 ;;
  75. --callsign) callsign="$2"; shift 2 ;;
  76. --kind) kind="$2"; shift 2 ;;
  77. --resume) resume="$2"; shift 2 ;;
  78. --log) log="$2"; shift 2 ;;
  79. --runtime) runtime="$2"; shift 2 ;;
  80. --window) shift ;; # accepted and ignored: tmux is the only seat channel
  81. --addr) addr="$2"; shift 2 ;;
  82. -h|--help) usage; exit 0 ;;
  83. *) echo "spawn-exec: unknown arg $1" >&2; exit 2 ;;
  84. esac
  85. done
  86. [ -n "$journey" ] && [ -n "$repo" ] && [ -n "$budget_h" ] && [ -n "$dispatch" ] || {
  87. echo "spawn-exec: need --journey --repo --budget-h --dispatch" >&2; exit 2; }
  88. # An executor that cannot be talked to, woken, or tracked is not started: a missing or
  89. # malformed address is refused before the runtime starts.
  90. case "$runtime" in codex|claude|hermes|openclaw|cursor) : ;; *) echo "spawn-exec: unsupported runtime: $runtime" >&2; exit 2 ;; esac
  91. if [ -n "$resume" ]; then
  92. case "$runtime" in codex|claude) : ;; *)
  93. echo "spawn-exec: --resume is not supported for runtime $runtime (only codex and claude sessions can be resumed); nothing was started" >&2; exit 2 ;; esac
  94. fi
  95. [ -n "$addr" ] || { echo "spawn-exec: --addr <executor Reach address> is required; an executor that cannot be addressed cannot be woken" >&2; exit 2; }
  96. [[ "$addr" =~ ^[a-z][a-z0-9-]{0,31}\.[a-z0-9][a-z0-9-]{0,63}@[a-z0-9][a-z0-9.-]{0,252}$ ]] || { echo "spawn-exec: invalid Reach address: $addr" >&2; exit 2; }
  97. jclass="${jclass:-build}"
  98. [ -f "$dispatch" ] || { echo "spawn-exec: dispatch file not found: $dispatch" >&2; exit 2; }
  99. if [ "$jclass" = operate ]; then
  100. for field in command working-directory artifact; do
  101. grep -qE "^${field}:[[:space:]]*[^[:space:]]" "$dispatch" || {
  102. echo "spawn-exec: operate dispatch missing $field field" >&2; exit 2;
  103. }
  104. done
  105. fi
  106. mkdir -p "$HOME/.local/state"; touch "$SPAWNS"
  107. [ -z "$fence" ] || [ -f "$fence" ] || { echo "spawn-exec: fence file not found: $fence" >&2; exit 2; }
  108. [ -d "$repo" ] || { echo "spawn-exec: repo dir not found: $repo" >&2; exit 2; }
  109. repo="$(cd -- "$repo" && pwd -P)"
  110. main_root="$(git -C "$repo" rev-parse --show-toplevel 2>/dev/null || printf '%s' "$repo")"
  111. # Check every prerequisite before any resource is claimed, and report all that are missing in one message.
  112. missing_deps=()
  113. runtime_cmd="$runtime"; [ "$runtime" != cursor ] || runtime_cmd=cursor-agent # `cursor` alone is the IDE launcher
  114. for dep in "$runtime_cmd" tmux sno flock systemd-run systemctl jq; do
  115. command -v "$dep" >/dev/null || missing_deps+=("$dep")
  116. done
  117. if [ "${#missing_deps[@]}" -gt 0 ]; then
  118. echo "spawn-exec: missing dependency: ${missing_deps[*]} (needs Linux with tmux, a systemd user session, flock, jq, the sno CLI and the runtime CLI on PATH; nothing was started)" >&2
  119. exit 6
  120. fi
  121. [ -x "$WALL_CONTROLLER" ] || { echo "spawn-exec: missing dependency: executable executor-wall.sh beside this script" >&2; exit 6; }
  122. [ -f "$LANE_RESOLVE" ] || { echo "spawn-exec: missing dependency: lane-resolve.sh beside this script" >&2; exit 6; }
  123. # Workspace layout: control files live under <repo>/ai-doc/ACTIVE/PL; created on first use.
  124. mb_base="$main_root/ai-doc"
  125. mkdir -p "$mb_base/ACTIVE/PL/exec-logs" || {
  126. echo "spawn-exec: cannot create $mb_base/ACTIVE/PL/exec-logs" >&2; exit 2; }
  127. # Mission registry: every charter carries one machine-readable mission header line;
  128. # this script is the only writer of missions.jsonl.
  129. missions="$mb_base/ACTIVE/PL/missions.jsonl"
  130. touch "$missions" || {
  131. echo "spawn-exec: cannot initialize mission registry: $missions" >&2
  132. exit 2
  133. }
  134. mhdr="$(grep -m1 -E '^mission:' "$dispatch" 2>/dev/null || true)"
  135. mfield() { { printf '%s\n' "$mhdr" | grep -oE "$1[[:space:]]*:[[:space:]]*[^·]+" | head -1 | sed -E "s/^$1[[:space:]]*:[[:space:]]*//; s/[[:space:]]+$//"; } || true; }
  136. m_id="$(mfield mission)"; m_op="$(mfield operation)"; m_test="$(mfield success-test)"
  137. m_evid="$(mfield evidence)"; m_owner="$(mfield owner)"; m_parent="$(mfield parent)"; m_pred="$(mfield predecessor)"
  138. m_pred_spawn="$(mfield predecessor-spawn-id)"
  139. m_id="${m_id:-$journey}"; m_op="${m_op:-open}"; m_test="${m_test:-unspecified}"
  140. m_evid="${m_evid:-unspecified}"; m_owner="${m_owner:-unspecified}"
  141. case "$budget_h" in ''|*[!0-9.]*|.|*.*.*) echo "spawn-exec: --budget-h must be a positive number" >&2; exit 2 ;; esac
  142. # JSON-ledger fields are written by naive printf — strip anything that could
  143. # break a JSON string or forge records (quotes, backslashes, control bytes).
  144. sane() { printf '%s' "${1:-}" | tr '[:cntrl:]' ' ' | tr -d '\\"'; }
  145. journey="$(sane "$journey")"; kind="$(sane "$kind")"; resume="$(sane "$resume")"
  146. runtime="$(sane "$runtime")"; addr="$(sane "$addr")"
  147. callsign="$(sane "$callsign")"; repo="$(sane "$repo")"; log="$(sane "$log")"
  148. # budget arithmetic (awk — no bc dependency); grace = 1.5 * budget.
  149. # One external controller sends TERM at T and KILL exactly at the 1.5T wall.
  150. budget_s=$(awk -v h="$budget_h" 'BEGIN{printf "%d", h*3600}')
  151. grace_s=$(awk -v h="$budget_h" 'BEGIN{printf "%d", h*3600*1.5}')
  152. [ "$budget_s" -gt 0 ] || { echo "spawn-exec: --budget-h must be > 0" >&2; exit 2; }
  153. # Two distinct deadlines require at least one second between TERM and KILL.
  154. [ "$grace_s" -ge 2 ] || { echo "spawn-exec: budget too small — 1.5x grace must be >= 2s (got ${grace_s}s)" >&2; exit 2; }
  155. wall_epoch="$(date +%s)"
  156. t_budget="$(date -d "@$((wall_epoch + budget_s))" '+%Y-%m-%d %H:%M %Z')"
  157. t_grace="$(date -d "@$((wall_epoch + grace_s))" '+%Y-%m-%d %H:%M %Z')"
  158. # comms deadlines (persisted ISO — roster.sh is the timer owner and needs
  159. # machine-comparable values; the roster owns the alarm)
  160. t_ack="$(date -d '+15 minutes' -Is)"
  161. t_conv="$(date -d '+90 minutes' -Is)"
  162. # Lane resolution keys on the REPOSITORY name.
  163. repo_base="$(basename "$main_root")"
  164. resolve_args=(--repo "$repo_base" --field addr)
  165. [ -z "$lane" ] || resolve_args+=(--lane "$lane")
  166. if ! pl_address="$(PL_REGISTRY="${PL_REGISTRY:-${SNO_PL_REGISTRY:-}}" \
  167. bash "$LANE_RESOLVE" "${resolve_args[@]}")"; then
  168. exit 2
  169. fi
  170. claimed_here=0
  171. if [ -z "$callsign" ]; then
  172. callsign="$("$CALLSIGN_SH" claim --journey "$journey" --repo "$main_root" --kind "$kind" \
  173. --label "spawned $(date '+%H:%M')")" || exit $?
  174. claimed_here=1
  175. fi
  176. # The executor that actually holds a primary open/transfer is the lifecycle
  177. # owner. Auto-claim cannot know that identity when the dispatch is authored,
  178. # so normalize only after the atomic claim; delegates retain the primary owner.
  179. case "$m_op" in
  180. open|transfer) m_owner="$callsign" ;;
  181. esac
  182. # ANY post-claim failure — cd, mktemp, disk-full, tmux — must not strand the
  183. # claim (`set -e` skips inline cleanup): EXIT trap releases
  184. # what WE claimed unless the spawn reached success.
  185. spawn_ok=0 mission_registered=0 abort_runner="" session_started=0
  186. wall_started=0 wall_unit="" runtime_started=0 runtime_unit=""
  187. seat_lock_fd="" startup_pane=""
  188. seat_dir="" startup_file="" reach_root=""
  189. mission_lock="${missions}.lock"
  190. cleanup_reach_startup() {
  191. local runtime_group="" runtime_deadline
  192. if [ "$session_started" = 1 ] && tmux has-session -t "$callsign" 2>/dev/null; then
  193. tmux kill-session -t "$callsign" 2>/dev/null || true
  194. fi
  195. if [ "$wall_started" = 1 ] && [ -n "$wall_unit" ]; then
  196. systemctl --user stop "$wall_unit" >/dev/null 2>&1 || true
  197. fi
  198. if [ "$runtime_started" = 1 ] && [ -n "$runtime_unit" ]; then
  199. if ! bash "$WALL_CONTROLLER" --spawn-id "$mission_spawn_id" --cleanup-now; then
  200. echo "spawn-exec: CRITICAL — failed startup left marked executor work alive; preserving mission and callsign for recovery" >&2
  201. return 1
  202. fi
  203. systemctl --user kill --kill-whom=all --signal=KILL "$runtime_unit" >/dev/null 2>&1 || true
  204. systemctl --user stop --no-block "$runtime_unit" >/dev/null 2>&1 || true
  205. runtime_deadline=$(( SECONDS + 5 ))
  206. while [ "$SECONDS" -lt "$runtime_deadline" ]; do
  207. runtime_group="$(systemctl --user show "$runtime_unit" -p ControlGroup --value 2>/dev/null || true)"
  208. if [ -z "$runtime_group" ] || [ ! -r "/sys/fs/cgroup$runtime_group/cgroup.procs" ] ||
  209. [ ! -s "/sys/fs/cgroup$runtime_group/cgroup.procs" ]; then
  210. runtime_started=0
  211. break
  212. fi
  213. sleep 0.1
  214. done
  215. if [ "$runtime_started" = 1 ]; then
  216. echo "spawn-exec: CRITICAL — failed startup left runtime unit $runtime_unit non-empty; preserving mission and callsign for recovery" >&2
  217. return 1
  218. fi
  219. fi
  220. if [ -n "$startup_pane" ] && [ -f "$seat_dir/reachable.json" ] &&
  221. jq -e --arg pane "$startup_pane" '.identity == {kind:"tmux-pane",value:$pane}' "$seat_dir/reachable.json" >/dev/null 2>&1; then
  222. sno reach unregister --as "$addr" >/dev/null ||
  223. echo "spawn-exec: could not unregister failed Reach seat $addr" >&2
  224. fi
  225. if [ -n "$seat_lock_fd" ]; then
  226. flock -u "$seat_lock_fd" 2>/dev/null || true
  227. exec {seat_lock_fd}>&-
  228. seat_lock_fd=""
  229. fi
  230. }
  231. release_on_fail() {
  232. [ "$spawn_ok" = 1 ] && return 0
  233. if ! cleanup_reach_startup; then
  234. return 1
  235. fi
  236. if [ "$mission_registered" = 1 ]; then
  237. if ! bash "$abort_runner" launch 1; then
  238. echo "spawn-exec: CRITICAL — launch failed and mission abort could not be recorded in $missions" >&2
  239. "$CALLSIGN_SH" release "$callsign" --journey "$journey" 2>/dev/null || true
  240. fi
  241. mission_registered=0
  242. claimed_here=0
  243. fi
  244. [ "$claimed_here" = 1 ] && "$CALLSIGN_SH" release "$callsign" --journey "$journey" 2>/dev/null || true
  245. }
  246. trap release_on_fail EXIT
  247. [ -n "$log" ] || {
  248. mkdir -p "$mb_base/ACTIVE/PL/exec-logs" 2>/dev/null || true
  249. log="$mb_base/ACTIVE/PL/exec-logs/${journey}-${callsign}.log"
  250. touch "$log" 2>/dev/null || log="$HOME/.local/state/${journey}-${callsign}.log"
  251. }
  252. [ -e "$log" ] || touch "$log" || {
  253. echo "spawn-exec: cannot create explicit log path: $log" >&2
  254. exit 2
  255. }
  256. # Render and lint the exact bytes the executor will send before any tmux session starts.
  257. # This proves message validity only; the on-station acknowledgement still proves Reach
  258. # readiness.
  259. #
  260. # The card carries the launcher's own measurement of the fence file (exists, bytes,
  261. # sha256); the executor sends its own reading separately, so the two can be compared.
  262. fence_exists_at_spawn=no
  263. fence_bytes_at_spawn=0
  264. fence_sha_at_spawn=none
  265. if [ -n "$fence" ] && [ -f "$fence" ]; then
  266. fence_exists_at_spawn=yes
  267. fence_bytes_at_spawn="$(wc -c <"$fence" | tr -d ' ')"
  268. fence_sha_at_spawn="$(sha256sum -- "$fence" | cut -d' ' -f1)"
  269. fi
  270. on_station_message="$log.on-station.eml"
  271. {
  272. printf 'From: %s <%s>\n' "$callsign" "$addr"
  273. printf 'To: PL <%s>\n' "$pl_address"
  274. printf 'Subject: [STATUS] on-station: %s\n' "$callsign"
  275. printf 'Date: %s\n' "$(date -R)"
  276. printf 'Message-ID: <on-station-%s-%s@%s>\n' "$(date +%s%N)" "$$" "$(hostname)"
  277. printf 'X-Work: %s\n' "$journey"
  278. printf 'X-Type: status\n\n'
  279. printf 'on station; charter=%s.dispatch read; fence=%s\n' "$log" "${fence:-NONE}"
  280. printf 'measured-at-spawn: fence-exists=%s fence-bytes=%s fence-sha256=%s\n' \
  281. "$fence_exists_at_spawn" "$fence_bytes_at_spawn" "$fence_sha_at_spawn"
  282. printf 'observed-by-executor: sent separately; a disagreement with the line above is a finding\n'
  283. } >"$on_station_message"
  284. if ! sno reach lint "$on_station_message"; then
  285. echo "spawn-exec: generated on-station message failed canonical lint; no executor was started" >&2
  286. exit 7
  287. fi
  288. # Serialize launches for one address while Reach initializes its persistent seat.
  289. reach_root="${SNO_REACH_ROOT:-$HOME/.local/state/sno-reach}"
  290. mkdir -p -- "$reach_root"
  291. exec {seat_lock_fd}>"$reach_root/.spawn-$addr.lock"
  292. flock -x "$seat_lock_fd"
  293. seat_dir="$reach_root/$addr"
  294. if [ -f "$seat_dir/reachable.json" ]; then
  295. old_pane="$(jq -er 'select(.channel == "tmux" and .identity.kind == "tmux-pane") | .identity.value' "$seat_dir/reachable.json" 2>/dev/null || true)"
  296. if [ -n "$old_pane" ] && tmux list-panes -a -F '#{pane_id}' 2>/dev/null | grep -qxF "$old_pane"; then
  297. echo "spawn-exec: Reach address $addr is already registered to live pane $old_pane" >&2
  298. exit 3
  299. fi
  300. sno reach unregister --as "$addr" >/dev/null || {
  301. echo "spawn-exec: could not clear stale Reach registration for $addr" >&2; exit 7;
  302. }
  303. fi
  304. sno reach init --as "$addr" --name "${addr%@*}" >/dev/null || {
  305. echo "spawn-exec: could not initialize Reach seat $addr" >&2; exit 7;
  306. }
  307. startup_file="$log.startup"
  308. rm -f -- "$startup_file"
  309. # Deadline block — appended to the dispatch, absolute times only.
  310. convergence_class="$jclass"
  311. [ "$convergence_class" != operate ] || convergence_class=closure
  312. merged="$(mktemp)"
  313. cat "$dispatch" > "$merged"
  314. cat >> "$merged" <<EOF
  315. === DEADLINE (enforced by the launcher) ===
  316. Your callsign: ${callsign}. Budget: ${budget_h}h.
  317. T (budget) = ${t_budget}: from this moment, STOP all feature/fix-forward
  318. work; smallest completion path ONLY (commit verified work via explicit
  319. paths, write the close report, send the close card).
  320. 1.5T (hard wall) = ${t_grace}: SIGTERM is sent at T and SIGKILL at this
  321. time — trapping/ignoring TERM buys you nothing.
  322. Anything uncommitted may be lost. There is no extension — no card, no
  323. apology, no reason changes this.
  324. Past T, do not add any out-of-charter work. Within budget, extra in-scope
  325. quality is welcome.
  326. You cannot feel time. Run \`date\` at every phase boundary and compare
  327. against the two timestamps above. Plan backward from T, not forward.
  328. === COMMS CONTRACT (acknowledgment required) ===
  329. Read accumulated work at each task boundary and after long commands:
  330. sno reach inbox --as ${addr}
  331. Read each exact card path printed by inbox. Handle decisions and questions before
  332. continuing interrupted work. A ring is a prompt to read the inbox, not a card.
  333. FIRST act, before any work — READ the charter and fence, then send the on-station
  334. card. The prepared card records the spawner's fence measurement; send your own
  335. measurement separately if it differs:
  336. charter: ${log}.dispatch
  337. fence: ${fence:-<none declared>}
  338. sno reach send --as ${addr} < '${on_station_message}'
  339. ACK deadline ${t_ack} (15 min): no card by then = the PL treats this
  340. dispatch as never delivered and re-dispatches.
  341. STATE to disk on every transition:
  342. \`bash "${scripts_dir}/callsign.sh" title run|wait|done ${callsign} --journey ${journey} "<label>"\`.
  343. CONVERGENCE every fix-verify cycle:
  344. \`bash "${scripts_dir}/convergence-watch.sh" record --journey ${journey} --class ${convergence_class} --remaining <N> --cycle <k>\`
  345. First sample due by ${t_conv}; a series silent for 90 min is treated as a stalled run.
  346. For a work card, accept before doing the work:
  347. printf '%s\n' 'Accepted.' | sno reach reply --as ${addr} --card "<exact card path>" --state accepted
  348. Then report the result with the same card path:
  349. printf '%s\n' '<result and evidence>' | sno reach reply --as ${addr} --card "<exact card path>" --state completed
  350. Use --state failed if the work failed. A question asking for information takes
  351. reply without --state. Do not dismiss an actionable question or decision.
  352. For later supervision, arm a heartbeat that rings your own seat, then end the turn:
  353. sno heartbeat --interval 10m --label pl-${callsign} -- sno reach ring ${addr}
  354. If Reach reports a delivered card with wake exit 5 or 6, inspect the recipient
  355. seat; do not resend the card.
  356. EOF
  357. cd "$repo"
  358. # Read the merged dispatch in the PARENT before backgrounding: bash performs a
  359. # background command's expansions in the forked child, so an early rm of the
  360. # temp file would race the child's $(cat …) and hand the executor an EMPTY
  361. # dispatch.
  362. dispatch_text="$(command cat "$merged")"
  363. rm -f "$merged"
  364. # Every executor runs inside a tmux session NAMED BY ITS CALLSIGN:
  365. # - persistent PTY: the session lives on its own — no resume pumping and no
  366. # double-spawn; mid-run instructions accumulate in the executor Reach
  367. # - attachable window: `tmux attach -t <callsign>` any time; scrollback and
  368. # titles stay visible
  369. # - no runtime sandbox: the codex workspace-write sandbox mounts .git read-only, so
  370. # commits would fail. The guardrails here are the wall, fence-check on every
  371. # commit, and explicit-path discipline.
  372. # The runtime receives the spawn marker and runs in a dedicated systemd user scope.
  373. # The wall is a separate user service, so it survives every scope it signals.
  374. # Callsign grammar check: a callsign is interpolated into tmux and shell commands, so it
  375. # must be provably inert.
  376. case "$callsign" in *[!a-z]*|'') echo "spawn-exec: callsign must be lowercase letters only: '$callsign'" >&2; exit 2 ;; esac
  377. if tmux has-session -t "$callsign" 2>/dev/null; then
  378. echo "spawn-exec: tmux session '$callsign' already exists — refusing double-spawn" >&2
  379. exit 3
  380. fi
  381. printf '%s' "$dispatch_text" > "$log.dispatch" # BEFORE the session starts (race)
  382. # Never build a shell program by interpolating caller values (an apostrophe in
  383. # --log/--resume would execute as the tmux user). All values are embedded via
  384. # printf %q into a per-spawn runner file.
  385. runner="$log.runner"
  386. abort_runner="$log.abort"
  387. mission_spawn_id="$(date -u +%Y%m%dT%H%M%S)-$$-$callsign"
  388. runtime_unit="sno-exec-${mission_spawn_id}.scope"
  389. wall_unit="sno-exec-wall-${mission_spawn_id}.service"
  390. wall_events="$log.wall.jsonl"
  391. rm -f -- "$wall_events" "$wall_events.lock"
  392. {
  393. printf '#!/usr/bin/env bash\nset -euo pipefail\n'
  394. printf 'missions=%q\nmission_lock=%q\nspawn_id=%q\n' \
  395. "$missions" "$mission_lock" "$mission_spawn_id"
  396. printf 'release_launch_claim=%q\n' "$claimed_here"
  397. printf 'callsign_sh=%q\ncallsign=%q\njourney=%q\n' \
  398. "$CALLSIGN_SH" "$callsign" "$journey"
  399. printf 'mission=%q\noperation=%q\nowner=%q\nsuccess_test=%q\nevidence=%q\nparent=%q\n' \
  400. "$m_id" "$m_op" "$m_owner" "$m_test" "$m_evid" "${m_parent:-none}"
  401. # A delegate is bound to the PRIMARY generation it was admitted under, never to
  402. # whichever delegate happens to be newest. Empty for a primary; the runner refuses
  403. # rather than guesses if a delegate ever reaches it unset.
  404. printf 'bound_primary_spawn=%q\n' "${m_pred_spawn:-}"
  405. cat <<'EOF'
  406. mode="${1:-runtime}"
  407. exit_rc="${2:-1}"
  408. exec {lock_fd}>>"$mission_lock"
  409. flock -x "$lock_fd"
  410. # A delegate spawn must not supersede the primary's generation. A primary reads
  411. # its generation from primary lifecycle events; delegates still count delegate events.
  412. if [ "$operation" = "delegate" ] && [ -z "${bound_primary_spawn:-}" ]; then
  413. echo "spawn-exec: CRITICAL — delegate $spawn_id has no bound primary generation; refusing to" >&2
  414. echo "spawn-exec: guess whether its terminal row belongs in $missions. Record it by hand." >&2
  415. exit 1
  416. fi
  417. current="$(
  418. jq -rs --arg m "$mission" --arg sid "$spawn_id" --arg op "$operation" \
  419. --arg bps "${bound_primary_spawn:-}" '
  420. [.[] | select(
  421. .mission == $m and
  422. (.event == "open" or .event == "transfer" or
  423. .event == "close" or .event == "abort")
  424. )][-1]
  425. | if $op == "delegate" then
  426. # A delegate is current while the primary generation it was admitted under is
  427. # still the live one. Two delegates under one primary therefore BOTH record a
  428. # terminal row — they are not each other'"'"'s successors. A transfer moves the
  429. # spawn id and a close or abort changes the event, so either suppresses it.
  430. (if (.event == "open" or .event == "transfer") and .spawn_id == $bps
  431. then "current" else "stale" end)
  432. else
  433. (if .spawn_id == $sid then "current" else "stale" end)
  434. end
  435. ' "$missions"
  436. )"
  437. if [ "$current" = "current" ]; then
  438. if [ "$mode" = "runtime" ] && [ "$operation" != "delegate" ]; then
  439. jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$mission" \
  440. --arg o "$owner" --arg sid "$spawn_id" --arg cs "$callsign" \
  441. --arg journey "$journey" --argjson rc "$exit_rc" \
  442. '{ts:$ts,mission:$m,event:"correction",owner:$o,outcome:"executor_stopped",callsign:$cs,corrects_spawn_id:$sid,journey:$journey,exit_rc:$rc,exit_rc_is:"the status returned by the dedicated runtime scope client. It proves only that the interactive runtime stopped, not that the task completed and not that the external wall fired. Task completion still requires the terminal artifact plus close card; wall enforcement is proven only by this spawn id in its wall event file.",reason:"executor process exited; mission and callsign remain reserved for exact-session continuation"}' \
  443. >> "$missions"
  444. elif [ "$operation" = "delegate" ]; then
  445. jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$mission" \
  446. --arg o "$owner" --arg sid "$spawn_id" --arg cs "$callsign" \
  447. --argjson rc "$exit_rc" \
  448. '{ts:$ts,mission:$m,event:"correction",owner:$o,corrects_spawn_id:$sid,delegate:$cs,outcome:(if $rc == 0 then "delegate_stopped" elif $rc >= 128 then "delegate_outcome_unknown" else "delegate_failed" end),exit_rc:$rc,exit_rc_is:"the status returned by the dedicated runtime scope client. It proves only that the interactive runtime stopped, not that the delegated task completed and not that the external wall fired. Task completion still requires an explicit result; wall enforcement is proven only by this spawn id in its wall event file. Treat delegate_outcome_unknown as neither done nor failed.",reason:"delegated executor exited; mission ownership and live state remain with the primary owner"}' \
  449. >> "$missions"
  450. else
  451. jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$mission" \
  452. --arg o "$owner" --arg st "$success_test" --arg ev "$evidence" \
  453. --arg pa "$parent" --arg pr "$callsign" --arg sid "$spawn_id" \
  454. '{ts:$ts,mission:$m,event:"abort",owner:$o,success_test:$st,evidence_form:$ev,parent:$pa,predecessor:$pr,spawn_id:$sid,reason:"spawn-exec executor exited nonzero after lifecycle admission; no executor remains live"}' \
  455. >> "$missions"
  456. fi
  457. else
  458. # This branch writes nothing to the registry, so it says so explicitly.
  459. echo "spawn-exec: NO stop record written for spawn $spawn_id (operation=$operation)." >&2
  460. echo "spawn-exec: The mission's own lifecycle already advanced past this spawn, so this" >&2
  461. echo "spawn-exec: exit is not the current generation and its stop is not recorded." >&2
  462. echo "spawn-exec: The callsign is NOT released by this path. If you expected a stop" >&2
  463. echo "spawn-exec: record, read $missions and find which later event superseded it." >&2
  464. fi
  465. flock -u "$lock_fd"
  466. exec {lock_fd}>&-
  467. if { [ "$mode" = "launch" ] && [ "$release_launch_claim" = 1 ]; } ||
  468. [ "$operation" = "delegate" ]; then
  469. if ! "$callsign_sh" release "$callsign" --journey "$journey"; then
  470. echo "spawn-exec: CRITICAL — stopped executor callsign release failed: $callsign" >&2
  471. exit 1
  472. fi
  473. fi
  474. EOF
  475. } > "$abort_runner"
  476. chmod +x "$abort_runner"
  477. # The runtime adapter owns exactly two things: how to launch, and how to resume. Every
  478. # other part of the lifecycle — registration, wake, liveness, close, archive — is written
  479. # once and never branches on this value.
  480. resume_line=""
  481. case "$runtime" in
  482. codex) [ -n "$resume" ] && resume_line="resume $(printf '%q' "$resume")" ;;
  483. claude) [ -n "$resume" ] && resume_line="--resume $(printf '%q' "$resume")" ;;
  484. esac
  485. state_file="$log.state"
  486. rm -f -- "$state_file"
  487. {
  488. printf '#!/usr/bin/env bash\nset -o pipefail\n'
  489. printf 'exec %d>&-\n' "$seat_lock_fd"
  490. printf 'export SNO_REACH_ROOT=%q\n' "$reach_root"
  491. printf 'export SNO_REACH_ADDR=%q\n' "$addr"
  492. printf 'startup_file=%q\nstartup_spawn_id=%q\n' "$startup_file" "$mission_spawn_id"
  493. cat <<'EOF'
  494. write_startup_receipt() {
  495. local state="$1" reason="${2:-}" tmp="${startup_file}.tmp.$$"
  496. jq -nc --arg sid "$startup_spawn_id" --arg state "$state" --arg reason "$reason" \
  497. '{spawn_id:$sid,state:$state,reason:$reason}' >"$tmp" || return 1
  498. mv -f -- "$tmp" "$startup_file"
  499. }
  500. EOF
  501. # The executor registers its Reach seat before it starts working; a failed registration
  502. # is a failed spawn rather than an executor nobody can reach.
  503. printf "sno reach register --as %q --channel tmux --handle \"\$(tmux display-message -p '#{pane_id}')\"\n" "$addr"
  504. printf 'register_rc=$?\n'
  505. printf 'if [ "$register_rc" -ne 0 ]; then\n'
  506. printf ' echo "[spawn-exec] REFUSING: %s could not register its Reach seat; an unreachable executor is not started"\n' "$addr"
  507. printf ' write_startup_receipt refused "registration-failed:$register_rc" || true\n'
  508. printf ' exit "$register_rc"\n'
  509. printf 'fi\n'
  510. printf 'write_startup_receipt registered || exit 74\n'
  511. # systemd-run --scope stays in the pane's foreground process group and moves the runtime plus
  512. # ordinary and setsid descendants into one dedicated cgroup. A separately armed service owns
  513. # the timer and discovers any normally inherited nested scope by this spawn's marker.
  514. printf 'systemd-run --user --scope --quiet --unit=%q env SNO_EXEC_SPAWN_ID=%q \\\n' \
  515. "$runtime_unit" "$mission_spawn_id"
  516. case "$runtime" in
  517. codex) printf ' codex --dangerously-bypass-approvals-and-sandbox %s \\\n' "$resume_line" ;;
  518. claude) printf ' claude --dangerously-skip-permissions %s \\\n' "$resume_line" ;;
  519. hermes) printf ' hermes chat --yolo --query \\\n' ;;
  520. openclaw) printf ' openclaw tui --message \\\n' ;;
  521. cursor) printf ' cursor-agent --force --trust \\\n' ;; # --trust: a fresh checkout's trust question would hold the seat
  522. esac
  523. # No pipe: an interactive terminal program dies when its stdout becomes a pipe
  524. # (`codex ... | tee log` ends the session). The transcript is captured by tapping the
  525. # pane from outside instead (tmux pipe-pane, set at launch).
  526. printf ' "$(cat %q)"\n' "$log.dispatch"
  527. printf 'ec=$?\necho\n'
  528. # Completion is an ARTIFACT, not an exit code. An interactive session returns to a
  529. # prompt rather than exiting, so the number below cannot mean what it meant before; the
  530. # supervisor reads the state file and the close card, and this file carries the spawn id
  531. # so a stale one from a previous generation can never be mistaken for this run's.
  532. printf 'printf %%s "spawn-id=%s\\nruntime=%s\\nexit=$ec\\nended-at=$(date -Is)\\n" > %q\n' \
  533. "$mission_spawn_id" "$runtime" "$state_file"
  534. printf 'bash %q runtime "$ec" || echo "[spawn-exec] CRITICAL: runtime stop bookkeeping failed"\n' "$abort_runner"
  535. printf 'echo "[spawn-exec] the runtime returned rc=$ec."\n'
  536. printf 'echo "[spawn-exec] This is NOT the completion signal. An interactive session"\n'
  537. printf 'echo "[spawn-exec] returns to its prompt instead of exiting, so a return code"\n'
  538. printf 'echo "[spawn-exec] here means the runtime stopped, not that the work finished."\n'
  539. printf 'echo "[spawn-exec] COMPLETION IS PROVEN BY TWO THINGS TOGETHER: the terminal"\n'
  540. printf 'echo "[spawn-exec] state file %s carrying THIS spawn id, and the close card."\n' "$state_file"
  541. printf 'echo "[spawn-exec] Either alone is a claim, not a proof."\n'
  542. } > "$runner"
  543. chmod +x "$runner"
  544. # The registry append is serialized under the mission lock. Every fallible artifact
  545. # preparation happens before the append. If the final tmux launch still fails, the EXIT
  546. # trap appends a terminal abort event.
  547. mission_event="$(
  548. jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$m_id" --arg e "$m_op" \
  549. --arg o "$m_owner" --arg st "$m_test" --arg ev "$m_evid" \
  550. --arg pa "${m_parent:-none}" --arg pr "${m_pred:-none}" --arg sid "$mission_spawn_id" \
  551. '{ts:$ts,mission:$m,event:$e,owner:$o,success_test:$st,evidence_form:$ev,parent:$pa,predecessor:$pr,spawn_id:$sid}'
  552. )"
  553. session_binding_event=""
  554. if [ -n "$resume" ]; then
  555. session_binding_event="$(
  556. jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$m_id" \
  557. --arg o "$m_owner" --arg cs "$callsign" --arg sid "$mission_spawn_id" \
  558. --arg session "$resume" --arg journey "$journey" \
  559. '{ts:$ts,mission:$m,event:"correction",owner:$o,outcome:"session_bound",callsign:$cs,binds_spawn_id:$sid,session:$session,journey:$journey}'
  560. )"
  561. fi
  562. exec {mission_lock_fd}>>"$mission_lock"
  563. flock -x "$mission_lock_fd"
  564. printf '%s\n' "$mission_event" >> "$missions"
  565. [ -z "$session_binding_event" ] || printf '%s\n' "$session_binding_event" >> "$missions"
  566. mission_registered=1
  567. flock -u "$mission_lock_fd"
  568. exec {mission_lock_fd}>&-
  569. tmux new-session -d -s "$callsign" -c "$repo" "bash $(printf '%q' "$runner")"
  570. session_started=1
  571. runtime_started=1
  572. pid="$(tmux list-panes -t "$callsign" -F '#{pane_pid}' | head -1)" || {
  573. echo "spawn-exec: session '$callsign' started but its PID cannot be resolved; refusing startup" >&2
  574. exit 7
  575. }
  576. exec_pane="$(tmux list-panes -t "$callsign" -F '#{pane_id}' | head -1)" || {
  577. echo "spawn-exec: session '$callsign' started but its pane cannot be resolved; refusing startup" >&2
  578. exit 7
  579. }
  580. if [ -z "$pid" ] || [ -z "$exec_pane" ]; then
  581. echo "spawn-exec: session '$callsign' returned an empty PID or pane; refusing startup" >&2
  582. exit 7
  583. fi
  584. startup_pane="$exec_pane"
  585. # Tap the pane instead of piping the runtime. This is the only way to keep a transcript of
  586. # an interactive terminal program: a shell pipe on its stdout destroys the terminal it
  587. # needs and the session dies at once.
  588. tmux pipe-pane -t "$callsign" -o "cat >> $(printf '%q' "$log")" 2>/dev/null || {
  589. echo "spawn-exec: WARNING — transcript tap failed for '$callsign'; the executor is live but unlogged" >&2; }
  590. # A detached tmux client returning only proves that a pane was created. The spawn becomes
  591. # successful only after this exact generation publishes an atomic registration receipt and
  592. # the canonical seat points at this exact pane. Without both checks, a rejected child looks
  593. # identical to a live executor at the caller boundary.
  594. startup_state="" startup_reason="" startup_deadline=$(( SECONDS + 10 ))
  595. while [ "$SECONDS" -lt "$startup_deadline" ]; do
  596. if [ -f "$startup_file" ] && [ ! -L "$startup_file" ]; then
  597. if jq -e --arg sid "$mission_spawn_id" \
  598. '.spawn_id == $sid and (.state == "registered" or .state == "refused") and
  599. (.reason | type == "string")' "$startup_file" >/dev/null 2>&1; then
  600. startup_state="$(jq -r '.state' "$startup_file")"
  601. startup_reason="$(jq -r '.reason' "$startup_file")"
  602. break
  603. fi
  604. startup_reason="invalid-or-uncorrelated-startup-receipt"
  605. break
  606. fi
  607. if ! tmux has-session -t "$callsign" 2>/dev/null; then
  608. startup_reason="session-ended-before-registration"
  609. break
  610. fi
  611. sleep 0.1
  612. done
  613. if [ -z "$startup_state" ] && [ -z "$startup_reason" ]; then
  614. startup_reason="startup-receipt-timeout"
  615. fi
  616. if [ "$startup_state" != registered ]; then
  617. echo "spawn-exec: executor '$callsign' refused before Reach registration completed: $startup_reason" >&2
  618. exit 7
  619. fi
  620. if ! tmux has-session -t "$callsign" 2>/dev/null ||
  621. ! jq -e --arg addr "$addr" --arg pane "$exec_pane" \
  622. '.address == $addr and .channel == "tmux" and
  623. .identity == {kind:"tmux-pane", value:$pane}' \
  624. "$seat_dir/reachable.json" >/dev/null 2>&1; then
  625. echo "spawn-exec: executor '$callsign' registered without exact live-pane reachability; refusing startup" >&2
  626. exit 7
  627. fi
  628. runtime_scope=""
  629. runtime_scope_deadline=$(( SECONDS + 5 ))
  630. while [ "$SECONDS" -lt "$runtime_scope_deadline" ]; do
  631. runtime_scope="$(systemctl --user show "$runtime_unit" -p ControlGroup --value 2>/dev/null || true)"
  632. [ -n "$runtime_scope" ] && break
  633. sleep 0.1
  634. done
  635. if [ -z "$runtime_scope" ]; then
  636. echo "spawn-exec: executor '$callsign' registered but its dedicated runtime scope was not created; refusing startup" >&2
  637. exit 7
  638. fi
  639. now_epoch="$(date +%s)"
  640. term_remaining=$(( wall_epoch + budget_s - now_epoch ))
  641. kill_remaining=$(( wall_epoch + grace_s - now_epoch ))
  642. if [ "$term_remaining" -lt 1 ] || [ "$kill_remaining" -le "$term_remaining" ]; then
  643. echo "spawn-exec: startup consumed the executor wall budget before the controller could be armed; refusing startup" >&2
  644. exit 7
  645. fi
  646. if ! systemd-run --user --quiet --collect --unit="$wall_unit" \
  647. bash "$WALL_CONTROLLER" --spawn-id "$mission_spawn_id" \
  648. --term-after "$term_remaining" --kill-after "$kill_remaining" \
  649. --events "$wall_events"; then
  650. echo "spawn-exec: could not arm the external wall controller; refusing startup" >&2
  651. exit 7
  652. fi
  653. wall_started=1
  654. if ! systemctl --user is-active --quiet "$wall_unit"; then
  655. echo "spawn-exec: external wall controller did not remain active; refusing startup" >&2
  656. exit 7
  657. fi
  658. # Registration is now externally visible and correlated to this pane. Transfer ownership
  659. # of the seat and session to the running executor before recording or announcing success.
  660. flock -u "$seat_lock_fd"
  661. exec {seat_lock_fd}>&-
  662. seat_lock_fd=""
  663. session_started=0
  664. wall_started=0
  665. runtime_started=0
  666. spawn_ok=1
  667. # The initial owned scopes are evidence, not the controller's discovery boundary. The exact
  668. # spawn marker lets the controller find normally inherited nested scopes again at TERM and KILL.
  669. pane_scope=""
  670. [ -z "$exec_pane" ] || pane_scope=$(sed 's|^0::||' "/proc/$pid/cgroup" 2>/dev/null | head -1 || true)
  671. printf '{"ts":"%s","pid":%d,"callsign":"%s","journey":"%s","repo":"%s","budget_h":%s,"class":"%s","t_budget":"%s","t_grace":"%s","ack_due":"%s","conv_due":"%s","fence":"%s","log":"%s","resume":"%s","runtime":"%s","addr":"%s","pane":"%s","state_file":"%s","spawn_id":"%s","pane_scope":"%s","runtime_scope":"%s","runtime_unit":"%s","wall_unit":"%s","wall_events":"%s"}\n' \
  672. "$(date -Is)" "$pid" "$callsign" "$journey" "$repo" "$budget_h" "$jclass" \
  673. "$t_budget" "$t_grace" "$t_ack" "$t_conv" "$(sane "$fence")" "$log" "$resume" \
  674. "$runtime" "$addr" "$(sane "$exec_pane")" "$log.state" "$mission_spawn_id" \
  675. "$(sane "$pane_scope")" "$(sane "$runtime_scope")" "$runtime_unit" "$wall_unit" \
  676. "$(sane "$wall_events")" >> "$SPAWNS"
  677. echo "spawned callsign=$callsign pid=$pid runtime=$runtime addr=$addr pane=$exec_pane budget=${budget_h}h T='$t_budget' WALL='$t_grace' log=$log state=$log.state"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.