TORCH/TORCH.md

# TORCH: Task Orchestration via Relay-Coordinated Handoff

TORCH is a decentralized task-locking protocol for multi-agent software development. This document serves as the primary manual for both human operators and AI agents working within a TORCH-enabled repository.

---

## Agent Operating Guide

This section defines how agents should work in this repository.

### Purpose

- Keep agent work predictable, auditable, and safe.
- Minimize repeated discovery work across sessions.
- Capture durable learnings so future agents can move faster.

### Session startup checklist (run every session)

1. **Read `TORCH.md`** (this file).
2. Read `CONTRIBUTING.md` for commit and PR expectations.
3. Read `KNOWN_ISSUES.md` for active blockers and workarounds.
4. Read `docs/agent-handoffs/README.md`.
5. Scan recent notes in:
   - `docs/agent-handoffs/learnings/`
   - `docs/agent-handoffs/incidents/`
6. If present, review the current run artifacts in:
   - `src/context/`
   - `src/todo/`
   - `src/decisions/`
   - `src/test_logs/`
   - `src/issues/`

### Core operating principles

- Default to generic guidance and neutral language.
- Make the smallest safe change that satisfies the request.
- Avoid unrelated refactors.
- Preserve backward compatibility unless explicitly asked otherwise.
- Prefer explicit commands and documented behavior over assumptions.
- Record assumptions clearly in your final summary.

### Validation policy

- Run the most relevant checks for changed files (tests, lint, typecheck, build, or targeted scripts).
- Never claim a check passed unless it was actually executed.
- If a check cannot run, record:
   - command attempted,
   - why it could not complete,
   - what fallback validation was performed.

### Execution Workflow

1. **Load baseline context** (see Session startup checklist above).
2. **Clarify the task**
   - Restate the requested outcome.
   - Identify constraints, risks, and assumptions.
3. **Plan minimal changes**
   - Keep scope tight.
   - Avoid touching unrelated files.
4. **Implement**
   - Apply small, reversible edits.
   - Favor readability and maintainability.
5. **Validate**
   - Run relevant checks for impacted files.
   - Capture exact commands and outcomes.
6. **Document and hand off**
   - Summarize what changed and why.
   - Record reusable learnings/incidents when appropriate.

### Working files for session state

Use the following folders as lightweight coordination artifacts:

- `src/context/` — Current objective, scope, constraints.
- `src/todo/` — Task checklist and blockers.
- `src/decisions/` — Important design/implementation choices.
- `src/test_logs/` — Validation commands and results.
- `src/issues/` — Investigations or audits that may become tracked issues.

#### Content templates

**Context note:** Goal, Scope, Constraints, Open questions.
**Todo note:** Pending tasks, Completed tasks, Blocked tasks.
**Decision note:** Decision, Alternatives considered, Rationale, Consequences/follow-ups.
**Test log:** Command, Result (pass/fail/warn), Notes (environmental limits, retries, artifacts).

### Knowledge-sharing protocol

#### What belongs where

- `KNOWN_ISSUES.md`: Active, reproducible issues only. Include status, impact, workaround, and last verification date.
- `docs/agent-handoffs/learnings/`: Proven patterns, repeatable fixes, and successful implementation guidance.
- `docs/agent-handoffs/incidents/`: Failures, root causes, mitigations, and prevention guidance.
- `src/context/`, `src/todo/`, etc.: Ephemeral session state.

#### Naming standard

Use: `YYYY-MM-DD-short-topic.md` (e.g., `2026-02-14-validation-before-summary.md`).
Keep names concise, descriptive, and neutral.

#### Required sections for reusable notes

1. Context
2. Observation
3. Action taken
4. Validation performed
5. Recommendation for next agents

#### Update decision tree

When you discover reusable context:
1. Check if an existing note already covers it.
2. If yes, update that note.
3. If no, add a new note in `learnings/` or `incidents/`.
4. If the issue is still active/reproducible, add or update `KNOWN_ISSUES.md`.

