sno-ai
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
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
Markdown
[](/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
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
- {
- "name": "sno-ai",
- "owner": {
- "name": "Sno Station Skills contributors"
- },
- "metadata": {
- "description": "Sno Station skills for coding agents."
- },
- "strict": false,
- "plugins": [
- {
- "name": "sno-station",
- "description": "Every Sno Station skill. Most need the Sno Station programs that `sno setup` installs.",
- "source": "./",
- "strict": false,
- "skills": [
- "./skills/H-reporting-and-visibility/agentic-time-estimate/skill",
- "./skills/H-reporting-and-visibility/away-brief/skill",
- "./skills/H-reporting-and-visibility/catch-report/skill",
- "./skills/J-peer-review-and-audit/agentic-walkthrough/skill",
- "./skills/J-peer-review-and-audit/cross-vendor-security-audit/skill",
- "./skills/J-peer-review-and-audit/e2e/skills/e2e-environment-preflight",
- "./skills/J-peer-review-and-audit/e2e/skills/e2e-red-triage",
- "./skills/J-peer-review-and-audit/first-principles-review/skill",
- "./skills/J-peer-review-and-audit/less-is-more/skill",
- "./skills/J-peer-review-and-audit/owner-intent-audit/skill",
- "./skills/J-peer-review-and-audit/peer-review/skill",
- "./skills/J-peer-review-and-audit/test-writer/skill",
- "./skills/M-build-and-rollout/codex-coder/overlay/claude",
- "./skills/M-build-and-rollout/medic/skill",
- "./skills/M-build-and-rollout/python-coder/skill",
- "./skills/M-build-and-rollout/rust-coder/skill",
- "./skills/M-build-and-rollout/shellscript-coder/skill",
- "./skills/M-build-and-rollout/sno-cli/skill",
- "./skills/M-build-and-rollout/ts-coder/skill",
- "./skills/R-recursive-self-improvement/rem-reflect/skill",
- "./skills/S-communication-and-handoff/handoff/skill",
- "./skills/S-communication-and-handoff/heartbeat/skill",
- "./skills/S-communication-and-handoff/join-talk/skill",
- "./skills/S-communication-and-handoff/reach/skill",
- "./skills/S-communication-and-handoff/rotate-agent/skill",
- "./skills/S-communication-and-handoff/subscription-quota-check/skill",
- "./skills/S-communication-and-handoff/tag-team/skill",
- "./skills/T-delegation-and-work-orders/charter/skill",
- "./skills/T-delegation-and-work-orders/cos/skills/cos",
- "./skills/T-delegation-and-work-orders/cos/skills/cos-evolve",
- "./skills/T-delegation-and-work-orders/cos/skills/cos-review",
- "./skills/T-delegation-and-work-orders/cos/skills/cos-watch",
- "./skills/T-delegation-and-work-orders/deliver/skill",
- "./skills/T-delegation-and-work-orders/pl/skills/pl",
- "./skills/T-delegation-and-work-orders/pl/skills/pl-analyze",
- "./skills/T-delegation-and-work-orders/pl/skills/pl-audit",
- "./skills/T-delegation-and-work-orders/pl/skills/pl-dispatch",
- "./skills/T-delegation-and-work-orders/pl/skills/pl-env",
- "./skills/T-delegation-and-work-orders/pl/skills/pl-watch"
- ]
- },
- {
- "name": "sno-station-standalone",
- "description": "Sno Station skills that run without Sno Station programs and without hooks.",
- "source": "./plugins/sno-station-standalone",
- "skills": [
- "./skills/agentic-walkthrough",
- "./skills/e2e-environment-preflight",
- "./skills/e2e-red-triage",
- "./skills/first-principles-review",
- "./skills/less-is-more",
- "./skills/owner-intent-audit",
- "./skills/charter",
- "./skills/shellscript-coder",
- "./skills/ts-coder",
- "./skills/python-coder",
- "./skills/rust-coder",
- "./skills/test-writer"
- ]
- }
- ]
- }
README.md · README · 656 lines · 1 finding marked
- # Sno Station Skills — The working habits of a real team, installed into your AI agents.
- 
- [](LICENSE)
- 
- 
- 
- Find out more on our website, [sno.ai](https://sno.ai).
- ## Install
- ### All skills with Sno Station
- Copy this prompt into your agent's chat:
- ```text
- 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:
- ```bash
- curl -fsSL https://sno.ai/install | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 28 on GitHub
- ```
- **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.
- ```text
- 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.
- ```text
- 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.
- ```text
- 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:
- ```bash
- claude plugin marketplace add sno-ai/sno-station-skills
- claude plugin install sno-station@sno-ai
- ```
- Codex:
- ```bash
- 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 changes for you
- You keep working exactly as before, in whichever agent you like. Then:
- 1. **You finish a change and want it checked.** Say "peer-review this". A reviewer from the other
- vendor reads it cold, reports what would break in real use, and the author fixes the root
- cause, round after round, until the review comes back clean.
- 2. **You start a long run before bed.** Say "arm rotate-agent". If the working agent's quota
- drops to the threshold overnight, it hands the task to a fresh agent from the other vendor,
- with the brief verified before a single file is touched.
- 3. **You come back.** Say "away brief". One page, at most 60 lines: what got done, what is
- stuck and why, what waits for your answer, and what it cost in quota.
- 4. **You have a job for someone else.** Say "write a charter". You get one file that says what
- to deliver, what is out of bounds, what you already decided, and how each success check will
- be proven. Any agent can then `deliver` it, and every check is proven by a recorded real run.
- 5. **Every night, the team looks back.** The nightly loop reads the day's Claude Code and Codex
- sessions, finds the mistakes that repeat, and proposes lessons and skill changes. In the
- morning you accept the ones you like with `sno rem-reflect accept <id>`. Nothing changes
- without that accept.
- ## Why these skills
- One AI agent is a brilliant new hire with no colleagues. It reviews its own work, so it misses
- what it cannot see. It stops dead when its quota runs out, at 3 a.m., halfway through your
- build. It says "done" when the tests are green and nothing actually happened. It builds three
- layers of machinery you never asked for. And tomorrow it makes the same mistake it made today,
- because nobody told it otherwise.
- **Sno Station Skills fixes the team, not the model.** These are the skills
- [Sno Station](https://github.com/sno-ai/sno-station) installs into the agents you already
- run. They give Claude Code and Codex the habits every good engineering team has: a second pair
- of eyes from a different vendor, a clean handover when someone has to leave, a lead who hands
- out work with a written definition of done, a one-page brief when you come back, and a
- retrospective every night that turns this week's mistakes into next week's rules.
- **Dual Brain: different roles, one team.** One agent carries out your task. The other reviews
- the result against your requirements. Claude Code and Codex can take either role. When both
- CLIs are installed, the review runs in the other vendor's CLI, in a fresh session with none of
- the author's conversation. The agents exchange findings and corrections. Add more roles, and
- you have an Agent Squad.
- **Work that finishes while you sleep.** Arm it before bed, and when the working agent's
- subscription runs low it writes a handover brief while it still can, wakes an agent from the
- other vendor, and hands the task over with the exact commit to continue from. Your build does not care which vendor finished it.
- **"Done" means proven.** Every task can carry a written list of success checks, each one
- answered pass or fail by a real run. Nothing counts as done because an agent said so.
- **Tested before it ships.** Every skill in a release passed its own self-tests on a clean copy,
- was scanned for personal paths and leftovers, and carries a stamp that says so. A skill that
- fails is not published.
- 
- ## The pain, and what fixes it
- *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.
- | What people said this week | What fixes it | Where |
- |---|---|---|
- | “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` |
- | “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` |
- | “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` |
- | “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` |
- | “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` |
- | “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` |
- | “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 |
- | “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 |
- | “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) |
- | “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 |
- 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.
- ## "I went to bed. It changed shifts."
- *From Sno Station's own repository, 2026-09-18.*
- 
- One of our agents was twenty-one tasks into a twenty-seven-task build when its weekly quota
- reached 2%. It did not wait to die. It wrote a handover brief: what was done, what was
- half-done, the exact commit to continue from. Then it woke an agent from the other vendor and
- would not let it touch anything until the brief was verified. Fourteen minutes and forty-one
- seconds after the handover began, the second agent was working and the first signed off with
- 1% left. The second agent continued from the first unchecked task, not from the beginning.
- That night ran on the same four skills that ship here: `subscription-quota-check` read the quota
- without spending it, `heartbeat` took a reading every five minutes, `rotate-agent` decided when
- and to whom, and `handoff` moved the work. Every quota reading, both versions of the brief and
- the commit summary are published in
- [Sno Station's evidence folder](https://github.com/sno-ai/sno-station/tree/main/docs/evidence/rotation-2026-09-18).
- ## "In months, the other one has never once said 'looks good.'"
- Claude Code has reviewed Codex's work, and Codex has reviewed Claude Code's, on Sno Station's
- own repository for months. Not one review has come back empty. We used to think that meant the
- work was bad. It means one reviewer from one vendor is never enough.
- That is what `peer-review` is for, and `catch-report` puts numbers on it: how many problems the
- second model caught, next to how many the agents caught in their own work, kept apart and never
- added together.
- ## "I yelled at my agent last night. It took notes."
- 
- The nightly loop is the `rem-reflect` skill. On its first night on our machine, the two things
- the owner had been frustrated about that evening were rules in the live skills by morning,
- after the owner accepted them; nobody typed them in. The next night it fired on its own at
- 00:58, read 113 sessions, and measured the three skills it had changed the day before: failures
- in all three had dropped to zero.
- 
- ## The skills
- 39 skills, shipped as 30 units, filed under six things a team has to be able to do. A unit is
- one skill or a small family that installs together. The full index with links is
- [skills/README.md](skills/README.md).
- | | Category | What your agents can do with it |
- |---|---|---|
- | **J** | [Peer Review & Audit](#j--peer-review--audit) | Check each other's work, and refuse to call anything done until it is proven. |
- | **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. |
- | **S** | [Communication & Handoff](#s--communication--handoff) | Message each other, and take over with full context when one has to stop. |
- | **H** | [Reporting & Visibility](#h--reporting--visibility) | Show you what got done, what got caught, and what it cost. |
- | **T** | [Delegation & Work Orders](#t--delegation--work-orders) | Hand out work with a written definition of done, and lead other agents. |
- | **R** | [Retrospective & Improvement](#r--retrospective--improvement) | Learn from their own mistakes, with you approving every change. |
- ### J · Peer Review & Audit
- *Colleagues review each other's work, and nothing counts as done until it passes audit.*
- #### [peer-review](skills/J-peer-review-and-audit/peer-review/) — a reviewer from the other vendor, and a fix loop until it is clean
- - **Truly independent.** The review runs in a fresh session with none of the author's
- conversation, and prefers the other vendor's CLI. With only one CLI installed it still runs,
- in a fresh session, and says on its first line that it was a same-vendor review.
- - **Hunts what actually costs you.** It walks the ordinary path first, with the real inputs your
- system produces, before it spends a minute on exotic edge cases. Data loss, silent wrong
- results and broken main flows come first; style is not on the list.
- - **Every finding has to earn its place.** Each one states how a real user reaches it, what
- breaks, and an honest attempt to refute it. Nothing the reviewer says is dropped or softened;
- a suspected false positive is labelled, not hidden.
- - **Cuts before it adds.** It lists what the change added that nobody needed, first, and keeps
- "must fix now" apart from "also found", so a review never turns into a pile of new code.
- - **Works on documents too.** Specs, plans and migration manifests get a structured report:
- what would make an implementer ship the wrong thing.
- *Use it when:* you finished a change, a plan or a spec and want it checked before it lands.
- #### [less-is-more](skills/J-peer-review-and-audit/less-is-more/) — the least code that works, and a knife for the rest
- - **Climbs a ladder before writing a line:** is it needed at all, is it already in the
- repository, does the standard library do it, does the platform do it, does an installed
- dependency do it. Only then the minimum code that works.
- - **Cuts what an agent over-built:** one-implementation interfaces, config knobs for values that
- never change, scaffolding "for later", checks and gates that block the real work.
- - **Spends your test budget wisely:** the smallest test that proves the change, not a full suite
- run as reassurance.
- - **Runs both ways by itself:** "write" or "fix" builds, "review" or "simplify" cuts, and after
- building it cuts its own diff before handing it over.
- *Use it when:* any coding task, or when you say "too complex" or "what can we delete".
- #### [owner-intent-audit](skills/J-peer-review-and-audit/owner-intent-audit/) — is this what you actually meant?
- - **Checks meaning, not wording.** A plan can keep all your nouns and still describe a
- different product. This catches a condition that became unconditional, an example that
- became the whole boundary, a prohibition that quietly disappeared.
- - **Finds the debts agents leave behind:** work nobody asked for, documents that no longer match
- reality, decisions nobody can reach, and "done" claims with no evidence behind them.
- - **Plans and code alike:** requirement documents, designs, task lists, test plans, or a diff an
- agent wrote.
- *Use it when:* before you approve a plan or merge an agent's work.
- #### [agentic-walkthrough](skills/J-peer-review-and-audit/agentic-walkthrough/) — everything says "success", and you still are not sure
- - **For the quiet failure no test catches:** a job that starts, finishes, writes a trace, passes
- its own checks, and touches nothing.
- - **Takes the program's seat:** walks the path hop by hop, finding every switch, default and
- fallback that can turn the work into a silent no-op.
- - **Makes each hop prove itself** with one narrow observation that only the real thing could
- produce: the stored row, the database file actually opened, the API call that actually left.
- *Use it when:* a run reports success and you need proof it did the work.
- #### [first-principles-review](skills/J-peer-review-and-audit/first-principles-review/) — challenge the idea before it becomes code
- - **Researches first,** then re-derives what you actually need without borrowing the proposed
- solution.
- - **Sorts every constraint** into hard limit, owner preference, or inherited habit, and tests
- every load-bearing assumption against evidence.
- - **Ends with one clear verdict:** proceed, reframe, simplify, replace, split, test first, or
- stop, plus a recommended direction and the evidence that would overturn it.
- - **Hands off cleanly:** a written report and a structured summary ready for whoever writes the
- requirements next.
- *Use it when:* a design or product idea is about to harden into a plan. You start it by name.
- #### [e2e](skills/J-peer-review-and-audit/e2e/) — end-to-end runs that fail for real reasons only
- - **`e2e-environment-preflight`** checks the external services, hosts, browser sessions, model
- endpoints and agents before the first test runs, so a long suite never fails on a dead
- dependency.
- - **`e2e-red-triage`** handles the rare failure the checks could not predict. It stops the
- guessing and splits the result into its two halves (accepted versus done, stopped versus
- crashed, empty versus unreadable), then decides: product bug, or a new environment check.
- *Use it when:* you run end-to-end suites against real services.
- #### [test-writer](skills/J-peer-review-and-audit/test-writer/) — tests that can actually go red
- - **Real over mocked:** the real parser, filesystem, database or service whenever the repo can
- provide it; a mock never stands in for the thing being tested.
- - **Every assertion can fail:** it checks returned content, saved state and real side effects,
- not call counts, and never loosens an assertion to make a test pass.
- - **Runs what it wrote, nothing more:** the narrowest command for the changed test, not the
- whole suite, and the report says what ran and what it showed.
- *Use it when:* you ask an agent to write or fix tests, fixtures or evals. It works on its own,
- without Sno Station.
- #### [cross-vendor-security-audit](skills/J-peer-review-and-audit/cross-vendor-security-audit/) — a security audit that rereads what it threw away
- **Three Claude passes missed a published high-severity bug. One Codex pass over what Claude
- threw away found it.** On this bug every extra Claude pass repeated Claude's own reason for
- dropping it; the second vendor brought a different one.
- We audited follow-redirects 1.16.1, which has a known bug
- ([GHSA-mrwp-f3q8-3g9p](https://github.com/advisories/GHSA-mrwp-f3q8-3g9p), high, fixed in 1.16.2):
- a list of secret headers built in another JavaScript realm is treated as empty, so the caller's
- API key follows a redirect to another host.
- - Claude, first audit: never saw it.
- - Claude, second audit: saw it, then filed it as "hardening, not a finding".
- - A fresh Claude rereading everything set aside: agreed, "caller misuse".
- - Codex, auditing alone: never saw it.
- - **Codex rereading what Claude set aside: disagreed, traced it through the source, and sent it
- back for validation.**
- That last step is what this skill adds to Cloudflare's security-audit skill (used under its MIT
- license; same audit, evidence bar, validators and report). Before the report, a model from the
- other vendor rereads every item the audit set aside, read-only, and must answer every one;
- anything it brings back is validated again. If validation rejects it again, the report lists it
- under "Reviewers disagree" with both reasons, and you decide.
- Two projects, three known bugs: a story, not a rate. On the other project either vendor's
- reviewer recovered the bug. When Claude's first audit never looked at the bug, the reread of
- that audit did not find it either.
- *Use it when:* you want a full security audit of a codebase. With Sno Station it picks the
- other-vendor reviewer that still has quota; without it, it calls Codex from Claude Code or
- Claude Code from Codex, and says so when only one vendor was available.
- ### M · Build & Rollout
- *Get the team set up on any workstation with one step, build what the work needs, then roll it out to every machine.*
- Setup itself is the `sno setup` command, not a skill. Two of these keep the machine healthy and
- make the `sno` command easy for your agents to drive; the rest write the code: one hands it to
- Codex, four write it in Shell, TypeScript, Python or Rust.
- #### [medic](skills/M-build-and-rollout/medic/) — is my agent team healthy? One line per answer.
- - **Checks everything a team needs** in about ten seconds: tools installed, skills installed,
- skill commands runnable, hooks configured, messaging live, both vendors' quota readable, temp
- space free.
- - **Every problem comes with its fix:** `WARN` or `FAIL`, what is wrong, and the exact command
- that fixes it.
- - **Reads, never touches.** It installs, repairs, starts and stops nothing. You decide what to
- fix.
- *Use it when:* on a new machine, when agents stop reaching each other, or when a long run will
- not start.
- #### [sno-cli](skills/M-build-and-rollout/sno-cli/) — your agent drives `sno` correctly the first time
- - **Never out of date:** the agent reads the exact commands and flags from the installed `sno`
- itself, not from memory.
- - **A task map and recipes** for install, update, health checks, accounts, skills and the
- nightly loop.
- - **Your choices stay yours:** it operates the tool, it does not decide your settings for you.
- *Use it when:* you ask an agent to install, update, check or configure Sno.
- #### [codex-coder](skills/M-build-and-rollout/codex-coder/) — Claude plans, Codex writes the code
- - **One session, two vendors:** Claude Code keeps the plan and the conversation and starts a
- plain `codex exec` run for the coding, so the expensive model is not the one typing.
- - **Picks the language for you:** Shell, TypeScript, Python or Rust, from the files the task
- touches; a language skill of yours is used when it is installed.
- - **A stalled run is caught:** Claude Code is told about progress while the run works, and a
- run that has written nothing for 15 minutes is killed and started once more.
- *Use it when:* your Claude quota runs out halfway through the coding, or you want Codex to
- write what Claude planned. On the Claude Code side it needs Sno Station's `heartbeat`.
- #### [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
- - **Reads before it writes:** the repo's own runtime, versions, helpers, callers and tests come
- first, so the new code looks like the code around it.
- - **Small on purpose:** no compatibility shims, no options nobody asked for, no helper that
- already exists two files over.
- - **Done means a command passed:** every claim in the report traces to a check it actually ran
- in your repo; it never reports done over a failing check.
- *Use it when:* you want an agent to write or change production code in one of those four
- languages. They work on their own, without Sno Station, and `codex-coder` picks the right one
- for each task.
- ### S · Communication & Handoff
- *People talk through a shared inbox, and when one is out the other takes over with full context.*
- These skills run on Sno Reach, the messaging layer Sno Station installs: each agent gets an
- address, sends stored messages to other agents' inboxes, and can wake another agent to read
- them. No daemon, no server.
- #### [handoff](skills/S-communication-and-handoff/handoff/) — hand a task over without losing a thing
- - **Captures the whole state:** what is done, what is half-done, uncommitted changes, the
- decisions you already made, and what is out of bounds.
- - **The receiver writes nothing until the release is verified,** so two agents never edit the
- same work at once.
- - **The sender really leaves.** After release it stops; there is no second owner hovering.
- - **Works even when the sender is already gone** (quota refused, crash, closed window): the
- `sno handoff-checkpoint` progress record lets a fresh agent continue from the first
- unfinished task.
- *Use it when:* one agent must give its task to another.
- #### [rotate-agent](skills/S-communication-and-handoff/rotate-agent/) — never lose a long run to a quota limit again
- - **Acts while the sender is still alive.** It watches the remaining quota every few minutes and
- hands over at a threshold, not after the refusal, when it is too late to write a brief.
- - **Either direction:** Codex to Claude Code, or Claude Code to Codex.
- - **Bounded:** it fires once, and you can limit how long the watch runs.
- - **A safety net for missed windows:** if the window was missed, `sno rotate-agent-resume`
- starts the replacement from the progress record on disk.
- *Use it when:* a long run must finish even if one vendor's quota runs out. Needs both CLIs
- logged in and tmux.
- #### [subscription-quota-check](skills/S-communication-and-handoff/subscription-quota-check/) — how much quota is left, without spending any
- - **Stops the worst habit:** finding out you are out of quota by making a real call and reading
- the error.
- - **Reads Claude Code and Codex together** in about eight seconds, and tells you when the quota
- resets.
- - **Honest about stale numbers:** it checks whether the reading is current or last-known, and
- says which.
- - **Never polls on its own,** so it never earns a rate limit of its own.
- *Use it when:* you ask, or right after a vendor refused work.
- #### [heartbeat](skills/S-communication-and-handoff/heartbeat/) — progress reports from long runs, delivered into the conversation
- - **Two shapes:** report every N minutes (training, a long build, a generation queue), or watch
- until something finishes.
- - **Ticks land where you are:** each reading arrives in the agent's conversation, not in a log
- nobody reads.
- - **Hard to misuse:** intervals are in minutes, and a seconds-sized number is refused instead of
- silently waking your agent every few seconds.
- *Use it when:* something long is running unattended and you want to hear from it.
- #### [reach](skills/S-communication-and-handoff/reach/) — agents talk to each other
- - **Start a Claude Code or Codex agent** with its own address and working folder.
- - **Send work and read replies** through stored messages, or talk to a live agent right now.
- - **Messages carry no extra authority:** a message never widens the task you gave.
- *Use it when:* one agent needs to contact, start or wait on another.
- #### [join-talk](skills/S-communication-and-handoff/join-talk/) — make any agent reachable in one command
- - **One line out:** `joined <address>`. Tell other agents that address and they can reach this
- terminal.
- - **Safe to repeat:** running it again from the same terminal changes nothing.
- - **Clear refusals:** when it cannot work, it says exactly why.
- *Use it when:* you opened an agent by hand and want others to reach it.
- #### [tag-team](skills/S-communication-and-handoff/tag-team/) — two agents on one task, one builds and one reviews
- - **One command:** `sno reach pair "the task"` starts both agents in the current folder, each
- in a tmux window you can open and watch.
- - **Argued over before it reaches you.** The reviewer reads the result and the changed files
- and answers with concrete defects or an explicit no-defect result; the two keep exchanging
- fixes and reviews between themselves, and your agent asks the reviewer before calling it clean.
- - **Says what kind of review you got.** Signed in to two vendors, the review comes from the
- other one. Signed in to one, the pair still runs and tells you the review stayed inside it.
- - **Does not call it clean too early.** A first review with findings is reported as open; no
- third reviewer, and no second pair because the first review had not arrived yet.
- *Use it when:* a task is worth a second opinion and you do not want to carry it between agents.
- ### H · Reporting & Visibility
- *Everyone can see what got done, who caught what, who covered for whom, what's in progress.*
- #### [away-brief](skills/H-reporting-and-visibility/away-brief/) — one page when you come back
- - **Four sections, at most 60 lines:** Done, Stuck, Needs you, Spend.
- - **What waits for you is never pushed off the page** by a long list of finished work.
- - **"Done" is only what is real:** in git, in a delivered work order, or in a finished progress
- record. Not what an agent said.
- - **Shows what the night cost:** run `sno away-brief mark` before you leave, and the next page
- shows the quota spent since.
- *Use it when:* after sleep, a meeting, or a long unattended run.
- #### [catch-report](skills/H-reporting-and-visibility/catch-report/) — is the second agent worth it? Here are the numbers.
- - **Two counts, side by side:** problems the other model caught in review, and moments when an
- agent caught its own mistake.
- - **Never inflated:** the two are kept apart, never added together, and when a part could not be
- measured it says so instead of reporting zero.
- - **Quotes the biggest catches** by title, from the review records already on your machine.
- *Use it when:* you want the week's review results, or need to justify running two agents.
- #### [agentic-time-estimate](skills/H-reporting-and-visibility/agentic-time-estimate/) — real estimates for agent work
- - **Agent wall time, not human-developer time:** how long this will take an agent, and how much
- longer the running job needs, measured before guessed.
- - **Clock times you can trust:** every time shown to you comes from `sno report-time`, in your
- own zone with UTC beside it.
- *Use it when:* you ask "how long?" or "when will it be done?"
- ### T · Delegation & Work Orders
- *A lead delegates work as work orders, and decides who takes each job.*
- #### [charter](skills/T-delegation-and-work-orders/charter/) — one file that says what done means
- - **Keeps your words.** It never invents a decision, a fact or a requirement, and asks one
- question at a time only when the answer would change the outcome.
- - **Success checks you can run:** each one names what will be observed, where and how, and is
- answered pass or fail.
- - **No ceremony:** nothing goes in unless someone can name the failure it catches.
- - **Any kind of project:** software, documents, campaigns, research, operations.
- *Use it when:* work needs a written brief before someone else does it.
- #### [deliver](skills/T-delegation-and-work-orders/deliver/) — carry a charter to a proven result
- - **The charter's checks are the definition of done,** and nothing else is.
- - **Every check proven by a recorded real run,** tracked with `sno deliver-proof`.
- - **One independent review,** then an honest close: what passed, what did not, and why.
- - **Picks up where someone else stopped:** if an earlier agent left a progress record, it
- continues from the next unfinished step instead of starting over.
- *Use it when:* a charter is released and someone has to do it.
- #### [pl](skills/T-delegation-and-work-orders/pl/) — a Project Lead agent for one line of work
- - **Runs up to four executor agents,** one charter each, serially or in parallel.
- - **A family of five more skills:** `pl-dispatch` opens and schedules the work, `pl-watch`
- supervises agents in flight, `pl-audit` checks acceptance before anything closes, `pl-env`
- fixes the environment the work runs in, and `pl-analyze` writes the root-cause analysis when
- something goes wrong.
- *Use it when:* one project needs several agents working under one lead. You start it by name.
- #### [cos](skills/T-delegation-and-work-orders/cos/) — a Chief of Staff: the one agent you talk to
- - **One conversation for you,** in your language. It coordinates one to three Project Leads in
- parallel and brings you only the hard decisions: money, direction, red lines.
- - **A family of three more skills:** `cos-watch` keeps every Project Lead alive and on schedule,
- `cos-review` reviews the night's decisions in one pass when you come back, and `cos-evolve`
- turns management failures that repeat into enforced rules.
- *Use it when:* you run several workstreams and want one point of contact. You start it by name.
- ### R · Retrospective & Improvement
- *The team looks back at its own work and turns lessons into rules and better practice.*
- #### [rem-reflect](skills/R-recursive-self-improvement/rem-reflect/) — the nightly loop: your agents learn from their own sessions
- - **Once a day,** it reads this machine's Claude Code and Codex sessions, finds the failures and
- corrections that repeat, and turns them into lessons and proposed skill changes.
- - **You approve everything:** `sno rem-reflect accept`, `reject` or `tbd` for each one. Nothing
- changes without your accept.
- - **Lessons come back when they matter:** an accepted lesson is shown to the agent at the start
- of the next session, for this project or for all of them.
- - **You choose what leaves the machine.** In `local-first` mode nothing is sent to Sno; a few of
- the night's sessions go only to your own Claude Code or Codex account to draft the lessons.
- In the other two modes, at their default sharing level, it uploads session text (common secrets redacted first, best effort)
- and your installed skills to Sno's cloud for stronger judgments. Turn uploading off at any
- time with `sno station consent off`. The skill lists exactly what it reads and sends.
- The family skills `pl-analyze` (incident analysis for the Project Lead) and `cos-evolve`
- (repeated failures into rules) also belong here; they ship with `pl` and `cos`.
- *Use it when:* always on, once `sno setup` has armed the daily run.
- ## Built to be trusted
- Every unit in a release passed the same checks before it was published:
- 1. the repository carries its `LICENSE` and `NOTICE`;
- 2. the unit is copied whole, with its family members and per-agent differences intact;
- 3. nothing personal survives: no home paths, owner names, internal hosts or hard-coded models,
- and no Chinese, Japanese or Korean characters;
- 4. every skill's header parses, and its declaration of what it needs from the agent is valid;
- 5. each skill's own self-tests pass on that clean copy, not on the author's machine;
- 6. a stamp, `PUBLISHED.json`, is written last with the self-test count and digests of the
- contract and the payload.
- A skill that fails a check is not published. The stamp is written by the publish step, never by
- hand. All skill text is in English, and your agent follows it in whatever language you talk to
- it in.
- ## For skill authors
- ### Layout
- ```
- skills/
- README.md the category index
- <category>/<unit>/
- skill/ one skill: SKILL.md, references/, scripts/
- skills/<member>/ or a family of skills that ship together
- overlay/claude|codex/ per-agent differences, when a skill needs them
- public-bin/ one file per `sno <file name>` command the skill provides
- PUBLISHED.json the stamp written by the publish step
- registry.yaml unit -> category code (and tier)
- scripts/
- requirements-contract.json the contract every requires: block is checked against
- LICENSE Apache-2.0
- ```
- Category codes are fixed, in this order: J M S H T R. They appear in directory names and in
- `registry.yaml`.
- ### Declaring what a skill needs
- Every `SKILL.md` starts with a `requires:` block. `sno setup` reads it to decide, per agent,
- whether to install the skill:
- ```yaml
- requires:
- programs: [reach] # Sno Station programs the skill calls
- harness:
- - {slot: 4.shell, need: required} # what the agent itself must be able to do
- ```
- - **programs** are Sno Station programs installed next to the skills and run as `sno <name>`:
- `reach`, `heartbeat`, `subscription-quota-check`, `report-time`.
- - **slots** name an agent ability: `4.shell` (run shell commands), `4.file-read-write` (read and
- write files), `4.background-processes` (run a command in the background),
- `2.pre-turn-context-injection` (add text to the agent's context before each turn) and
- `3.reader-to-agent-delivery` (output of a background reader reaches the agent).
- - **need** is `required` (an agent without the slot does not get the skill), `preferred` (the
- skill is installed and works in a reduced way) or `optional` (only a convenience).
- ## License
- 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
- #!/usr/bin/env bash
- # exec-trust.sh — answer Claude Code's first-run screens before an executor meets them.
- #
- # Claude Code stops in a directory it has never seen with a question ("Is this a project
- # you created or one you trust?"). An unattended executor waits there forever: it looks
- # alive, holds its window, and never reads its inbox. There are three first-run screens:
- # 1. the folder-trust question, which waits forever;
- # 2. the bypass-permissions warning, whose default answer is Exit, so a blind Enter kills
- # the session;
- # 3. the onboarding theme picker, which appears once the first two are answered.
- #
- # WHAT THIS CHANGES ON YOUR MACHINE (read before running). It edits the Claude Code config
- # file `<config-dir>/.claude.json` (default: ~/.claude.json, or $CLAUDE_CONFIG_DIR):
- # - sets bypassPermissionsModeAccepted=true and hasCompletedOnboarding=true GLOBALLY, for
- # every project and every future Claude Code session of that user, not only this
- # checkout;
- # - sets hasTrustDialogAccepted and hasCompletedProjectOnboarding for the given repo;
- # - records the installed claude version as lastOnboardingVersion.
- # Keys are only added or overwritten, never removed. Executors launched by spawn-exec.sh
- # with --runtime claude run `claude --dangerously-skip-permissions` (and codex runs with
- Note: Starts a coding agent with its permission prompts off
- Line 20 on GitHub
- # --dangerously-bypass-approvals-and-sandbox): no permission prompts and no sandbox. Use
- # --check to see whether a directory is already pre-answered without changing anything.
- # Pass --config-dir to use a separate config directory instead of your own.
- #
- # Run this against the existing checkout selected for the executor; this command
- # never creates that checkout:
- #
- # bash "${PL_SKILL_DIR}/scripts/exec-trust.sh" --repo "$checkout"
- # bash "${PL_SKILL_DIR}/scripts/spawn-exec.sh" --repo "$checkout" --runtime claude ...
- #
- # usage: exec-trust.sh --repo <absolute path> [--config-dir <dir>]
- # exec-trust.sh --check --repo <absolute path> [--config-dir <dir>]
- # exit: 0 every first-run screen is pre-answered · 1 (--check only) not · 64 usage · 65 refused
- set -Eeuo pipefail
- repo='' config_dir="${CLAUDE_CONFIG_DIR:-$HOME}" mode=set
- while (($# > 0)); do
- case "$1" in
- --repo) repo="${2:-}"; shift 2 ;;
- --config-dir) config_dir="${2:-}"; shift 2 ;;
- --check) mode=check; shift ;;
- -h|--help) sed -n '2,/^# exit:/p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
- *) printf 'exec-trust: unsupported option: %s\n' "$1" >&2; exit 64 ;;
- esac
- done
- [[ -n "$repo" ]] || { printf 'exec-trust: --repo <absolute path to the checkout> is required\n' >&2; exit 64; }
- # The config keys the runtime on the absolute path it is started in; a relative path
- # would write a key nothing matches.
- [[ "$repo" == /* ]] || { printf 'exec-trust: --repo must be absolute, got: %s\n' "$repo" >&2; exit 64; }
- [[ -d "$repo" ]] || { printf 'exec-trust: no such directory: %s\n' "$repo" >&2; exit 65; }
- command -v jq >/dev/null 2>&1 || { printf 'exec-trust: jq is required\n' >&2; exit 69; }
- config="$config_dir/.claude.json"
- if [[ "$mode" == check ]]; then
- [[ -f "$config" ]] || { printf 'exec-trust: no config at %s — every first-run screen would appear\n' "$config" >&2; exit 1; }
- jq -e --arg p "$repo" \
- '(.bypassPermissionsModeAccepted == true) and (.hasCompletedOnboarding == true)
- and (.projects[$p].hasTrustDialogAccepted == true)' \
- "$config" >/dev/null 2>&1 || {
- printf 'exec-trust: %s is not pre-answered for %s\n' "$config" "$repo" >&2; exit 1; }
- printf 'exec-trust: every first-run screen is pre-answered for %s\n' "$repo"
- exit 0
- fi
- mkdir -p -- "$config_dir"
- lock="$config_dir/.claude.json.exec-trust.lock"
- exec 9>>"$lock" || { printf 'exec-trust: cannot take the config lock at %s\n' "$lock" >&2; exit 65; }
- flock 9 || { printf 'exec-trust: cannot lock %s\n' "$lock" >&2; exit 65; }
- # The runtime writes this file too, so this is a read-modify-write under a lock that only
- # adds keys, written to a temporary file and renamed, so concurrent changes are not lost.
- current='{}'
- if [[ -f "$config" ]]; then
- current="$(cat -- "$config")"
- jq -e . <<<"$current" >/dev/null 2>&1 || {
- printf 'exec-trust: %s is not valid JSON; refusing to touch it\n' "$config" >&2
- exec 9>&-; exit 65; }
- fi
- # The onboarding version is read from the binary that will run; a stale value makes the
- # runtime re-run onboarding (the theme picker returns).
- onboarding_version=''
- if command -v claude >/dev/null 2>&1; then
- onboarding_version="$(claude --version 2>/dev/null | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+' || true)"
- fi
- updated="$(jq --arg p "$repo" --arg ver "$onboarding_version" '
- .bypassPermissionsModeAccepted = true
- | .hasCompletedOnboarding = true
- | (if $ver == "" then . else .lastOnboardingVersion = $ver end)
- | .projects = ((.projects // {}) | .[$p] = ((.[$p] // {})
- | .hasTrustDialogAccepted = true
- | .hasCompletedProjectOnboarding = true))
- ' <<<"$current")" || { printf 'exec-trust: failed to compose the updated config\n' >&2; exec 9>&-; exit 65; }
- tmp="$config.exec-trust.$$"
- printf '%s\n' "$updated" > "$tmp" && mv -f -- "$tmp" "$config" || {
- rm -f -- "$tmp"; printf 'exec-trust: failed to write %s\n' "$config" >&2; exec 9>&-; exit 65; }
- exec 9>&-
- 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
- #!/usr/bin/env bash
- # spawn-exec.sh — launch one executor agent in its own tmux session (the supported way
- # for a PL to start an executor).
- #
- # Needs: Linux, tmux, systemd user session (systemd-run, systemctl --user), flock, jq,
- # git, the `sno` CLI, and the chosen runtime CLI (codex, claude, hermes, openclaw or cursor-agent).
- #
- # A separate systemd service enforces the wall budget T: SIGTERM at T, then SIGKILL at
- # 1.5T. A relaunch needs a fresh spawn; a relaunch after the wall needs the owner
- # (whoever owns the work) to approve it.
- #
- # BEGIN SPAWN-EXEC USAGE
- # Usage:
- # spawn-exec.sh --journey <j-id> --repo <path> --budget-h <hours>
- # --dispatch <file> --class closure|build|operate
- # --addr <executor Reach address> [--lane <name>]
- # [--fence <file>] [--callsign <name>] [--kind executor]
- # [--resume <session-id>] [--log <path>]
- # [--runtime codex|claude|hermes|openclaw|cursor] [--window]
- # spawn-exec.sh -h|--help
- #
- # Required: --journey, --repo, --budget-h, --dispatch, --addr.
- # Values: --class closure|build|operate (default build);
- # --runtime codex|claude|hermes|openclaw|cursor (default codex; pass --runtime claude when
- # the executor should be a Claude session). hermes (the Hermes Agent CLI), openclaw
- # (the OpenClaw CLI) and cursor (the Cursor CLI, cursor-agent) are further supported agent
- # CLIs; they cannot resume a session.
- # --resume <session-id> relaunches an existing codex or claude session; other runtimes refuse it.
- # --window is accepted and ignored: tmux is the only seat channel.
- # Exit: 0 spawned; 2 usage; 3 live-session conflict;
- # 6 missing dependency; 7 startup proof failed.
- # END SPAWN-EXEC USAGE
- #
- # Behavior:
- # 1. Claims a callsign if not provided (callsign.sh claim).
- # 2. Appends the enforced DEADLINE BLOCK to the dispatch text
- # (absolute clock times — agents cannot feel time; they must read it).
- # 3. Launches the executor INSIDE A TMUX SESSION NAMED BY ITS CALLSIGN
- # with the runtime in a dedicated systemd user scope. One external controller
- # sends SIGTERM at T and cgroup-wide
- # SIGKILL at 1.5T, then records whether every owned container is empty.
- # Attach: `tmux attach -t <callsign>` for observation.
- # Mid-run instructions travel through the executor's Reach address. The runtime
- # runs without its own sandbox or approval prompts (codex --dangerously-bypass-
- # approvals-and-sandbox, claude --dangerously-skip-permissions): the guardrails are
- Note: Starts a coding agent with its permission prompts off
- Line 45 on GitHub
- # the wall and fence-check.sh instead, so use it only in a repo and on a
- # machine where an unattended agent may act freely.
- # 4. Records the spawn (pid, callsign, deadlines) in
- # ~/.local/state/agent-spawns.jsonl and prints a summary line.
- set -euo pipefail
- scripts_dir="$(cd -- "$(dirname -- "$(readlink -f -- "${BASH_SOURCE[0]}")")" && pwd)"
- SPAWNS="$HOME/.local/state/agent-spawns.jsonl"
- CALLSIGN_SH="$(dirname "$0")/callsign.sh"
- LANE_RESOLVE="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/lane-resolve.sh"
- WALL_CONTROLLER="$(dirname "$0")/executor-wall.sh"
- journey="" repo="" lane="" budget_h="" dispatch="" callsign="" kind="executor" resume="" log="" jclass="" fence=""
- # The runtime is selectable per spawn, Codex by default. The adapter
- # owns exactly two things: how to launch and how to resume.
- runtime="codex"
- # The Reach address this executor answers to. It is passed at launch and never inferred.
- addr=""
- usage() {
- sed -n '/^# BEGIN SPAWN-EXEC USAGE$/,/^# END SPAWN-EXEC USAGE$/p' "$0" |
- sed '1d;$d;s/^# \{0,1\}//'
- }
- while [ $# -gt 0 ]; do
- case "$1" in
- --journey) journey="$2"; shift 2 ;;
- --repo) repo="$2"; shift 2 ;;
- --lane) lane="$2"; shift 2 ;;
- --budget-h) budget_h="$2"; shift 2 ;;
- --dispatch) dispatch="$2"; shift 2 ;;
- --class) jclass="$2"; shift 2 ;;
- --fence) fence="$2"; shift 2 ;;
- --callsign) callsign="$2"; shift 2 ;;
- --kind) kind="$2"; shift 2 ;;
- --resume) resume="$2"; shift 2 ;;
- --log) log="$2"; shift 2 ;;
- --runtime) runtime="$2"; shift 2 ;;
- --window) shift ;; # accepted and ignored: tmux is the only seat channel
- --addr) addr="$2"; shift 2 ;;
- -h|--help) usage; exit 0 ;;
- *) echo "spawn-exec: unknown arg $1" >&2; exit 2 ;;
- esac
- done
- [ -n "$journey" ] && [ -n "$repo" ] && [ -n "$budget_h" ] && [ -n "$dispatch" ] || {
- echo "spawn-exec: need --journey --repo --budget-h --dispatch" >&2; exit 2; }
- # An executor that cannot be talked to, woken, or tracked is not started: a missing or
- # malformed address is refused before the runtime starts.
- case "$runtime" in codex|claude|hermes|openclaw|cursor) : ;; *) echo "spawn-exec: unsupported runtime: $runtime" >&2; exit 2 ;; esac
- if [ -n "$resume" ]; then
- case "$runtime" in codex|claude) : ;; *)
- 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
- fi
- [ -n "$addr" ] || { echo "spawn-exec: --addr <executor Reach address> is required; an executor that cannot be addressed cannot be woken" >&2; exit 2; }
- [[ "$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; }
- jclass="${jclass:-build}"
- [ -f "$dispatch" ] || { echo "spawn-exec: dispatch file not found: $dispatch" >&2; exit 2; }
- if [ "$jclass" = operate ]; then
- for field in command working-directory artifact; do
- grep -qE "^${field}:[[:space:]]*[^[:space:]]" "$dispatch" || {
- echo "spawn-exec: operate dispatch missing $field field" >&2; exit 2;
- }
- done
- fi
- mkdir -p "$HOME/.local/state"; touch "$SPAWNS"
- [ -z "$fence" ] || [ -f "$fence" ] || { echo "spawn-exec: fence file not found: $fence" >&2; exit 2; }
- [ -d "$repo" ] || { echo "spawn-exec: repo dir not found: $repo" >&2; exit 2; }
- repo="$(cd -- "$repo" && pwd -P)"
- main_root="$(git -C "$repo" rev-parse --show-toplevel 2>/dev/null || printf '%s' "$repo")"
- # Check every prerequisite before any resource is claimed, and report all that are missing in one message.
- missing_deps=()
- runtime_cmd="$runtime"; [ "$runtime" != cursor ] || runtime_cmd=cursor-agent # `cursor` alone is the IDE launcher
- for dep in "$runtime_cmd" tmux sno flock systemd-run systemctl jq; do
- command -v "$dep" >/dev/null || missing_deps+=("$dep")
- done
- if [ "${#missing_deps[@]}" -gt 0 ]; then
- 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
- exit 6
- fi
- [ -x "$WALL_CONTROLLER" ] || { echo "spawn-exec: missing dependency: executable executor-wall.sh beside this script" >&2; exit 6; }
- [ -f "$LANE_RESOLVE" ] || { echo "spawn-exec: missing dependency: lane-resolve.sh beside this script" >&2; exit 6; }
- # Workspace layout: control files live under <repo>/ai-doc/ACTIVE/PL; created on first use.
- mb_base="$main_root/ai-doc"
- mkdir -p "$mb_base/ACTIVE/PL/exec-logs" || {
- echo "spawn-exec: cannot create $mb_base/ACTIVE/PL/exec-logs" >&2; exit 2; }
- # Mission registry: every charter carries one machine-readable mission header line;
- # this script is the only writer of missions.jsonl.
- missions="$mb_base/ACTIVE/PL/missions.jsonl"
- touch "$missions" || {
- echo "spawn-exec: cannot initialize mission registry: $missions" >&2
- exit 2
- }
- mhdr="$(grep -m1 -E '^mission:' "$dispatch" 2>/dev/null || true)"
- mfield() { { printf '%s\n' "$mhdr" | grep -oE "$1[[:space:]]*:[[:space:]]*[^·]+" | head -1 | sed -E "s/^$1[[:space:]]*:[[:space:]]*//; s/[[:space:]]+$//"; } || true; }
- m_id="$(mfield mission)"; m_op="$(mfield operation)"; m_test="$(mfield success-test)"
- m_evid="$(mfield evidence)"; m_owner="$(mfield owner)"; m_parent="$(mfield parent)"; m_pred="$(mfield predecessor)"
- m_pred_spawn="$(mfield predecessor-spawn-id)"
- m_id="${m_id:-$journey}"; m_op="${m_op:-open}"; m_test="${m_test:-unspecified}"
- m_evid="${m_evid:-unspecified}"; m_owner="${m_owner:-unspecified}"
- case "$budget_h" in ''|*[!0-9.]*|.|*.*.*) echo "spawn-exec: --budget-h must be a positive number" >&2; exit 2 ;; esac
- # JSON-ledger fields are written by naive printf — strip anything that could
- # break a JSON string or forge records (quotes, backslashes, control bytes).
- sane() { printf '%s' "${1:-}" | tr '[:cntrl:]' ' ' | tr -d '\\"'; }
- journey="$(sane "$journey")"; kind="$(sane "$kind")"; resume="$(sane "$resume")"
- runtime="$(sane "$runtime")"; addr="$(sane "$addr")"
- callsign="$(sane "$callsign")"; repo="$(sane "$repo")"; log="$(sane "$log")"
- # budget arithmetic (awk — no bc dependency); grace = 1.5 * budget.
- # One external controller sends TERM at T and KILL exactly at the 1.5T wall.
- budget_s=$(awk -v h="$budget_h" 'BEGIN{printf "%d", h*3600}')
- grace_s=$(awk -v h="$budget_h" 'BEGIN{printf "%d", h*3600*1.5}')
- [ "$budget_s" -gt 0 ] || { echo "spawn-exec: --budget-h must be > 0" >&2; exit 2; }
- # Two distinct deadlines require at least one second between TERM and KILL.
- [ "$grace_s" -ge 2 ] || { echo "spawn-exec: budget too small — 1.5x grace must be >= 2s (got ${grace_s}s)" >&2; exit 2; }
- wall_epoch="$(date +%s)"
- t_budget="$(date -d "@$((wall_epoch + budget_s))" '+%Y-%m-%d %H:%M %Z')"
- t_grace="$(date -d "@$((wall_epoch + grace_s))" '+%Y-%m-%d %H:%M %Z')"
- # comms deadlines (persisted ISO — roster.sh is the timer owner and needs
- # machine-comparable values; the roster owns the alarm)
- t_ack="$(date -d '+15 minutes' -Is)"
- t_conv="$(date -d '+90 minutes' -Is)"
- # Lane resolution keys on the REPOSITORY name.
- repo_base="$(basename "$main_root")"
- resolve_args=(--repo "$repo_base" --field addr)
- [ -z "$lane" ] || resolve_args+=(--lane "$lane")
- if ! pl_address="$(PL_REGISTRY="${PL_REGISTRY:-${SNO_PL_REGISTRY:-}}" \
- bash "$LANE_RESOLVE" "${resolve_args[@]}")"; then
- exit 2
- fi
- claimed_here=0
- if [ -z "$callsign" ]; then
- callsign="$("$CALLSIGN_SH" claim --journey "$journey" --repo "$main_root" --kind "$kind" \
- --label "spawned $(date '+%H:%M')")" || exit $?
- claimed_here=1
- fi
- # The executor that actually holds a primary open/transfer is the lifecycle
- # owner. Auto-claim cannot know that identity when the dispatch is authored,
- # so normalize only after the atomic claim; delegates retain the primary owner.
- case "$m_op" in
- open|transfer) m_owner="$callsign" ;;
- esac
- # ANY post-claim failure — cd, mktemp, disk-full, tmux — must not strand the
- # claim (`set -e` skips inline cleanup): EXIT trap releases
- # what WE claimed unless the spawn reached success.
- spawn_ok=0 mission_registered=0 abort_runner="" session_started=0
- wall_started=0 wall_unit="" runtime_started=0 runtime_unit=""
- seat_lock_fd="" startup_pane=""
- seat_dir="" startup_file="" reach_root=""
- mission_lock="${missions}.lock"
- cleanup_reach_startup() {
- local runtime_group="" runtime_deadline
- if [ "$session_started" = 1 ] && tmux has-session -t "$callsign" 2>/dev/null; then
- tmux kill-session -t "$callsign" 2>/dev/null || true
- fi
- if [ "$wall_started" = 1 ] && [ -n "$wall_unit" ]; then
- systemctl --user stop "$wall_unit" >/dev/null 2>&1 || true
- fi
- if [ "$runtime_started" = 1 ] && [ -n "$runtime_unit" ]; then
- if ! bash "$WALL_CONTROLLER" --spawn-id "$mission_spawn_id" --cleanup-now; then
- echo "spawn-exec: CRITICAL — failed startup left marked executor work alive; preserving mission and callsign for recovery" >&2
- return 1
- fi
- systemctl --user kill --kill-whom=all --signal=KILL "$runtime_unit" >/dev/null 2>&1 || true
- systemctl --user stop --no-block "$runtime_unit" >/dev/null 2>&1 || true
- runtime_deadline=$(( SECONDS + 5 ))
- while [ "$SECONDS" -lt "$runtime_deadline" ]; do
- runtime_group="$(systemctl --user show "$runtime_unit" -p ControlGroup --value 2>/dev/null || true)"
- if [ -z "$runtime_group" ] || [ ! -r "/sys/fs/cgroup$runtime_group/cgroup.procs" ] ||
- [ ! -s "/sys/fs/cgroup$runtime_group/cgroup.procs" ]; then
- runtime_started=0
- break
- fi
- sleep 0.1
- done
- if [ "$runtime_started" = 1 ]; then
- echo "spawn-exec: CRITICAL — failed startup left runtime unit $runtime_unit non-empty; preserving mission and callsign for recovery" >&2
- return 1
- fi
- fi
- if [ -n "$startup_pane" ] && [ -f "$seat_dir/reachable.json" ] &&
- jq -e --arg pane "$startup_pane" '.identity == {kind:"tmux-pane",value:$pane}' "$seat_dir/reachable.json" >/dev/null 2>&1; then
- sno reach unregister --as "$addr" >/dev/null ||
- echo "spawn-exec: could not unregister failed Reach seat $addr" >&2
- fi
- if [ -n "$seat_lock_fd" ]; then
- flock -u "$seat_lock_fd" 2>/dev/null || true
- exec {seat_lock_fd}>&-
- seat_lock_fd=""
- fi
- }
- release_on_fail() {
- [ "$spawn_ok" = 1 ] && return 0
- if ! cleanup_reach_startup; then
- return 1
- fi
- if [ "$mission_registered" = 1 ]; then
- if ! bash "$abort_runner" launch 1; then
- echo "spawn-exec: CRITICAL — launch failed and mission abort could not be recorded in $missions" >&2
- "$CALLSIGN_SH" release "$callsign" --journey "$journey" 2>/dev/null || true
- fi
- mission_registered=0
- claimed_here=0
- fi
- [ "$claimed_here" = 1 ] && "$CALLSIGN_SH" release "$callsign" --journey "$journey" 2>/dev/null || true
- }
- trap release_on_fail EXIT
- [ -n "$log" ] || {
- mkdir -p "$mb_base/ACTIVE/PL/exec-logs" 2>/dev/null || true
- log="$mb_base/ACTIVE/PL/exec-logs/${journey}-${callsign}.log"
- touch "$log" 2>/dev/null || log="$HOME/.local/state/${journey}-${callsign}.log"
- }
- [ -e "$log" ] || touch "$log" || {
- echo "spawn-exec: cannot create explicit log path: $log" >&2
- exit 2
- }
- # Render and lint the exact bytes the executor will send before any tmux session starts.
- # This proves message validity only; the on-station acknowledgement still proves Reach
- # readiness.
- #
- # The card carries the launcher's own measurement of the fence file (exists, bytes,
- # sha256); the executor sends its own reading separately, so the two can be compared.
- fence_exists_at_spawn=no
- fence_bytes_at_spawn=0
- fence_sha_at_spawn=none
- if [ -n "$fence" ] && [ -f "$fence" ]; then
- fence_exists_at_spawn=yes
- fence_bytes_at_spawn="$(wc -c <"$fence" | tr -d ' ')"
- fence_sha_at_spawn="$(sha256sum -- "$fence" | cut -d' ' -f1)"
- fi
- on_station_message="$log.on-station.eml"
- {
- printf 'From: %s <%s>\n' "$callsign" "$addr"
- printf 'To: PL <%s>\n' "$pl_address"
- printf 'Subject: [STATUS] on-station: %s\n' "$callsign"
- printf 'Date: %s\n' "$(date -R)"
- printf 'Message-ID: <on-station-%s-%s@%s>\n' "$(date +%s%N)" "$$" "$(hostname)"
- printf 'X-Work: %s\n' "$journey"
- printf 'X-Type: status\n\n'
- printf 'on station; charter=%s.dispatch read; fence=%s\n' "$log" "${fence:-NONE}"
- printf 'measured-at-spawn: fence-exists=%s fence-bytes=%s fence-sha256=%s\n' \
- "$fence_exists_at_spawn" "$fence_bytes_at_spawn" "$fence_sha_at_spawn"
- printf 'observed-by-executor: sent separately; a disagreement with the line above is a finding\n'
- } >"$on_station_message"
- if ! sno reach lint "$on_station_message"; then
- echo "spawn-exec: generated on-station message failed canonical lint; no executor was started" >&2
- exit 7
- fi
- # Serialize launches for one address while Reach initializes its persistent seat.
- reach_root="${SNO_REACH_ROOT:-$HOME/.local/state/sno-reach}"
- mkdir -p -- "$reach_root"
- exec {seat_lock_fd}>"$reach_root/.spawn-$addr.lock"
- flock -x "$seat_lock_fd"
- seat_dir="$reach_root/$addr"
- if [ -f "$seat_dir/reachable.json" ]; then
- old_pane="$(jq -er 'select(.channel == "tmux" and .identity.kind == "tmux-pane") | .identity.value' "$seat_dir/reachable.json" 2>/dev/null || true)"
- if [ -n "$old_pane" ] && tmux list-panes -a -F '#{pane_id}' 2>/dev/null | grep -qxF "$old_pane"; then
- echo "spawn-exec: Reach address $addr is already registered to live pane $old_pane" >&2
- exit 3
- fi
- sno reach unregister --as "$addr" >/dev/null || {
- echo "spawn-exec: could not clear stale Reach registration for $addr" >&2; exit 7;
- }
- fi
- sno reach init --as "$addr" --name "${addr%@*}" >/dev/null || {
- echo "spawn-exec: could not initialize Reach seat $addr" >&2; exit 7;
- }
- startup_file="$log.startup"
- rm -f -- "$startup_file"
- # Deadline block — appended to the dispatch, absolute times only.
- convergence_class="$jclass"
- [ "$convergence_class" != operate ] || convergence_class=closure
- merged="$(mktemp)"
- cat "$dispatch" > "$merged"
- cat >> "$merged" <<EOF
- === DEADLINE (enforced by the launcher) ===
- Your callsign: ${callsign}. Budget: ${budget_h}h.
- T (budget) = ${t_budget}: from this moment, STOP all feature/fix-forward
- work; smallest completion path ONLY (commit verified work via explicit
- paths, write the close report, send the close card).
- 1.5T (hard wall) = ${t_grace}: SIGTERM is sent at T and SIGKILL at this
- time — trapping/ignoring TERM buys you nothing.
- Anything uncommitted may be lost. There is no extension — no card, no
- apology, no reason changes this.
- Past T, do not add any out-of-charter work. Within budget, extra in-scope
- quality is welcome.
- You cannot feel time. Run \`date\` at every phase boundary and compare
- against the two timestamps above. Plan backward from T, not forward.
- === COMMS CONTRACT (acknowledgment required) ===
- Read accumulated work at each task boundary and after long commands:
- sno reach inbox --as ${addr}
- Read each exact card path printed by inbox. Handle decisions and questions before
- continuing interrupted work. A ring is a prompt to read the inbox, not a card.
- FIRST act, before any work — READ the charter and fence, then send the on-station
- card. The prepared card records the spawner's fence measurement; send your own
- measurement separately if it differs:
- charter: ${log}.dispatch
- fence: ${fence:-<none declared>}
- sno reach send --as ${addr} < '${on_station_message}'
- ACK deadline ${t_ack} (15 min): no card by then = the PL treats this
- dispatch as never delivered and re-dispatches.
- STATE to disk on every transition:
- \`bash "${scripts_dir}/callsign.sh" title run|wait|done ${callsign} --journey ${journey} "<label>"\`.
- CONVERGENCE every fix-verify cycle:
- \`bash "${scripts_dir}/convergence-watch.sh" record --journey ${journey} --class ${convergence_class} --remaining <N> --cycle <k>\`
- First sample due by ${t_conv}; a series silent for 90 min is treated as a stalled run.
- For a work card, accept before doing the work:
- printf '%s\n' 'Accepted.' | sno reach reply --as ${addr} --card "<exact card path>" --state accepted
- Then report the result with the same card path:
- printf '%s\n' '<result and evidence>' | sno reach reply --as ${addr} --card "<exact card path>" --state completed
- Use --state failed if the work failed. A question asking for information takes
- reply without --state. Do not dismiss an actionable question or decision.
- For later supervision, arm a heartbeat that rings your own seat, then end the turn:
- sno heartbeat --interval 10m --label pl-${callsign} -- sno reach ring ${addr}
- If Reach reports a delivered card with wake exit 5 or 6, inspect the recipient
- seat; do not resend the card.
- EOF
- cd "$repo"
- # Read the merged dispatch in the PARENT before backgrounding: bash performs a
- # background command's expansions in the forked child, so an early rm of the
- # temp file would race the child's $(cat …) and hand the executor an EMPTY
- # dispatch.
- dispatch_text="$(command cat "$merged")"
- rm -f "$merged"
- # Every executor runs inside a tmux session NAMED BY ITS CALLSIGN:
- # - persistent PTY: the session lives on its own — no resume pumping and no
- # double-spawn; mid-run instructions accumulate in the executor Reach
- # - attachable window: `tmux attach -t <callsign>` any time; scrollback and
- # titles stay visible
- # - no runtime sandbox: the codex workspace-write sandbox mounts .git read-only, so
- # commits would fail. The guardrails here are the wall, fence-check on every
- # commit, and explicit-path discipline.
- # The runtime receives the spawn marker and runs in a dedicated systemd user scope.
- # The wall is a separate user service, so it survives every scope it signals.
- # Callsign grammar check: a callsign is interpolated into tmux and shell commands, so it
- # must be provably inert.
- case "$callsign" in *[!a-z]*|'') echo "spawn-exec: callsign must be lowercase letters only: '$callsign'" >&2; exit 2 ;; esac
- if tmux has-session -t "$callsign" 2>/dev/null; then
- echo "spawn-exec: tmux session '$callsign' already exists — refusing double-spawn" >&2
- exit 3
- fi
- printf '%s' "$dispatch_text" > "$log.dispatch" # BEFORE the session starts (race)
- # Never build a shell program by interpolating caller values (an apostrophe in
- # --log/--resume would execute as the tmux user). All values are embedded via
- # printf %q into a per-spawn runner file.
- runner="$log.runner"
- abort_runner="$log.abort"
- mission_spawn_id="$(date -u +%Y%m%dT%H%M%S)-$$-$callsign"
- runtime_unit="sno-exec-${mission_spawn_id}.scope"
- wall_unit="sno-exec-wall-${mission_spawn_id}.service"
- wall_events="$log.wall.jsonl"
- rm -f -- "$wall_events" "$wall_events.lock"
- {
- printf '#!/usr/bin/env bash\nset -euo pipefail\n'
- printf 'missions=%q\nmission_lock=%q\nspawn_id=%q\n' \
- "$missions" "$mission_lock" "$mission_spawn_id"
- printf 'release_launch_claim=%q\n' "$claimed_here"
- printf 'callsign_sh=%q\ncallsign=%q\njourney=%q\n' \
- "$CALLSIGN_SH" "$callsign" "$journey"
- printf 'mission=%q\noperation=%q\nowner=%q\nsuccess_test=%q\nevidence=%q\nparent=%q\n' \
- "$m_id" "$m_op" "$m_owner" "$m_test" "$m_evid" "${m_parent:-none}"
- # A delegate is bound to the PRIMARY generation it was admitted under, never to
- # whichever delegate happens to be newest. Empty for a primary; the runner refuses
- # rather than guesses if a delegate ever reaches it unset.
- printf 'bound_primary_spawn=%q\n' "${m_pred_spawn:-}"
- cat <<'EOF'
- mode="${1:-runtime}"
- exit_rc="${2:-1}"
- exec {lock_fd}>>"$mission_lock"
- flock -x "$lock_fd"
- # A delegate spawn must not supersede the primary's generation. A primary reads
- # its generation from primary lifecycle events; delegates still count delegate events.
- if [ "$operation" = "delegate" ] && [ -z "${bound_primary_spawn:-}" ]; then
- echo "spawn-exec: CRITICAL — delegate $spawn_id has no bound primary generation; refusing to" >&2
- echo "spawn-exec: guess whether its terminal row belongs in $missions. Record it by hand." >&2
- exit 1
- fi
- current="$(
- jq -rs --arg m "$mission" --arg sid "$spawn_id" --arg op "$operation" \
- --arg bps "${bound_primary_spawn:-}" '
- [.[] | select(
- .mission == $m and
- (.event == "open" or .event == "transfer" or
- .event == "close" or .event == "abort")
- )][-1]
- | if $op == "delegate" then
- # A delegate is current while the primary generation it was admitted under is
- # still the live one. Two delegates under one primary therefore BOTH record a
- # terminal row — they are not each other'"'"'s successors. A transfer moves the
- # spawn id and a close or abort changes the event, so either suppresses it.
- (if (.event == "open" or .event == "transfer") and .spawn_id == $bps
- then "current" else "stale" end)
- else
- (if .spawn_id == $sid then "current" else "stale" end)
- end
- ' "$missions"
- )"
- if [ "$current" = "current" ]; then
- if [ "$mode" = "runtime" ] && [ "$operation" != "delegate" ]; then
- jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$mission" \
- --arg o "$owner" --arg sid "$spawn_id" --arg cs "$callsign" \
- --arg journey "$journey" --argjson rc "$exit_rc" \
- '{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"}' \
- >> "$missions"
- elif [ "$operation" = "delegate" ]; then
- jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$mission" \
- --arg o "$owner" --arg sid "$spawn_id" --arg cs "$callsign" \
- --argjson rc "$exit_rc" \
- '{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"}' \
- >> "$missions"
- else
- jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$mission" \
- --arg o "$owner" --arg st "$success_test" --arg ev "$evidence" \
- --arg pa "$parent" --arg pr "$callsign" --arg sid "$spawn_id" \
- '{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"}' \
- >> "$missions"
- fi
- else
- # This branch writes nothing to the registry, so it says so explicitly.
- echo "spawn-exec: NO stop record written for spawn $spawn_id (operation=$operation)." >&2
- echo "spawn-exec: The mission's own lifecycle already advanced past this spawn, so this" >&2
- echo "spawn-exec: exit is not the current generation and its stop is not recorded." >&2
- echo "spawn-exec: The callsign is NOT released by this path. If you expected a stop" >&2
- echo "spawn-exec: record, read $missions and find which later event superseded it." >&2
- fi
- flock -u "$lock_fd"
- exec {lock_fd}>&-
- if { [ "$mode" = "launch" ] && [ "$release_launch_claim" = 1 ]; } ||
- [ "$operation" = "delegate" ]; then
- if ! "$callsign_sh" release "$callsign" --journey "$journey"; then
- echo "spawn-exec: CRITICAL — stopped executor callsign release failed: $callsign" >&2
- exit 1
- fi
- fi
- EOF
- } > "$abort_runner"
- chmod +x "$abort_runner"
- # The runtime adapter owns exactly two things: how to launch, and how to resume. Every
- # other part of the lifecycle — registration, wake, liveness, close, archive — is written
- # once and never branches on this value.
- resume_line=""
- case "$runtime" in
- codex) [ -n "$resume" ] && resume_line="resume $(printf '%q' "$resume")" ;;
- claude) [ -n "$resume" ] && resume_line="--resume $(printf '%q' "$resume")" ;;
- esac
- state_file="$log.state"
- rm -f -- "$state_file"
- {
- printf '#!/usr/bin/env bash\nset -o pipefail\n'
- printf 'exec %d>&-\n' "$seat_lock_fd"
- printf 'export SNO_REACH_ROOT=%q\n' "$reach_root"
- printf 'export SNO_REACH_ADDR=%q\n' "$addr"
- printf 'startup_file=%q\nstartup_spawn_id=%q\n' "$startup_file" "$mission_spawn_id"
- cat <<'EOF'
- write_startup_receipt() {
- local state="$1" reason="${2:-}" tmp="${startup_file}.tmp.$$"
- jq -nc --arg sid "$startup_spawn_id" --arg state "$state" --arg reason "$reason" \
- '{spawn_id:$sid,state:$state,reason:$reason}' >"$tmp" || return 1
- mv -f -- "$tmp" "$startup_file"
- }
- EOF
- # The executor registers its Reach seat before it starts working; a failed registration
- # is a failed spawn rather than an executor nobody can reach.
- printf "sno reach register --as %q --channel tmux --handle \"\$(tmux display-message -p '#{pane_id}')\"\n" "$addr"
- printf 'register_rc=$?\n'
- printf 'if [ "$register_rc" -ne 0 ]; then\n'
- printf ' echo "[spawn-exec] REFUSING: %s could not register its Reach seat; an unreachable executor is not started"\n' "$addr"
- printf ' write_startup_receipt refused "registration-failed:$register_rc" || true\n'
- printf ' exit "$register_rc"\n'
- printf 'fi\n'
- printf 'write_startup_receipt registered || exit 74\n'
- # systemd-run --scope stays in the pane's foreground process group and moves the runtime plus
- # ordinary and setsid descendants into one dedicated cgroup. A separately armed service owns
- # the timer and discovers any normally inherited nested scope by this spawn's marker.
- printf 'systemd-run --user --scope --quiet --unit=%q env SNO_EXEC_SPAWN_ID=%q \\\n' \
- "$runtime_unit" "$mission_spawn_id"
- case "$runtime" in
- codex) printf ' codex --dangerously-bypass-approvals-and-sandbox %s \\\n' "$resume_line" ;;
- Note: Starts a coding agent with its permission prompts off
- Line 537 on GitHub
- claude) printf ' claude --dangerously-skip-permissions %s \\\n' "$resume_line" ;;
- Note: Starts a coding agent with its permission prompts off
- Line 538 on GitHub
- hermes) printf ' hermes chat --yolo --query \\\n' ;;
- openclaw) printf ' openclaw tui --message \\\n' ;;
- cursor) printf ' cursor-agent --force --trust \\\n' ;; # --trust: a fresh checkout's trust question would hold the seat
- esac
- # No pipe: an interactive terminal program dies when its stdout becomes a pipe
- # (`codex ... | tee log` ends the session). The transcript is captured by tapping the
- # pane from outside instead (tmux pipe-pane, set at launch).
- printf ' "$(cat %q)"\n' "$log.dispatch"
- printf 'ec=$?\necho\n'
- # Completion is an ARTIFACT, not an exit code. An interactive session returns to a
- # prompt rather than exiting, so the number below cannot mean what it meant before; the
- # supervisor reads the state file and the close card, and this file carries the spawn id
- # so a stale one from a previous generation can never be mistaken for this run's.
- printf 'printf %%s "spawn-id=%s\\nruntime=%s\\nexit=$ec\\nended-at=$(date -Is)\\n" > %q\n' \
- "$mission_spawn_id" "$runtime" "$state_file"
- printf 'bash %q runtime "$ec" || echo "[spawn-exec] CRITICAL: runtime stop bookkeeping failed"\n' "$abort_runner"
- printf 'echo "[spawn-exec] the runtime returned rc=$ec."\n'
- printf 'echo "[spawn-exec] This is NOT the completion signal. An interactive session"\n'
- printf 'echo "[spawn-exec] returns to its prompt instead of exiting, so a return code"\n'
- printf 'echo "[spawn-exec] here means the runtime stopped, not that the work finished."\n'
- printf 'echo "[spawn-exec] COMPLETION IS PROVEN BY TWO THINGS TOGETHER: the terminal"\n'
- printf 'echo "[spawn-exec] state file %s carrying THIS spawn id, and the close card."\n' "$state_file"
- printf 'echo "[spawn-exec] Either alone is a claim, not a proof."\n'
- } > "$runner"
- chmod +x "$runner"
- # The registry append is serialized under the mission lock. Every fallible artifact
- # preparation happens before the append. If the final tmux launch still fails, the EXIT
- # trap appends a terminal abort event.
- mission_event="$(
- jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$m_id" --arg e "$m_op" \
- --arg o "$m_owner" --arg st "$m_test" --arg ev "$m_evid" \
- --arg pa "${m_parent:-none}" --arg pr "${m_pred:-none}" --arg sid "$mission_spawn_id" \
- '{ts:$ts,mission:$m,event:$e,owner:$o,success_test:$st,evidence_form:$ev,parent:$pa,predecessor:$pr,spawn_id:$sid}'
- )"
- session_binding_event=""
- if [ -n "$resume" ]; then
- session_binding_event="$(
- jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg m "$m_id" \
- --arg o "$m_owner" --arg cs "$callsign" --arg sid "$mission_spawn_id" \
- --arg session "$resume" --arg journey "$journey" \
- '{ts:$ts,mission:$m,event:"correction",owner:$o,outcome:"session_bound",callsign:$cs,binds_spawn_id:$sid,session:$session,journey:$journey}'
- )"
- fi
- exec {mission_lock_fd}>>"$mission_lock"
- flock -x "$mission_lock_fd"
- printf '%s\n' "$mission_event" >> "$missions"
- [ -z "$session_binding_event" ] || printf '%s\n' "$session_binding_event" >> "$missions"
- mission_registered=1
- flock -u "$mission_lock_fd"
- exec {mission_lock_fd}>&-
- tmux new-session -d -s "$callsign" -c "$repo" "bash $(printf '%q' "$runner")"
- session_started=1
- runtime_started=1
- pid="$(tmux list-panes -t "$callsign" -F '#{pane_pid}' | head -1)" || {
- echo "spawn-exec: session '$callsign' started but its PID cannot be resolved; refusing startup" >&2
- exit 7
- }
- exec_pane="$(tmux list-panes -t "$callsign" -F '#{pane_id}' | head -1)" || {
- echo "spawn-exec: session '$callsign' started but its pane cannot be resolved; refusing startup" >&2
- exit 7
- }
- if [ -z "$pid" ] || [ -z "$exec_pane" ]; then
- echo "spawn-exec: session '$callsign' returned an empty PID or pane; refusing startup" >&2
- exit 7
- fi
- startup_pane="$exec_pane"
- # Tap the pane instead of piping the runtime. This is the only way to keep a transcript of
- # an interactive terminal program: a shell pipe on its stdout destroys the terminal it
- # needs and the session dies at once.
- tmux pipe-pane -t "$callsign" -o "cat >> $(printf '%q' "$log")" 2>/dev/null || {
- echo "spawn-exec: WARNING — transcript tap failed for '$callsign'; the executor is live but unlogged" >&2; }
- # A detached tmux client returning only proves that a pane was created. The spawn becomes
- # successful only after this exact generation publishes an atomic registration receipt and
- # the canonical seat points at this exact pane. Without both checks, a rejected child looks
- # identical to a live executor at the caller boundary.
- startup_state="" startup_reason="" startup_deadline=$(( SECONDS + 10 ))
- while [ "$SECONDS" -lt "$startup_deadline" ]; do
- if [ -f "$startup_file" ] && [ ! -L "$startup_file" ]; then
- if jq -e --arg sid "$mission_spawn_id" \
- '.spawn_id == $sid and (.state == "registered" or .state == "refused") and
- (.reason | type == "string")' "$startup_file" >/dev/null 2>&1; then
- startup_state="$(jq -r '.state' "$startup_file")"
- startup_reason="$(jq -r '.reason' "$startup_file")"
- break
- fi
- startup_reason="invalid-or-uncorrelated-startup-receipt"
- break
- fi
- if ! tmux has-session -t "$callsign" 2>/dev/null; then
- startup_reason="session-ended-before-registration"
- break
- fi
- sleep 0.1
- done
- if [ -z "$startup_state" ] && [ -z "$startup_reason" ]; then
- startup_reason="startup-receipt-timeout"
- fi
- if [ "$startup_state" != registered ]; then
- echo "spawn-exec: executor '$callsign' refused before Reach registration completed: $startup_reason" >&2
- exit 7
- fi
- if ! tmux has-session -t "$callsign" 2>/dev/null ||
- ! jq -e --arg addr "$addr" --arg pane "$exec_pane" \
- '.address == $addr and .channel == "tmux" and
- .identity == {kind:"tmux-pane", value:$pane}' \
- "$seat_dir/reachable.json" >/dev/null 2>&1; then
- echo "spawn-exec: executor '$callsign' registered without exact live-pane reachability; refusing startup" >&2
- exit 7
- fi
- runtime_scope=""
- runtime_scope_deadline=$(( SECONDS + 5 ))
- while [ "$SECONDS" -lt "$runtime_scope_deadline" ]; do
- runtime_scope="$(systemctl --user show "$runtime_unit" -p ControlGroup --value 2>/dev/null || true)"
- [ -n "$runtime_scope" ] && break
- sleep 0.1
- done
- if [ -z "$runtime_scope" ]; then
- echo "spawn-exec: executor '$callsign' registered but its dedicated runtime scope was not created; refusing startup" >&2
- exit 7
- fi
- now_epoch="$(date +%s)"
- term_remaining=$(( wall_epoch + budget_s - now_epoch ))
- kill_remaining=$(( wall_epoch + grace_s - now_epoch ))
- if [ "$term_remaining" -lt 1 ] || [ "$kill_remaining" -le "$term_remaining" ]; then
- echo "spawn-exec: startup consumed the executor wall budget before the controller could be armed; refusing startup" >&2
- exit 7
- fi
- if ! systemd-run --user --quiet --collect --unit="$wall_unit" \
- bash "$WALL_CONTROLLER" --spawn-id "$mission_spawn_id" \
- --term-after "$term_remaining" --kill-after "$kill_remaining" \
- --events "$wall_events"; then
- echo "spawn-exec: could not arm the external wall controller; refusing startup" >&2
- exit 7
- fi
- wall_started=1
- if ! systemctl --user is-active --quiet "$wall_unit"; then
- echo "spawn-exec: external wall controller did not remain active; refusing startup" >&2
- exit 7
- fi
- # Registration is now externally visible and correlated to this pane. Transfer ownership
- # of the seat and session to the running executor before recording or announcing success.
- flock -u "$seat_lock_fd"
- exec {seat_lock_fd}>&-
- seat_lock_fd=""
- session_started=0
- wall_started=0
- runtime_started=0
- spawn_ok=1
- # The initial owned scopes are evidence, not the controller's discovery boundary. The exact
- # spawn marker lets the controller find normally inherited nested scopes again at TERM and KILL.
- pane_scope=""
- [ -z "$exec_pane" ] || pane_scope=$(sed 's|^0::||' "/proc/$pid/cgroup" 2>/dev/null | head -1 || true)
- 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' \
- "$(date -Is)" "$pid" "$callsign" "$journey" "$repo" "$budget_h" "$jclass" \
- "$t_budget" "$t_grace" "$t_ack" "$t_conv" "$(sane "$fence")" "$log" "$resume" \
- "$runtime" "$addr" "$(sane "$exec_pane")" "$log.state" "$mission_spawn_id" \
- "$(sane "$pane_scope")" "$(sane "$runtime_scope")" "$runtime_unit" "$wall_unit" \
- "$(sane "$wall_events")" >> "$SPAWNS"
- 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 inFree to use. If it’s helped, pass it on.