updated to remove /dist from gitignore

dist/src/docs/agent-handoffs/README.md

@@ -0,0 +1,56 @@
+# Agent Handoffs
+
+This directory stores reusable context so future agents can work faster without repeating discovery.
+
+## Directory purpose
+
+- `learnings/`: successful patterns, proven fixes, and repeatable implementation guidance.
+- `incidents/`: failures, root causes, mitigations, and prevention guidance.
+
+## When to write a note
+
+Create or update a note when your work reveals knowledge likely useful in future sessions.
+
+Examples:
+
+- A reliable fix pattern that can be reused.
+- A recurring failure mode and its mitigation.
+- A validation approach that prevented regressions.
+
+If the issue is still active/reproducible, also update `KNOWN_ISSUES.md`.
+
+## Naming convention
+
+Use:
+
+- `YYYY-MM-DD-short-topic.md`
+
+Examples:
+
+- `2026-02-14-validation-before-summary.md`
+- `2026-02-14-missing-baseline-context.md`
+
+## Required note structure
+
+Each learning/incident note should include:
+
+1. Context
+2. Observation
+3. Action taken
+4. Validation performed
+5. Recommendation for next agents
+
+## Writing guidelines
+
+- Keep entries short and actionable.
+- Prefer bullets over long narrative.
+- Include exact commands when useful for reproduction.
+- Avoid secrets, credentials, and identifying data.
+- Distinguish facts from assumptions.
+
+## Maintenance workflow
+
+1. Search for an existing related note.
+2. Update it if it already covers your case.
+3. Otherwise, add a new note using the naming convention.
+4. Cross-link related notes when helpful.

dist/src/docs/agent-handoffs/incidents/2026-02-14-missing-baseline-context.md

@@ -0,0 +1,7 @@
+# Missing Baseline Context
+
+- **Context:** Agent started editing without reviewing baseline policy files first.
+- **Observation:** Resulting patch required rework to match repository standards.
+- **Action taken:** Re-read policy docs, reverted conflicting edits, and reapplied changes correctly.
+- **Validation performed:** Compared final output to policy docs and reran checks.
+- **Recommendation for next agents:** Read `AGENTS.md` and `CLAUDE.md` first on every run to avoid avoidable churn.

dist/src/docs/agent-handoffs/incidents/2026-02-15-hermit-text-file-busy.md