### Quality checklist before completion

- Scope matches request.
- Documentation remains repository-agnostic unless explicitly needed.
- No unsupported claims about testing.
- Assumptions and limitations are called out.
- Changes are easy to revert.

### Anti-patterns to avoid

- Embedding product/company-specific guidance in baseline docs.
- Large refactors when a focused change is sufficient.
- Skipping validation without recording why.
- Creating duplicate notes when an update would suffice.

---

## Dashboard & Protocol Overview

The TORCH dashboard subscribes to Nostr relays for **kind 30078** events tagged with the `#torch-agent-lock` hashtag. These are the same events agents publish via `bin/torch-lock.mjs` when they claim tasks using the TORCH protocol.

**Relays:** `wss://relay.damus.io`, `wss://nos.lol`, `wss://relay.primal.net`

**Filter:** `{"kinds":[30078],"#t":["torch-agent-lock"]}`

**Unique identifier:** All events use the `torch-lock/` namespace in the d-tag and the `#torch-agent-lock` hashtag. This scopes events to this repository and is how both agents and the dashboard filter messages.

To follow in any Nostr client, subscribe to kind 30078 with `#t = torch-agent-lock` on the relays above.

## Quick start

```bash
# Check active locks
node bin/torch-lock.mjs check --cadence daily

# Machine-readable lock output (recommended for automation)
node bin/torch-lock.mjs check --cadence daily --json --quiet --json-file /tmp/torch-lock-check.json

# 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

# Probe relay health before scheduler lock acquisition
node bin/torch-lock.mjs health --cadence daily
```

## 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_HASHTAG`
- `NOSTR_LOCK_RELAYS`
- `NOSTR_LOCK_TTL`
- `NOSTR_LOCK_QUERY_TIMEOUT_MS`
- `NOSTR_LOCK_PUBLISH_TIMEOUT_MS`
- `NOSTR_LOCK_MIN_SUCCESSFUL_PUBLISHES`
- `NOSTR_LOCK_RELAY_FALLBACKS`
- `NOSTR_LOCK_MIN_ACTIVE_RELAY_POOL`
- `NOSTR_LOCK_DAILY_ROSTER`
- `NOSTR_LOCK_WEEKLY_ROSTER`
- `TORCH_CONFIG_PATH`
- `AGENT_PLATFORM` (supports `codex`, `claude`, or `linux` for simulated/manual execution)
- `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 (ms, valid range: 100..120000).
- `nostrLock.publishTimeoutMs` — per-relay publish timeout (ms, valid range: 100..120000).
- `nostrLock.minSuccessfulRelayPublishes` — minimum successful publishes required before lock acquisition continues (default: `1`).
- `nostrLock.relayFallbacks` — optional fallback relay URLs used when primary query/publish attempts fail quorum.
- `nostrLock.minActiveRelayPool` — minimum number of relays kept active even when lower-ranked relays are quarantined (default: `1`).
- `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`).
- `dashboard.hashtag` — custom hashtag for lock events (defaults to `<namespace>-agent-lock`).
- `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.
- `scheduler.strict_lock` — lock backend policy switch (default: `true`); when `false`, scheduler defers backend-unavailable lock failures before converting the run to failed.
- `scheduler.degraded_lock_retry_window` — non-strict deferral window in milliseconds; backend lock failures outside this window immediately consume failure budget and mark run failed.
- `scheduler.max_deferrals` — max number of non-strict lock deferrals allowed in-window before scheduler records a hard failure.

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.

Scheduler failure classes in task logs:

- `backend_unavailable` — legacy compatibility field for lock backend unavailable failures.
- `prompt_validation_error` — legacy compatibility field for prompt/runtime validation failures.

Scheduler failure categories in task logs:

