thePR0M3TH3AN/bitvid
1
0 Fork 0
mirror of https://github.com/PR0M3TH3AN/bitvid.git synced 2026-10-29 00:42:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2474 from PR0M3TH3AN/claude/fix-jules-task-locking-fVCuW

Browse Source 
Add Nostr-based distributed task locking for multi-agent coordination
This commit is contained in:
thePR0M3TH3AN authored and GitHub committed 2026-02-13 16:11:50 -05:00
2 parents b1be38a24b 9d4c98a872
commit fe39d9500d
7 files changed
+1160 -61
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+23 -18
View File
@@ -244,32 +244,37 @@ When you create a PR or start work, leave a clear signal:
- **PR title prefix**: Use a descriptive prefix like `[nostr-core]`, `[playback]`, `[ui]`, `[ci]` so the scope is visible at a glance.
- **PR description**: Include a "Files Modified" section listing the key files touched, so other agents can quickly detect conflicts.
### Task Claiming Protocol (Draft PR Lock)
### Task Claiming Protocol (TORCH)
To prevent multiple agents from working on the same task simultaneously, every agent must **check open PRs and create a claim** before starting work. The claim (pushed branch + `started` log file) acts as a distributed lock visible to all agents across all platforms (Claude Code, Codex, Jules).
Task coordination uses **TORCH** (Task Orchestration via Relay-Coordinated Handoff) — a decentralized locking protocol built on Nostr. Agents publish ephemeral lock events to public relays; locks auto-expire via NIP-40. No tokens, no secrets, no git push required. Works across all platforms (Claude Code, Codex, Jules). See `docs/agents/TORCH.md` for the full protocol documentation.
**Before starting any task:**
1. **Check for existing claims.** Search for open PRs matching the task:
1. **Check for existing claims:**
```bash
node scripts/agent/nostr-lock.mjs check --cadence <daily|weekly>
```
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, titles: [.[].title]}'
```
If a matching PR exists (open or draft) for the same agent or subsystem, **skip the task** — another agent is already working on it.
Returns JSON with `locked` (claimed agents) and `available` (free agents) arrays. If an agent appears in the `locked` list, **skip it**.
2. **Claim the task.** If no matching PR exists:
a. Create your working branch.
b. Make a minimal initial commit (e.g., create a `context/CONTEXT_<timestamp>.md` with the task scope).
c. Create a `started` log file in the appropriate task-log directory.
d. Push the branch immediately to make the claim visible.
e. Only after the branch is pushed and the claim is visible, begin the actual work.
3. **Handle race conditions.** After pushing your claim, re-check for duplicates:
2. **Claim the task:**
```bash
AGENT_PLATFORM=<jules|claude-code|codex> \
node scripts/agent/nostr-lock.mjs lock \
--agent <agent-name> \
--cadence <daily|weekly>
```
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, titles: [.[].title]}'
```
If you find another agent's PR for the same task that was created **before** yours, abandon your branch and skip the task.
The script generates an ephemeral keypair, publishes a lock event to public Nostr relays, and performs a built-in race check. The key is used once and discarded. Locks auto-expire after 2 hours (configurable via `NOSTR_LOCK_TTL`).
**Scheduler agents:** Daily and weekly scheduler agents must follow this protocol in addition to their directory-based rotation logic (`docs/agents/task-logs/daily/` and `docs/agents/task-logs/weekly/`). The draft PR check happens _after_ determining the next task but _before_ executing it. See the scheduler prompts for the specific implementation steps.
- **Exit 0** = lock acquired, begin work.
- **Exit 3** = race lost, another agent claimed first. Go back to step 1.
- **Exit 2** = relay error. Write a `_failed.md` log and stop.
3. **View all active locks** (optional, for debugging):
```bash
node scripts/agent/nostr-lock.mjs list
```
**Scheduler agents:** Daily and weekly scheduler agents must follow this protocol in addition to their directory-based rotation logic (`docs/agents/task-logs/daily/` and `docs/agents/task-logs/weekly/`). The lock check happens _after_ determining the next task but _before_ executing it. See the scheduler prompts for the specific implementation steps.
### Currently In-Flight Work
CLAUDE.md
+1
View File
@@ -488,6 +488,7 @@ When assigning work to agents:
| `docs/playback-fallback.md` | URL-first strategy |
| `docs/moderation/README.md` | Moderation system |
| `docs/logging.md` | Logger usage |
| `docs/agents/TORCH.md` | TORCH distributed task locking protocol |
| `context/` / `todo/` / `decisions/` / `test_logs/` | Agent persistent state files (see AGENTS.md §15) |
---
docs/agents/TORCH.md
+309
View File
@@ -0,0 +1,309 @@
# TORCH: Task Orchestration via Relay-Coordinated Handoff
TORCH is a decentralized task-locking protocol for multi-agent development. It uses the Nostr protocol to coordinate AI coding agents (Claude Code, Google Jules, OpenAI Codex, etc.) working in parallel on the same repository, preventing them from colliding on the same task.
## The Problem
When multiple AI agents operate on a shared codebase, they need a way to signal "I'm working on this" so other agents don't duplicate the effort. The traditional approach uses draft pull requests as locks, but this breaks down in practice:
- **Sandboxed environments** (e.g., Google Jules) block `git push` and don't provide GitHub CLI tools.
- **Token management** adds operational overhead — GitHub PATs must be created, rotated, and injected into each agent environment.
- **Platform coupling** ties the coordination mechanism to GitHub specifically, making it non-portable.
- **Complex reasoning chains** force agents to parse jq pipelines, handle multi-method fallbacks, and perform manual race detection, consuming tokens and increasing error rates.
## The Solution
TORCH replaces all of that with a single protocol:
1. An agent **publishes a Nostr event** to claim a task.
2. Other agents **query the relay** to see what's claimed.
3. Locks **auto-expire** via NIP-40 — no cleanup required.
4. Each lock uses an **ephemeral keypair** — no secrets to manage.
The entire locking mechanism is handled by a single script (`scripts/agent/nostr-lock.mjs`) that any agent can call with two commands. The agent's reasoning chain reduces to: "run check, run lock, read exit code."
## How It Works
### Protocol Overview
```
Agent A Nostr Relays Agent B
| | |
|-- check (query locks) ---->| |
|<--- JSON: locked=[] -------| |
| | |
|-- lock (publish event) --->| |
|<--- OK (published) --------| |
| | |
|-- race check (re-query) -->| |
|<--- only my event ---------| |
| | |
| RACE CHECK: won | |
| (begin work) | |
| | |
| |<-- check (query locks) ----|
| |--- JSON: locked=[A] ------>|
| | |
| | (Agent B picks |
| | a different task) |
| | |
| (2 hours pass) | |
| |--- lock auto-expires ----->|
| | |
```
### Event Schema (NIP-78 / Kind 30078)
Each lock is a NIP-33 parameterized replaceable event:
```json
{
"kind": 30078,
"pubkey": "<ephemeral-pubkey>",
"created_at": 1739484362,
"tags": [
["d", "bitvid-lock/daily/nip-research-agent/2026-02-13"],
["t", "bitvid-agent-lock"],
["t", "bitvid-lock-daily"],
["t", "bitvid-lock-daily-2026-02-13"],
["expiration", "1739491562"]
],
"content": "{\"agent\":\"nip-research-agent\",\"cadence\":\"daily\",\"status\":\"started\",\"date\":\"2026-02-13\",\"platform\":\"jules\",\"lockedAt\":\"2026-02-13T20:06:02.000Z\",\"expiresAt\":\"2026-02-13T22:06:02.000Z\"}"
}
```
**Tag breakdown:**
| Tag | Purpose |
|-----|---------|
| `d` | NIP-33 identifier: `<namespace>/<cadence>/<agent>/<date>`. Makes the event replaceable per agent per day. |
| `t` (bitvid-agent-lock) | Broad category filter for all TORCH lock events. |
| `t` (bitvid-lock-daily) | Cadence-specific filter. |
| `t` (bitvid-lock-daily-2026-02-13) | Date-specific filter for precise relay-side queries. |
| `expiration` | NIP-40 auto-expiration timestamp. Relays may garbage-collect after this time. |
### Ephemeral Keys
Each `lock` invocation generates a fresh secp256k1 keypair:
```
generateSecretKey() → 32 random bytes → sign event → discard key
```
The private key exists only in process memory for the duration of the script. It is never written to disk, never stored, never reused. The public key is included in the event for Nostr protocol compliance but has no ongoing identity or authority.
This means:
- **No secret management.** No tokens, no `.env` files, no rotation schedules.
- **No key reuse.** Every lock is cryptographically independent.
- **No cleanup authority.** The lock can't be manually deleted (the key is gone), but it doesn't need to be — NIP-40 expiration handles it.
### Race Detection
When two agents try to claim the same task simultaneously:
1. Both agents run `check` — neither sees a lock.
2. Both agents run `lock` — both publish events to relays.
3. Both agents re-query after a 1.5-second propagation delay.
4. Both agents see two lock events for the same task.
5. The event with the **earlier `created_at`** wins.
6. The loser exits with code 3. The winner proceeds.
The losing agent's event remains on relays but is harmless — it auto-expires, and it doesn't prevent the winner from working. Other agents checking later see both events but this just means the task appears (correctly) as locked.
### Auto-Expiration
Locks expire via NIP-40 after a configurable TTL (default: 2 hours). This provides:
- **Self-healing.** If an agent crashes mid-task, its lock doesn't persist forever.
- **No stale state.** No equivalent of orphaned draft PRs blocking future runs.
- **Zero maintenance.** No cron jobs to clean up expired locks, no manual intervention.
The client-side `check` command also filters by expiration, so even if a relay hasn't garbage-collected an expired event, it won't appear in the exclusion set.
## Usage
### Commands
**Check what's locked:**
```bash
node scripts/agent/nostr-lock.mjs check --cadence daily
```
Returns JSON to stdout:
```json
{
"cadence": "daily",
"date": "2026-02-13",
"locked": ["audit-agent", "ci-health-agent"],
"available": ["const-refactor-agent", "content-audit-agent", ...],
"lockCount": 2,
"locks": [...]
}
```
**Claim a task:**
```bash
AGENT_PLATFORM=jules \
node scripts/agent/nostr-lock.mjs lock \
--agent nip-research-agent \
--cadence daily
```
Returns key=value pairs to stdout:
```
LOCK_STATUS=ok
LOCK_EVENT_ID=ea2724c76d2bd707...
LOCK_PUBKEY=7ee606dd0619e339...
LOCK_AGENT=nip-research-agent
LOCK_CADENCE=daily
LOCK_DATE=2026-02-13
LOCK_EXPIRES=1739491562
LOCK_EXPIRES_ISO=2026-02-13T22:06:02.000Z
```
Exit codes:
- `0` — Lock acquired.
- `3` — Race lost or task already locked.
- `2` — Relay error.
- `1` — Usage error.
**List all active locks (human-readable):**
```bash
node scripts/agent/nostr-lock.mjs list
```
**Test without publishing:**
```bash
node scripts/agent/nostr-lock.mjs lock --agent test --cadence daily --dry-run
```
### Configuration
| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `NOSTR_LOCK_RELAYS` | `wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net` | Comma-separated relay URLs |
| `NOSTR_LOCK_TTL` | `7200` (2 hours) | Lock expiration in seconds |
| `AGENT_PLATFORM` | `unknown` | Platform identifier included in lock metadata |
## Integration with the Scheduler
The bitvid scheduler uses TORCH as its sole coordination mechanism. The full flow is documented in `docs/agents/prompts/scheduler-flow.md`, but the TORCH-specific part is just two steps:
```bash
# 1. Build exclusion set
node scripts/agent/nostr-lock.mjs check --cadence daily
# → Use the "locked" array to skip already-claimed agents
# 2. Claim the selected agent
AGENT_PLATFORM=jules \
node scripts/agent/nostr-lock.mjs lock --agent <agent-name> --cadence daily
# → Exit 0: proceed with work
# → Exit 3: pick a different agent
```
The scheduler meta prompts (`docs/agents/prompts/META_PROMPTS.md`) embed these commands directly, so agents execute them without needing to understand the underlying protocol.
## Architecture
```
┌──────────────────────────────────────────────────────────┐
│ Agent Platforms │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Claude Code │ │ Google Jules│ │ OpenAI Codex│ │
│ │ │ │ │ │ │ │
│ │ nostr-lock │ │ nostr-lock │ │ nostr-lock │ │
│ │ .mjs │ │ .mjs │ │ .mjs │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
└─────────┼────────────────┼────────────────┼──────────────┘
│ │ │
│ WebSocket (NIP-01) │
│ │ │
┌─────────▼────────────────▼────────────────▼──────────────┐
│ Nostr Relay Network │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │relay.damus.io│ │ nos.lol │ │relay.primal │ │
│ │ │ │ │ │ .net │ │
│ │ Kind 30078 │ │ Kind 30078 │ │ Kind 30078 │ │
│ │ lock events │ │ lock events │ │ lock events │ │
│ │ (NIP-40 │ │ (NIP-40 │ │ (NIP-40 │ │
│ │ auto-exp) │ │ auto-exp) │ │ auto-exp) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ Events replicate across relays. Queries go to all. │
│ Publishing succeeds if at least 1 relay accepts. │
└──────────────────────────────────────────────────────────┘
```
### Dependencies
TORCH uses only packages already in the bitvid project:
- **nostr-tools** (v2.19.4) — Key generation, event signing, relay pool
- **ws** (v8.19.0) — WebSocket for Node.js relay connections
No additional dependencies are needed.
## Why Nostr?
The bitvid project is built on Nostr. Using Nostr for agent coordination means:
1. **No new infrastructure.** Public relays already exist and are free to use.
2. **No platform coupling.** Works with any agent platform that has Node.js and WebSocket access, regardless of their relationship with GitHub.
3. **No credentials.** Ephemeral keys eliminate the entire category of secret management.
4. **Protocol-native race resolution.** NIP-33 replaceable events and relay-side ordering provide deterministic conflict resolution without custom logic.
5. **Self-healing by default.** NIP-40 expiration means locks clean themselves up.
6. **Dogfooding.** A Nostr project using Nostr for its own development tooling.
## Toward a Generalizable Drop-In
TORCH is designed to be extracted from bitvid and used in any repository. The components that would need to be generalized:
| Component | Current State | To Generalize |
|-----------|--------------|---------------|
| `nostr-lock.mjs` | Hardcoded bitvid agent rosters | Accept roster via config file or CLI flag |
| Tag namespace | `bitvid-agent-lock` | Configurable project prefix |
| `d` tag pattern | `bitvid-lock/<cadence>/<agent>/<date>` | `<project>-lock/<cadence>/<agent>/<date>` |
| Relay defaults | 3 hardcoded relays | Config file with sensible defaults |
| Scheduler flow | bitvid-specific docs | Template scheduler docs with project placeholders |
| Agent rosters | Inline arrays in the script | External `torch.config.json` or similar |
A future `torch` npm package could look like:
```bash
# Install
npm install --save-dev @bitvid/torch
# Initialize in a new repo
npx torch init --project myproject --relays wss://relay.damus.io
# Creates:
# torch.config.json — project name, relays, TTL, roster
# scripts/torch-lock.mjs — pre-configured lock script
# docs/torch-scheduler.md — template scheduler flow
# Use in agent prompts
npx torch check --cadence daily
npx torch lock --agent my-agent --cadence daily
```
The protocol itself (NIP-78 events with NIP-40 expiration) is already generic. The bitvid-specific parts are just the roster definitions and tag namespaces.
## Related Files
| File | Purpose |
|------|---------|
| `scripts/agent/nostr-lock.mjs` | TORCH lock script (check, lock, list) |
| `docs/agents/prompts/scheduler-flow.md` | Scheduler procedure using TORCH |
| `docs/agents/prompts/META_PROMPTS.md` | Agent meta prompts with TORCH commands |
| `AGENTS.md` | Task Claiming Protocol referencing TORCH |
| `scripts/agents/claim-audit.mjs` | Legacy claim audit (predates TORCH) |
## NIPs Referenced
| NIP | Usage in TORCH |
|-----|---------------|
| [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) | Basic event structure and relay communication |
| [NIP-33](https://github.com/nostr-protocol/nips/blob/master/33.md) | Parameterized replaceable events (d-tag uniqueness) |
| [NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md) | Expiration tag for auto-expiring locks |
| [NIP-78](https://github.com/nostr-protocol/nips/blob/master/78.md) | Application-specific data (Kind 30078) |
docs/agents/prompts/META_PROMPTS.md
+24 -20
View File
@@ -17,22 +17,24 @@ MUST 1: Set cadence config to:
- branch_prefix = agents/daily/
- prompt_dir = docs/agents/prompts/daily/
MUST 2: Run this exact preflight command first:
MUST 2: Run preflight to get the exclusion set:
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/daily/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
node scripts/agent/nostr-lock.mjs check --cadence daily
MUST 3: Run the exact command list in this order:
Use the `locked` array from the JSON output as the exclusion set.
MUST 3: Run these commands in this order:
1) cat AGENTS.md CLAUDE.md
2) ls -1 docs/agents/task-logs/daily/ | sort | tail -n 1
3) [claim] create branch, create+commit `_started.md`, push
4) rerun preflight command from MUST 2
5) execute selected prompt from docs/agents/prompts/daily/
3) Select next roster agent not in exclusion set
4) Claim via Nostr lock:
AGENT_PLATFORM=jules node scripts/agent/nostr-lock.mjs lock --agent <agent-name> --cadence daily
Exit 0 = lock acquired, proceed. Exit 3 = race lost, go back to step 2.
5) Execute selected prompt from docs/agents/prompts/daily/
6) npm run lint
7) create `_completed.md` or `_failed.md`, commit, push
7) Create `_completed.md` or `_failed.md`, commit, push
MUST 4: Race rule: after step 3, compare only matching derived `agent` claims from the rerun. Earlier `created_at` wins; if tied, lower PR number wins. Print exactly one line: `RACE CHECK: won` or `RACE CHECK: lost (agent already claimed by PR #<number>)`.
MUST 5: If all daily agents are excluded, stop and write `_failed.md` with this exact reason: `All roster tasks currently claimed by other agents`.
MUST 4: If all daily agents are excluded, stop and write `_failed.md` with this exact reason: `All roster tasks currently claimed by other agents`.
```
## Weekly Scheduler Meta Prompt
@@ -48,20 +50,22 @@ MUST 1: Set cadence config to:
- branch_prefix = agents/weekly/
- prompt_dir = docs/agents/prompts/weekly/
MUST 2: Run this exact preflight command first:
MUST 2: Run preflight to get the exclusion set:
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/weekly/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
node scripts/agent/nostr-lock.mjs check --cadence weekly
MUST 3: Run the exact command list in this order:
Use the `locked` array from the JSON output as the exclusion set.
MUST 3: Run these commands in this order:
1) cat AGENTS.md CLAUDE.md
2) ls -1 docs/agents/task-logs/weekly/ | sort | tail -n 1
3) [claim] create branch, create+commit `_started.md`, push
4) rerun preflight command from MUST 2
5) execute selected prompt from docs/agents/prompts/weekly/
3) Select next roster agent not in exclusion set
4) Claim via Nostr lock:
AGENT_PLATFORM=jules node scripts/agent/nostr-lock.mjs lock --agent <agent-name> --cadence weekly
Exit 0 = lock acquired, proceed. Exit 3 = race lost, go back to step 2.
5) Execute selected prompt from docs/agents/prompts/weekly/
6) npm run lint
7) create `_completed.md` or `_failed.md`, commit, push
7) Create `_completed.md` or `_failed.md`, commit, push
MUST 4: Race rule: after step 3, compare only matching derived `agent` claims from the rerun. Earlier `created_at` wins; if tied, lower PR number wins. Print exactly one line: `RACE CHECK: won` or `RACE CHECK: lost (agent already claimed by PR #<number>)`.
MUST 5: If all weekly agents are excluded, stop and write `_failed.md` with this exact reason: `All roster tasks currently claimed by other agents`.
MUST 4: If all weekly agents are excluded, stop and write `_failed.md` with this exact reason: `All roster tasks currently claimed by other agents`.
```
docs/agents/prompts/scheduler-flow.md
+56 -23
View File
@@ -1,6 +1,6 @@
# Scheduler Flow (Single Source of Truth)
Use this document for **all scheduler runs**.
Use this document for **all scheduler runs**. Task locking uses the **TORCH** protocol (see `docs/agents/TORCH.md`).
## Scheduler Override (Top-Line Rule)
@@ -27,61 +27,94 @@ During scheduler execution, the scheduler-specific instructions in this document
- `branch_prefix` = `agents/<cadence>/`
- `prompt_dir` = `docs/agents/prompts/<cadence>/`
2. **MUST** run this command first and save the JSON output as the preflight exclusion set:
2. **MUST** run the preflight check to build the exclusion set:
```bash
curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/<cadence>/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
node scripts/agent/nostr-lock.mjs check --cadence <cadence>
```
3. **MUST** derive excluded agents from command output using this order only:
1) parse `head.ref` as `agents/<cadence>/<agent-name>/...`; 2) fallback to title regex; 3) if still unknown, stop with a global lock message.
This queries Nostr relays for active lock events and returns JSON with `locked` and `available` agent lists. Use the `locked` array as the exclusion set.
4. **MUST** run this command and read both policy files before selecting an agent:
3. **MUST** read both policy files before selecting an agent:
```bash
cat AGENTS.md CLAUDE.md
```
5. **MUST** run this command to identify the latest cadence log file, then choose the next roster agent not excluded by Step 2:
4. **MUST** run this command to identify the latest cadence log file, then choose the next roster agent not in the exclusion set:
```bash
ls -1 <log_dir> | sort | tail -n 1
```
6. **MUST** stop and write a `_failed.md` log with `All roster tasks currently claimed by other agents` when every roster agent is excluded.
5. **MUST** stop and write a `_failed.md` log with `All roster tasks currently claimed by other agents` when every roster agent is excluded.
7. **MUST** claim the selected agent in this exact order:
1) create branch,
2) create and commit `<timestamp>_<agent>_started.md` in `<log_dir>`,
3) push branch and commit.
6. **MUST** claim the selected agent:
8. **MUST** re-run the same PR preflight command from Step 2 immediately after push. If an earlier claim exists for the same derived agent, print `RACE CHECK: lost (agent already claimed by PR #<number>)`, abandon the run, and return to Step 5. Otherwise print `RACE CHECK: won`.
```bash
AGENT_PLATFORM=<jules|claude-code|codex> \
node scripts/agent/nostr-lock.mjs lock \
--agent <agent-name> \
--cadence <cadence>
```
9. **MUST** execute `<prompt_dir>/<prompt-file>` end-to-end.
The script generates an ephemeral keypair, publishes a NIP-78 lock event to Nostr relays with NIP-40 auto-expiration (2 hours), and performs a built-in race check. No tokens or secrets needed.
10. **MUST** create exactly one final status file (`_completed.md` or `_failed.md`), run `npm run lint`, then commit and push.
- **Exit code 0** = lock acquired, proceed to Step 7.
- **Exit code 3** = race lost (another agent claimed first). Return to Step 2.
- **Exit code 2** = relay error. Write a `_failed.md` log with reason `Nostr relay error` and stop.
## Canonical Example Run Output
7. **MUST** execute `<prompt_dir>/<prompt-file>` end-to-end.
8. **MUST** create exactly one final status file (`_completed.md` or `_failed.md`), run `npm run lint`, then commit and push.
## Canonical Example Run
```text
$ curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/daily/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
{ "count": 12, "prs": [ ... ] }
# Step 1: Set cadence
cadence=daily
# Step 2: Preflight — check Nostr locks
$ node scripts/agent/nostr-lock.mjs check --cadence daily
{
"cadence": "daily",
"date": "2026-02-14",
"locked": ["audit-agent"],
"available": ["ci-health-agent", "const-refactor-agent", ...],
"lockCount": 1,
"locks": [...]
}
# Step 3: Read policies
$ cat AGENTS.md CLAUDE.md
# bitvid — AI Agent Guide
...
# Step 4: Check logs, select next agent
$ ls -1 docs/agents/task-logs/daily/ | sort | tail -n 1
2026-02-13_18-40-00_load-test-agent_completed.md
Selected agent: nip-research-agent
Created: docs/agents/task-logs/daily/2026-02-14_00-00-00_nip-research-agent_started.md
Pushed branch: agents/daily/nip-research-agent/2026-02-14-run
$ curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, created_at, draft, head: {ref: .head.ref}, agent: ((.head.ref | capture("^agents/daily/(?<agent>[^/]+)/")?.agent) // (.title | capture("(?<agent>[A-Za-z0-9-]+-agent)")?.agent // null))}] | sort_by(.created_at, .number)}'
{ "count": 13, "prs": [ ... ] }
# Step 6: Claim via Nostr lock
$ AGENT_PLATFORM=jules node scripts/agent/nostr-lock.mjs lock --agent nip-research-agent --cadence daily
Locking: agent=nip-research-agent, cadence=daily, date=2026-02-14
Step 1: Checking for existing locks...
Step 2: Generating ephemeral keypair...
Step 3: Building lock event...
Step 4: Publishing to relays...
Published to 3/3 relays
Step 5: Race check...
RACE CHECK: won
LOCK_STATUS=ok
LOCK_EVENT_ID=ea2724c76d2bd707...
LOCK_AGENT=nip-research-agent
LOCK_CADENCE=daily
LOCK_EXPIRES_ISO=2026-02-14T02:00:00.000Z
# Step 7: Execute agent prompt
(agent runs nip-research-agent prompt...)
# Step 8: Finalize
$ npm run lint
> lint passed
scripts/agent/claim-task-api.sh
Executable
+228
View File
@@ -0,0 +1,228 @@
#!/usr/bin/env bash
set -euo pipefail
# claim-task-api.sh — Create a remote branch + started.md + draft PR
# entirely via GitHub REST API, bypassing 'git push'.
#
# This solves the Jules sandbox restriction where git push is blocked
# but curl/HTTP requests are allowed.
#
# Usage:
# ./scripts/agent/claim-task-api.sh \
# --agent <agent-name> \
# --cadence <daily|weekly> \
# [--base <branch>] \
# [--run-id <id>]
#
# Environment:
# GITHUB_TOKEN — Required. A token with repo write access.
# Falls back to GH_TOKEN if GITHUB_TOKEN is unset.
#
# Outputs (stdout):
# CLAIM_BRANCH=<branch-name>
# CLAIM_PR_NUMBER=<number>
# CLAIM_PR_URL=<url>
#
# Exit codes:
# 0 — Claim created successfully
# 1 — Usage error or missing token
# 2 — API error (branch/file/PR creation failed)
OWNER="PR0M3TH3AN"
REPO="bitvid"
API_BASE="https://api.github.com/repos/${OWNER}/${REPO}"
# ---------------------------------------------------------------------------
# Parse arguments
# ---------------------------------------------------------------------------
AGENT=""
CADENCE=""
BASE_BRANCH="unstable"
RUN_ID=""
while [[ $# -gt 0 ]]; do
case "$1" in
--agent) AGENT="$2"; shift 2 ;;
--cadence) CADENCE="$2"; shift 2 ;;
--base) BASE_BRANCH="$2"; shift 2 ;;
--run-id) RUN_ID="$2"; shift 2 ;;
*)
echo "ERROR: Unknown argument: $1" >&2
echo "Usage: $0 --agent <name> --cadence <daily|weekly> [--base <branch>] [--run-id <id>]" >&2
exit 1
;;
esac
done
if [[ -z "$AGENT" || -z "$CADENCE" ]]; then
echo "ERROR: --agent and --cadence are required." >&2
exit 1
fi
if [[ "$CADENCE" != "daily" && "$CADENCE" != "weekly" ]]; then
echo "ERROR: --cadence must be 'daily' or 'weekly'." >&2
exit 1
fi
# ---------------------------------------------------------------------------
# Resolve token
# ---------------------------------------------------------------------------
TOKEN="${GITHUB_TOKEN:-${GH_TOKEN:-}}"
if [[ -z "$TOKEN" ]]; then
echo "ERROR: GITHUB_TOKEN (or GH_TOKEN) must be set for API access." >&2
echo "Without a token, remote task locking is impossible." >&2
exit 1
fi
# ---------------------------------------------------------------------------
# Helper: authenticated GitHub API call
# ---------------------------------------------------------------------------
gh_api() {
local method="$1"
local endpoint="$2"
local data="${3:-}"
local args=(
-s -f
-X "$method"
-H "Authorization: Bearer ${TOKEN}"
-H "Accept: application/vnd.github+json"
-H "X-GitHub-Api-Version: 2022-11-28"
)
if [[ -n "$data" ]]; then
args+=(-H "Content-Type: application/json" -d "$data")
fi
curl "${args[@]}" "${API_BASE}${endpoint}"
}
# ---------------------------------------------------------------------------
# Generate identifiers
# ---------------------------------------------------------------------------
TIMESTAMP=$(date -u +"%Y-%m-%d_%H-%M-%S")
DATE_ONLY=$(date -u +"%Y-%m-%d")
RUN_ID="${RUN_ID:-$(date -u +"%s")}"
BRANCH_NAME="agents/${CADENCE}/${AGENT}/${DATE_ONLY}-run-${RUN_ID}"
LOG_DIR="docs/agents/task-logs/${CADENCE}"
LOG_FILE="${TIMESTAMP}_${AGENT}_started.md"
LOG_PATH="${LOG_DIR}/${LOG_FILE}"
echo "Claiming task: ${AGENT} (${CADENCE})" >&2
echo "Branch: ${BRANCH_NAME}" >&2
echo "Log file: ${LOG_PATH}" >&2
# ---------------------------------------------------------------------------
# Step 1: Get the latest commit SHA of the base branch
# ---------------------------------------------------------------------------
echo "Step 1: Fetching base branch SHA (${BASE_BRANCH})..." >&2
BASE_REF_JSON=$(gh_api GET "/git/refs/heads/${BASE_BRANCH}")
BASE_SHA=$(echo "$BASE_REF_JSON" | jq -r '.object.sha // empty')
if [[ -z "$BASE_SHA" ]]; then
echo "ERROR: Could not resolve base branch '${BASE_BRANCH}'." >&2
echo "API response: ${BASE_REF_JSON}" >&2
exit 2
fi
echo " Base SHA: ${BASE_SHA}" >&2
# ---------------------------------------------------------------------------
# Step 2: Create the remote branch
# ---------------------------------------------------------------------------
echo "Step 2: Creating remote branch..." >&2
CREATE_REF_JSON=$(gh_api POST "/git/refs" "$(jq -n \
--arg ref "refs/heads/${BRANCH_NAME}" \
--arg sha "$BASE_SHA" \
'{ref: $ref, sha: $sha}')")
CREATED_REF=$(echo "$CREATE_REF_JSON" | jq -r '.ref // empty')
if [[ -z "$CREATED_REF" ]]; then
# Check if it's a 422 (already exists) — another agent may have claimed it
ERROR_MSG=$(echo "$CREATE_REF_JSON" | jq -r '.message // empty')
if [[ "$ERROR_MSG" == *"Reference already exists"* ]]; then
echo "RACE DETECTED: Branch '${BRANCH_NAME}' already exists. Another agent claimed first." >&2
exit 2
fi
echo "ERROR: Failed to create branch." >&2
echo "API response: ${CREATE_REF_JSON}" >&2
exit 2
fi
echo " Created: ${CREATED_REF}" >&2
# ---------------------------------------------------------------------------
# Step 3: Create the started.md log file on the branch
# ---------------------------------------------------------------------------
echo "Step 3: Creating started.md log file..." >&2
LOG_CONTENT=$(cat <<LOGEOF
# Started ${AGENT} run
Agent: ${AGENT}
Date: ${DATE_ONLY}
Branch: ${BRANCH_NAME}
Claimed-via: GitHub API (claim-task-api.sh)
LOGEOF
)
# Base64 encode the content (compatible with both GNU and BSD base64)
ENCODED_CONTENT=$(echo "$LOG_CONTENT" | base64 -w 0 2>/dev/null || echo "$LOG_CONTENT" | base64)
CREATE_FILE_JSON=$(gh_api PUT "/contents/${LOG_PATH}" "$(jq -n \
--arg message "chore(agents): claim ${CADENCE} task for ${AGENT}" \
--arg content "$ENCODED_CONTENT" \
--arg branch "$BRANCH_NAME" \
'{message: $message, content: $content, branch: $branch}')")
FILE_PATH_CREATED=$(echo "$CREATE_FILE_JSON" | jq -r '.content.path // empty')
if [[ -z "$FILE_PATH_CREATED" ]]; then
echo "ERROR: Failed to create log file." >&2
echo "API response: ${CREATE_FILE_JSON}" >&2
# Clean up: delete the branch we created
gh_api DELETE "/git/refs/heads/${BRANCH_NAME}" >/dev/null 2>&1 || true
exit 2
fi
echo " Created: ${FILE_PATH_CREATED}" >&2
# ---------------------------------------------------------------------------
# Step 4: Create a draft PR
# ---------------------------------------------------------------------------
echo "Step 4: Creating draft PR..." >&2
PR_TITLE="[${CADENCE}] ${AGENT}: ${DATE_ONLY} run"
PR_BODY="Automated task claim for **${AGENT}** (${CADENCE} cadence).
Branch: \`${BRANCH_NAME}\`
Claimed at: ${TIMESTAMP} UTC
Method: GitHub API (claim-task-api.sh)
---
*This draft PR serves as a distributed lock. Do not merge until the agent completes its work.*"
CREATE_PR_JSON=$(gh_api POST "/pulls" "$(jq -n \
--arg title "$PR_TITLE" \
--arg body "$PR_BODY" \
--arg head "$BRANCH_NAME" \
--arg base "$BASE_BRANCH" \
'{title: $title, body: $body, head: $head, base: $base, draft: true}')")
PR_NUMBER=$(echo "$CREATE_PR_JSON" | jq -r '.number // empty')
PR_URL=$(echo "$CREATE_PR_JSON" | jq -r '.html_url // empty')
if [[ -z "$PR_NUMBER" ]]; then
echo "WARNING: Draft PR creation failed. Branch and log file exist as partial lock." >&2
echo "API response: ${CREATE_PR_JSON}" >&2
# Don't exit — the branch itself is still a visible claim
PR_NUMBER="FAILED"
PR_URL="FAILED"
else
echo " PR #${PR_NUMBER}: ${PR_URL}" >&2
fi
# ---------------------------------------------------------------------------
# Output machine-readable results
# ---------------------------------------------------------------------------
echo "CLAIM_BRANCH=${BRANCH_NAME}"
echo "CLAIM_PR_NUMBER=${PR_NUMBER}"
echo "CLAIM_PR_URL=${PR_URL}"
echo "CLAIM_LOG_FILE=${LOG_PATH}"
echo ""
echo "Task claimed successfully." >&2
scripts/agent/nostr-lock.mjs
Executable
+519
View File
@@ -0,0 +1,519 @@
#!/usr/bin/env node
// scripts/agent/nostr-lock.mjs
//
// TORCH — Task Orchestration via Relay-Coordinated Handoff
//
// Decentralized task locking for multi-agent development using Nostr.
// Each lock generates a fresh ephemeral keypair and discards it.
// Locks auto-expire via NIP-40 — no cleanup, no tokens, no secrets.
//
// See docs/agents/TORCH.md for the full protocol documentation.
//
// Commands:
// check --cadence <daily|weekly> JSON list of locked agents
// lock --agent <name> --cadence <daily|weekly> Claim a lock (exit 0=won, 3=lost)
// list [--cadence <daily|weekly>] Human-readable lock table
//
// Environment:
// NOSTR_LOCK_RELAYS Comma-separated relay WSS URLs (overrides defaults)
// NOSTR_LOCK_TTL Lock TTL in seconds (default: 7200 = 2 hours)
import { generateSecretKey, getPublicKey, finalizeEvent } from 'nostr-tools/pure';
import { SimplePool } from 'nostr-tools/pool';
import { useWebSocketImplementation } from 'nostr-tools/relay';
import WebSocket from 'ws';
useWebSocketImplementation(WebSocket);
// ---------------------------------------------------------------------------
// Configuration
// ---------------------------------------------------------------------------
const DEFAULT_RELAYS = [
'wss://relay.damus.io',
'wss://nos.lol',
'wss://relay.primal.net',
];
const DEFAULT_TTL = 7200; // 2 hours in seconds
const QUERY_TIMEOUT_MS = 15_000;
const VALID_CADENCES = new Set(['daily', 'weekly']);
const DAILY_ROSTER = [
'audit-agent',
'ci-health-agent',
'const-refactor-agent',
'content-audit-agent',
'decompose-agent',
'deps-security-agent',
'design-system-audit-agent',
'docs-agent',
'docs-alignment-agent',
'docs-code-investigator',
'innerhtml-migration-agent',
'known-issues-agent',
'load-test-agent',
'nip-research-agent',
'onboarding-audit-agent',
'perf-agent',
'prompt-curator-agent',
'scheduler-update-agent',
'style-agent',
'test-audit-agent',
'todo-triage-agent',
];
const WEEKLY_ROSTER = [
'bug-reproducer-agent',
'changelog-agent',
'dead-code-agent',
'event-schema-agent',
'frontend-console-debug-agent',
'fuzz-agent',
'interop-agent',
'perf-deepdive-agent',
'perf-optimization-agent',
'pr-review-agent',
'race-condition-agent',
'refactor-agent',
'smoke-agent',
'telemetry-agent',
'test-coverage-agent',
'weekly-synthesis-agent',
];
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
function getRelays() {
const envRelays = process.env.NOSTR_LOCK_RELAYS;
if (envRelays) {
return envRelays
.split(',')
.map((r) => r.trim())
.filter(Boolean);
}
return DEFAULT_RELAYS;
}
function getTtl() {
const envTtl = process.env.NOSTR_LOCK_TTL;
if (envTtl) {
const parsed = parseInt(envTtl, 10);
if (!Number.isNaN(parsed) && parsed > 0) return parsed;
}
return DEFAULT_TTL;
}
function todayDateStr() {
return new Date().toISOString().slice(0, 10); // YYYY-MM-DD
}
function todayStartUnix() {
const d = new Date();
d.setUTCHours(0, 0, 0, 0);
return Math.floor(d.getTime() / 1000);
}
function nowUnix() {
return Math.floor(Date.now() / 1000);
}
function getRoster(cadence) {
return cadence === 'daily' ? DAILY_ROSTER : WEEKLY_ROSTER;
}
/** Parse a lock event into a structured object. */
function parseLockEvent(event) {
const dTag = event.tags.find((t) => t[0] === 'd')?.[1] ?? '';
const expTag = event.tags.find((t) => t[0] === 'expiration')?.[1];
const expiresAt = expTag ? parseInt(expTag, 10) : null;
let content = {};
try {
content = JSON.parse(event.content);
} catch {
// content might not be valid JSON
}
return {
eventId: event.id,
pubkey: event.pubkey,
createdAt: event.created_at,
createdAtIso: new Date(event.created_at * 1000).toISOString(),
expiresAt,
expiresAtIso: expiresAt ? new Date(expiresAt * 1000).toISOString() : null,
dTag,
agent: content.agent ?? null,
cadence: content.cadence ?? null,
status: content.status ?? null,
date: content.date ?? null,
platform: content.platform ?? null,
};
}
/** Filter out expired locks. */
function filterActiveLocks(locks) {
const now = nowUnix();
return locks.filter((lock) => {
if (lock.expiresAt && lock.expiresAt <= now) return false;
return true;
});
}
// ---------------------------------------------------------------------------
// Relay operations
// ---------------------------------------------------------------------------
/**
* Query relays for lock events matching a cadence and date.
* Returns parsed lock objects.
*/
async function queryLocks(relays, cadence, dateStr) {
const pool = new SimplePool();
const tagFilter = `bitvid-lock-${cadence}-${dateStr}`;
try {
const events = await Promise.race([
pool.querySync(relays, {
kinds: [30078],
'#t': [tagFilter],
}),
new Promise((_, reject) =>
setTimeout(() => reject(new Error('Relay query timed out')), QUERY_TIMEOUT_MS),
),
]);
return filterActiveLocks(events.map(parseLockEvent));
} finally {
pool.close(relays);
}
}
/**
* Publish a lock event to relays.
* Returns the signed event.
*/
async function publishLock(relays, event) {
const pool = new SimplePool();
try {
const publishPromises = pool.publish(relays, event);
const results = await Promise.allSettled(publishPromises);
const successes = results.filter((r) => r.status === 'fulfilled');
if (successes.length === 0) {
const errors = results.map((r, i) => {
if (r.status === 'rejected') {
const reason = r.reason;
const msg = reason instanceof Error ? reason.message : String(reason ?? 'unknown');
return `${relays[i]}: ${msg}`;
}
return `${relays[i]}: unknown`;
});
throw new Error(`Failed to publish to any relay:\n ${errors.join('\n ')}`);
}
console.error(` Published to ${successes.length}/${relays.length} relays`);
return event;
} finally {
pool.close(relays);
}
}
// ---------------------------------------------------------------------------
// Commands
// ---------------------------------------------------------------------------
async function cmdCheck(cadence) {
const relays = getRelays();
const dateStr = todayDateStr();
console.error(`Checking locks: cadence=${cadence}, date=${dateStr}`);
console.error(`Relays: ${relays.join(', ')}`);
const locks = await queryLocks(relays, cadence, dateStr);
const lockedAgents = [...new Set(locks.map((l) => l.agent).filter(Boolean))];
const roster = getRoster(cadence);
const available = roster.filter((a) => !lockedAgents.includes(a));
const result = {
cadence,
date: dateStr,
locked: lockedAgents.sort(),
available: available.sort(),
lockCount: locks.length,
locks: locks.map((l) => ({
agent: l.agent,
eventId: l.eventId,
createdAt: l.createdAtIso,
expiresAt: l.expiresAtIso,
platform: l.platform,
})),
};
// Machine-readable JSON to stdout
console.log(JSON.stringify(result, null, 2));
}
async function cmdLock(agent, cadence, dryRun = false) {
const relays = getRelays();
const dateStr = todayDateStr();
const ttl = getTtl();
const now = nowUnix();
const expiresAt = now + ttl;
console.error(`Locking: agent=${agent}, cadence=${cadence}, date=${dateStr}`);
console.error(`TTL: ${ttl}s, expires: ${new Date(expiresAt * 1000).toISOString()}`);
console.error(`Relays: ${relays.join(', ')}`);
// Step 1: Check for existing locks on this agent
console.error('Step 1: Checking for existing locks...');
const existingLocks = await queryLocks(relays, cadence, dateStr);
const conflicting = existingLocks.filter((l) => l.agent === agent);
if (conflicting.length > 0) {
const earliest = conflicting.sort((a, b) => a.createdAt - b.createdAt)[0];
console.error(
`LOCK DENIED: ${agent} already locked by event ${earliest.eventId} ` +
`(created ${earliest.createdAtIso}, platform: ${earliest.platform})`,
);
console.log(`LOCK_STATUS=denied`);
console.log(`LOCK_REASON=already_locked`);
console.log(`LOCK_EXISTING_EVENT=${earliest.eventId}`);
process.exit(3);
}
// Step 2: Generate ephemeral keypair
console.error('Step 2: Generating ephemeral keypair...');
const sk = generateSecretKey();
const pk = getPublicKey(sk);
console.error(` Ephemeral pubkey: ${pk.slice(0, 16)}...`);
// Step 3: Build and sign the lock event
console.error('Step 3: Building lock event...');
const event = finalizeEvent(
{
kind: 30078,
created_at: now,
tags: [
['d', `bitvid-lock/${cadence}/${agent}/${dateStr}`],
['t', 'bitvid-agent-lock'],
['t', `bitvid-lock-${cadence}`],
['t', `bitvid-lock-${cadence}-${dateStr}`],
['expiration', String(expiresAt)],
],
content: JSON.stringify({
agent,
cadence,
status: 'started',
date: dateStr,
platform: process.env.AGENT_PLATFORM || 'unknown',
lockedAt: new Date(now * 1000).toISOString(),
expiresAt: new Date(expiresAt * 1000).toISOString(),
}),
},
sk,
);
console.error(` Event ID: ${event.id}`);
// Step 4: Publish to relays
if (dryRun) {
console.error('Step 4: [DRY RUN] Skipping publish — event built but not sent');
console.error('RACE CHECK: won (dry run — no real contention possible)');
} else {
console.error('Step 4: Publishing to relays...');
await publishLock(relays, event);
// Step 5: Race check — re-query and verify we're the earliest
console.error('Step 5: Race check...');
// Brief pause to let relays propagate
await new Promise((resolve) => setTimeout(resolve, 1500));
const postLocks = await queryLocks(relays, cadence, dateStr);
const racingLocks = postLocks
.filter((l) => l.agent === agent)
.sort((a, b) => a.createdAt - b.createdAt);
if (racingLocks.length > 1 && racingLocks[0].eventId !== event.id) {
const winner = racingLocks[0];
console.error(
`RACE CHECK: lost (earlier lock by event ${winner.eventId}, ` +
`created ${winner.createdAtIso})`,
);
console.log(`LOCK_STATUS=race_lost`);
console.log(`LOCK_REASON=earlier_claim_exists`);
console.log(`LOCK_WINNER_EVENT=${winner.eventId}`);
process.exit(3);
}
console.error('RACE CHECK: won');
}
// Output machine-readable results to stdout
console.log(`LOCK_STATUS=ok`);
console.log(`LOCK_EVENT_ID=${event.id}`);
console.log(`LOCK_PUBKEY=${pk}`);
console.log(`LOCK_AGENT=${agent}`);
console.log(`LOCK_CADENCE=${cadence}`);
console.log(`LOCK_DATE=${dateStr}`);
console.log(`LOCK_EXPIRES=${expiresAt}`);
console.log(`LOCK_EXPIRES_ISO=${new Date(expiresAt * 1000).toISOString()}`);
}
async function cmdList(cadence) {
const relays = getRelays();
const dateStr = todayDateStr();
const cadences = cadence ? [cadence] : ['daily', 'weekly'];
console.error(`Listing active locks for: ${cadences.join(', ')}`);
for (const c of cadences) {
const locks = await queryLocks(relays, c, dateStr);
console.log(`\n${'='.repeat(72)}`);
console.log(`Active ${c} locks (${dateStr})`);
console.log('='.repeat(72));
if (locks.length === 0) {
console.log(' (no active locks)');
continue;
}
const sorted = locks.sort((a, b) => a.createdAt - b.createdAt);
for (const lock of sorted) {
const age = nowUnix() - lock.createdAt;
const ageMin = Math.round(age / 60);
const remaining = lock.expiresAt ? lock.expiresAt - nowUnix() : null;
const remainMin = remaining ? Math.round(remaining / 60) : '?';
console.log(
` ${(lock.agent ?? 'unknown').padEnd(30)} ` +
`age: ${String(ageMin).padStart(4)}m ` +
`ttl: ${String(remainMin).padStart(4)}m ` +
`platform: ${lock.platform ?? '?'} ` +
`event: ${lock.eventId?.slice(0, 12)}...`,
);
}
const roster = getRoster(c);
const lockedAgents = new Set(locks.map((l) => l.agent).filter(Boolean));
const available = roster.filter((a) => !lockedAgents.has(a));
console.log(`\n Locked: ${lockedAgents.size}/${roster.length}`);
console.log(` Available: ${available.join(', ') || '(none)'}`);
}
}
// ---------------------------------------------------------------------------
// CLI argument parsing
// ---------------------------------------------------------------------------
function parseArgs(argv) {
const args = { command: null, agent: null, cadence: null, dryRun: false };
let i = 0;
// First positional arg is the command
if (argv.length > 0 && !argv[0].startsWith('-')) {
args.command = argv[0];
i = 1;
}
for (; i < argv.length; i++) {
const arg = argv[i];
if (arg === '--agent' || arg === '-a') {
args.agent = argv[++i];
} else if (arg === '--cadence' || arg === '-c') {
args.cadence = argv[++i];
} else if (arg.startsWith('--agent=')) {
args.agent = arg.split('=')[1];
} else if (arg.startsWith('--cadence=')) {
args.cadence = arg.split('=')[1];
} else if (arg === '--dry-run') {
args.dryRun = true;
}
}
return args;
}
function usage() {
console.error(`Usage: node scripts/agent/nostr-lock.mjs <command> [options]
Commands:
check --cadence <daily|weekly> Check which agents are locked (JSON)
lock --agent <name> --cadence <daily|weekly> Claim a lock for an agent
list [--cadence <daily|weekly>] Human-readable lock table
Options:
--dry-run Build and sign the event but don't publish (for testing)
Environment:
NOSTR_LOCK_RELAYS Comma-separated relay WSS URLs
NOSTR_LOCK_TTL Lock TTL in seconds (default: 7200)
AGENT_PLATFORM Platform identifier (e.g., "jules", "claude-code")
Exit codes:
0 Success (lock acquired or check complete)
1 Usage error
2 Relay/network error
3 Lock denied (already locked or race lost)`);
}
// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------
async function main() {
const args = parseArgs(process.argv.slice(2));
if (!args.command) {
usage();
process.exit(1);
}
switch (args.command) {
case 'check': {
if (!args.cadence || !VALID_CADENCES.has(args.cadence)) {
console.error('ERROR: --cadence <daily|weekly> is required for check');
process.exit(1);
}
await cmdCheck(args.cadence);
break;
}
case 'lock': {
if (!args.agent) {
console.error('ERROR: --agent <name> is required for lock');
process.exit(1);
}
if (!args.cadence || !VALID_CADENCES.has(args.cadence)) {
console.error('ERROR: --cadence <daily|weekly> is required for lock');
process.exit(1);
}
await cmdLock(args.agent, args.cadence, args.dryRun);
break;
}
case 'list': {
if (args.cadence && !VALID_CADENCES.has(args.cadence)) {
console.error('ERROR: --cadence must be daily or weekly');
process.exit(1);
}
await cmdList(args.cadence || null);
break;
}
default:
console.error(`ERROR: Unknown command: ${args.command}`);
usage();
process.exit(1);
}
}
main().catch((err) => {
console.error(`nostr-lock failed: ${err.message}`);
process.exit(2);
});