@@ -0,0 +1,111 @@
+# Hermit "text file busy" (ETXTBSY) blocks all Torch commands on Goose Desktop
+
+## Context
+
+- **Date discovered:** 2026-02-15
+- **Platform:** Goose Desktop (Linux), any version shipping `/usr/lib/goose/resources/bin/node-setup-common.sh`
+- **Impact:** 100% of Torch lock/check/complete commands fail. Daily and weekly scheduler runs cannot proceed.
+- **Severity:** Critical — completely blocks all agent scheduling.
+
+## Observation
+
+Every `node` or `npx` invocation on Goose Desktop runs through a Bash wrapper (`/usr/lib/goose/resources/bin/node`) that sources `node-setup-common.sh`. This setup script:
+
+1. Downloads the hermit binary (~20 MB ELF) directly into `~/.config/goose/mcp-hermit/bin/hermit`
+2. Runs `hermit init` — which **overwrites its own binary** in-place (replaces the ELF with a ~1.5 KB shell stub)
+3. On Linux, writing to a binary that is currently executing produces `ETXTBSY` ("text file busy")
+
+The error is **100% reproducible** on clean state. Once hermit is downloaded, `hermit init` always fails because the running process holds the binary open.
+
+### Secondary bug: exit code swallowing
+
+The Goose `node` wrapper also swallows non-zero exit codes:
+
+```bash
+node "$@" || log "Failed to execute 'node' with arguments: $*"
+```
+
+This means `torch-lock lock` returning exit 3 (lock denied) appears as exit 0 to the caller, breaking the scheduler's lock-race retry logic.
+
+## Root cause analysis
+
+```
+/usr/lib/goose/resources/bin/node (bash wrapper)
+  → sources node-setup-common.sh
+    → downloads hermit ELF binary to ~/.config/goose/mcp-hermit/bin/hermit
+    → runs: hermit init
+      → hermit init tries to overwrite ~/.config/goose/mcp-hermit/bin/hermit
+      → ETXTBSY because that's the binary currently executing
+      → ERR trap fires → script exits 1
+```
+
+## Fix applied (local workaround)
+
+Patched `node-setup-common.sh` at `/home/user/.local/goose-fix/bin/node-setup-common.sh` with three changes:
+
+### 1. Atomic download (prevents partial writes / concurrent corruption)
+```bash
+HERMIT_TMP=$(mktemp ~/.config/goose/mcp-hermit/bin/.hermit-download.XXXXXX)
+curl ... | gzip -dc > "$HERMIT_TMP"
+chmod +x "$HERMIT_TMP"
+mv -f "$HERMIT_TMP" "$HERMIT_BIN"   # atomic rename
+sync
+```
+
+### 2. Copy-for-init (prevents ETXTBSY)
+```bash
+HERMIT_INIT_COPY=$(mktemp /tmp/.hermit-init-copy.XXXXXX)
+cp "$HERMIT_BIN" "$HERMIT_INIT_COPY"
+chmod +x "$HERMIT_INIT_COPY"
+"$HERMIT_INIT_COPY" init   # executing binary ≠ write target → no ETXTBSY
+rm -f "$HERMIT_INIT_COPY"
+```
+
+### 3. flock for concurrency (prevents download races)
+```bash
+exec 9>"$HERMIT_LOCK"
+flock -w 30 9
+# ... download + init ...
+flock -u 9
+```
+
+### 4. Save/restore working directory
+```bash
+_GOOSE_ORIG_CWD="$(pwd)"
+cd ~/.config/goose/mcp-hermit
+# ... setup ...
+cd "$_GOOSE_ORIG_CWD"   # restore so caller's relative paths work
+```
+
+## Validation performed
+
+```bash
+# Clean state test (from scratch):
+rm -rf ~/.config/goose/mcp-hermit
+PATH=/home/user/.local/goose-fix/bin:$PATH node bin/torch-lock.mjs check --cadence daily
+# → Exit 0, full JSON output with lock state
+# → hermit downloaded, initialized, node installed, lock check completed
+```
+
+## What needs to happen upstream
+
+### Goose repo PR (permanent fix)
+1. Apply the patch from `docs/agent-handoffs/incidents/goose-hermit-etxtbsy-fix.patch` to `/usr/lib/goose/resources/bin/node-setup-common.sh`
+2. Fix exit code swallowing in `/usr/lib/goose/resources/bin/node` and `npx`:
+   ```bash
+   # Before (swallows exit code):
+   node "$@" || log "Failed to execute 'node' with arguments: $*"
+   # After (preserves exit code):
+   node "$@"
+   ```
+3. File: <https://github.com/block/goose> — component: `resources/bin/node-setup-common.sh`
+
+### Torch repo (defensive improvement, optional)
+- Add `HERMIT_BIN_PATH` env var support so operators can point to a pre-initialized hermit
+- Add diagnostics to lock preflight failure messages (hermit stderr, `fuser` output, suggested fixes)
+
+## Recommendation for next agents
+
+- Until the upstream Goose fix ships, use `PATH=/home/user/.local/goose-fix/bin:$PATH` before any `node`/`npm` commands
+- If hermit gets stuck again: `rm -rf ~/.config/goose/mcp-hermit` and retry
+- The exit code swallowing bug means schedulers must parse stdout for `LOCK_STATUS=denied` rather than relying on exit codes

dist/src/docs/agent-handoffs/incidents/2026-02-16-npm-test-timeout.md

@@ -0,0 +1,23 @@
+# Incident: `npm test` Timeout in Sandbox Environment
+
+## Context
+Running `npm test` as part of the `onboarding-audit-agent` daily check.
+
+## Observation
+`npm test` timed out after 401 seconds.
+The command runs: `npm run validate:scheduler && npm run test:integration:e2e && node --test test/*.test.mjs tests/*.test.js`.
+- `validate:scheduler` passed (200ms).
+- `test:integration:e2e` passed (692ms).
+- `node --test test/*.test.mjs tests/*.test.js` timed out.
+Individual runs of many test files passed quickly.
+
+## Action taken
+Recorded the timeout in `artifacts/onboarding-audit-agent/report.md`.
+Verified individual tests passed.
+
+## Validation performed
+Ran individual tests (`lock-ops.test.mjs`, `lock-acquisition-resilience.integration.test.mjs`, etc.) and they passed.
+
+## Recommendation for next agents
+Investigate why running the full suite causes a timeout. It might be resource contention or a specific test that hangs only in the full suite context.
+Workaround: Run specific test subsets or increase timeout if possible.

dist/src/docs/agent-handoffs/incidents/2026-02-20-codex-test-failures-platform-and-telemetry.md

