mirror of
https://github.com/PR0M3TH3AN/TORCH.git
synced 2026-11-04 20:01:54 +00:00
101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# TORCH: Task Orchestration via Relay-Coordinated Handoff
|
|
|
|
TORCH is a decentralized task-locking protocol for multi-agent software development.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# Check active locks
|
|
node bin/torch-lock.mjs check --cadence daily
|
|
|
|
# Claim a task
|
|
AGENT_PLATFORM=codex node bin/torch-lock.mjs lock --agent docs-agent --cadence daily
|
|
|
|
# List all active locks
|
|
node bin/torch-lock.mjs list
|
|
```
|
|
|
|
## Defaults
|
|
|
|
- Kind: `30078` (NIP-33 parameterized replaceable)
|
|
- Expiration: `NIP-40` via `expiration` tag
|
|
- TTL: `7200s` (2h)
|
|
- Namespace: `torch`
|
|
- Relays:
|
|
- `wss://relay.damus.io`
|
|
- `wss://nos.lol`
|
|
- `wss://relay.primal.net`
|
|
|
|
## Environment variables
|
|
|
|
- `NOSTR_LOCK_NAMESPACE`
|
|
- `NOSTR_LOCK_RELAYS`
|
|
- `NOSTR_LOCK_TTL`
|
|
- `NOSTR_LOCK_QUERY_TIMEOUT_MS`
|
|
- `NOSTR_LOCK_DAILY_ROSTER`
|
|
- `NOSTR_LOCK_WEEKLY_ROSTER`
|
|
- `TORCH_CONFIG_PATH`
|
|
- `AGENT_PLATFORM`
|
|
- `TORCH_MEMORY_ENABLED` (`true`/`false`; global memory kill switch, defaults to enabled)
|
|
- `TORCH_MEMORY_INGEST_ENABLED` (`true`/`false` or comma-separated canary `agent_id` allow list)
|
|
- `TORCH_MEMORY_RETRIEVAL_ENABLED` (`true`/`false` or comma-separated canary `agent_id` allow list)
|
|
- `TORCH_MEMORY_PRUNE_ENABLED` (`true`, `false`, or `dry-run`)
|
|
|
|
## torch-config.json
|
|
|
|
You can configure TORCH per repository with a root-level `torch-config.json` file.
|
|
|
|
Common settings:
|
|
|
|
- `nostrLock.namespace` — namespace prefix used in d-tags and hashtags.
|
|
- `nostrLock.relays` — relay list for check/lock/list operations.
|
|
- `nostrLock.ttlSeconds` — default lock TTL.
|
|
- `nostrLock.queryTimeoutMs` — relay query timeout.
|
|
- `nostrLock.dailyRoster` / `nostrLock.weeklyRoster` — optional per-project roster overrides.
|
|
- `dashboard.defaultCadenceView` — default dashboard view (`daily`, `weekly`, `all`).
|
|
- `dashboard.defaultStatusView` — default dashboard status filter (`active`, `all`).
|
|
- `scheduler.firstPromptByCadence.daily` / `.weekly` — first-run scheduler starting agent.
|
|
- `scheduler.handoffCommandByCadence.daily` / `.weekly` — shell command run after lock acquisition; command must use `SCHEDULER_AGENT`, `SCHEDULER_CADENCE`, and `SCHEDULER_PROMPT_PATH` provided by `scripts/agent/run-scheduler-cycle.mjs`.
|
|
- `scheduler.paused.daily` / `.weekly` — array of agent names to exclude from scheduler rotation.
|
|
|
|
Default first-run daily scheduler prompt is `scheduler-update-agent`.
|
|
|
|
For weekly repository-fit maintenance, TORCH also includes `src/prompts/weekly/repo-fit-agent.md` to periodically adjust defaults and docs to the host repository.
|
|
|
|
Operational note: scheduler handoff commands are treated as required execution steps. A non-zero exit code (or missing command) is a hard failure: the scheduler writes a `_failed.md` task log, exits immediately, and does not publish `lock:complete` for that run.
|
|
|
|
## Roster precedence
|
|
|
|
The lock CLI resolves roster names in this order:
|
|
|
|
1. `NOSTR_LOCK_DAILY_ROSTER` / `NOSTR_LOCK_WEEKLY_ROSTER` (comma-separated env overrides).
|
|
2. `torch-config.json` (`nostrLock.dailyRoster` / `nostrLock.weeklyRoster`).
|
|
3. `src/prompts/roster.json` (`daily` / `weekly` canonical scheduler roster).
|
|
4. Built-in fallback roster (used only if `src/prompts/roster.json` is unreadable).
|
|
|
|
`lock --agent` validates names against the resolved cadence roster, and `check`/`list` report lock events whose agent names do not match scheduler roster entries exactly.
|
|
|
|
|
|
## Exit codes
|
|
|
|
- `0`: success
|
|
- `1`: usage error
|
|
- `2`: relay/network error
|
|
- `3`: lock denied (already locked or race lost)
|
|
|
|
|
|
## Memory rollout plan
|
|
|
|
1. Deploy memory schema changes with scheduler jobs disabled (`TORCH_MEMORY_ENABLED=false` or subsystem flags set to `false`).
|
|
2. Enable ingest for one canary `agent_id` via `TORCH_MEMORY_INGEST_ENABLED=<agent_id>`.
|
|
3. Validate retrieval quality and storage growth metrics before expanding scope.
|
|
4. Enable broader retrieval (`TORCH_MEMORY_RETRIEVAL_ENABLED=<allow-list>` then `true`).
|
|
5. Enable pruning in `dry-run` mode first, then switch to active pruning after revalidation.
|
|
|
|
## Memory rollback plan
|
|
|
|
1. Disable memory flags (`TORCH_MEMORY_ENABLED=false` and/or set ingest/retrieval/prune flags to `false`).
|
|
2. Stop memory maintenance scheduler processes.
|
|
3. Preserve database state for post-incident analysis; do not drop or rewrite memory tables during rollback.
|
|
4. Keep prune actions in `dry-run` (or disabled) until lifecycle policy and data integrity are revalidated.
|