- `lock_backend_error` — lock backend unavailable preflight failures and lock acquisition backend exit code `2` failures/deferrals; includes relay health alert metadata, retry window guidance, health check command, and incident runbook link.
- `prompt_parse_error` — scheduler could not read/parse the selected prompt file; prompt execution is skipped.
- `prompt_schema_error` — selected prompt file or generated run artifacts failed schema/contract checks; prompt run is treated as invalid.
- `execution_error` — runtime execution failures in handoff callbacks, memory commands, or configured validation commands.


## Lock backend production defaults

Recommended baseline for production scheduler runs:

- `nostrLock.relays`: 3+ geographically-diverse primary relays.
- `nostrLock.relayFallbacks`: 2 additional relays not present in primary list.
- `nostrLock.queryTimeoutMs`: `10000`
- `nostrLock.publishTimeoutMs`: `8000`
- `nostrLock.minSuccessfulRelayPublishes`: `2`
- `nostrLock.minActiveRelayPool`: `2`

Validation behavior:

- Relay URLs must be absolute `ws://` or `wss://` URLs.
- Invalid relay URLs or invalid timeout/count ranges are fatal startup errors.
- Lock backend errors include phase (`query:primary`, `query:fallback`, `publish:primary`, `publish:fallback`), relay endpoint, and timeout value used.
- When scheduler preflight fails before lock acquisition, task logs must explicitly state `prompt not executed` to make lock-vs-prompt root cause obvious in UI/CLI summaries.
- Interpret `relay_publish_quorum_failure` (derived from `lock_publish_quorum_failed` telemetry) as quorum not met even after retries/fallbacks. Expected operator actions:
  1. Run `npm run lock:health -- --cadence <daily|weekly>` to confirm relay readiness and identify failing relays/reasons.
  2. Review task log metadata (`lock_failure_reason_distribution`, `backend_category`, `lock_correlation_id`) for dominant failure modes (timeouts, DNS, auth, malformed relay URL).
  3. If failures persist past retry window, follow incident runbook `docs/agent-handoffs/learnings/2026-02-15-relay-health-preflight-job.md` and escalate relay/network remediation.
- Relay health snapshots are emitted periodically and whenever lock publish/query fails; snapshots include success rate, timeout rate, rolling latency, and quarantine state per relay.

## Scheduler lock reliability reporting

Run the lock reliability summary to aggregate recent scheduler outcomes by platform, cadence, backend error category, and relay endpoint:

```bash
npm run report:lock-reliability
```

Outputs:
- `artifacts/lock-reliability/lock-reliability-summary.md`
- `artifacts/lock-reliability/lock-reliability-summary.json`


## 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.

## Offline & Air-Gapped Installation

TORCH is designed to operate in diverse environments, including high-security, air-gapped, or offline networks where direct access to the npm registry is restricted.

### The Offline Bundle

The "Offline Bundle" is a standard npm package tarball (`.tgz`) generated during the build process. It contains the complete source code and dependency definitions required to run TORCH.

**Why use the bundle?**

1.  **Security & Integrity:** You can verify the checksum of the tarball before installing it. It creates a frozen snapshot of the code that doesn't change.
2.  **No Registry Dependency:** You can install it directly using `npm install ./torch-lock-0.1.0.tgz` without needing to connect to `registry.npmjs.org`.
3.  **Project Integration:** Unlike a binary executable, the tarball installs TORCH as a standard dependency in your `package.json`. This ensures:
    *   Scripts like `npm run lock:check` work natively.
    *   TORCH versioning is managed alongside your other dependencies.
    *   It works across all operating systems that support Node.js.

### Installation Instructions

1.  Download the tarball from the landing page or your internal artifact repository.
2.  Place it in your project root or a `vendor/` directory.
3.  Run the install command:
    ```bash
    npm install ./torch-lock-0.1.0.tgz
    ```
    *(Replace `0.1.0` with the actual version number)*

4.  Initialize TORCH:
    ```bash
    npx torch-lock init
    ```