@@ -0,0 +1,30 @@
+# Codex environment test failures: scheduler platform assertion and memory telemetry capture
+
+## Context
+- Date: 2026-02-20
+- Agent: `docs-code-investigator`
+- Validation stage for documentation-only updates (`src/services/memory/index.js`).
+
+## Observation
+- `npm test` fails in `test/scheduler-preflight-lock.e2e.test.mjs`.
+- Failure detail: first e2e assertion expects frontmatter platform to be `unknown`, but scheduler log in this environment reports `platform: codex`.
+- Targeted memory test bundle (`node --test test/memory-*.test.mjs test/memory.test.js`) fails in `test/memory-telemetry.test.mjs`.
+- Direct run (`node test/memory-telemetry.test.mjs`) shows fixture child process exits with code `0` but both `stdout` and `stderr` are empty, failing assertions that expect `[PASS]` and `TORCH-MEMORY` output.
+
+## Action taken
+- Confirmed failures are reproducible and unrelated to documentation edits.
+- Captured reproductions with direct command runs to reveal assertion details.
+- Updated `KNOWN_ISSUES.md` with active issue entries for both failures.
+
+## Validation performed
+- `npm run lint` (pass)
+- `npm test` (fails in `test/scheduler-preflight-lock.e2e.test.mjs`)
+- `node --test test/scheduler-preflight-lock.e2e.test.mjs`
+- `node test/scheduler-preflight-lock.e2e.test.mjs`
+- `node --test test/memory-*.test.mjs test/memory.test.js`
+- `node test/memory-telemetry.test.mjs`
+
+## Recommendation for next agents
+- Treat these as environment-sensitive test failures until assertions are aligned with Codex platform semantics and child-process output behavior.
+- If updating tests, follow spec-correction protocol and preserve strict behavioral intent.
+- Keep `KNOWN_ISSUES.md` dates/status current after remediation.

dist/src/docs/agent-handoffs/incidents/2026-02-20-content-audit-no-upload-surface.md

@@ -0,0 +1,26 @@
+# content-audit-agent: no upload/contribution surface to audit
+
+## Context
+- Date: 2026-02-20
+- Agent: `content-audit-agent`
+- Prompt scope: verify upload/contribution user docs against runtime behavior.
+
+## Observation
+- `docs/` contains TORCH scheduler/lock documentation, not upload/contribution-media product docs.
+- Repository codebase has no upload UI/API/storage/moderation implementation paths to validate.
+- Keyword scans for upload/resumability/moderation claims return prompt text and unrelated matches only.
+
+## Action taken
+- Completed required startup and memory retrieval.
+- Produced canonical run artifacts under `src/context/`, `src/todo/`, `src/decisions/`, `src/test_logs/`.
+- Generated reproducible audit evidence in `artifacts/docs-audit/2026-02-20/`.
+- Added active issue entry in `KNOWN_ISSUES.md`.
+
+## Validation performed
+- `rg --hidden --files docs | sort`
+- `rg --hidden --line-number -i "upload|contribut|media|mime|multipart|resum|chunk|thumbnail|transcod|moderat|attribution|license" docs`
+- `rg --hidden --line-number -i "upload|multipart|mime|thumbnail|transcod|resumable|presign|signed url|moderat|attribution|drag.?drop|content-type" src docs test`
+
+## Recommendation for next agents
+- Treat this prompt as a scope-mismatch no-op until repository adds upload/contribution features or prompt scope is revised.
+- If scope is changed, target actual TORCH user docs contracts (lock lifecycle, scheduler flow, dashboard behavior) instead of upload-media behavior.

dist/src/docs/agent-handoffs/incidents/2026-02-20-pr-review-agent-artifact-metadata-failure.md

@@ -0,0 +1,35 @@
+# Incident: pr-review-agent verify-run-artifacts failure
+
+**Date:** 2026-02-19T05:06:16Z
+**Agent:** pr-review-agent
+**Platform:** linux
+**Incident ID:** PR-REVIEW-ARTIFACT-METADATA-2026-02-19
+
+## Context
+
+The `pr-review-agent` ran on 2026-02-19 (weekly cadence) on a linux platform. The scheduler's validate step (`node scripts/agent/verify-run-artifacts.mjs`) exited with code 1 while `npm run lint` passed (exit 0).
+
+## Observation
+
+- **failure_reason:** `Validation failed (Verify: 1, Lint: 0)`
+- The `verify-run-artifacts.mjs` script checks four artifact directories: `src/context/`, `src/todo/`, `src/decisions/`, `src/test_logs/`.
+- Each artifact must include YAML frontmatter with keys: `agent:`, `cadence:`, and `session:` or `run-start:`.
+- The agent either did not write any artifacts for the run window, or wrote files that lacked the required metadata fields.
+
+## Action taken
+
+- Documented this failure as an incident note.
+- No code changes made — the verify script and prompt are correct.
+- The prompt already instructs artifact writing (`Run artifacts (required)`) but does not specify the required metadata format.
+
+## Validation performed
+
+- Reviewed `verify-run-artifacts.mjs` source — the metadata validation logic (`validateArtifactMetadata`) is correct and checks for `agent:`, `cadence:`, and `session:`/`run-start:` keys.
+- No structural defects found in the verify script.
+
+## Recommendation for next agents
+
+1. When writing run artifacts, always include YAML frontmatter with `agent:`, `cadence:`, and `run-start:` (or `session:`) fields.
+2. Artifact content must also reference the active agent name and prompt file path.
+3. See `scripts/agent/verify-run-artifacts.mjs` lines 190–237 for the exact validation logic.
+4. Consider updating agent prompts to include an explicit artifact metadata template (a task for `prompt-maintenance-agent`).

dist/src/docs/agent-handoffs/incidents/2026-02-20-sandbox-test-permissions-eprem.md

@@ -0,0 +1,33 @@
+# Sandbox test permission failures: local socket bind and shell spawn blocked
+
+## Context
+- Date: 2026-02-20
+- Agent: `known-issues-agent`
+- Scope: daily `KNOWN_ISSUES.md` verification in Codex sandbox.
+
+## Observation
+- `npm test` fails in this environment for tests that require local socket listeners or shell-backed child processes.
+- Repro signals:
+  - `node test/dashboard-auth.test.mjs` => `listen EPERM: operation not permitted 127.0.0.1`
+  - `node test/nostr-lock.test.mjs` => `listen EPERM: operation not permitted 0.0.0.0`
+  - `node test/ops.test.mjs` => `spawnSync /bin/sh EPERM`
+- Additional child-process stdio assertion failures remain in `test/memory-telemetry.test.mjs` (empty `stdout`/`stderr`).
+
+## Action taken
+- Reproduced failures with targeted commands and captured exact failing signatures.
+- Updated `KNOWN_ISSUES.md` with an active sandbox-permissions entry and refreshed verification dates/status for all related entries.
+- Did not modify tests to relax assertions or bypass behavior checks.
+
+## Validation performed
+- `npm test`
+- `node --test test/scheduler-preflight-lock.e2e.test.mjs`
+- `node test/memory-telemetry.test.mjs`
+- `node test/dashboard-auth.test.mjs`
+- `node test/nostr-lock.test.mjs`
+- `node test/ops.test.mjs`
+- `npm run lock:health -- --cadence daily`
+
+## Recommendation for next agents
+- Treat these failures as environment constraints unless running in a runtime that permits local bind/listen and shell execution.
+- For CI portability, consider medium-scope refactors to isolate privileged test paths behind explicit environment guards, without weakening assertions.
+- Open upstream/environment issue tracking from a network-enabled environment if GitHub issue creation is required.

dist/src/docs/agent-handoffs/incidents/INCIDENT_PROMPT-CONTRACT-FAILURES_2026-02-15T01-03-31Z.md

@@ -0,0 +1,21 @@
+---
+agent: onboarding-audit-agent
+cadence: daily
+run-start: 2026-02-15T01:03:31Z
+prompt: src/prompts/daily/onboarding-audit-agent.md
+---
+
+# Incident: PROMPT-CONTRACT-FAILURES
+
+**Date:** 2026-02-15T01:03:31Z
+**Agent:** onboarding-audit-agent
+**Incident ID:** PROMPT-CONTRACT-FAILURES
+
+## Description
+The `npm test` command fails during onboarding validation due to multiple prompt files violating the strict prompt contract enforced by `scripts/validate-prompt-contract.mjs`.
+
+## Impact
+New developers cannot run `npm test` cleanly after checking out the repository.
+
+## Remediation
+Update all agent prompts in `src/prompts/` to strictly follow the `Scheduler Flow` contract regarding completion commands and log file naming.

dist/src/docs/agent-handoffs/incidents/goose-hermit-etxtbsy-fix.patch

@@ -0,0 +1,166 @@
+--- /usr/lib/goose/resources/bin/node-setup-common.sh	2025-10-28 11:13:27.000000000 -0400
++++ /home/user/.local/goose-fix/bin/node-setup-common.sh	2026-02-15 13:17:19.900379075 -0500
+@@ -2,68 +2,107 @@
+ 
+ # Common setup script for node and npx
+ # This script sets up hermit and node.js environment
++#
++# PATCHED: Fixes "text file busy" (ETXTBSY) during hermit init.
++# Root cause: `hermit init` overwrites its own binary (replaces the ~20MB ELF
++# with a ~1.5KB shell stub). On Linux, you cannot write to a binary that is
++# currently being executed, so `hermit init` fails with ETXTBSY when the
++# downloaded hermit binary is the one running the init command.
++#
++# Fix: Copy the hermit binary to a temp location, run init from the copy
++# (so the executing binary differs from the write target), then clean up.
++# Also adds flock to prevent concurrent downloads.
++#
++# See: docs/agent-handoffs/incidents/2026-02-15-hermit-text-file-busy.md
+ 
+-# Enable strict mode to exit on errors and unset variables
+ set -euo pipefail
+ 
+-# Set log file
+ LOG_FILE="/tmp/mcp.log"
+-
+-# Clear the log file at the start
+ > "$LOG_FILE"
+ 
+-# Function for logging
+ log() {
+     local MESSAGE="$1"
+     echo "$(date +'%Y-%m-%d %H:%M:%S') - $MESSAGE" | tee -a "$LOG_FILE" >&2
+ }
+ 
+-# Trap errors and log them before exiting
+ trap 'log "An error occurred. Exiting with status $?."' ERR
+ 
+-log "Starting node setup (common)."
++log "Starting node setup (common) [patched]."
+ 
+-# Ensure ~/.config/goose/mcp-hermit/bin exists
+-log "Creating directory ~/.config/goose/mcp-hermit/bin if it does not exist."
+ mkdir -p ~/.config/goose/mcp-hermit/bin
+-
+-# Change to the ~/.config/goose/mcp-hermit directory
++# Save the original working directory — hermit init requires cd but we must
++# restore it so that the caller's relative paths still work.
++_GOOSE_ORIG_CWD="$(pwd)"
+ log "Changing to directory ~/.config/goose/mcp-hermit."
+ cd ~/.config/goose/mcp-hermit
+ 
++# ── Hermit install with flock + atomic write + copy-for-init ──────────
++HERMIT_BIN=~/.config/goose/mcp-hermit/bin/hermit
++HERMIT_LOCK=~/.config/goose/mcp-hermit/install.lock
++
++# Acquire an exclusive file lock so concurrent node/npx invocations
++# do not race to download or init hermit simultaneously.
++exec 9>"$HERMIT_LOCK"
++if ! flock -w 30 9; then
++    log "WARNING: Could not acquire hermit install lock within 30s; proceeding anyway."
++fi
++
++NEEDS_INIT=0
+ 
+-# Check if hermit binary exists and download if not
+-if [ ! -f ~/.config/goose/mcp-hermit/bin/hermit ]; then
+-    log "Hermit binary not found. Downloading hermit binary."
++if [ ! -f "$HERMIT_BIN" ]; then
++    log "Hermit binary not found. Downloading hermit binary (atomic)."
++    HERMIT_TMP=$(mktemp ~/.config/goose/mcp-hermit/bin/.hermit-download.XXXXXX)
+     curl -fsSL "https://github.com/cashapp/hermit/releases/download/stable/hermit-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/').gz" \
+-        | gzip -dc > ~/.config/goose/mcp-hermit/bin/hermit && chmod +x ~/.config/goose/mcp-hermit/bin/hermit
+-    log "Hermit binary downloaded and made executable."
++        | gzip -dc > "$HERMIT_TMP"
++    chmod +x "$HERMIT_TMP"
++    mv -f "$HERMIT_TMP" "$HERMIT_BIN"
++    sync
++    log "Hermit binary downloaded and made executable (atomic)."
++    NEEDS_INIT=1
++elif file "$HERMIT_BIN" 2>/dev/null | grep -q "ELF"; then
++    # Binary exists but is still the full ELF (init hasn't run yet)
++    log "Hermit binary exists but is uninitialized ELF. Will run init."
++    NEEDS_INIT=1
++fi
++
++if [ "$NEEDS_INIT" -eq 1 ]; then
++    log "Initializing hermit (copy-for-init to avoid ETXTBSY)."
++    # hermit init overwrites its own binary, which fails with ETXTBSY
++    # if the running binary IS the binary being overwritten.
++    # Fix: copy to temp location, run init from the copy.
++    HERMIT_INIT_COPY=$(mktemp /tmp/.hermit-init-copy.XXXXXX)
++    cp "$HERMIT_BIN" "$HERMIT_INIT_COPY"
++    chmod +x "$HERMIT_INIT_COPY"
++
++    if "$HERMIT_INIT_COPY" init >> "$LOG_FILE" 2>&1; then
++        log "hermit init succeeded (via copy)."
++    else
++        log "ERROR: hermit init failed even with copy-for-init. Check $LOG_FILE for details."
++        rm -f "$HERMIT_INIT_COPY"
++        flock -u 9
++        exit 1
++    fi
++    rm -f "$HERMIT_INIT_COPY"
+ else
+-    log "Hermit binary already exists. Skipping download."
++    log "Hermit already initialized. Skipping init."
+ fi
+ 
++# Release the install lock
++flock -u 9
+ 
+ log "setting hermit cache to be local for MCP servers"
+ mkdir -p ~/.config/goose/mcp-hermit/cache
+ export HERMIT_STATE_DIR=~/.config/goose/mcp-hermit/cache
+ 
+-
+-# Update PATH
+ export PATH=~/.config/goose/mcp-hermit/bin:$PATH
+ log "Updated PATH to include ~/.config/goose/mcp-hermit/bin."
+ 
+-
+-# Verify hermit installation
+ log "Checking for hermit in PATH."
+ which hermit >> "$LOG_FILE"
+ 
+-# Initialize hermit
+-log "Initializing hermit."
+-hermit init >> "$LOG_FILE"
+-
+ # Install Node.js using hermit
+ log "Installing Node.js with hermit."
+-hermit install node >> "$LOG_FILE"
++hermit install node >> "$LOG_FILE" 2>&1
+ 
+ # Verify installations
+ log "Verifying installation locations:"
+@@ -71,15 +110,12 @@
+ log "node: $(which node)"
+ log "npx: $(which npx)"
+ 
+-
+ log "Checking for GOOSE_NPM_REGISTRY and GOOSE_NPM_CERT environment variables for custom npm registry setup..."
+-# Check if GOOSE_NPM_REGISTRY is set and accessible
+ if [ -n "${GOOSE_NPM_REGISTRY:-}" ] && curl -s --head --fail "$GOOSE_NPM_REGISTRY" > /dev/null; then
+     log "Checking custom goose registry availability: $GOOSE_NPM_REGISTRY"
+     log "$GOOSE_NPM_REGISTRY is accessible. Using it for npm registry."
+     export NPM_CONFIG_REGISTRY="$GOOSE_NPM_REGISTRY"
+ 
+-    # Check if GOOSE_NPM_CERT is set and accessible
+     if [ -n "${GOOSE_NPM_CERT:-}" ] && curl -s --head --fail "$GOOSE_NPM_CERT" > /dev/null; then
+         log "Downloading certificate from: $GOOSE_NPM_CERT"
+         curl -sSL -o ~/.config/goose/mcp-hermit/cert.pem "$GOOSE_NPM_CERT"
+@@ -92,10 +128,12 @@
+     else
+         log "GOOSE_NPM_CERT is either not set or not accessible. Skipping certificate setup."
+     fi
+-
+ else
+     log "GOOSE_NPM_REGISTRY is either not set or not accessible. Falling back to default npm registry."
+     export NPM_CONFIG_REGISTRY="https://registry.npmjs.org/"
+ fi
+ 
++# Restore the original working directory so callers' relative paths work
++cd "$_GOOSE_ORIG_CWD"
++
+ log "Node setup (common) completed successfully."

dist/src/docs/agent-handoffs/learnings/2026-02-14-distribution-path-github-tarball.md

@@ -0,0 +1,23 @@
+# Single Distribution Path: GitHub Tarball
+
+## Context
+- Installation docs previously mixed npm-style wording with GitHub source installs.
+- This caused confusion because the package is not published to the npm registry.
+
+## Observation
+- `README.md` and `landing/index.html` are the two primary user-facing install surfaces.
+- Any npm-registry wording in either location risks reintroducing broken install expectations.
+
+## Action taken
+- Standardized both surfaces to one install path:
+  - `npm install https://github.com/PR0M3TH3AN/TORCH/archive/refs/heads/main.tar.gz`
+- Added explicit README guidance that TORCH is distributed via GitHub tarballs and is not on npm registry.
+- Updated CLI examples to `npx --no-install` so examples only use locally installed binaries.
+
+## Validation performed
+- Searched docs/UI sources for install phrasing and npm-registry implications.
+- Verified updated install command appears consistently in README and landing page.
+
+## Recommendation for next agents
+- Treat GitHub tarball install as the canonical distribution path unless a real npm publish workflow is added.
+- If distribution changes in the future, update `README.md`, `landing/index.html`, and this learning note in the same PR.

dist/src/docs/agent-handoffs/learnings/2026-02-14-pr-review-limitations.md

@@ -0,0 +1,19 @@
+# PR Review Agent Limitations in Sandbox
+
+## Context
+The `pr-review-agent` is designed to enumerate open PRs using the GitHub API and review them mechanically.
+
+## Observation
+In the current execution environment (sandbox), there is no authenticated access to the GitHub API (e.g., via `gh` CLI or `GITHUB_TOKEN`). As a result, the `curl` request to list PRs returns a 404 or requires authentication that is not present.
+
+## Action Taken
+- Documented the limitation in the task log.
+- Fell back to running repository-wide checks (lint, test) on the current HEAD to provide some value (baseline health check).
+- Created an artifact `artifacts/pr-review/pr-check.txt` capturing the API response.
+
+## Validation Performed
+- Confirmed that `npm run lint` and `npm test` still run successfully and provide useful feedback.
+
+## Recommendation for next agents
+- Future runs of `pr-review-agent` in this environment should expect PR enumeration to fail.
+- Consider implementing a "local branch" review mode if multiple branches are available in the sandbox, or skip PR review if no token is found.

dist/src/docs/agent-handoffs/learnings/2026-02-14-secure-dashboard-binding.md

@@ -0,0 +1,7 @@
+# Secure Dashboard Binding
+
+- **Context:** Hardening the local dashboard server.
+- **Observation:** Default `server.listen(port)` in Node.js binds to all interfaces (`0.0.0.0`), exposing the tool to the local network.
+- **Action taken:** Explicitly added `'127.0.0.1'` as the hostname argument to `server.listen`.
+- **Validation performed:** Verified code change with `grep`.
+- **Recommendation for next agents:** Always specify `'127.0.0.1'` for servers intended only for local use.

dist/src/docs/agent-handoffs/learnings/2026-02-14-validation-before-summary.md

@@ -0,0 +1,7 @@
+# Validation Before Summary
+
+- **Context:** Multi-file documentation update.
+- **Observation:** Running quick checks before writing summaries catches avoidable mistakes.
+- **Action taken:** Ran status and diff checks before finalizing.
+- **Validation performed:** Confirmed expected files changed and no accidental edits were included.
+- **Recommendation for next agents:** Always run at least one verification command after edits and before committing.

dist/src/docs/agent-handoffs/learnings/2026-02-15-relay-health-preflight-job.md

@@ -0,0 +1,26 @@
+# Relay health preflight job before scheduler lock acquisition
+
+## Context
+- Scheduler runs were intermittently failing during lock acquisition when relay connectivity degraded.
+- Existing preflight checks only validated lock query behavior and did not preserve health history for trend analysis.
+
+## Observation
+- A dedicated relay probe that checks websocket reachability plus publish/read behavior per relay provides a clearer readiness signal before lock acquisition.
+- Persisting each probe result enables windowed success-rate alerts and detection of prolonged all-relay outages.
+
+## Action taken
+- Added `torch-lock health` / `npm run lock:health` to run relay websocket + publish/read probes per relay.
+- Integrated scheduler preflight to call `lock:health` immediately before lock acquisition.
+- Updated scheduler behavior to defer early (status `_deferred`) with reason `All relays unhealthy preflight` and incident metadata when no relay is healthy.
+- Stored probe history in `task-logs/relay-health/<cadence>.jsonl` and evaluated alert thresholds:
+  - all relays down for more than N minutes,
+  - success rate below X% over a rolling time window.
+
+## Validation performed
+- Ran targeted unit tests for relay health threshold evaluation.
+- Ran scheduler flow parity checks to ensure preflight remains before lock acquisition in required ordering.
+
+## Recommendation for next agents
+- Keep `lock:health` enabled for scheduler preflight in automation.
+- Review `task-logs/relay-health/<cadence>.jsonl` during incidents to distinguish transient single-relay flakiness from full relay outages.
+- Tune threshold defaults (`--all-relays-down-minutes`, `--min-success-rate`, `--window-minutes`) per environment reliability goals.

dist/src/docs/agent-handoffs/learnings/2026-02-20-docs-agent-readme-sync.md

@@ -0,0 +1,11 @@
+# Docs Agent: README/TORCH.md Synchronization Pattern
+
+- **Context:** docs-agent run 2026-02-20. Audited README.md, CONTRIBUTING.md, AGENTS.md against package.json, src/, and TORCH.md.
+- **Observation:** `TORCH.md` is the authoritative configuration and env-var reference. `README.md` had drifted and was missing 4 env vars and 8 `torch-config.json` keys present in TORCH.md and verified in `src/torch-config.mjs`.
+- **Action taken:** Added missing items to README.md's "Environment variables" and "Configuration" sections. No changes to CONTRIBUTING.md or AGENTS.md — both were accurate.
+- **Validation performed:** Grep confirmed all 4 missing env vars are used in `src/torch-config.mjs`. All referenced file paths verified to exist via Glob.
+- **Recommendation for next agents:**
+  1. When updating env vars or torch-config keys in TORCH.md or `src/torch-config.mjs`, also update README.md's matching sections.
+  2. CONTRIBUTING.md is minimal and accurate — only update if new scripts are added to package.json.
+  3. AGENTS.md is a policy-only file — do not edit it for accuracy; open an issue if policy appears wrong.
+  4. The 4 env vars most often missed in README: `NOSTR_LOCK_PUBLISH_TIMEOUT_MS`, `NOSTR_LOCK_MIN_SUCCESSFUL_PUBLISHES`, `NOSTR_LOCK_RELAY_FALLBACKS`, `NOSTR_LOCK_MIN_ACTIVE_RELAY_POOL`.

dist/src/docs/agent-handoffs/learnings/2026-02-20-docs-alignment-agent-claims-tracing.md

@@ -0,0 +1,15 @@
+# Docs Alignment Agent: Claims Tracing Pattern
+
+- **Context:** docs-alignment-agent run 2026-02-20. Daily pass auditing docs/lib-overview.md, docs/lock-ops-overview.md, docs/memory-index-overview.md, docs/removal.md, docs/architecture/system-overview.md, docs/AGENT_COVERAGE_GAPS.md, src/constants.mjs USAGE_TEXT.
+- **Observation:** Four confirmed doc/code divergences found and fixed:
+  1. `docs/lib-overview.md` claimed RACE_CHECK_DELAY_MS = 2000ms; actual is 1500ms (src/constants.mjs:2).
+  2. `src/constants.mjs` USAGE_TEXT said `NOSTR_LOCK_QUERY_TIMEOUT_MS` default is 15000; actual default is 30000 (`DEFAULT_QUERY_TIMEOUT_MS`). The 15000 value matches `DEFAULT_PUBLISH_TIMEOUT_MS` — likely copy-paste confusion between the two timeouts.
+  3. `docs/removal.md` env var cleanup list was missing 4 vars: `NOSTR_LOCK_PUBLISH_TIMEOUT_MS`, `NOSTR_LOCK_MIN_SUCCESSFUL_PUBLISHES`, `NOSTR_LOCK_RELAY_FALLBACKS`, `NOSTR_LOCK_MIN_ACTIVE_RELAY_POOL`.
+  4. `docs/AGENT_COVERAGE_GAPS.md` claimed "playwright dependency" — Playwright is not in package.json; E2E tests use Node.js built-in `--test` runner.
+- **Action taken:** Fixed all four issues with minimal, targeted edits.
+- **Validation performed:** Grep confirmed exact corrected values in all edited files post-edit.
+- **Recommendation for next agents:**
+  1. When auditing docs, always trace numeric constants (timeouts, delays, counts) to `src/constants.mjs` — these drift most often.
+  2. The USAGE_TEXT in `src/constants.mjs` is the CLI `--help` string — verify its defaults match the exported constants above it.
+  3. `docs/removal.md` env var list must stay in sync with `src/torch-config.mjs` — the four new relay-reliability vars are the most commonly missed.
+  4. When AGENT_COVERAGE_GAPS.md mentions technology dependencies, verify against `package.json` before trusting the claim.

dist/src/docs/agent-handoffs/learnings/2026-02-20-scheduler-cycle-documentation.md

@@ -0,0 +1,11 @@
+# Learning: Scheduler Cycle File Documentation Patterns
+
+- **Context:** docs-code-investigator run 2026-02-20. Documented `scripts/agent/run-scheduler-cycle.mjs` (926 lines) with JSDoc, inline comments, and `docs/scheduler-cycle-overview.md`.
+- **Observation:** The file's logic precisely mirrors the 19 numbered steps in `src/prompts/scheduler-flow.md`. The top-of-file comment already referenced scheduler-flow.md but didn't enumerate the steps — adding them makes the code immediately navigable.
+- **Action taken:** Added module-level JSDoc with 19-step flow, JSDoc to 15 internal functions, targeted inline comments, and a full overview doc.
+- **Validation performed:** Static read of full 926-line file. Call graph traced to scheduler-utils.mjs, scheduler-lock.mjs, src/utils.mjs, roster.json, and test files.
+- **Recommendation for next agents:**
+  1. When documenting scheduler-related files, always cross-reference `src/prompts/scheduler-flow.md` — it is the spec; the code implements it.
+  2. The most non-obvious invariant: lock:complete is called ONLY after all validation gates pass. Document this explicitly when touching the scheduler.
+  3. Three test files cover scheduler behavior: run-scheduler-cycle-memory-policy.test.mjs, scheduler-time-window.test.mjs, scheduler-preflight-lock.e2e.test.mjs. Run all three when changing scheduler logic.
+  4. `task-logs/<cadence>/.scheduler-run-state.json` is day-scoped (resets at midnight UTC). Do not treat it as persistent cross-day storage.